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

  1. Decisions belong to the approver. Never run approve, later, wontfix, accept or sendback on your own. Run them only when the approver tells you to ("approve 3 and 8, park 7" means approve 3 8 and later 7 --note "…").
  2. Never fix a bug that isn't approved. openbugfix fix refuses anyway.
  3. Every fix has a regression test on every affected surface. A website and an app are separate surfaces, even when they share a server.
  4. Code owned by someone else (owner in surfaces.yaml) is theirs to change. Record the bug and tell them.
  5. 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

  1. Find it: steps a person can repeat, and the cause with file:line. Check the code; don't guess.
  2. 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.

  1. Link a lesson: openbugfix link BUG-NNNN P-NNN for one that exists, or openbugfix pattern "the rule in one line" --applies web,app,server --from BUG-NNNN for a new one. Check openbugfix library first: a general lesson may already cover it (openbugfix adopt L-NNN).
  2. 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

  1. 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.
  2. Do this on every affected surface.
  3. 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.

  1. After each deploy: openbugfix deployed NNNN --to staging|testflight|live.
  2. It now waits for the approver's review: accept (done) or sendback (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:

Reading another owner's code to sweep it is fine; changing it is theirs.

Before calling product work done

  1. Read the lessons that touch what you changed (openbugfix list, the files in patterns/) and check your change against them.
  2. Run openbugfix validate. Fix every ERROR and report the TO DO lines (open bugs, unchecked surfaces) plainly.
  3. Run the surface's own tests (tests: in surfaces.yaml) if you touched it.
  4. Tell the approver what waits for them (openbugfix view); openbugfix web shows the same in a browser.