# How to keep generated files out of a coding agent's edits

> Mark generated paths once in .gitattributes, refuse agent edits to them with a hook, and regenerate in CI so an edit that slips through fails the build.

Source: https://voxgig.com/howto/keep-generated-files-out-of-agent-edits

- Audience: platform-team
- Level: intermediate
- Verified: 2026-11-20
- Published: 2026-11-20

## Short answer

Mark the generated paths linguist-generated in .gitattributes, then enforce that list twice. A Claude Code PreToolUse hook asks git check-attr and exits 2 on an edit to a marked file, while reads stay allowed. A CI job regenerates and runs git diff --exit-code, which catches edits from any agent or shell command. Per-agent ignore files differ per tool and also hide the types.

---
## You will need

Node 22 or later, git, and a generated SDK checked into the repository. Verified 2026-11-20
against Node 22.23.5. The sample repository holds a file sdkgen generated, the client oapi-codegen
generated, and the Bookshelf document both came from.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [`.cursorignore`, `.aiderignore`, `.geminiignore` and `.clineignore`](https://cursor.com/docs/reference/ignore-file) | One agent, and you accept a hint the tool may not honor | Four formats with four meanings, and most hide the files from reading too | You need a refusal, or the agent must read the types |
| [Claude Code deny rules and PreToolUse hook](https://code.claude.com/docs/en/hooks) | Claude Code is the agent, and you want edits refused at the tool call | Claude Code only, and a script that opens files itself gets past both | Several agents work in the repository |
| [linguist-generated plus a CI regeneration check](https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github) | Any agent and any person, with the generator runnable in CI | The edit is caught at pull request time, after the agent's work is done | Feedback must reach the agent while it works |
| [oapi-codegen go generate and its DO NOT EDIT header](https://github.com/oapi-codegen/oapi-codegen) | A Go client, where tools already read the generated-code header | The header is a convention, so nothing stops an edit without a CI check | You need the refusal at edit time |
| [`swift-openapi-generator` build plugin](https://swiftpackageindex.com/apple/swift-openapi-generator/1.14.4/documentation/swift-openapi-generator/manually-invoking-the-generator-cli) | A Swift package, where generated code need not be committed at all | Generated code is out of the source tree, so review and audit read nothing | You must commit the generated code |
| [voxgig-sdkgen doctor and JOSTRACA_PROTECT](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) | An sdkgen project, where `.sdk/` is the place for changes | `doctor` checks `.sdk/` only, so edits under `ts/` pass it with exit 0 | The edit to guard is in the generated output |

Voxgig maintains sdkgen. It is one of six options here, not the recommendation.

The ignore files are the cheapest and differ the most from tool to tool. The hook refuses at edit time but only in
Claude Code. The CI check works for every agent and arrives last. Each generator offers something
different. The Swift plugin keeps the output out of the repository, oapi-codegen labels it, and
sdkgen guards its own `.sdk/` tree.

## Mark the generated paths once

[`.gitattributes`](https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github)
is the one list every tool here can read. GitHub collapses `linguist-generated` files in diffs and
leaves them out of language counts; the hook and the CI job read the same lines.

```text title="project/gitattributes.txt"
ts/** linguist-generated
bookshelf/*.gen.go linguist-generated
```

## Refuse the edit at the tool call

A [`PreToolUse` hook](https://code.claude.com/docs/en/hooks) receives the tool call as JSON on
stdin. Exit code 2 blocks the call, and stderr goes back to Claude as the reason. This hook asks git
whether the target is marked, so it never keeps a second list. It first resolves the path from the
repository root, following any symlink in it:

```js title="project/scripts/guard-generated.mjs"
const rel = relative(root, real(resolve(cwd, target)))
if (rel === '' || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) process.exit(0) // outside this repository

// Any .gitattributes, at any depth, and .git/info/attributes can unset the mark.
if (basename(rel) === '.gitattributes' || rel === '.git' || rel.startsWith('.git' + sep)) {
  block(`guard-generated: ${rel} decides what is generated; ask a person to change it`)
}

let attr
try {
  attr = execFileSync('git', ['check-attr', 'linguist-generated', '--', rel], { cwd: root, encoding: 'utf8' })
} catch {
  block(`guard-generated: git check-attr failed for ${rel}, so the edit is refused`)
}

// git prints "<path>: linguist-generated: <set|unset|unspecified|value>"
const value = attr.trim().split(': ').pop()
if (value === 'set' || value === 'true') {
  block(`guard-generated: ${rel} is generated. Change api.json or the generator config and regenerate.`)
}
process.exit(0)
```

`project/claude-settings.json` registers it for `Edit|Write|MultiEdit|NotebookEdit` and adds
`Edit(/ts/**)` and `Edit(/bookshelf/*.gen.go)` as
[deny rules](https://code.claude.com/docs/en/permissions). The demo feeds the hook six tool calls in
the documented input shape:

```bash
node hook-demo.mjs
```

```text output
Edit  ts/src/BookshelfError.ts           blocked
      guard-generated: ts/src/BookshelfError.ts is generated. Change api.json or the generator config and regenerate.
Write bookshelf/bookshelf.gen.go         blocked
      guard-generated: bookshelf/bookshelf.gen.go is generated. Change api.json or the generator config and regenerate.
Edit  docs/../ts/src/BookshelfError.ts   blocked
      guard-generated: ts/src/BookshelfError.ts is generated. Change api.json or the generator config and regenerate.
Read  ts/src/BookshelfError.ts           allowed
Edit  api.json                           allowed
Edit  .gitattributes                     blocked
      guard-generated: .gitattributes decides what is generated; ask a person to change it
```

The path is resolved before git sees it, so `docs/../ts` is caught, and so are a symlink into `ts/`
and a session whose working directory is a subdirectory. The `Read` passes, which keeps the SDK's
types visible. The hook also refuses an edit to any `.gitattributes` file and to anything under
`.git/`, since an attributes file anywhere could unset the mark.

## Catch what the hook cannot see

Claude Code's permissions page says Edit deny rules do not apply to a Node or Python script
that opens files itself. A CI job that regenerates and compares catches those, and edits from
every other agent. `ci-demo.mjs` commits an agent's patch to both files, regenerates, and runs the
check.

```bash
node ci-demo.mjs
```

```text output
ts/src/BookshelfError.ts: linguist-generated: set
bookshelf/bookshelf.gen.go: linguist-generated: set
api.json: linguist-generated: unspecified
git diff --exit-code: exit 1
 bookshelf/bookshelf.gen.go | 1 -
 ts/src/BookshelfError.ts   | 1 -
 2 files changed, 2 deletions(-)
```

Exit 1 fails the job, and the stat names each file the agent touched. In the demo, regenerating
copies the committed generator output back, because the gate cannot run sdkgen or Go. Your job
runs `npm run generate` in `.sdk/`, or `go generate ./...`.

## Find out what sdkgen guards and what it passes

sdkgen 4.44.3 writes the rule into the project's `AGENTS.md`: `ts/` is build output, never edited
by hand. To see what enforces it, make the agent's edit in a scaffolded project, mark a second
file with `JOSTRACA_PROTECT`, and regenerate. `generate.sh` ran these steps once:

```bash title="generate.sh"
cd bookshelf-sdk
echo "// agent edit: retry patched here" >> ts/src/BookshelfError.ts
{ echo '// JOSTRACA_PROTECT'; cat ts/src/utility/FetcherUtility.ts; } > ../protected.ts
mv ../protected.ts ts/src/utility/FetcherUtility.ts
echo "// agent edit: kept" >> ts/src/utility/FetcherUtility.ts
(cd .sdk && npm run generate)
```

It then ran `npx voxgig-sdkgen doctor` in `.sdk/` five times, after each change below, and kept
the files and the log in `sdkgen-run/`. `sdkgen-run.mjs` reads them:

```bash
node sdkgen-run.mjs
```

```text output
ts/src/BookshelfError.ts         no marker                   edit overwritten
ts/src/utility/FetcherUtility.ts JOSTRACA_PROTECT on line 1  edit kept

doctor after appending a line to ts/src/BookshelfError.ts and ts/src/utility/FetcherUtility.ts
  exit 0: .sdk matches the scaffold (0 additive, 0 customized)
doctor after appending a line to the component .sdk/src/cmp/ts/Config_ts.ts
  CUSTOMIZED src/cmp/ts/Config_ts.ts
  exit 0: .sdk matches the scaffold (0 additive, 1 customized)
doctor after also appending a line to the template master .sdk/tm/ts/src/Spec.ts
  CUSTOMIZED src/cmp/ts/Config_ts.ts
  CUSTOMIZED tm/ts/src/Spec.ts
  exit 0: .sdk matches the scaffold (0 additive, 2 customized)
doctor with the same two edits and main: kit: copies: 'overwrite' in .sdk/model/project.aontu
  FORKED     src/cmp/ts/Config_ts.ts
  EDITED     tm/ts/src/Spec.ts
  exit 1: .sdk has drifted: 1 forked, 1 edited, 0 stale, 0 missing, 0 outdated, 0 unresolved
doctor with both edits undone, after adding a file .sdk/tm/ts/src/Extra.ts that target add does not write
  STALE      tm/ts/src/Extra.ts
  exit 1: .sdk has drifted: 0 forked, 0 edited, 1 stale, 0 missing, 0 outdated, 0 unresolved
```

Regeneration overwrote the unmarked edit. The file holding `JOSTRACA_PROTECT` kept its edit, which
is how to keep one file on purpose. `doctor` compares `.sdk/src/cmp/`, `.sdk/tm/` and the target
model with the scaffold, as the [CLI reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md)
says, so it passed both edits under `ts/`.

Its `--help` says it exits non-zero for a forked component or an edited template master. In the
default merge mode it filed both edits as CUSTOMIZED and exited 0, because the copy record in
`.sdk/log/copies.jsonl` shows the project made them. Only with `copies: 'overwrite'` set did it
report FORKED and EDITED and exit 1. A stale file failed it in the default mode.

## Use oapi-codegen's header and the Swift build plugin

oapi-codegen v2.8.2 writes `// Code generated by github.com/oapi-codegen/oapi-codegen/v2 version
v2.8.2 DO NOT EDIT.` on line 3. That matches the regular expression the
[`go generate` documentation](https://pkg.go.dev/cmd/go) asks generated files to carry, so linters
and reviewers can tell. Its README drives generation from a `//go:generate` directive, which makes
the CI check one line. oapi-codegen beats sdkgen here for a Go-only team, because the Go
toolchain already knows which files are generated.

`swift-openapi-generator` was not run, since this sandbox has no Swift toolchain. Its documentation
recommends the package plugin, which generates at build time so the code is not committed to your
source repository. A file that is not in the tree cannot be edited by any agent. That beats
every other row for a Swift package, unless you must commit the code for auditing, where the
manual CLI applies and the CI check returns.

## Check it worked

Six tests cover the hook both ways and the symlink, subdirectory, and attributes-file tricks. They
also cover a call the hook cannot check, the deny rules matching `.gitattributes`, the CI check, and
the five `doctor` exits.

```bash
node --test guard.test.mjs
```

```text output
# tests 6
# suites 0
# pass 6
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

Then ask the agent to edit `ts/src/BookshelfError.ts`, and expect the hook's message in its reply.

## When it goes wrong

The agent stops using the SDK's types and invents its own. The generated directory is in an
ignore file that also blocks reading. Cursor's page says it blocks ignored files from Agent, Tab and
@ mentions. Prefer a rule that refuses writes only: the hook here, or Aider's
[`--read` option](https://aider.chat/docs/config/options.html), which specifies a read-only file.

The hook passes an edit that CI then fails. The agent edited through Bash, with `sed -i` or a
script, which a file-tool hook does not see. Keep the CI check; the
[Cline page](https://docs.cline.bot/customization/clineignore) says its own shell guard is a token
check that a sufficiently creative command could slip through.[^1]

CI fails on a clean branch. The generator version in CI differs from the one that wrote the
committed files. Pin it, as `go run ...@v2.8.2` does in `generate.sh`.

## When not to do this

Do not rely on one ignore file for several agents. `.geminiignore` applies only to the tools that
support it. `.clineignore` filters what Cline loads automatically, is being deprecated, and does
not refuse an edit either.[^2]

Do not treat `voxgig-sdkgen doctor` as the guard for generated output. It checks `.sdk/`, and in
the run shown earlier it passed two edits under `ts/` with exit 0. In the default merge mode it
also passed edits inside `.sdk/`. Pair it with the CI regeneration check, and use
`JOSTRACA_PROTECT` only for a file you mean to own.

Do not commit generated Swift when the package plugin will do. `swift-openapi-generator`
generates at build time, and a file outside the repository needs no guard at all.

Do not deny reads of the generated tree to stop edits. An agent that cannot read the client
writes a second one.

## Related how-tos

- [Let a coding agent customize a generated SDK safely](/howto/customise-a-generated-sdk-with-an-agent-safely)

- [Fail a build when a generator customization becomes a fork](/howto/audit-generator-customisations-for-drift)

- [Preview a regeneration as a diff before writing files](/howto/preview-a-regeneration-as-a-diff)

- [Scope agent instructions to one package in a monorepo](/howto/scope-agent-instructions-per-package)

- [Inject network failures into an AI-written client](/howto/inject-failures-into-an-ai-written-client)

## Last verified

Verified 2026-11-20 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3
with jostraca 0.42.0, and oapi-codegen v2.8.2. Every output block is what the command preceding it
printed. sdkgen and oapi-codegen were run once and their output is committed. `swift-openapi-generator`
was not run; its behavior comes from its documentation. Claude Code was not run with these
settings; the hook was run on the input shape its hooks reference documents. Cursor, Aider, Gemini
CLI and Cline were not run.

[^1]: The [Cline page](https://docs.cline.bot/customization/clineignore) offers an enforced
`PreToolUse` hook beside the original file, and lists what each misses. The original does not stop
reads through explicit @ mentions or shell commands. The hook does not catch a symlink that existed
before it, and the command line turns hooks off in `--yolo` mode.

[^2]: The [Gemini CLI page](https://geminicli.com/docs/cli/gemini-ignore/) adds that ignored paths
stay visible to other services such as Git. [Cursor's page](https://cursor.com/docs/reference/ignore-file)
says the terminal and MCP server tools its Agent uses cannot block access to ignored code, and that
complete protection is not guaranteed due to LLM unpredictability.