Human readability comes first; coding-agent traceability is the minimum gate. A human should understand the code in one pass. An agent must at least be able to trace a feature from CLI flag to executed branch, tensor/record, metric, and test without reconstructing hidden control flow. Every rule below is an instance of that ordering. These are hard correctness rules, not style preferences. A violation is a bug and must be fixed before the change ships.
-
Code a human can't follow at a glance is a bug. If a reviewer can't read a function top-to-bottom in one pass, restructure or delete it. Nesting, indirection, and clever constructs count against correctness — cleverness that costs comprehension is a defect, whatever it saves.
-
Too much / redundant code is a bug. Solve the problem in the fewest lines that stay readable. Prefer deleting code over adding it. A fix that adds more than ~20 lines for a problem statable in one sentence is suspect — find the smaller fix first.
-
Simplicity is the core engineering metric. When two designs both work, ship the one with less code, fewer concepts, fewer files. Never add config, record types, or return-shape changes "for the future".
-
No over-encapsulation. No new class / dataclass / helper / module for a single call site. A helper needs 3+ real call sites AND nontrivial logic — otherwise inline it. Never wrap trivial code. Never change a function signature or return shape to thread data that only one caller needs.
-
Simplicity is not deletion of capability. Features, performance knobs, and observability are intentional — do not remove them in the name of simplicity. Knobs default ON stay ON. Simplify the implementation, keep the behavior surface.
Checklist before finishing any change
- Would a human reading this cold understand it in one pass? That is the gate.
- Could this diff be half the size? If unsure, make it smaller.
- Any new class or file? Justify each with 3+ call sites, or delete it.
- Any signature / return-shape change? Verify every caller genuinely needs it.
- Comments: concise "why" only, 2-4 lines max, written for an external reader — no job ids, commit hashes, single-run metrics, or internal paths; keep upstream issue/PR links.
- One problem = one minimal diff. Do not batch unrelated "improvements".
- A "bug" that cannot trigger under the real recipes is not worth fixing.