Agent Wranglers

ARC-84Recommended

Keep generated code apart and never edit it by hand

Keep code that a tool generates from a source in marked files of its own. Sources include an API schema, a protobuf file or a database schema. Regenerate the code in CI, and fail when the result differs from the committed copy.

By Agent Wranglers. Updated .

How to do it

A hand edit in generated code vanishes at the next run, and a stale copy hides a schema change. Start each file with the marker the tool writes. Go defines one that tools and linters recognise, a line matching ^// Code generated .* DO NOT EDIT\.$. Mark the folder as generated in the code host, such as linguist-generated in .gitattributes, so reviews fold it away. Linters and the formatter skip it. Code that an agent writes is not generated in this sense. It is source, and it follows Check where generated code came from. The dependency rules still apply to generated files.

Examples

Shell example

# CI: regenerate from the sources, then fail on any difference
npx openapi-typescript api/openapi.yaml -o src/generated/api.ts
buf generate
git diff --exit-code -- src/generated gen/ || { echo "FAIL: generated code is stale or hand-edited"; exit 1; }

Plain text example

src/generated/** linguist-generated=true
gen/** linguist-generated=true

How to check

CI runs every generator and then git diff --exit-code, and any difference fails the build. A pull request that edits a generated file without changing its source fails the same check.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/architecture/structure/generated-code-apart">Agent Wranglers clean code and architecture playbook</a>. In code you write, add a comment next to it with the same link.