AnthropicClaude Certified Architect – Professional2026-107.2 Improve developer workflows using AI-assisted tooling
Require checks before accepting generated changes
Completed by the knowledge check
Learning objective
Validate AI-generated work with verification loops — tests, linters, builds — plus independent review and deterministic gates.
Core idea
A generated change is complete when the final revision satisfies the team’s executable checks and independent acceptance criteria. Test-first iteration and a fresh reviewer are useful mechanisms; an architect combines them into a completion policy that neither the authoring model nor an incomplete CI run can waive.
Anthropic’s best practices distinguish verification signals, deterministic Stop hooks, and fresh-context review. These controls answer different questions. A test checks specified behavior, a linter checks defined rules, a build checks whether the deliverable can be produced, and a reviewer investigates defects those checks might miss. None should be silently substituted for another.
How it works
Define acceptance outside the generating session
Create a project-owned completion checklist for the change class. Name the actual test, lint, and build commands, the requirements that need human review, the responsible owner, and the source revision being accepted. For an API change, this might require compatibility fixtures, static checks, a distributable build, and review of the exposed behavior. Avoid requiring arbitrary extra checks that have no bearing on the change.
Use repository instructions to tell Claude which commands matter, as Anthropic recommends for CLAUDE.md. Keep the authoritative commands in executable scripts rather than letting each session invent an equivalent command. The change author can propose a faster focused check while iterating, but the final completion decision uses the agreed set.
Record when a check cannot run. A missing dependency, unavailable test service, or denied tool call leaves the relevant condition unverified. It does not establish a defect in the implementation, and it does not establish a pass. Assign that condition to someone who can repair the environment or authorize a documented exception.
Make the loop preserve the requirement
Give Claude the command, returned output, and violated acceptance condition. Anthropic recommends repairing root causes rather than suppressing the error. After a repair, rerun the checks affected by it and complete the final agreed suite against the resulting revision.
The professional failure mode is accepting a moving target. A generator can make a red suite green by deleting an assertion, suppressing a lint rule, or changing a fixture to match the defect. Require review of changes to tests and configuration alongside production code. The acceptance owner decides whether an expectation was wrong; the implementation session cannot silently redefine it to finish.
Preserve the association between revision and result. A successful build before the final dependency edit is historical information. It does not verify the edited dependency. The completion record should state the revision, commands, results, and unresolved limitations so another reviewer can assess what actually ran.
Add a deterministic session check
Anthropic describes four ways to sustain verification: request the check and repair loop in one prompt, set a session-wide /goal condition, run a deterministic Stop script, or obtain a second opinion from a verification subagent. /goal uses a session-scoped prompt-based Stop hook with a separate evaluator that rechecks the condition after each turn; this is model-evaluated judgment. For deterministic local enforcement, configure a Stop hook with type: "command" to execute a verification script. On a failed check, return decision: "block" and a required reason, or exit 2 with the failure explanation on stderr. Claude receives the reason and continues. The script should evaluate the real check result; matching “tests passed” in the assistant’s final message would merely automate trust in a claim.
Account for the hook lifecycle. Stop runs when the main agent finishes responding, not when a user interrupts it; API errors use StopFailure. Its input includes stop_hook_active, which identifies continuation caused by a stop hook. Handle that state deliberately so an impossible condition does not cause repeated attempts without useful progress.
The documented default is an eight-consecutive-continuation cap. Claude Code overrides the next block after eight continuations, and a tool call resets that counter. CLAUDE_CODE_STOP_HOOK_BLOCK_CAP changes the cap. Therefore a Stop hook improves the repair loop but is not an unconditional guarantee that failed work can never stop. Preserve the external merge check even when local hooks are installed.
A failed check blocks the stop and Claude continues, until Claude Code overrides the next block after eight continuations.
Keep review and merge decisions independent
Use a fresh review context to compare the final diff with requirements and relevant source. Anthropic documents the Writer/Reviewer pattern and a bundled /code-review skill for correctness findings. Ask for defects affecting correctness or stated requirements, not a quota of criticisms. A plausible allegation still needs verification before the author changes sound code.
The reviewer should assess what the checks omit: untested business assumptions, missing compatibility cases, weakened assertions, and unintended scope. It can request another check, but a clean model review cannot waive a failing build. A passing build likewise cannot waive a confirmed requirement defect.
For repositories hosted on GitHub, configure Require status checks before merging for the selected checks and Require pull request reviews before merging for approval. Choose the expected status source where appropriate, and apply the intended bypass restrictions. Required checks can be considered satisfied by successful, skipped, or neutral status, so the workflow must not emit a skipped or neutral result for a verification step that actually needed to execute. Branch protection alone cannot infer that missing coverage.
Key distinctions and trade-offs
The completion controls have separate responsibilities:
| Control | What it establishes | What it cannot establish alone |
|---|---|---|
| Tests, linters, builds | Executed assertions and configured rules pass | Every business requirement is correct and covered |
| Independent review | Another context investigates the artifact against criteria | Every finding is true or all defects are absent |
Command-based Stop hook | A script can request continued local repair | Every session termination is blocked until success |
| Required repository checks and reviews | The configured merge conditions are met | A skipped check actually tested the change |
Extra verification consumes runner time and reviewer attention. Keep fast feedback during iteration and complete the agreed acceptance set at the final revision. Optimize redundant work without weakening the condition that protects the release.
Architecture / decision scenario
A healthcare software team generates a change to referral routing. Its release policy requires routing fixtures, lint, a packaged build, and approval from the referral owner. A proposal would accept any change once Claude’s /code-review reports no findings, reducing a 12-minute check run to a two-minute model review.
The architect rejects that substitution. A fresh reviewer inspects the routing rule independently, while a command-based Stop hook returns decision: "block" when the local verification script fails. The first build fails because a configuration file was omitted. Claude repairs the packaging rather than disabling the build check.
CI runs the required commands against the final revision, and repository settings require those checks plus an approving review. The release owner checks that none of the required jobs was skipped and that the approved diff matches the verified one. If the referral assertion itself needs changing, the referral owner must authorize it. The team pays the 12-minute verification cost because a fast opinion cannot establish that the application packages or routes referrals correctly.
Common exam traps
- Accepting a model’s success statement instead of command results.
- Making checks pass by weakening the requirement they represent.
- Treating a Stop hook as protection against every termination path.
- Reusing results from a revision that predates the final repair.
- Letting independent review replace deterministic tests, lint, or build checks.
- Assuming a required check marked skipped performed verification.
What to remember
Define completion outside the generating session and bind it to the final revision. Combine repair loops, verified independent findings, and externally enforced merge conditions. Local hooks help Claude continue; the release owner still requires the actual checks and approvals.
Knowledge check
A team wants a local repair loop that runs the project’s real test suite and requests continued work on failure. CI remains the final merge gate. The local check must not depend on a model’s judgment of whether the condition holds. Which mechanism fits?
/goal condition stating that the test suite passesStop hook that runs the suite and blocks on failureStop hook that blocks unless the final message reports passing testsCLAUDE.md instruction to run the suite before finishingStop hook executes the actual check and, on failure, returns decision: "block" with a reason so Claude continues. /goal uses a prompt-based Stop hook whose separate evaluator is a model, and a hook that matches the final message only automates trust in Claude’s claim. A CLAUDE.md instruction guides behavior without enforcing it.A team’s command-based Stop hook returns decision: "block" whenever its verification script finds failing tests. In a long session, Claude ended its turn while the tests still failed. The hook log shows that the script ran normally and returned a block nine times in a row, with no tool call in between. Claude Code runs with its default environment variables, nobody interrupted the session and no API error occurred. Why did the turn end?
stop_hook_active field turned the hook offStopFailure instead of StopCLAUDE_CODE_STOP_HOOK_BLOCK_CAP changes that cap. stop_hook_active only tells the script that a continuation is under way; the script decides what to do with it. A Stop hook therefore strengthens the repair loop but cannot guarantee that failing work never stops, which is why the required merge checks stay in place.Branch protection requires a verify status check and an approving review. After a workflow edit, verify reports skipped on pull requests that touch only src/routing/, the code it exists to test. A routing change merges with no tests run. What should the team change?
verify execute on every pull request whose code it testsverify as a required status check in branch protection/code-review to confirm that the routing tests ransuccessful , skipped or neutral result, so branch protection cannot tell that a skipped job tested nothing. The workflow itself must run the verification wherever it is needed. The check is already required, and more review cannot stand in for tests that never executed.To fix a failing referral-routing suite, Claude changes an expected destination in a fixture so that it matches the implementation’s output. All required checks now pass on the final revision. What should happen before the change is accepted?
A generated API change passes the team’s agreed tests, lint, and build. Claude then edits a dependency configuration to resolve a review finding and submits the patch with the earlier passing results. What should the acceptance owner require?
References
- Anthropic, Best practices for Claude Code
- Anthropic, Hooks reference
- GitHub, About protected branches