On 2026-01-02 Boris Cherny, the creator of Claude Code, posted a thread of thirteen points about how he uses the tool, opening with the remark that his setup is surprisingly plain. When we read it on 2026-11-08, the first post showed about 8.2 million views and point 13 about 575 thousand. Ten months is a long time for Claude Code: the default model, the default permission mode, the way slash commands are organized and the way local and cloud sessions hand off have all changed. So instead of retelling the thread, this article places every point next to the documentation as it read on that day.
Boris Cherny: thread opener (2026-01-02) · Boris Cherny: point 13, the verification loop
The yardstick comes from the official best-practices page: every instruction is either non-deterministic (written for the model, which decides whether to follow it: your prompt, CLAUDE.md, a skill) or deterministic (executed by Claude Code, the harness, whatever the model decided: a hook, a deny rule, a managed setting). Some of the thread’s habits belong to the first kind, some to the second, and their reliability differs completely. The thread’s strongest claim is point 13: give Claude a way to verify its work and the final result improves two to three times. The structure of this article follows that loop.
Boris Cherny: point 13, the verification loop · Claude Code docs: Best practices
Boundaries first. We did not run Claude Code, did not enable these hooks in any real repository, and checked the JSON, Markdown and shell blocks offline only. Where the thread names a model, a command or a plugin that the current documentation no longer matches, the text says so (as described in the thread) and points at the current page. View counts and version numbers are readings from 2026-11-08 and may not hold later.
1. What the thread says and what we checked
The thirteen points fall into four groups. Session orchestration: five local Claude instances in numbered terminal tabs with system notifications when one needs input (point 1); another five to ten sessions on claude.ai/code, local sessions handed to the web with an ampersand and occasionally pulled back with --teleport (point 2); Opus 4.5 with thinking for everything, bigger and slower than Sonnet but needing less steering (point 3). Knowledge capture: one CLAUDE.md for the Claude Code repository, checked into git, edited by the whole team several times a week, with a note added whenever Claude does something wrong (point 4); tagging Claude on coworkers’ pull requests so the GitHub Action adds the lesson to CLAUDE.md as part of the PR, which the author calls compounding engineering after Dan Shipper (point 5).
Process and permissions: most sessions start in plan mode, iterate on the plan, then switch to auto-accepting edits (point 6); a slash command for every frequent inner-loop workflow, checked in under .claude/commands/ (point 7); a few subagents, code-simplifier to clean up after Claude finishes and verify-app holding end-to-end test instructions (point 8); a PostToolUse hook that formats code and catches the roughly ten percent the model misses so CI stays green (point 9); no --dangerously-skip-permissions, but /permissions to pre-allow safe commands, saved in a shared .claude/settings.json (point 10); Slack over MCP from a shared .mcp.json, BigQuery through the bq CLI, logs from Sentry (point 11).
And verification: for long tasks, ask Claude to verify with a background agent when done, use a Stop hook to do it more deterministically, or use the ralph-wiggum plugin (point 12); and the closing tip that verification is probably the most important thing, with Claude testing every change to claude.ai/code through the Chrome extension, opening a browser, exercising the UI and iterating, while the right check depends on the domain: a bash command, a test suite, a browser or a phone simulator (point 13). Our comparison target is the code.claude.com documentation as of 2026-11-08; current docs below always means that date.
Boris Cherny: point 13, the verification loop · Claude Code docs: Best practices
2. The 13 points mapped to current docs, mechanism type and file
This table is the index for the rest of the article. The mechanism column follows the best-practices definition: model-decided means Claude reads the instruction and chooses; harness-enforced means Claude Code applies it regardless. The same goal often exists in both forms. A passing typecheck before finishing can be a CLAUDE.md line (model-decided) or a Stop hook (harness-enforced), and the docs’ advice is that a CLAUDE.md line you keep emphasizing belongs in a hook.
| Point | Thread (2026-01) | Current docs (2026-11-08) | Mechanism | File or command |
|---|---|---|---|---|
| 1 | 5 local sessions in parallel, numbered tabs, system notifications | Terminal config: Ghostty, Kitty and iTerm2 can show desktop notifications; for parallel work give each session its own worktree (claude -w) | Tooling, not model behaviour | claude -w feature-x; terminal notification settings |
| 2 | 5–10 cloud sessions; hand off with an ampersand; --teleport back | Cloud sessions page: --cloud starts a new cloud task; --teleport pulls a cloud session into the terminal; the CLI cannot push an existing local session to the cloud (the ampersand handoff is thread-only) | Tooling | claude --cloud ...; claude --teleport |
| 3 | Opus 4.5 with thinking for everything | Model config: Opus 5.5 at medium effort is the default on most plans; adjust with /effort, not prompt wording | Model-decided (effort sets how much it thinks) | /model; /effort high |
| 4 | One shared CLAUDE.md in git, add a note on every mistake | Memory page: keep CLAUDE.md under 200 lines; write only what the repo does not show; /init, /doctor, /doctor prompt-audit | Model-decided | CLAUDE.md; .claude/rules/*.md |
| 5 | Tag Claude on PRs to update CLAUDE.md via the GitHub Action | GitHub Actions page: /install-github-app installs the app and workflow; mention @claude in a PR or issue comment (the thread says /install-github-action) | Model-decided (the Action runs deterministically, the text is model-written) | /install-github-app; .github/workflows/claude.yml |
| 6 | Start in plan mode (Shift+Tab twice), then auto-accept edits | Permission modes: interactive sessions start in auto mode; Shift+Tab cycles auto → default → acceptEdits → plan; or prefix a prompt with /plan; approving the plan picks the next mode | Model-decided plan; edits blocked by the harness while planning | Shift+Tab; /plan; claude --permission-mode plan |
| 7 | A slash command per inner-loop workflow in .claude/commands/ | Skills page: custom commands merged into skills; .claude/commands/*.md still works; new form .claude/skills/<name>/SKILL.md with optional disable-model-invocation | Model-decided (who may invoke it is configurable) | .claude/skills/verify-app/SKILL.md |
| 8 | Subagents code-simplifier and verify-app | Sub-agents page: .claude/agents/<name>.md with name, description, tools, model and more; the tools list is harness-enforced | Mixed: delegation is model-decided, tool scope is enforced | .claude/agents/code-simplifier.md |
| 9 | PostToolUse hook formats code | Hooks and best-practices pages: matcher Edit|Write, command reads .tool_input.file_path; optional onFailure block | Harness-enforced | .claude/settings.json hooks.PostToolUse |
| 10 | No --dangerously-skip-permissions; /permissions pre-allows, shared settings.json | Permissions page: allow, ask and deny rules; deny holds in every mode; allow rules in the shared file wait for each person’s trust dialog | Harness-enforced | .claude/settings.json permissions |
| 11 | Slack MCP in .mcp.json; bq CLI; Sentry | Best practices: prefer a CLI when one exists; otherwise claude mcp add --transport http; disable unused servers in /mcp | Tooling | claude mcp add ...; .mcp.json |
| 12 | Long tasks: background agent, or Stop hook, or ralph-wiggum plugin | Hooks page: a Stop hook exits 2 to send Claude back, capped at 8 consecutive blocks, CLAUDE_CODE_STOP_HOOK_BLOCK_CAP adjustable; /goal is the built-in alternative; the ralph-wiggum plugin was not found at the repository path we checked | Stop hook enforced; /goal is judged by a model | hooks.Stop; /goal <condition> |
| 13 | Give Claude a way to verify; 2–3x quality; Chrome extension tests the UI | Best practices: give Claude something that returns pass or fail; ask for evidence (command and output, or screenshot); Chrome page: claude --chrome, needs a direct Pro, Max, Ultra, Team or Enterprise plan signed in with /login | The check is deterministic; whether Claude trusts it is model-decided; a Stop hook can enforce it | scripts/verify.sh; claude --chrome; /verify |
Claude Code docs: Best practices · Claude Code docs: Hooks reference · Claude Code docs: Subagents · Claude Code docs: Memory and CLAUDE.md · Claude Code docs: Skills (slash-commands redirects here) · Claude Code docs: Chrome integration · Claude Code docs: Permission modes · Claude Code docs: Permission rules · Claude Code docs: Cloud sessions (--cloud and --teleport) · Claude Code docs: GitHub Actions · Claude Code docs: Terminal configuration and notifications · Claude Code docs: /goal · Claude Code docs: Model configuration
Three rows disagree with the thread and are worth remembering. First, the command is now /install-github-app, not /install-github-action. Second, the ampersand handoff of a local session to the web has no counterpart in the cloud-sessions page, which states that CLI handoff is one-way: --teleport pulls a cloud session into your terminal, --cloud creates a new cloud task, and only the desktop app can send a local session to the cloud. Third, the plugins directory of anthropics/claude-code held only a README when we looked, so the location of the ralph-wiggum plugin is unconfirmed; this article mentions it as described in the thread and gives no install steps.
Claude Code docs: Cloud sessions (--cloud and --teleport) · Claude Code docs: GitHub Actions
3. The verification loop: plan, implement, verify, evidence, review
Join points 6, 9, 12 and 13 and you get one loop. Plan mode settles what to build and what counts as done. After approval Claude implements in acceptEdits or auto mode. Every edit is formatted by the PostToolUse hook. When Claude tries to finish, the Stop hook runs the typecheck or tests and, on failure, hands the compiler output back so Claude keeps working. When it passes, Claude presents evidence: the commands it ran, their exit codes and output, or a browser screenshot. Finally someone who did not write the code reviews it, either a fresh subagent started by /code-review or another engineer.
Which steps are deterministic? The formatter hook and the Stop hook are run by the harness; test and typecheck results come from the compiler and the test runner, not from the model’s memory; and plan mode’s refusal to edit source files is enforced by the harness as well. Whether the plan is sound, whether the evidence is sufficient and whether review findings are accepted remain judgments by the model or a person. When you design the loop, put the few steps that may never be skipped on the deterministic side and leave the rest to the model.
The best-practices page is blunt about evidence: the sentence all tests pass carries almost no information; read the command and its output, and for a session you did not watch it is the only evidence you have. The verify.sh script in section 8 exists for this step. It writes each check’s exit code, duration and log path into a timestamped Markdown file, so Claude, the Stop hook and the reviewer quote the same document.
- Plan mode: read the code, propose, agree on the definition of done (Shift+Tab or /plan)
- Approve the plan → switch to acceptEdits or auto; Claude implements
- After every Edit/Write the PostToolUse hook formats the file (harness-enforced)
- Claude runs the check command listed in CLAUDE.md, reads the output, fixes until it passes
- Claude tries to stop → the Stop hook runs tsc or verify.sh; exit 2 sends it back (harness-enforced, 8 consecutive blocks cap)
- Pass → evidence: commands, exit codes, log paths, screenshots (scripts/verify.sh writes .claude/evidence/)
- Independent review: a fresh /code-review subagent or another engineer reads the evidence against the plan
- A person approves the merge; branch protection is the last deterministic gate
Claude Code docs: Best practices · Claude Code docs: Hooks reference · Claude Code docs: Permission modes
4. CLAUDE.md: shared, grown from mistakes, kept short
Point 4 survives in the memory and best-practices pages with two limits attached. Length: the memory page targets under 200 lines per CLAUDE.md file, because longer files cost context and reduce adherence; rules that matter only for one part of the tree go into .claude/rules/ files with a paths: front matter so they load only when Claude touches matching files. Content: write only what Claude cannot read from the repository, such as a decision made in a meeting, a deploy process that lives in one head, the environment variable the integration tests need, and anything you have corrected twice. Architecture and directory layout do not belong there; Claude reads the repo itself.
Claude Code docs: Best practices · Claude Code docs: Memory and CLAUDE.md
Adding a line whenever Claude slips still works, but the docs are clear about its ceiling: CLAUDE.md is non-deterministic, and however strongly a line is worded, following it remains Claude’s call. If a rule keeps getting missed after bold text and IMPORTANT, either the file is long enough to bury it or the rule allows no exceptions, in which case it belongs in a hook or a deny rule. The sample below follows those rules. Its last block, the definition of done, serves the evidence requirement of section 3; it raises the odds that Claude shows evidence, while the enforcement lives in the Stop hook.
# Commands
- Install: pnpm install
- Typecheck: pnpm tsc --noEmit
- Run one test file: pnpm vitest run path/to/file.test.ts
- Full verification with evidence file: bash scripts/verify.sh
# Conventions
- Use the error helpers in src/lib/errors.ts; never throw raw strings
- src/legacy/ is still live, but do not copy its patterns into new code
# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
- src/gen/ is generated (2026-10-30: edited by hand once); run pnpm gen instead
# Definition of done
- Before saying a task is complete, show the command you ran and its output,
or the screenshot. "Tests pass" without output does not count.Three commands maintain it. /init drafts a file from the codebase and suggests improvements rather than overwriting an existing one; /doctor proposes cuts for anything Claude can work out from the code; /doctor prompt-audit flags instructions written for older models, pointing at files that no longer exist, or contradicting each other. In a session, /context all confirms the file was loaded. Point 5, letting Claude amend CLAUDE.md during PR review, relies on the GitHub Action: the current install command is /install-github-app, which installs the GitHub App, stores the authentication secret, pushes a branch with the workflow files and opens a pull request; once merged, mentioning @claude in an issue or PR comment triggers it. The output of that step is text the model wrote, so whether it lands in CLAUDE.md is still a human review decision.
Claude Code docs: Best practices · Claude Code docs: Memory and CLAUDE.md · Claude Code docs: GitHub Actions
5. Plan mode, permission rules and two hooks in one settings.json
Point 6 says Shift+Tab twice for plan mode, which was the count from the manual default of January 2026. The permission-modes page now states that from Claude Code v2.1.283 interactive terminal and VS Code sessions start in auto mode, where a classifier model reviews risky actions instead of you; from auto, Shift+Tab goes to default (manual), then acceptEdits, then plan. Prefixing one prompt with /plan or starting with claude --permission-mode plan is quicker. In plan mode Claude reads files, runs exploratory commands and writes a plan but cannot edit source, and the harness guarantees that; when you approve the plan you choose the mode that follows, which is the thread’s switch to auto-accepting edits.
Point 10 is intact in the permissions page: allow rules pre-approve, ask rules force a prompt, and deny rules hold in every mode including auto and bypassPermissions. Two edges matter. A deny on Read(./.env) also stops cat .env, because Claude Code recognizes common file-reading commands, but not a script that opens the file; and a WebFetch domain deny does nothing about curl unless the sandbox is on. The best-practices page adds that auto mode’s classifier is a judgment call, not a hard rule, so your never rules belong in deny rules or hooks. The thread’s avoidance of --dangerously-skip-permissions matches the current docs, which reserve bypassPermissions for disposable containers.
Claude Code docs: Best practices · Claude Code docs: Permission rules · Claude Code docs: Permission modes
{
"permissions": {
"allow": [
"Bash(pnpm tsc --noEmit)",
"Bash(pnpm vitest run *)",
"Bash(bash scripts/verify.sh)",
"Bash(git status *)",
"Bash(git diff *)"
],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\""
}
]
}
],
"Stop": [
{
"hooks": [
{ "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
]
}
]
}
}The two hooks are points 9 and 12. The PostToolUse matcher is Edit|Write, and the command pulls .tool_input.file_path from the JSON on stdin with jq and hands it to Prettier; the docs note that a file rewritten by a Bash command or an outside process does not trigger this hook, for which the FileChanged event exists. The Stop hook contract is exit code 2 to block the stop, with stderr returned to Claude as the reason it cannot finish, which is why the example redirects the compiler output there. The hooks page adds two safety valves: after eight consecutive Stop blocks with no tool call in between, Claude Code overrides the next block and ends the turn (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP raises the cap), and the input field stop_hook_active is true when the turn is already a hook continuation, so scripts should read it to avoid looping on a condition that can never hold.
Claude Code docs: Hooks reference · Claude Code docs: Best practices
What if the hook itself breaks? By default a hook that fails or times out lets the action proceed and leaves an error notice. For a security hook you can set onFailure: block so a hook that cannot even start still blocks the action; but the hooks page warns that on Stop events a block sends Claude back to work, and Claude cannot repair a hook that will not run, so the example leaves it off the Stop hook. Keep the best-practices reminder in mind too: the enforced set should stay small, and at forty rules most are probably preferences the model could have weighed itself.
Claude Code docs: Hooks reference · Claude Code docs: Best practices
| File or location | Applies to | Put here | Note |
|---|---|---|---|
| ~/.claude/settings.json | You, every project on this machine | Theme, default model, personal allow rules, autoMode config | The autoMode block works only here; the classifier ignores it in project settings |
| .claude/settings.local.json | You, this project only | Personal overrides; where Yes, and don’t ask again is saved | Claude Code adds it to git excludes when it creates the file; gitignore it yourself if hand-made |
| .claude/settings.json | Everyone in the folder | Team allow/ask/deny, hooks, plugins, env vars | Deny applies at once; allow rules and hooks wait for each person’s trust dialog |
| Managed settings (managed-settings.json and others) | Everyone the organization deploys it to | Security policy, compliance | No personal file can override it; the only place for a security team’s policy |
| CLAUDE.md | Everyone in the folder | Commands, conventions, gotchas, team decisions | Non-deterministic; under 200 lines |
| CLAUDE.local.md | You, this project only | Preferences, local URLs, test data | Gitignored; loads alongside CLAUDE.md |
| .claude/rules/*.md | Everyone, but only for matching paths | Rules for one directory or file type | paths: front matter controls loading |
| .claude/skills/, .claude/agents/ | Everyone | Multi-step procedures, subagent definitions | Skills can set disable-model-invocation; a subagent’s tools list is harness-enforced |
Claude Code docs: Settings files and precedence · Claude Code docs: Best practices · Claude Code docs: Memory and CLAUDE.md · Claude Code docs: Subagents · Claude Code docs: Skills (slash-commands redirects here)
6. Slash commands became skills; subagents gained front matter
Point 7 keeps commands in .claude/commands/. On 2026-11-08 the slash-commands documentation URL resolves to the skills page, which opens by saying custom commands have merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, old files keep working, and the new form adds a directory for supporting files, front matter and control over who invokes it. For an inner-loop workflow with side effects or a long runtime, the docs suggest disable-model-invocation: true, so it runs only when you type /verify-app and Claude cannot start it on its own. $ARGUMENTS is replaced by whatever you type after the command.
The verify-app below corresponds to the subagent in point 8 that held end-to-end test instructions, but we wrote it as a skill rather than a subagent because it needs to drive the browser in the current session and hand the evidence back. allowed-tools applies only for the turn that invokes it and pre-approves verify.sh and reading the evidence file. The content asks Claude to record what it did, what it expected and what it saw at every step, and forbids saying works without evidence. Note that the skills page lists a bundled /verify that builds and runs your app to confirm a change; when no recipe is recorded it writes the steps that worked to .claude/skills/verify/SKILL.md, and a recorded skill at the repository root replaces the bundled one, so avoid the bare name verify for your own skill.
---
name: verify-app
description: End-to-end check of the web app after a change. Runs the evidence script, drives the changed flow in the browser and reports what was seen. Use before opening a PR.
disable-model-invocation: true
argument-hint: [flow-name]
allowed-tools: Bash(bash scripts/verify.sh) Read
---
1. Run `bash scripts/verify.sh`, then read .claude/evidence/latest.md.
If any step shows a non-zero exit code, stop and report it.
2. Start the app with the command from CLAUDE.md and open it in the
connected browser (http://localhost:3000).
3. Exercise the flow named in $ARGUMENTS: the happy path, one invalid
input, one empty state.
4. For each step write down what you did, what you expected, what you saw.
Take a screenshot of the final state.
5. Report: commands with exit codes, the evidence file path, screenshot
paths, and every mismatch against the plan. Never write "works" without
attaching the evidence.Subagents are one Markdown file each under .claude/agents/ for the project (committed) or ~/.claude/agents/ for yourself. The current sub-agents page lists the front matter: name and description are required; tools, disallowedTools, model, permissionMode, maxTurns, skills, memory, isolation and others are optional. The tools field is deterministic: a subagent given Read, Grep, Glob is a reviewer that cannot edit, and Claude Code enforces that limit rather than a prompt requesting it. The thread’s code-simplifier needs to change files and run checks, so the sample grants Edit and Bash; model: inherit keeps the main session’s model. Whether the main session delegates to it is decided by Claude from the description, and you can also name it in a prompt.
---
name: code-simplifier
description: Simplifies code that was just written without changing behaviour. Use after the implementation passes its tests and before review.
tools: Read, Grep, Glob, Edit, Bash
model: inherit
---
You are cleaning up a diff you did not write. Work only on files changed
since the base branch: `git diff --name-only main...HEAD`.
- Remove dead code, duplicated helpers and abstraction layers used once.
- Keep public interfaces and observable behaviour identical. Add no features.
- After each file, run `pnpm tsc --noEmit` and the test file for that module.
- Finish with a table: file, lines before, lines after, commands run and
their exit codes. If a check fails, revert that file and say so.A cost note from the best-practices page: every subagent request counts against your usage, and a fresh subagent first gathers context your conversation already had, so it can be slower; handing the same task to a subagent does not produce a smarter answer, only parallelism, long output kept out of the main conversation, and a pair of eyes that did not watch the reasoning. Set model: haiku for simple jobs and check /usage for what each subagent type costs.
Claude Code docs: Best practices · Claude Code docs: Subagents
7. Verification differs by domain: which check, what evidence, who enforces
The core of point 13 is not the Chrome extension but giving Claude something that returns pass or fail. The best-practices page lists test files, a build’s exit code, a linter, a script that diffs output against a fixture, and a browser screenshot next to the mockup, and says that if the repo already has one, the single most useful CLAUDE.md line is the command that runs it. Strictness comes in four levels: in the prompt (Claude decides when it is satisfied), as a /goal (a separate model checks the condition after every turn, useful for long background runs), as a Stop hook (harness-enforced until it passes or the cap is hit), and by someone who did not write the code (/code-review in a fresh subagent).
| Domain | Check | Evidence | Who enforces |
|---|---|---|---|
| Library / pure logic | Unit tests, typecheck, lint | Command, exit code, names of failing cases | Toolchain judges; Stop hook can guarantee the run |
| CLI tool | One bash command against expected output; diff a fixture | Command and stdout/stderr excerpt | Script exit code; Stop hook |
| Web UI | Chrome integration opens the local page, fills forms, reads the console; /verify builds and runs | Screenshots, console error list, step notes | Model drives the browser; a person reads the screenshots |
| Mobile app | Run in a simulator, as the thread describes; no dedicated docs page found | Screenshots, build log | Model-decided; depends on your toolchain |
| Data / scripts | Re-run on fixed input, compare output hash or row count | Output hash, row counts, diff | Script judges; can live in verify.sh |
| Long unattended run | /goal condition plus Stop hook plus --max-turns | Evidence file plus PR description | /goal judged by a model; hook and turn cap by the harness |
Claude Code docs: Best practices · Claude Code docs: Chrome integration · Claude Code docs: Skills (slash-commands redirects here) · Claude Code docs: /goal
Chrome deserves its own prerequisite check. The current Chrome page requires Chrome, Edge or another Chromium browser with the Claude in Chrome extension 1.0.36 or later; a direct Anthropic Pro, Max, Ultra, Team or Enterprise plan signed in with /login, because with an API key or a long-lived token the integration stays off; no third-party cloud providers; and no WSL. You start with claude --chrome or set Enabled by default in /chrome, with the warning that always-on browser tools increase context use. Claude pauses at login pages and CAPTCHAs and asks you to handle them. From the thread’s habit of testing every claude.ai/code change, what you can copy is having Claude open the page on localhost, walk the changed flow, read console errors and take screenshots; what you cannot copy is the other team’s test content.
At every level, ask for evidence. The best-practices page says, in substance, that all tests pass tells you very little, that reading the output is faster than rerunning the check, and that for a session you did not watch it is the only evidence you have. It also gives a counter-intuitive review tip: tell the reviewer to skip style, because a reviewer asked to find problems always finds something, and fixing every finding piles up abstraction layers and tests for cases that cannot happen.
8. The evidence script: one file for Claude, the Stop hook and the reviewer
verify.sh below is this article’s own example; it passed bash -n offline and was not run in a real project. It runs the typecheck, the tests and the build in turn, writes each step’s exit code, duration and log path into .claude/evidence/ under a timestamped .md name, points latest.md at the newest file, and finally prints the whole file to stderr, so that used as a Stop hook (bash scripts/verify.sh || exit 2) the reason Claude sees for not being allowed to finish is the evidence itself. The CLAUDE.md sample and the verify-app skill reference the same command, so all three quote one output.
Claude Code docs: Best practices · Claude Code docs: Hooks reference
#!/usr/bin/env bash
# scripts/verify.sh - run the project's checks and write an evidence file
# that Claude, a Stop hook and a human reviewer can all quote.
set -u
OUT_DIR=".claude/evidence"; mkdir -p "$OUT_DIR"
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
OUT="$OUT_DIR/$STAMP.md"
status=0
run() { # run <label> <command...>
local label="$1"; shift
local start; start=$(date +%s)
local rc=0
"$@" >"$OUT_DIR/$label.log" 2>&1 || rc=$?
printf -- '- %s: exit %s, %ss, log %s/%s.log\n' \
"$label" "$rc" "$(( $(date +%s) - start ))" "$OUT_DIR" "$label" >>"$OUT"
[ "$rc" -ne 0 ] && status=1
return 0
}
{
echo "# Verification evidence $STAMP"
echo "- commit: $(git rev-parse --short HEAD 2>/dev/null || echo none)"
echo "- changed files: $(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')"
} >"$OUT"
run typecheck pnpm tsc --noEmit
run tests pnpm vitest run
run build pnpm build
echo "- overall: $([ "$status" -eq 0 ] && echo PASS || echo FAIL)" >>"$OUT"
ln -sfn "$STAMP.md" "$OUT_DIR/latest.md"
cat "$OUT" >&2 # stderr, so "bash scripts/verify.sh || exit 2" works as a Stop hook
exit "$status"Three trade-offs. Whether to hang the whole script on Stop: running the full tests and build every time Claude wants to finish can be slow, so the settings.json in section 5 runs only tsc on Stop and leaves the full script to the skill or the prompt; if your suite takes a minute or two, hanging it all on Stop is fine. The script deliberately ignores stop_hook_active because it recomputes everything and has no condition that can never hold; if your check depends on an outside service, read the JSON on stdin at the top and exit 0 when stop_hook_active is true and the failure repeats, handing the problem back to a person. And whether to commit the evidence directory: gitignore it and paste latest.md into the PR description, or every run becomes commit noise.
Keep the roles apart when combining the script with CLAUDE.md. CLAUDE.md tells Claude the command exists, and Claude will usually run it after finishing; the Stop hook guarantees it ran and passed at least once before the turn ends; the evidence file lets a person check without rerunning. That is why the best-practices page keeps the typecheck line in CLAUDE.md to just the command: the command is for the model, the enforcement is for the hook.
9. What changed between January and November
Points 1, 2, 3 and 11 are mostly environment and tool choices, and they need updating before you copy them. Opus 4.5 with thinking was the author’s choice at the time; the model-config page now lists Opus 5.5 at medium effort as the default on most plans and providers, and the best-practices page makes effort the main control for how long Claude thinks, with phrases like think hard being ordinary prompt text. The thread’s reasoning, that a bigger model needing less steering is faster overall, still stands; the model name should come from /model. For parallel sessions the docs now recommend a worktree per session (claude -w feature-x) to avoid colliding edits, and the terminal-config page says Ghostty, Kitty and iTerm2 can show desktop notifications, with iTerm2 needing its alert settings turned on first.
Claude Code docs: Model configuration · Claude Code docs: Best practices · Claude Code docs: Terminal configuration and notifications
| Thread (2026-01) | Docs on 2026-11-08 | What it means for a team |
|---|---|---|
| Opus 4.5 with thinking | Default Opus 5.5 at medium effort; /effort adjusts | Do not hard-code a model name in CLAUDE.md; use /effort, not prompt wording |
| Shift+Tab twice for plan mode | Sessions start in auto; three presses from auto, or /plan | Write /plan in your docs |
| Ampersand hands a local session to the web | CLI handoff is one-way: --cloud creates, --teleport pulls back; the desktop app can send a local session | The ampersand handoff is thread-only; document the current commands |
| .claude/commands/ for slash commands | Merged into skills; old files work; new form is SKILL.md | Write new workflows as skills and control who invokes them |
| /install-github-action | /install-github-app | Command renamed |
| No --dangerously-skip-permissions | Still exists; docs limit it to disposable containers | Same stance; deny rules still apply in that mode |
| ralph-wiggum plugin | Not found at the repository path we checked | Do not install from the thread; confirm the source first |
| Background agent verifies long tasks | Subagents run in the background by default; /goal is the built-in alternative | Prefer /goal or a Stop hook for long tasks |
Claude Code docs: Model configuration · Claude Code docs: Permission modes · Claude Code docs: Cloud sessions (--cloud and --teleport) · Claude Code docs: Skills (slash-commands redirects here) · Claude Code docs: GitHub Actions · Claude Code docs: Hooks reference · Claude Code docs: Subagents · Claude Code docs: /goal
Point 11’s principle is unchanged: prefer a CLI when one exists, since with gh installed and signed in Claude opens pull requests and reads reviews without explanation; for systems without a CLI use MCP with claude mcp add --transport http followed by a name and the server URL, after which the server appears under /mcp. The best-practices page adds a cost note: connected servers add their tool names and instructions to the context even when unused, so turn off the ones you do not need. Sharing the Slack configuration through .mcp.json as the thread does is consistent with this; keep credentials in environment variables rather than in the file.
10. Reproducing it in a team within a week: order and acceptance
Order the work by dependency and start with what tests can confirm. The sequence assumes the repository already has a test or typecheck command; if not, add one command that returns pass or fail first, because every later step hangs on it. Each step says how to confirm it took effect, and every confirmation method comes from the current docs.
- Day 1: write CLAUDE.md from the section 4 template with only commands, conventions, gotchas and a definition of done; let /init draft it, then cut to under 200 lines; confirm with /context all and read /doctor’s suggestions.
- Day 2: commit the permissions part of .claude/settings.json; have every member accept the trust dialog for the folder, or the allow rules stay inert; inspect the effective rules with /permissions and ask Claude to read .env to confirm the refusal.
- Day 3: add the PostToolUse formatter hook; ask Claude to add a badly indented line to a file Prettier handles and confirm the saved file comes back fixed; list registered hooks with /hooks.
- Day 4: add scripts/verify.sh and the Stop hook (tsc only at first); ask Claude for a change that breaks a type and confirm it receives the compiler errors and keeps working instead of stopping; if the eight-block cap appears, the condition itself is wrong.
- Day 5: add the verify-app skill and the code-simplifier subagent; run /verify-app <flow> once and check the evidence file and screenshots; have Claude call code-simplifier and inspect the exit codes it reports.
- Weekly: move repeated review corrections into CLAUDE.md (or let the GitHub Action do it); run /doctor prompt-audit monthly; when the enforced set passes a dozen rules, ask which are really preferences.
Claude Code docs: Best practices · Claude Code docs: Hooks reference · Claude Code docs: Memory and CLAUDE.md · Claude Code docs: Skills (slash-commands redirects here) · Claude Code docs: Permission rules
One acceptance criterion is enough: for any change Claude completed, a reviewer can see from the PR description or the evidence file what was run, with which exit codes and which screenshots, without rerunning a command. When that holds, the loop from point 13 exists. The two-to-three-times quality claim is the author’s experience; we had no way to reproduce the factor and did not try.
What we did not verify: we did not run Claude Code, so we did not observe the eight-block Stop cap, the PostToolUse trigger timing or the Chrome integration in practice; we did not confirm the current location of the ralph-wiggum plugin; the ampersand handoff of a local session to the web has no counterpart in the current docs and we cannot say whether it still works; the view counts are readings from 2026-11-08; the two-to-three-times quality improvement is the author’s personal experience and was not reproduced. This article analyzes Anthropic’s public documentation and one engineer’s public thread; this site is not affiliated with Anthropic. The related articles below cover unattended boundaries, the account-email User-Agent incident and the researcher usage report.