agentic-clean-code

Agent Clean Code

The primary reader of this code is an AI agent. Optimize for grep navigation, single tool-call comprehension, and headless test loops.

Size and structure

• Functions: 4–30 lines; split if longer.
• Files: under 500 lines; ideal 200–300. Split by responsibility.
• One responsibility per module (SRP).
• Follow framework conventions (Rails, Django, Next.js, etc.) so paths are predictable.
• Prefer small focused modules over god files.

Grep-friendly names

• Names must reveal intent and be distinct in the codebase.
• Avoid generic names: data, process, handler, Manager, Service, util, helper.
• Prefer specific names: UserRegistrationValidator, InvoiceLineItemTotal.
• Target: rg "<symbol>" returns fewer than 5 hits; if not, rename or namespace.

Types

• Explicit types everywhere the language supports them.
• No untyped public APIs (any, bare Dict, untyped function signatures).
• Typed code gives the agent immediate contracts and reduces inference errors.

DRY and control flow

• No duplicated logic across files — extract shared functions or modules.
• Named constants instead of magic numbers.
• Early returns and guard clauses; max 2 indentation levels.
• Prefer pattern matching / guard clauses over deep nesting.

Comments (provenance, not narration)

• Write WHY and provenance, not WHAT the syntax does.
• Keep agent-written comments on refactor — do not strip them.
• Document non-obvious constraints: upstream bugs, business rules, protocol quirks.
• Reference issue numbers when logic exists because of a specific bug or decision.
• Docstrings on public APIs: intent + one usage example.
• Skip obvious comments (// increment counter above count++).

Errors

• Error and exception messages must include the offending value and expected shape.
• Bad: raise ValueError("invalid input")
• Good: raise ValueError(f"invalid input: received {x!r}, expected non-empty string of digits")

Testability

• Inject dependencies through constructor, parameter, or context — not hidden globals.
• Wrap third-party libraries behind a thin project-owned interface when they may be swapped.
• Mock external I/O (API, DB, filesystem) with named fakes, not scattered inline stubs.
• Every new public function gets a test; every bug fix gets a regression test.