docs: correct and restructure the AI agent configuration guide

[rsdmike]

What this is

I checked CLAUDE.md against a recent paper on common mistakes in agent
config files (arXiv 2606.15828) and fixed
the problems that were real. Docs only — no code changed.

1. We were telling people to do something impossible

CLAUDE.md said:

Run go run ./cmd/openapi-gen and commit the regenerated doc/openapi.json

But doc/openapi.json is in .gitignore (line 39) and has never been tracked.
git add doc/openapi.json fails with "paths are ignored by .gitignore".

CI already handles this. In release.yml, on a release build it checks if
anything under internal/controller/openapi/ changed, and if yes it runs
go run ./cmd/openapi-gen and uploads the result to SwaggerHub. So editing the
Fuego declaration is the only thing you need to commit.

Fixed in CLAUDE.md and in .github/copilot-instructions.md, which said the
same thing.

2. Two different line limits for commit messages

The old text was:

Subject + body lines ≤72 chars (commitlint enforces body-max-line-length: 200)

This reads like the limit is 72 and also 200. The real rule (and what
CONTRIBUTING.md says) is: 72 is a preference, 200 is the hard limit that
fails the build. Now written as two separate sentences.

3. Simpler English

A lot of the guide used English idioms — "big bang", "hold it in their head",
"while I was in there", "ship invisibly", "lock-step". The PR rules in the
"non-negotiable" section had nine of these in three lines.

Since several of us read English as a second language, and these are the rules
we least want people to get wrong, I rewrote them as plain instructions with
real numbers. For example, "do not scope-creep" is now:

• Change only the files needed for the issue you are working on.
• Target roughly 50–300 changed lines.
• If your PR changes more than about 300 lines, or fixes more than one
  problem, split it into two or more PRs.

The release-type rules are now a table instead of a paragraph.

4. Moved five sections into .github/agents/

These are things you only need sometimes. They are now separate files, with a
table in CLAUDE.md saying when to read each one:

File	Read when
.github/agents/mocks.md	You changed an interface and need make mock
.github/agents/openapi.md	You changed a route
.github/agents/databases.md	You need Postgres/Mongo, or a migration
.github/agents/building.md	You need a release binary or cross-compile
.github/agents/fuzzing.md	You are working on a fuzz target

Each file is now longer and more detailed than the old section was, because it
does not have to be short any more.

5. Added a rule about keeping the file updated

CLAUDE.md had one commit in its whole history, while 66 commits landed on
top of it. That is why the wrong instructions above stayed there. The header now
says to update it in the same PR when an instruction turns out to be wrong, or
when a reviewer explains something the file should have already covered.

Not in this PR

CONTRIBUTING.md (lines 137 and 152) and README.md still tell you to commit
doc/openapi.json. Same bug, but those are contributor docs rather than agent
docs, so I left them out to keep this PR focused. Happy to do a follow-up.

Testing

No code changed — git diff --stat is markdown only. I checked that every
make target and every file path mentioned in CLAUDE.md actually exists, and
that all five new links resolve.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 50.82%. Comparing base (76d223b) to head (0f7c99b).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1224   +/-   ##
=======================================
  Coverage   50.82%   50.82%           
=======================================
  Files         149      149           
  Lines       13873    13873           
=======================================
  Hits         7051     7051           
  Misses       6218     6218           
  Partials      604      604           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Updates the repository’s AI agent guidance to be clearer, more accurate, and easier to maintain, including splitting occasional-use guidance into dedicated doc/agents/* documents and correcting prior instructions around OpenAPI generation and commit message limits.

Changes:

• Refactors CLAUDE.md to add a maintenance rule, simplify language, and link out to task-specific guides.
• Adds new task-specific agent docs under doc/agents/ (OpenAPI, mocks, databases, building, fuzzing).
• Aligns .github/copilot-instructions.md with the corrected OpenAPI workflow guidance (do not commit doc/openapi.json).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
doc/agents/openapi.md	New guide explaining route/OpenAPI dual-source-of-truth and why doc/openapi.json is not committed.
doc/agents/mocks.md	New guide for regenerating mocks via make mock.
doc/agents/fuzzing.md	New guide describing fuzz target locations and make fuzz-* helpers.
doc/agents/databases.md	New guide for Postgres/Mongo dev, migrations, and repository method requirements.
doc/agents/building.md	New guide for release builds, cross-compilation, and build tags/targets.
CLAUDE.md	Restructures and clarifies agent guidance; moves occasional-use sections into doc/agents/*; fixes OpenAPI + commit message wording.
.github/copilot-instructions.md	Updates OpenAPI guidance to match CI behavior (generated + published; not committed).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.