Documentation Generation

Scenario

You maintain a library where part of the documentation is generated from source metadata.

The repository contains:

• handwritten guides;
• source comments and metadata;
• generated API reference pages.

Coding agents need to distinguish editable documentation from generated documentation.

Repository Structure

sdk/
├── src/
│   ├── client.ts
│   └── resources/
├── docs/
│   ├── guides/
│   │   ├── getting-started.md
│   │   └── authentication.md
│   └── reference/
│       ├── client.md
│       └── users.md
├── scripts/
│   └── generate-docs.ts
├── package.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## Documentation

Documentation has two categories:

- `docs/guides` contains handwritten documentation.
- `docs/reference` contains generated API reference documentation.

## Generated Reference

- Do not manually edit files under `docs/reference`.
- Update the source code, comments, or metadata that drives the reference generator.
- Regenerate reference documentation with `pnpm generate:docs`.

## Handwritten Guides

- Edit `docs/guides` directly when user-facing explanations or tutorials change.
- Keep examples synchronized with the current public API.
- Prefer runnable or verified examples where the repository supports them.

## Public API Changes

When changing a documented public API:

- update source documentation metadata;
- regenerate reference documentation;
- update affected handwritten guides;
- check examples for outdated usage.

## Validation

After documentation generation:

- inspect the generated diff;
- run documentation validation supported by the repository;
- check important links and code examples when affected.

What This Does

This tells the agent that:

docs/

does not have one universal editing rule.

Instead:

docs/guides/
    ↓
human-authored
    ↓
edit directly

while:

docs/reference/
    ↓
generated
    ↓
modify source and regenerate

This distinction is more useful than a blanket instruction such as:

- Do not edit docs.

What This Does NOT Do

The instructions do not treat all documentation as generated.

Human-authored material such as:

tutorials
concept explanations
migration guides
architecture guides

often should be edited directly.

Likewise, the file does not say generated documentation requires no review.

Automation can generate outdated, malformed, or unexpectedly large changes when its source changes.

Why These Instructions Matter

Suppose a generated reference page says:

createUser(email)

but the actual public API has changed to:

createUser({ email, name })

An agent might fix:

docs/reference/users.md

directly.

The documentation now looks correct.

But the next generation run restores the old content because the source metadata was never updated.

The real fix belongs upstream.

By contrast, if a tutorial explains the old workflow in:

docs/guides/getting-started.md

that file may need a direct edit.

Key Decisions

Document generation boundaries explicitly

Directory names alone may not make generated ownership obvious.

Update upstream sources

Generated documentation should reflect authoritative source metadata.

Human documentation still needs maintenance

Generated API references do not replace tutorials and explanations.

Validate examples

Documentation containing invalid code can mislead users even if the application itself works correctly.

Review generated changes

Generation does not remove the need for review.

When to Use This Pattern

Use this pattern when:

• API references are generated;
• guides are maintained manually;
• source metadata drives documentation;
• public API changes affect multiple documentation surfaces;
• generated and handwritten files coexist.

This pattern prevents temporary documentation fixes that disappear during the next generation run.