---
title: "Keep generated code apart and never edit · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/structure/generated-code-apart
id: ARC-84
level: Recommended
updated: 2026-10-22
build: a2a6bdfed830
tokens: 912
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Keep generated code apart and never edit it by hand

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Structure](https://agentwranglers.se/playbook/architecture/structure.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: ARC-84
- Level: Recommended
- Chapter: [Structure](https://agentwranglers.se/playbook/architecture/structure.md)
- Rule: 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.
- 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.
- How: 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](https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/code-provenance.md). The [dependency rules](https://agentwranglers.se/playbook/architecture/structure/layers-point-inward.md) still apply to generated files.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Shell example

```sh
# 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

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

## Sources

- [Go generated file marker](https://pkg.go.dev/cmd/go#hdr-Generate_Go_files_by_processing_source)
- [GitHub on how changed files appear](https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github)

## Related rules

- AID-21 [Check where generated code came from](https://agentwranglers.se/playbook/ai-assisted-development/reviewing-agent-output/code-provenance.md) in AI-assisted development
- ARC-63 [Point dependencies inward](https://agentwranglers.se/playbook/architecture/structure/layers-point-inward.md) in Clean code and architecture

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Format all code with one tool](https://agentwranglers.se/playbook/architecture/structure/one-formatter.md)
- Next: [Split off a service only for a written reason](https://agentwranglers.se/playbook/architecture/structure/split-services-for-a-reason.md)
- [Structure](https://agentwranglers.se/playbook/architecture/structure.md)