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.mdis 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.
Pick your path
Section titled “Pick your path”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
/mrand nothing else. - A dependency bump runs
dependency, thenchangelog-check, then/mr. - A bug fix with a known cause runs
regression-check,test-scaffoldif 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
/voc— your personas react to the idea. Why: the most expensive bug is a feature nobody needed. (A simulation, not user research.)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.ux-design— layout, components, every state. Why: if the implementer has to make design decisions, every screen invents its own patterns.- Implement. Tests and docs go in the same commit as the code.
- 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. ux-review+accessibility— Why: visual drift and keyboard traps are invisible in a code diff.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.completeness-check— a fresh agent that didn’t write the branch checks it against the issue. Why: most gaps that reachmainbreak rules already written down; what’s missing is someone other than the author checking before the push.changelog-check(make check-changelog) — Why: CI blocks the MR without a fragment, and the release notes are built from these lines./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.
Go deeper
Section titled “Go deeper”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.
The duplicate-work gate
Section titled “The duplicate-work gate”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.