Skip to content

Development workflow

The big picture: Every change runs through a chain of reviews, but the chain is sized to the change. A typo fix opens an MR and that’s it; a new full-stack feature gets user, design, security, and completeness reviews.

Why it matters: Too little review ships bugs; too much review ships nothing. Matching review to risk is what keeps an AI-assisted project both safe and fast.

How it works:

  • The Fast paths by change class table in CLAUDE.md is the authority. Find the row that matches your change; run only the gates it names.
  • Claude follows that table on its own, because it is in the repository and loads every session (see Start a project, step 7).
  • When a change fits two rows, take both. When unsure, take the heavier row and say why.

Find the row that matches your change in the Fast paths table, which is read straight from CLAUDE.md so it is always the full, current list. Run the gates that row names, in order, and stop. Some examples:

  • A chore, CI config, or lint-only change runs /mr and nothing else.
  • A dependency bump runs dependency, then changelog-check, then /mr.
  • A bug fix with a known cause runs regression-check, test-scaffold if it is untested, completeness-check, changelog-check, then /mr.
  • A new user-visible feature runs the full chain below.

The full chain, and why each step is there

Section titled “The full chain, and why each step is there”
flowchart TB
  V["1. /voc all #lt;feature#gt;<br/>Would users want this?"]
  T["threat-model<br/>(only if it crosses a trust boundary)"]
  A["2. architect<br/>Is the technical plan sound?"]
  U["3. ux-design<br/>What exactly should the UI be?"]
  I["4. implement<br/>Write the code"]
  G["5. pre-MR gate batch<br/>Four reviews of the diff, in parallel"]
  R["6. ux-review + accessibility<br/>Does the UI match the design system and WCAG?"]
  TS["7. test-scaffold<br/>Is there test coverage?"]
  CC["8. completeness-check<br/>Does the branch do everything the issue asked?"]
  CL["9. changelog-check<br/>A fragment exists (make check-changelog)"]
  MR["10. /mr<br/>Open the MR, with every review's result recorded"]
  FX["/fix-mr<br/>(only if the pipeline fails or the MR conflicts)"]
  V --> T -.-> A
  V --> A
  A --> U --> I --> G --> R --> TS --> CC --> CL --> MR
  MR -.-> FX
  1. /voc — your personas react to the idea. Why: the most expensive bug is a feature nobody needed. (A simulation, not user research.)
  2. architect — debt, coupling, migration risk, reversibility. Why: changing a plan costs minutes; changing merged code costs days. Don’t start coding until its blocking questions are answered.
  3. ux-design — layout, components, every state. Why: if the implementer has to make design decisions, every screen invents its own patterns.
  4. Implement. Tests and docs go in the same commit as the code.
  5. Pre-MR gate batch — regression-check, security-review, rbac-check, perf-check, each only if the diff touches its area. Why in parallel: they’re independent reads of the same diff, and running them one after another was the biggest avoidable source of delay.
  6. ux-review + accessibility — Why: visual drift and keyboard traps are invisible in a code diff.
  7. test-scaffold — Why: new code without tests is a future regression. Each new test must be seen failing on the unfixed code first. Coverage alone doesn’t prove the tests are good when an AI wrote both sides; see Testing AI-written code.
  8. completeness-check — a fresh agent that didn’t write the branch checks it against the issue. Why: most gaps that reach main break rules already written down; what’s missing is someone other than the author checking before the push.
  9. changelog-check (make check-changelog) — Why: CI blocks the MR without a fragment, and the release notes are built from these lines.
  10. /mr — Why: a consistent MR description is the permanent record of what ran and what it found.

Each agent is described in full on the Agents page, and each skill on the Skills page.

See Flows for the whole lifecycle as one diagram per flow.

Completeness-check: one more pass, at most

Section titled “Completeness-check: one more pass, at most”

After completeness-check reports, the author fixes every finding in a new commit (never an amend, so the fix stays separable). Then at most one more pass runs:

Round 1 found… Next
a structural problem (another instance of the same bug, or something else the change broke) Round 2: a full audit by a fresh agent on round 1’s model that isn’t shown round 1’s findings
a fix changed executable code Fix-diff re-check: audit only the fix commits
neither nothing more

On a branch that touches the rigor floor (release and security gates, hooks and settings; see the rigor floor), round 2 always runs, on Opus, whatever round 1 found. On its lighter strict-light tier (the reporting and ledger scripts), round 1 may run on Sonnet first.

Never a loop. If the last pass still finds a blocker, the problem is the branch, not the review — stop and decide with a human: split it, rethink it, or ship with the risk stated.

/conventions-review vs. the specialist agents

Section titled “/conventions-review vs. the specialist agents”
Review Looks for Use on
/conventions-review Code quality, patterns, consistency, naming Any change — the generalist pass
security-review OWASP Top 10, auth, injection Endpoints, auth, user input
rbac-check Login required, per-object access, roles Endpoints and permission rules
ux-review Design-system compliance UI changes
accessibility WCAG 2.1 AA UI changes
regression-check Stale mocks, broken suites, permission drift Every source change
completeness-check Issue fully delivered, whole bug class, tests that can fail, true docs Every source or docs branch, before push

Safety hooks: guardrails that don’t depend on memory

Section titled “Safety hooks: guardrails that don’t depend on memory”

Why they matter: an instruction in CLAUDE.md is followed most of the time. A hook runs every time. Use hooks for the few things that must never slip.

Before an edit — .claude/hooks/pre-tool-safety.sh (PreToolUse, on Edit|Write):

File Action Why
Lock files (package-lock.json, yarn.lock, uv.lock, go.sum, …) Block The package manager must regenerate them
Existing migrations (migrations/<number>…) Block Editing a migration that already ran corrupts real databases; write a new one (creating a new migration file is allowed)
CI config (.gitlab-ci.yml, ci/*.yml, .github/workflows/) Warn Affects every branch — verify before pushing
Env files (.env, .env.local, .env.production) Warn May hold secrets — never commit them

A block prints its reason to stderr and exits 2, so Claude sees why and changes course. A warning reaches Claude as context and the edit proceeds. When you really must hand-edit a lock file or an existing migration, start the session with BLUEPRINT_ALLOW_PROTECTED_EDIT=1 (for example in the env block of .claude/settings.local.json); the block then becomes a warning.

After an edit — .claude/hooks/post-edit-checks.sh (PostToolUse) hands Claude a reminder as context:

File Reminder
models.py, schema.prisma, *.sql Verify migration safety
views.py, routes/, handlers/, controllers/ Run rbac-check and security-review as a parallel batch
permissions.py, auth.*, middleware Run rbac-check and security-review
UI components (.tsx, .jsx, .vue, .svelte under components/pages/…) /voc before design; ux-review and accessibility after
Production source (not tests) Update its test in the same commit
TypeScript source Run make typecheck before committing
Settings and config files If you renamed a key, grep for the old name everywhere

Before opening an MR — .claude/hooks/pre-mr-security-gate.sh (PreToolUse, on Bash) stops an MR-creating command when source or sensitive paths changed and tells Claude to run the access-control and security reviews first. It tokenizes the command (quoted arguments are ignored) and catches glab mr create behind global flags, env, subshells and bash -c, plus git push -o merge_request.create and glab api -X POST .../merge_requests. Once the reviews have run, Claude records that with .claude/hooks/pre-mr-security-gate.sh record ran (or record skipped when you told it to skip, so the MR’s ## Gates section says skipped) and retries the same command. The record is a marker file, .claude/state/pre-mr-gate, keyed to the HEAD sha: a new commit invalidates it. It is an auditable record, not a security boundary, because the agent writes it. If jq or python3 is missing the hook blocks (exit 2) rather than allowing. It hooks the actual command rather than the /mr prompt, so it also fires when an agent opens the MR directly.

At the end of a turn — .claude/hooks/on-stop.sh (Stop) blocks (exit 2) when production source is dirty vs HEAD and make test-scoped has not run since the newest edit (marker: .claude/state/tests-ran, gitignored). It exits 0 in a few milliseconds when nothing is dirty, when stop_hook_active is true (Claude Code sets it when already continuing because of a stop hook, so a continuing turn is never re-blocked), or while make test is still the unconfigured stub. It diffs against HEAD, so work already committed is not re-checked, and Stop fires for the main agent only, not subagents (documented non-goals); the marker is a nudge, not a security control. make test-scoped is a stub-guarded alias for make test; customize it. Opt out by removing the on-stop.sh handler from Stop in .claude/settings.json or setting "disableAllHooks": true in your settings.

.claude/hooks/context-nudge.sh (also Stop) never blocks. When the main session’s context reaches 150,000 tokens it shows you one line suggesting /clear between issues or /compact at a logical break, once per crossing. See Hooks.

Adapt the patterns to your stack. A hook blocks with exit code 2 and allows with 0.

scripts/check-issue-collision.sh runs first on every git push (via make pre-push-checks).

Situation Result
The branch’s issue already has an open MR from a different branch Blocked — override with ALLOW_DUP_MR=1 for deliberate stacked work
The issue carries the WIP label but has no MR yet, and the check-out comment wt new left does not name your branch (a hand-applied label, or another session) Warning
No issue number in the branch, or the issue is unclaimed Pass

Why at push time: a branch can be created many ways (wt new, a plain git checkout -b, another session), but every one passes through git push. It reads every page of open MRs, and if it can’t read them at all (offline, not logged in), it says so out loud instead of passing quietly. Works with glab or gh.