scope-guard — Claude Code hook: what it does, how to install
A Claude Code hook that warns when files outside a specification scope are modified.
npx claude-code-templates@latest --hook quality-gates/scope-guardWhat scope-guard does
The hook tracks which files the assistant modifies and compares them against project specifications. If a .spec.md document includes a 'Files to Create/Modify' section, the script inspects Git changes against that declared list.
Any edited files outside the declared scope trigger a non-blocking warning. The hook does not interrupt the workflow completely. It also ignores documentation, test files, configuration files, and infrastructure files on its own.
The underlying script runs as a Stop hook at .claude/hooks/scope-guard.sh. A working Git repository is required, because the script depends on Git to detect changed files.
What it helps with
- keep the AI agent within files declared in the task specification
- catch accidental edits made outside the intended scope
- prevent scope creep during spec-driven development runs
Example prompts for the agent
- Implement the feature according to auth.spec.md
- Check if modified files match the scope defined in task.spec.md
How to install scope-guard
1claude-code-templates
npx claude-code-templates@latest --hook quality-gates/scope-guard2Manually: put the files in place
.claude/settings.jsonThe hooks block: event (PreToolUse, PostToolUse, Stop…) → command. Personal ones go to ~/.claude/settings.json
Step by step, with commands for each platform: Claude Code hooks: what they are, where to configure them, how to block a risky command
Questions about scope-guard
How to install scope-guard in Claude Code?
Run npx claude-code-templates@latest --hook quality-gates/scope-guard in your terminal. This command places the script in .claude/hooks/scope-guard.sh and updates .claude/settings.json.
What does scope-guard do?
It compares Git-modified files with the 'Files to Create/Modify' section in your .spec.md specification. If any unlisted files were touched, it prints a warning.
Does scope-guard block Claude Code from finishing?
No, the warning is non-blocking. The hook also ignores tests, documentation, config files, and infrastructure changes automatically.
Source text
scope-guard.json · MIT
{
"description": "Scope guard that detects files modified outside the declared scope of a specification. When a .spec.md file contains a 'Files to Create/Modify' section, this hook compares git-modified files against the declared list. Files outside scope trigger a warning (non-blocking). Automatically excludes test files, config files, infrastructure files, and documentation. Essential for Spec-Driven Development to prevent scope creep during implementation.",
"supportingFiles": [
{
"source": "scope-guard.sh",
"destination": ".claude/hooks/scope-guard.sh",
"executable": true
}
],
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scope-guard.sh"
}
]
}
]
}
}
© davila7 · MIT · davila7/claude-code-templates
