Claude 代码应随附的验证线束
Comin' in Hot! Shipping multiple unstable releases per day at the moment. If you want prove_it to actually work, email Justin for updates
If you experience errors after an upgrade, reset your setup with prove_it reinstall && prove_it reinit.
By far the most frustrating thing about Claude Code is its penchant for prematurely declaring success. Out-of-the-box, Claude will happily announce a task is complete. But has it run the tests? No. Did it add any tests? No. Did it run the code? Also no.
prove_it hooks into Claude Code's lifecycle events and runs whatever tasks you configure—test suites, lint scripts, AI code reviewers—blocking Claude until they pass.
(And in case it's not obvious, prove_it currently only works with Claude Code.)
brew install searlsco/tap/prove_it
prove_it install
cd your-project && prove_it initRestart Claude Code and you're live.
prove_it is a config-driven framework for enforcing quality in Claude Code sessions. You can easily configure script and subagent tasks in a few lines of JSON that:
prove_it signal done), or when Claude gets caught in a doom loop (prove_it signal stuck --message "can't figure out Liquid Glass")when: { sourcesModifiedSinceLastRun: true })Out of the box, prove_it init generates the Searls-stack of configured tasks:
./script/test_fast and blocks until it passes./script/test when Claude signals done (and source files were edited)prove-coverage subagent fires in the background after 541+ net lines of churn, enforced on the next stopprove-done subagent runs a thorough pre-ship review when Claude signals doneprove-approach subagent runs when Claude signals stuck, surfacing alternative approaches./script/test (Claude commits only — human commits pass through)Every one of these is a config entry you can change, disable, or replace. The framework supports any combination of lifecycle events, conditions, and task types — the default config is just a starting point.
# Install the CLI
brew install searlsco/tap/prove_it
# Register prove_it hooks in ~/.claude/settings.json
prove_it installcd your-project
prove_it initThis interactively sets up .claude/prove_it/config.json, creates script/test and script/test_fast stubs if you don't have them, installs git hooks, and generates a starter .claude/rules/testing.md. Restart Claude Code and you're live.
Pass flags to skip prompts (useful for CI or scripting):
prove_it init --git-hooks --default-checks| Flag | Default | Effect |
|---|---|---|
--[no-]git-hooks |
on | Install git pre-commit/pre-push hooks |
--[no-]default-checks |
on | Include AI coverage review, pre-ship review |
--[no-]automatic-git-hook-merge |
off | Merge with existing git hooks (fails if hooks exist) |
--[no-]overwrite |
— | Overwrite customized config with current defaults |
By default, prove_it looks for two test scripts by convention:
| Script | Purpose | When it runs |
|---|---|---|
script/test |
Full test suite (units, integration, linters, etc.) | Before every git commit |
script/test_fast |
Fast unit tests only | Every time Claude stops work |
For example, your script/test_fast script might run:
#!/usr/bin/env bash
set -e
trap 'rc=$?; command -v prove_it >/dev/null 2>&1 && prove_it record --name fast-tests --result $rc' EXIT
rake testAnd your full script/test command will probably run that and more:
#!/usr/bin/env bash
set -e
trap 'rc=$?; command -v prove_it >/dev/null 2>&1 && prove_it record --name full-tests --result $rc' EXIT
rake test standard:fix test:systemThe trap ... EXIT pattern ensures results are always recorded, even when set -e causes early exit. prove_it uses this to skip re-running tests when code hasn't changed.
prove_it record options:
--result —record pass (N=0) or fail (N!=0), exit with code N (best for traps)--pass / --fail—record explicitly (exit 0 / exit 1)--name —must match the task name in your configprove_it is configured with a hooks object in .claude/prove_it/config.json. Hooks are keyed by type (claude, git) then by event (Stop, PreToolUse, SessionStart, pre-commit, pre-push, etc.), with each event mapping to an ordered list of tasks:
{
"enabled": true,
"sources": ["src/**/*.js", "lib/**/*.js", "test/**/*.js"],
"tests": ["test/**/*.test.js"],
"hooks": {
"claude": {
"Stop": [
{ "name": "fast-tests", "type": "script", "command": "./script/test_fast" },
{ "name": "coverage-review", "type": "agent", "prompt": "Check coverage...\n\n{{session_diff}}" }
]
}
}
}Config files merge (later overrides earlier):
~/.claude/prove_it/config.json—global defaults.claude/prove_it/config.json—project config (commit this).claude/prove_it/config.local.json—local overrides (gitignored, per-developer)Hooks merge by task name: a task in a descendant config with the same name as one in an ancestor fully replaces the ancestor's task; a task with a new name is appended. Global tasks run first (most general to most specific). Other array fields (like sources) replace rather than merge.
sources defines which files prove_it considers "your code" — these globs drive conditions like sourcesModifiedSinceLastRun, sourceFilesEdited, and linesChanged. Test files should be included in sources so that edits to tests are tracked as source changes.
tests identifies which source files are test files. This drives the test-first check, which enforces red-green TDD by tracking whether Claude writes and runs failing tests before implementing source code. See Session phases for how enforcement varies by activity. tests is typically a subset of sources — it doesn't need to be disjoint.
Both sources and tests are preserved across prove_it init / reinit when customized, so you won't lose your globs on upgrade.
Claude events:
| Event | Purpose | Behavior |
|---|---|---|
SessionStart |
Environment setup, injecting context | Non-blocking. All tasks run. Output is injected into Claude's context. Use this to inject prompts, announce project state, set environment variables, or run setup scripts. |
PreToolUse |
Guarding tool usage | Blocking, fail-fast. Tasks run in order; the first failure denies the tool and stops. Use this for config protection, enforcing workflows, or vetting commands. |
Stop |
Verifying completed work | Blocking, fail-fast. Tasks run in order; the first failure sends Claude back to fix it. Put cheap tasks first (test suite), expensive ones last (AI reviewer). Async results are harvested before sync tasks run. |
PostToolUse |
Observing tool results | Non-blocking. Fires after a tool succeeds. Used by TDD enforcement to detect test passes. Matcher filters by tool name. |
PostToolUseFailure |
Observing tool failures | Non-blocking. Fires after a tool fails. Used by TDD enforcement to detect test failures. Matcher filters by tool name. |
Git events:
| Event | Purpose | Behavior |
|---|---|---|
pre-commit |
Validating before commit | Blocking, fail-fast. Runs only under Claude Code (CLAUDECODE env var)—human commits pass through instantly. |
pre-push |
Validating before push | Blocking, fail-fast. Same as pre-commit but triggers on push. |
script—runs a shell command, fails on non-zero exitagent—sends a prompt to an AI reviewer, expects PASS/FAIL response (see Agent tasks)env—runs a command that outputs environment variables, injected into Claude's session (SessionStart only, see Env tasks)params)Script tasks accept a params object that is passed to the script as input.params in the stdin JSON payload:
{
"name": "lock-config",
"type": "script",
"command": "$(prove_it prefix)/libexec/guard-config",
"quiet": true,
"params": {
"paths": [".claude/prove_it/config.json", ".claude/prove_it/config.local.json"]
}
}Scripts read params from the parsed stdin JSON alongside tool_name, tool_input, etc. This is a generic mechanism—any script can use params to accept structured configuration without inventing CLI arg parsing.
guard-config with custom paths: The built-in guard-config script uses params.paths to decide which file paths to block. Add your own paths to guard additional files:
{
"name": "lock-config",
"type": "script",
"command": "$(prove_it prefix)/libexec/guard-config",
"quiet": true,
"params": {
"paths": [".claude/prove_it/config.json", ".claude/prove_it/config.local.json", ".env", "credentials/**"]
}
}When params.paths is omitted, guard-config falls back to blocking prove_it config files by default (backward compatible).
Tasks can include a briefing field — a string that's injected into every SessionStart orientation. This lets infrastructure tasks (like TDD enforcement) provide persistent guidance without being SessionStart tasks themselves.
{
"name": "my-task",
"type": "script",
"command": "./my-script",
"briefing": "Remember to frobnicate the widgets before shipping."
}Set enabled: false on a task to skip it without removing it from config:
{ "name": "slow-review", "type": "agent", "prompt": "prove-coverage",
"promptType": "skill", "enabled": false }Disabled tasks are logged as SKIP with reason "Disabled".
Set quiet: true on a task to suppress all log outp
暂无开放 Issues,或尚未同步最近议题。