Skip to main content

Coding standards for agent-built code

Agents write most of the code, at volume. Standards therefore have to be machine-enforceable and agent-readable — shipped as linter config in the project scaffold, not as prose nobody runs. Humans never review anything a formatter can decide.

Principles​

  • Style is delegated entirely to formatters. No human review comment is ever about formatting. The formatter's output is the style; there is nothing to debate.
  • Rules ship as config. Every rule below exists as linter/formatter configuration in the scaffold. A rule that isn't enforced by a tool is advisory, and advisory rules rot.
  • Readable like the surrounding code. Agents match the file's existing naming, idiom and comment density — new code should be indistinguishable from well-written neighbouring code.
  • Comments state constraints, not narration. A comment explains a non-obvious constraint the code can't express — never what the next line does or why the change is correct.

Enforced rules​

  • Formatting: the language's standard formatter, run in CI; failure blocks the merge gate.
  • Complexity & size limits: per-function cyclomatic complexity and per-file length ceilings; breaches fail CI.
  • Error handling: no swallowed exceptions; errors are handled or propagated with context. Language-specific patterns encoded in lint rules.
  • Logging: structured logging only (an observability standard follows); no secrets or PII in logs, enforced by secret-scanning.
  • Secure coding: mapped to OWASP ASVS L2 — parameterised queries, output encoding, authenticated-by-default (see Secure-by-default).

Anti-patterns agents are prone to​

Encode these as lint rules or review-checklist items; they are the failure modes AI-generated code shows most:

  • Dead abstractions — layers and indirection with a single caller, added "for flexibility".
  • Swallowed exceptions — catch {} that hides failure.
  • Hallucinated APIs — calls to methods/params that don't exist; caught by type-checking and tests.
  • Reimplemented stdlib — hand-rolling what the standard library already provides.
  • Silent dependency additions — pulling in a package rather than using what's present (blocked: see below).

Dependencies​

Agents may not add a new dependency without explicit human approval in the PR — the primary defence against hallucinated and typosquatted packages. Approved additions still pass the intake gate (licence, CVE, maintenance, provenance). See the supply-chain standard (to follow).