Protecting Generated Files

Scenario

You maintain a repository containing several forms of generated output:

• API clients;
• database types;
• GraphQL types;
• documentation;
• build metadata.

Different generators have different sources of truth.

Agents need a clear map showing:

generated output
→ authoritative source
→ generation command

This prevents generated files from being mistaken for normal source code.

Repository Structure

platform/
├── src/
│   ├── generated/
│   │   ├── api/
│   │   ├── database.types.ts
│   │   └── graphql.ts
│   └── features/
├── api/
│   └── openapi.yaml
├── graphql/
│   └── schema.graphql
├── supabase/
│   └── migrations/
├── docs/
│   └── reference/
├── scripts/
│   └── generators/
├── package.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## Generated Files

Do not manually edit generated output.

Generated areas include:

- `src/generated/api` — generated from `api/openapi.yaml`;
- `src/generated/database.types.ts` — generated from the database schema;
- `src/generated/graphql.ts` — generated from `graphql/schema.graphql`;
- `docs/reference` — generated from source documentation metadata.

## Generation Commands

Use the repository commands:

- `pnpm generate:api`
- `pnpm generate:db-types`
- `pnpm generate:graphql`
- `pnpm generate:docs`

Use `pnpm generate` when the repository requires all generated artifacts to be refreshed together.

## Workflow

When generated output needs to change:

1. Identify the authoritative source.
2. Modify the source.
3. Run the appropriate generator.
4. Inspect the generated diff.
5. Update affected application code.
6. Run relevant validation.

## Unexpected Generated Changes

- Do not hand-edit generated output to reduce or clean up an unexpected diff.
- Investigate the source, generator version, configuration, or environment.
- Avoid committing unrelated generated churn.

## Validation

After generation:

- inspect generated changes;
- run `pnpm typecheck`;
- run relevant tests;
- run the build when generated artifacts affect production code.

What This Does

This turns generated-code ownership into an explicit map.

For example:

src/generated/api
        ↑
api/openapi.yaml
        ↑
pnpm generate:api

and:

src/generated/graphql.ts
        ↑
graphql/schema.graphql
        ↑
pnpm generate:graphql

An agent no longer has to guess what should be edited.

What This Does NOT Do

The instructions do not say generated files should be ignored.

Agents may need to:

• inspect them;
• understand their exported API;
• review their diffs;
• update code that consumes them.

The rule is about ownership of changes, not visibility.

The instructions also do not assume every generated artifact must always be regenerated.

Run the generator relevant to the source being changed unless the repository's workflow requires a full generation pass.

Why These Instructions Matter

Large repositories often contain multiple generators.

Without a map, an agent may encounter:

database.types.ts

and not know whether it comes from:

Prisma
Supabase
custom SQL generator
manual TypeScript

A generic comment such as:

// Generated file

helps, but it still does not tell the agent what to modify instead.

Good AGENTS.md guidance answers both questions:

Should I edit this?

and:

If not, what should I edit?

Another important case is generated churn.

Suppose changing one OpenAPI field unexpectedly modifies hundreds of generated files.

Manually reverting parts of those files can create output that no longer matches the generator.

The better response is to investigate:

generator version
configuration
source specification
environment
dependency changes

Key Decisions

Map output to source

Instead of only saying:

- Don't edit generated files.

say:

this output
comes from this source
using this command

That gives the agent an actionable path.

Generated output is replaceable

A useful mental model is:

Source of truth
      ↓
Generator
      ↓
Replaceable output

Manual changes below the generator are fragile.

Inspect generated diffs

Automation can still produce incorrect or unintended output.

Generated does not mean automatically acceptable.

Investigate churn upstream

Unexpected generated changes often indicate:

source change
configuration change
generator upgrade
environment difference

Fix the cause rather than editing symptoms.

Keep generated and custom logic separate

Application-specific behavior should live outside replaceable generated directories.

This keeps regeneration safe.

When to Use This Pattern

Use this pattern when:

• a repository contains multiple generators;
• generated output is committed;
• different artifacts have different sources of truth;
• agents may not know which files are safe to edit;
• generator churn can create large diffs.

This is the general pattern behind the entire generated-code category:

protect the output, identify the source, document the command, and validate the regeneration.