How-to › Use AI to do the integration

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.

Audience
Platform team
Level
intermediate
Topic
Write an integration with a coding agent
Verified

You ask the agent to add a timeout, and it patches bookshelf.gen.go, the file oapi-codegen wrote. The tests pass and the change merges. The next go generate rewrites all 633 lines of the file and drops the timeout without a warning, because nothing records that the file was edited.

What you get

You will end up with one list of generated paths, a hook that refuses agent edits to them, and a CI job that fails when one slips through. This is for you if a generated SDK lives in a repository an agent works in.

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
.cursorignore, .aiderignore, .geminiignore and .clineignoreOne agent, and you accept a hint the tool may not honorFour formats with four meanings, and most hide the files from reading tooYou need a refusal, or the agent must read the types
Claude Code deny rules and PreToolUse hookClaude Code is the agent, and you want edits refused at the tool callClaude Code only, and a script that opens files itself gets past bothSeveral agents work in the repository
linguist-generated plus a CI regeneration checkAny agent and any person, with the generator runnable in CIThe edit is caught at pull request time, after the agent’s work is doneFeedback must reach the agent while it works
oapi-codegen go generate and its DO NOT EDIT headerA Go client, where tools already read the generated-code headerThe header is a convention, so nothing stops an edit without a CI checkYou need the refusal at edit time
swift-openapi-generator build pluginA Swift package, where generated code need not be committed at allGenerated code is out of the source tree, so review and audit read nothingYou must commit the generated code
voxgig-sdkgen doctor and JOSTRACA_PROTECTAn sdkgen project, where .sdk/ is the place for changesdoctor checks .sdk/ only, so edits under ts/ pass it with exit 0The 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 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.

ts/** linguist-generated
bookshelf/*.gen.go linguist-generated

Refuse the edit at the tool call

A PreToolUse hook 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:

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. The demo feeds the hook six tool calls in the documented input shape:

node hook-demo.mjs
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.

node ci-demo.mjs
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:

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:

node sdkgen-run.mjs
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 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 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.

node --test guard.test.mjs
# 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, 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 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.

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.

Footnotes

  1. The Cline page 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. ↩︎ Back to text

  2. The Gemini CLI page adds that ignored paths stay visible to other services such as Git. Cursor’s page 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.