Minimal modular code

Minimal Modular Code

Keep agent-written code minimal and modular. Minimal is not fewest lines: it is behavior behind a small interface, reused before rebuilt, legible to a finite-context reader. Steer by named heuristics:

• Reuse before write — grep the repo and deps for an existing helper before adding one.
• Subtract first — ask "what can be removed?"; the subtractive option never surfaces on its own.
• Rule of three — duplication is cheaper than the wrong abstraction; back a bad abstraction out rather than parameterize it.
• Deep modules — small interface over substantial behavior; single-caller indirection and pass-through layers are negative-value structure.
• Information hiding — put the seam where it hides the likely-to-change decision; dependencies point toward stable code.
• Concise, not terse — fewer semantic elements, never code golf.
• Gates, not prose — a load-bearing invariant needs a failing check, not a sentence.

Deletion needs proof. Never delete guards, tests, validation, error paths, or boundaries to make a diff smaller unless the prompt supplies proof they are obsolete — from blame, tests, the contract, or an upstream invariant. "Not in scope", downstream behavior, or a promised later PR is not proof. When proof is missing, keep the code and say why.

Workflow

1. Restate the ask: smallest safe change, slop/coupling audit, or boundary design. Infer it from the request.
2. Read the touched code and its callers; search for existing helpers before proposing new ones. Compute the blast radius: what does the change touch beyond the stated scope?
3. Load the one reference the task needs: references/minimalism.md for amount-of-code and readability questions (slop, duplication, over-engineering, deletion, cleverness); references/boundaries.md for seam, coupling, parallel-work, and gate-coverage questions.
4. Propose the minimal change or the findings. Preserve unrelated names, control flow, and interfaces. Snippets include imports for newly referenced types; with partial context keep multi-file details conceptual rather than invented.
5. When reviewing, severity is one line: blocking (violated invariant, wrong-direction dependency, deleted safety behavior) vs advisory (style, deferred cleanup).

Stop conditions

• Stop when the requested behavior is achieved and nothing more can be removed with proof. Do not expand a fix into a rewrite; opportunistic cleanup is out unless the fix requires it.
• Run to completion without check-ins: state assumptions inline and proceed. Ask only on a genuine blocker — a missing file or a contradictory requirement.