Generated Code Ownership Boundaries: Sources, Artifacts, and Safe Regeneration

The src/generated directory in a repository looks like ordinary source code, so when a coding Agent finds an error, it is easy to modify the files directly. The next codegen run will overwrite the patch. Worse, the team may commit only the artifacts without committing the schema or generator upgrade, leaving nobody able to reproduce the same result. Generated code needs explicit ownership: people modify sources and templates, the generator owns the artifacts, and extension logic belongs behind boundaries that will not be overwritten.

The repository map should identify generated paths. The Coding Agent Repository Map provides an entry point; this article goes further by defining an ownership contract that CI can enforce.

The commands in this article are intended to run in a Linux/GNU CI container with Bash, GNU coreutils, and Git. macOS/Windows runners must use the same container.

Use a Generation Manifest to Connect Sources and Artifacts

Register the inputs, templates, generator, parameters, and outputs for every generation target instead of leaving only a command in the README. Represent the generator with a container digest or an exact package version from a lockfile. Pin remote schemas by content digest before use; do not read a mutable latest URL during the build.

target: payments-ts-client
inputs:
  - path: api/payments.openapi.yaml
    sha256: 9e31...
templates:
  path: tools/openapi-templates
  sha256: b21a...
generator:
  image: registry.example/openapi-generator@sha256:4ac8...
outputs:
  - packages/payments-client/src/generated
owners: [payments-platform]

Artifact headers should include a marker such as Code generated ... DO NOT EDIT., the target ID, and the generation manifest digest, but not the current time or an absolute local path. Go's generation convention treats go generate as an explicit development action and does not run it automatically during an ordinary build. The same principle applies to other languages: when regeneration occurs must be determined by a versioned command.

Keep Manual Extensions Out of Overwritten Areas

Place custom behavior in adapters, partial classes, interface implementations, or template layers supported by the generator. OpenAPI Generator's ignore file can prevent certain files from being overwritten, but every exception must identify the true owner. A large ignore list often indicates a poorly designed boundary. If an emergency patch can only be applied to an artifact, treat it as a time-limited exception, then backport it to the source or template and prove through regeneration that the patch will not disappear.

Before an Agent modifies a generated directory, CI should look up the manifest in reverse. If the diff does not also contain a corresponding input, template, or generator change, block it by default. Conversely, if a source changes without the expected artifact diff, block that as well to prevent authors from forgetting to regenerate. API clients must also pass Contract Compatibility Gates for Agent-Authored API Changes, because "generated successfully" does not mean existing consumers remain compatible.

Prove Determinism in a Clean Worktree

Regeneration checks must not run against a developer's existing artifacts and caches. CI should create an isolated checkout, install frozen dependencies, run the sole entry point, and then require the worktree to match the commit:

set -euo pipefail
TMP_ROOT=$(mktemp -d)
CHECKOUT="$TMP_ROOT/checkout"
cleanup() {
  git worktree remove --force "$CHECKOUT" >/dev/null 2>&1 || true
  rmdir "$TMP_ROOT" >/dev/null 2>&1 || true
}
trap cleanup EXIT

git worktree add --detach "$CHECKOUT" HEAD
(
  cd "$CHECKOUT"
  GENERATED_PATHSPEC=':(glob)packages/*/src/generated/**'
  pnpm install --frozen-lockfile
  pnpm codegen
  git diff --exit-code HEAD -- "$GENERATED_PATHSPEC"
  test -z "$(git ls-files --deleted -- "$GENERATED_PATHSPEC")"
  test -z "$(git ls-files --others --exclude-standard -- \
    "$GENERATED_PATHSPEC")"
)

cleanup
trap - EXIT

The status checks cover both modifications to tracked files and newly generated artifacts. If the first generation produces a diff, the commit is missing artifacts or uses inconsistent tool versions. If two consecutive generations still produce a diff, investigate timestamps, random ordering, path separators, and unpinned network inputs. Do not hide irreproducibility by having CI automatically commit generated files back to the branch.

The generation gate must also validate the file set. When a schema removes a type, the old artifact must be deleted; merely overwriting existing files leaves behind ghost APIs. Record the previous output list in the manifest, generate the new output in a staging directory, and atomically replace the target directory after validation so that a mid-process failure cannot leave a mixture of old and new state.

Review Source Changes and Artifact Risk

A large diff should not force reviewers to read machine-generated boilerplate line by line, but it should not be collapsed completely either. The report should summarize added and removed public symbols, protocol fields, dependencies, and file counts, while showing samples of high-risk output. Generator images and templates are supply-chain artifacts, so verify their signatures, provenance, and vulnerabilities. These boundaries can be combined with AI Supply Chain Security.

Before release, build generated clients across the supported language and runtime matrix, then run tests for serialization, error responses, and compatibility with older services. Ideally, split a generator upgrade and a business-level schema change into two commits: the former demonstrates mechanical differences for identical inputs, while the latter shows the actual contract changes. Combining them makes regressions impossible to attribute.

Rollbacks Must Restore the Complete Generation Tuple

The correct rollback unit is inputs + templates + generator + parameters + artifacts. When a production issue occurs, switch back to the previous verified artifact digest and revert the entire tuple in a commit. Restoring only the artifacts allows the next generation to reintroduce the problem, while restoring only the schema may leave the current binary and client mismatched.

Execute and revalidate the complete tuple on an isolated rollback branch:

git revert --no-edit "$CODEGEN_CHANGE_SHA"
GENERATED_PATHSPEC=':(glob)packages/*/src/generated/**'
pnpm install --frozen-lockfile
pnpm codegen
git diff --exit-code HEAD -- "$GENERATED_PATHSPEC"
test -z "$(git ls-files --deleted -- "$GENERATED_PATHSPEC")"
test -z "$(git ls-files --others --exclude-standard -- \
  "$GENERATED_PATHSPEC")"
pnpm build

After restoration, rerun pnpm codegen and the build in a clean checkout, require a zero diff, and verify that older clients or services can still interoperate. Retain the generation manifest, validation report, and rollback digest as release artifacts in the CI/CD Pipeline Design. Clear ownership boundaries ultimately tell the Agent where changes belong and allow every artifact to answer: "What generated this, with which version, and under what parameters?"