api-code-generation

---
name: api-code-generation
description: Use when generating API code from a contract or by pattern, meaning handlers or clients generated from a schema, scaffolding a new resource from a sibling, regenerating an SDK, or changing the schema or generator config itself. Keeps the contract the single source, generated output reproducible, and breaking changes explicit.
---

# API code generation

## Required context

1. `.agents/areas.json`: the area the generated code lands in, its guardrail and its `verify`
   command.
2. `.agents/guardrails/code-style.md`: what generated and hand-written code must both satisfy.
3. `.agents/skills/secure-api-endpoint/SKILL.md`: the security rules still apply to generated
   endpoints; a generator does not know your authorization model.
4. `.agents/policy/data-classification.yml`: which fields are confidential and may not be exposed.
5. The contract (`contracts/openapi.json` in this repository) and the generator's config, and one
   sibling resource already generated the same way.

## The rules that bite

- **The contract is the single source.** Change the schema, then regenerate. A hand edit to
  generated output is lost on the next run and, until then, disagrees with the contract that
  clients were built from.
- **Generated files say so.** Each carries a header naming its generator and input, so a reviewer
  and a merge resolver know to regenerate rather than hand-merge.
- **Reproducible output.** Pin the generator's version, commit its input and its output in the
  same change, and keep a check that regenerates and diffs, so drift fails a gate instead of a
  client.
- **The route table matches the contract.** `tools/check-contract.py` compares what
  `make -C app/api routes-json` prints with `contracts/openapi.json`: every method, path, operation id
  and public or protected standing. Change the contract first, in the same change as the route.
- **Do not invent the contract.** Every endpoint, field and status code comes from the schema or
  the operator's request. A plausible extra field is a public commitment nobody made.
- **Generated is not authorized.** Scaffolding produces a handler; it does not produce the
  authorization check, the query scoping or the page-size clamp. Add them and test them as for a
  hand-written endpoint.
- **Public identifiers only.** A generated serializer exposes what the schema says. Check the
  schema does not expose an internal id, a token or a confidential field.
- **Breaking changes are explicit.** Removing or renaming a field, narrowing a type, adding a
  required input or changing a status code breaks existing clients. It needs a new version or a
  recorded decision, never a quiet regeneration.
- **Follow the sibling.** When scaffolding by pattern, copy the shape of the newest good sibling,
  not the oldest: old ones carry the conventions the codebase has since dropped.
- **Adding or upgrading a generator is a dependency change**, which is an escalation.

## Verify

```bash
<the regenerate command, then git diff --exit-code on the output>   # generated matches the contract
<the area's test runner, filtered to the new resource>
make verify
```

Then the area's `verify` command exactly as `.agents/areas.json` declares it; tests follow
`.agents/skills/api-test-generation/SKILL.md`. Reviewers: `api-standards-reviewer` and
`code-reviewer`; `security-data-reviewer` when a field's data class changes.

## Escalate when

- The change breaks a public contract clients depend on.
- A generator or its runtime is added, replaced or upgraded (a dependency change).
- The schema would expose a confidential or secret data class.
- The contract and the operator's request disagree: ask which one is right, do not pick.