Build a Claude Code harness with hooks and tests A seven-layer Claude Code harness for Claude Opus, built around a Next.js App Router invoicing dashboard with about 30 routes and 120 components, uses hooks and executable checks to catch requirements missed during multi-session tasks such as an English, German, French and Arabic localization migration with next-intl. The workflow keeps the plan and progress in version control via harness/plan.md and harness/progress.md, runs format.mjs on a PostToolUse hook for Edit and Write, blocks edits to protected files with a PreToolUse guard.mjs, and uses a Stop hook (stop-gate.mjs) to return failing checks to Claude, with a human making the final acceptance decision. The approach organizes Anthropic's Claude Code best-practices guidance, including plan mode started with claude --permission-mode plan, into a reusable structure for large tasks. An AI harness is the code and configuration around a model that controls how it works and checks what it produces. In Claude Code, that can include project instructions, tool hooks, and scripts that test the application before you accept a change. This matters when a frontend task spans several sessions. A localization migration, for example, can look complete while a toast still contains hardcoded English or a new route has no Arabic layout coverage. A written plan gives Claude the requirements; executable checks help you find the omissions. This article develops a seven-layer workflow for Claude Opus in Claude Code, using a multilingual dashboard as the example. You’ll keep the plan and progress in version control, add checks at defined milestones, and use a stop hook to give Claude feedback when those checks fail. A large task creates several opportunities for requirements to get missed: t ” may receive less attention after many edits and a context compaction Claude Code already supports resuming previous conversations https://code.claude.com/docs/en/common-workflows resume-previous-conversations with claude --continue or claude --resume . Closing the terminal does not, by itself, erase the saved session. A progress file provides a shorter handoff that a teammate can also read. Plan mode https://code.claude.com/docs/en/common-workflows plan-before-editing is useful for exploring a codebase and agreeing on an approach before implementation. You can start it with claude --permission-mode plan . For this workflow, also save the approved plan in the repository so you can review changes to it alongside the code. The emphasis on verification follows Anthropic’s Claude Code guidance https://code.claude.com/docs/en/best-practices . This article organizes those practices into a workflow you can adapt to your project. Each layer has a different role. Instructions guide the model, configured hooks run at matching events, and a person makes the final acceptance decision. | Layer | Artifact | Purpose | How it runs | |---|---|---|---| | 1. Plan | harness/plan.md | Record requirements and milestones | Read at the start of work | | 2. Context | CLAUDE.md , milestone file lists | Limit scope and document conventions | Loaded instructions and explicit file reads | | 3. Formatting | format.mjs | Format edited source files and report lint failures | PostToolUse hook for Edit and Write | | 4. Edit controls | Permission rules, guard.mjs | Block direct edits to protected files | Permission checks and a PreToolUse hook | | 5. Verification | harness/checks.md | Define the checks required at each milestone | run-checks.mjs | | 6. Review | stop-gate.mjs , verifier subagent | Return failures to Claude and review the diff | Stop hook plus an explicit review request | | 7. Acceptance | harness/done.md | Confirm release requirements | Human review and CI | harness/progress.md records the active milestone and unresolved work. Updating it is part of the workflow; the file is only useful if it stays current. For the example, assume a Next.js App Router invoicing dashboard built with TypeScript and Tailwind CSS, with about 30 routes and 120 components. Its interface strings are initially hardcoded in English. The task is to add English, German, French, and Arabic using next-intl. This internationalization work https://blog.logrocket.com/complete-guide-internationalization-nextjs/ includes extracting interface text into message files, making the layout work right to left, and routing date and currency formatting through a shared module. Translations require vendor approval in this example. During development, a sync script may insert English fallbacks into the other message files, but those fallbacks must remain on an untranslated-key list. Matching keys across locales does not establish that the translations are ready to ship. The examples below concentrate on the harness. They assume an existing application with TypeScript, ESLint, Prettier, and Playwright configured, plus project-specific localization checks. The Node.js scripts use built-in modules; the tools they invoke still need to be installed locally. Use a supported Node.js release and record the exact model and Claude Code versions when evaluating the workflow. Create and review the harness files before enabling the edit guard. That prevents the guard from blocking its own initial setup. The file list is: .claude/settings.json .claude/hooks/guard.mjs .claude/hooks/format.mjs .claude/hooks/stop-gate.mjs .claude/agents/verifier.md CLAUDE.md harness/plan.md harness/checks.md harness/progress.md harness/done.md scripts/run-checks.mjs scripts/i18n-sync.mjs scripts/check-locale-parity.mjs scripts/check-literals.mjs scripts/check-logical-css.mjs e2e/routes.ts e2e/seed-ids.json e2e/pseudo-locale.spec.ts e2e/rtl.spec.ts The sync script, static scanners, and Arabic test need implementations tailored to your application. Define them before connecting the stop gate. The excerpts here do not supply a complete dashboard or its acceptance suite. Save the approved plan to harness/plan.md . Number the requirements so test failures and review comments can refer to them: Invariants - I1: Interface copy uses message keys, including JSX text, accessible labels, placeholders, image descriptions, and page titles. - I2: Every production locale has the same leaf keys as messages/en.json. - I3: Non-English messages change only through the approved sync or vendor-import workflow. English fallbacks remain marked as untranslated. - I4: Direction-sensitive layout uses logical properties. Any physical-direction exception needs review. - I5: Dates, numbers, and currency use src/lib/format.ts. Milestones - M1: Routing and message infrastructure. Checks: C1 to C3. - M2: Extract interface strings from routes and components. Checks: C1 to C5. - M3: RTL layout and shared formatting. Checks: C1 to C8. List the allowed files for each milestone in the actual plan. For locale routing, follow the next-intl setup instructions https://next-intl.dev/docs/routing/setup for your Next.js version: newer versions use src/proxy.ts , while older projects use src/middleware.ts . Add a test-only en-XA pseudo-locale that renders English messages with markers, such as Invoices . Generate it from the English catalog while preserving ICU message syntax, and keep it out of production routing. This makes missing message lookups easier to spot in browser tests. Keep CLAUDE.md short enough to use during routine work: 1. Read harness/progress.md and harness/plan.md before editing. Work on the active milestone and its listed files. 2. Open a component's definition before using it. Check its actual props. 3. Add English copy to messages/en.json, then run npm run i18n:sync. Do not write translations yourself. 4. Run the milestone checks and request a verifier review. Ask for approval before advancing the milestone. 5. Record the files changed, checks run, and unresolved failures in harness/progress.md before ending the session. Lessons < -- Add specific, reusable corrections here. -- Claude Code loads project instructions from CLAUDE.md https://code.claude.com/docs/en/memory , but their presence does not guarantee compliance. Check the resulting diff and command output when accepting a milestone. Put the following configuration in .claude/settings.json . These command examples assume a macOS or Linux shell and locally installed dependencies: { "permissions": { "allow": "Bash npm run i18n:sync ", "Bash npm run build ", "Bash node scripts/run-checks.mjs --milestone M1 ", "Bash node scripts/run-checks.mjs --milestone M2 ", "Bash node scripts/run-checks.mjs --milestone M3 " , "deny": "Bash git push ", "Bash npx vercel ", "Read ./.env ", "Read ./.env. " }, "hooks": { "PreToolUse": { "matcher": "Edit|Write", "hooks": { "type": "command", "command": "node \"$CLAUDE PROJECT DIR/.claude/hooks/guard.mjs\"" } } , "PostToolUse": { "matcher": "Edit|Write", "hooks": { "type": "command", "command": "node \"$CLAUDE PROJECT DIR/.claude/hooks/format.mjs\"", "timeout": 120 } } , "Stop": { "hooks": { "type": "command", "command": "node \"$CLAUDE PROJECT DIR/.claude/hooks/stop-gate.mjs\"", "timeout": 900 } } } } Review the allowed scripts before granting these permissions. A command such as npm run build can execute project code. Over 200k developers use LogRocket to create better digital experiences Learn more → The permission rules https://code.claude.com/docs/en/permissions match particular tool calls; they do not provide complete isolation from secrets, deployments, or indirect file access. For stronger restrictions, use an appropriately configured sandbox https://code.claude.com/docs/en/sandboxing and keep production credentials out of the working environment. The edit guard checks paths before Claude uses Edit or Write : js // .claude/hooks/guard.mjs import { readFileSync } from 'node:fs'; import { relative, resolve, sep } from 'node:path'; const block = reason = { process.stderr.write Blocked by harness: ${reason}\n ; process.exit 2 ; }; try { const { tool input } = JSON.parse readFileSync 0, 'utf8' ; const root = resolve process.env.CLAUDE PROJECT DIR ?? '.' ; if tool input?.file path block 'Missing file path.' ; const file = relative root, resolve root, tool input.file path .split sep .join '/' ; if file === '..' || file.startsWith '../' { block 'This edit is outside the project.' ; } if /^messages\/. \.json$/.test file && file == 'messages/en.json' { block 'Use the reviewed sync or vendor-import workflow for other locales.' ; } if /^ e2e|scripts|\.claude \//.test file || /^harness\/ checks|plan|done \.md$/.test file { block 'This file belongs to the reviewed harness. Request a human change.' ; } } catch error { block Cannot validate the edit: ${error.message} ; } This catches direct file edits that match the hook. Shell commands, indirect writes, and symlink handling need separate controls. Keep an authoritative copy of the check scripts and test fixtures outside the agent’s writable checkout, and use that copy for final scoring or CI. After a permitted source edit, the formatting hook runs the project’s local tools: js // .claude/hooks/format.mjs import { readFileSync } from 'node:fs'; import { relative, resolve, sep } from 'node:path'; import { spawnSync } from 'node:child process'; try { const { tool input } = JSON.parse readFileSync 0, 'utf8' ; const root = resolve process.env.CLAUDE PROJECT DIR ?? '.' ; if tool input?.file path throw new Error 'Missing file path.' ; const file = relative root, resolve root, tool input.file path .split sep .join '/' ; if /^src\/. \. cm ? jt sx?$/.test file process.exit 0 ; for const args of '--no-install', 'prettier', '--write', file , '--no-install', 'eslint', '--fix', file { const result = spawnSync 'npx', args, { cwd: root, stdio: 'inherit', timeout: 45 000 } ; if result.error || result.status == 0 { throw new Error Formatting or linting failed for ${file}. ; } } } catch error { process.stderr.write ${error.message}\n ; process.exit 2 ; } A PostToolUse failure reports a problem after the edit has happened. It does not undo the change. The milestone suite must still run against the resulting files. To enforce I5, configure ESLint to flag direct formatting calls outside src/lib/format.ts . Include the APIs your codebase uses, such as Intl.DateTimeFormat , Intl.NumberFormat , and relevant toLocaleString methods. A syntax rule only covers the patterns it recognizes, so review aliases and wrappers too. Define npm run i18n:sync as a reviewed project script. It should preserve approved translations, add English fallbacks for missing keys, and produce an explicit list of untranslated or stale entries when source messages change. Have a person review key removals before the script drops translated content. Store the checks in harness/checks.md . Each row describes an assertion the project can test; a successful command establishes only that its implemented assertions passed. | ID | Check | Command | From | |---|---|---|---| | C1 | Types pass, with next-intl message-key typing configured | npx --no-install tsc --noEmit | all | | C2 | Lint passes, including the shared-formatting rule | npx --no-install eslint . | all | | C3 | Production locales have the same leaf keys as English | node scripts/check-locale-parity.mjs | M1+ | | C4 | The static scan finds no unapproved interface literals | node scripts/check-literals.mjs | M2+ | | C5 | Tested pseudo-locale routes contain no unexpected unmarked text | npx --no-install playwright test e2e/pseudo-locale.spec.ts | M2+ | | C6 | The scan finds no unapproved physical-direction layout rules | node scripts/check-logical-css.mjs | M3+ | | C7 | Tested Arabic routes set RTL direction and stay within the viewport | npx --no-install playwright test e2e/rtl.spec.ts | M3+ | | C8 | The production build succeeds | npm run build | M3+ | For C1, follow next-intl’s TypeScript augmentation setup https://next-intl.dev/docs/workflows/typescript . Running tsc alone does not give message keys stricter types. C3 should compare nested leaf paths, while C4 needs a TypeScript-aware parser and reviewed exceptions for dynamic content. The runner below rejects an invalid milestone or an incomplete table before executing commands. Its shell commands come from a trusted, reviewed file: js // scripts/run-checks.mjs import { readFileSync } from 'node:fs'; import { spawnSync } from 'node:child process'; try { const args = process.argv.slice 2 ; if args.length == 2 || args 0 == '--milestone' || /^M 1-3 $/.test args 1 { throw new Error 'Usage: node scripts/run-checks.mjs --milestone M1|M2|M3' ; } const current = Number args 1 .slice 1 ; const scopes = 'all', 'all', 'M1+', 'M2+', 'M2+', 'M3+', 'M3+', 'M3+' ; const rows = readFileSync 'harness/checks.md', 'utf8' .split '\n' .filter line = /^\|\s C\d+\s \|/.test line ; const pattern = /^\|\s C\d+ \s \| ^| + \|\s ^ + \s \|\s all|M 1-3 \+ \s \|\s $/; const checks = rows.map line = { const match = line.match pattern ; if match throw new Error Invalid check row: ${line} ; return match.slice 1 .map value = value.trim ; } ; if checks.length == scopes.length || checks.some id, , , scope , i = id == C${i + 1} || scope == scopes i { throw new Error 'Expected C1 to C8 in order with the reviewed milestone scopes.' ; } let failed = false; for const id, description, command, scope of checks { if scope == 'all' && current < Number scope 1 continue; console.log Running ${id}: ${description} ; const result = spawnSync command, { shell: true, stdio: 'inherit', timeout: 90 000 } ; const passed = result.error && result.status === 0; console.log ${id}: ${passed ? 'PASS' : 'FAIL'} ; if passed failed = true; } process.exit failed ? 1 : 0 ; } catch error { process.stderr.write ${error.message}\n ; process.exit 1 ; } Adjust command timeouts to your suite. If you add checks, update the runner’s expected IDs and scopes in the same reviewed change. Static analysis can miss a toast assembled in a hook or a title returned by generateMetadata . A browser test can inspect the rendered output, provided the test reaches the relevant state. Start with a route inventory. This example discovers page.tsx files, removes route-group segments, and substitutes fixture IDs for ordinary dynamic segments: python // e2e/routes.ts import { readdirSync } from 'node:fs'; import seed from './seed-ids.json'; const ids: Record