A guide for AI coding agents
Point your AGENTS.md, CLAUDE.md or equivalent at this file. It applies to any agent: Claude Code, Codex, Cursor, OpenCode and others.
The command is openbugfix (openbugfix -h lists everything). It finds the bug list from the folder you're in; openbugfix stores lists the lists on this computer and --store NAME picks one. A list is plain files: bugs/, patterns/, surfaces.yaml, coverage.yaml. Use the command rather than editing the front matter by hand; write the prose sections (What was seen, Cause, Fix) in the files directly.
Rules
- Decisions belong to the approver. Never run
approve,later,wontfix,acceptorsendbackon your own. Run them only when the approver tells you to ("approve 3 and 8, park 7" meansapprove 3 8andlater 7 --note "…"). - Never fix a bug that isn't
approved.openbugfix fixrefuses anyway. - Every fix has a regression test on every affected surface. A website and an app are separate surfaces, even when they share a server.
- Code owned by someone else (
ownerinsurfaces.yaml) is theirs to change. Record the bug and tell them. - Run checks when asked. Don't set up scheduled or background runs of these checks unless the approver asks.
When a bug is found or reported
- Find it: steps a person can repeat, and the cause with
file:line. Check the code; don't guess. - Record it:
openbugfix new "what goes wrong, in the user's words" --type ui|function|money|content|speed|security \ --source internal|ai-scan|user|test --surface SURFACE [--surface SURFACE] --severity low|medium|high|critical \ --found-by WHO
Surface ids: openbugfix surfaces. Then write What was seen and Cause in the file it prints.
- Link a lesson:
openbugfix link BUG-NNNN P-NNNfor one that exists, oropenbugfix pattern "the rule in one line" --applies web,app,server --from BUG-NNNNfor a new one. Checkopenbugfix libraryfirst: a general lesson may already cover it (openbugfix adopt L-NNN). openbugfix triage BUG-NNNN --effort "…" --risk "…". It now waits for the approver. Tell them what is waiting (openbugfix view --status waiting).
When fixing an approved bug
- Write the regression test first, named after the bug (
test/regression/BUG-0007.spec.ts,test/regression/bug_0007_test.dart,.maestro/BUG-0007.yaml). Watch it fail, fix, watch it pass. - Do this on every affected surface.
- Record it:
openbugfix fix BUG-NNNN --commit SHA --test SURFACE:PATH [--test SURFACE:PATH …] --check "2-3 steps to check it"
PATH is from the surface's repo folder (repo: in surfaces.yaml), not from the folder you run the command in: with repo: ~/code/shop and the test at ~/code/shop/web/tests/BUG-0007.spec.ts, give --test shop-web:web/tests/BUG-0007.spec.ts. An app screen that shows the website's own page (a web view) can be covered by the web test: --test APP_SURFACE:@WEB_SURFACE.
- After each deploy:
openbugfix deployed NNNN --to staging|testflight|live. - It now waits for the approver's review:
accept(done) orsendback(back to approved, with a note). Other remarks:openbugfix note NNNN --note "…" --by WHO.
Sweep the lesson across every other surface
openbugfix sweep P-NNN shows how to check and which surfaces nobody has checked. For each one:
openbugfix mark P-NNN SURFACE clean --note "how you checked": checked, no problem;openbugfix mark P-NNN SURFACE affected --bug BUG-NNNN: it has the bug (record that bug first);openbugfix mark P-NNN SURFACE test --path PATH: a regression test guards it;openbugfix mark P-NNN SURFACE n/a --note "why it can't happen there".
Reading another owner's code to sweep it is fine; changing it is theirs.
Before calling product work done
- Read the lessons that touch what you changed (
openbugfix list, the files inpatterns/) and check your change against them. - Run
openbugfix validate. Fix every ERROR and report the TO DO lines (open bugs, unchecked surfaces) plainly. - Run the surface's own tests (
tests:insurfaces.yaml) if you touched it. - Tell the approver what waits for them (
openbugfix view);openbugfix webshows the same in a browser.