The Guardrails File — Claude Code CLAUDE.md
The standing rules an autonomous coding agent becomes — scope, git discipline, secrets, workspace hygiene, context management, testing, stopping conditions, and cost control. Claude Code auto-loads it from the project root, so you don't run it, you install it.
The configuration
Create your own on ClaudeDrop this in your project root as CLAUDE.md. Claude Code auto-loads it at every session start, so the rules apply to every run without being pasted.
# CLAUDE.md — Universal Guardrails
Behavioral rules live here. Mechanical enforcement (force-push, protected-branch
pushes, bulk `git add`, recursive deletes, `.env` writes, and the test/lint/type
gate) is installed per project as hooks generated at kickoff; those rules are
intentionally not restated here. See the hooks bundle in the framework.
## Scope & Execution
- Work exclusively within this project directory. Never operate outside it.
- Follow ROADMAP.md phases in order. Do only the current phase.
- Out-of-scope ideas, refactors, or "while I'm here" fixes → log to BACKLOG.md, do not implement.
- Don't ask clarifying questions. Make reasonable decisions and log them in DECISIONS.md.
## Environment
- Windows 11. No crontab, no Linux-only tooling, no POSIX paths in shell commands.
- Scheduled tasks → Windows Task Scheduler via scripts/jobs/setup_task_scheduler.ps1.
- Python venv: `.venv/Scripts/python.exe`. Forward slashes in Python, backslashes in PowerShell/cmd.
- Use `uv` for Python dependency and environment management.
## Git Workflow
- Feature branch per phase. Commit after each completed phase with a message referencing it.
- Stage files explicitly after confirming .gitignore is correct.
- (Force-push, protected-branch, and bulk-add blocks are enforced by the guard hook.)
## Secrets
- Never hardcode API keys, tokens, or credentials. Read from environment variables only.
- A new secret means add its name to `.env.example` (no value) and document it in README.
- (Writes to .env files are blocked by the guard hook.)
## Filesystem Safety
- Read a file before overwriting it. Never blind-write over existing work.
- No operations outside the project directory, ever.
- (Recursive deletes are blocked by the guard hook unless the path is allowlisted.)
## Workspace Discipline
- Working docs live in `.dev/` (gitignored): PROJECT.md, ROADMAP.md, INITIAL_INSTRUCTIONS.md, DECISIONS.md, UPDATES.md, BACKLOG.md, api_usage.jsonl, and any BLOCKED.md or BUDGET_EXCEEDED.md.
- Diagnostics and debug scripts → `.dev/scratch/`, cleared when the phase no longer needs them.
- A diagnostic reached for a second time graduates to `.dev/toolkit/` with a docstring and a `.dev/toolkit/README.md` entry.
- The repo holds shipped code and committed tests only.
## Context Economy
- One phase, one context. Finish the phase, write state to UPDATES.md, commit, then /clear.
- Past ~70% of the window mid-phase, checkpoint UPDATES.md and /clear rather than riding into auto-compaction.
- Run exploration and diagnosis in subagents so only summaries return to the main window.
- Large outputs go to files, not the transcript. The files are the memory, not the window.
## Dependencies
- Prefer stdlib. Justify each new dependency in DECISIONS.md (what, why, alternatives).
- Pin versions in requirements.txt / package.json. Install only into the project venv, never globally.
## Testing & Validation
- Run tests after each phase. New code requires tests before the phase is marked complete.
- "No tests exist" is not "tests pass." Write them.
- (The pre-commit hook blocks the commit on a test, lint, or type failure.)
## Documentation
- Append a dated entry to UPDATES.md after each phase: what changed, what was verified (with the actual test output or command result, not just "passed"), what's deferred.
- Update README.md whenever setup, structure, commands, or dependencies change.
- DECISIONS.md: log every non-obvious choice with date, decision, rationale, alternatives considered.
## Stopping Conditions
- 3 consecutive failed attempts at the same problem → stop, write BLOCKED.md with what was tried.
- Ambiguity that cannot be resolved from ROADMAP.md + existing code → stop, write BLOCKED.md.
- Any operation you are uncertain is safe → stop, do not proceed.
- No background processes, daemons, or non-terminating scripts without explicit instruction.
## API & Cost Discipline
- Before any paid API call, log it to api_usage.jsonl: {timestamp, api, endpoint, estimated_cost}.
- Never retry a failed API call more than twice. Never call batch/bulk endpoints without explicit per-item limits.
- Prefer cached/local results before making API calls. Per-project cost caps and API-specific limits live in PROJECT.md.
Everything else in these two libraries was designed for you to copy. These two were not designed at all — they evolved, across enough real projects to grow a changelog. Behind every Claude Code project that ships from this desk sit exactly two hand-maintained files: a guardrails file the executor becomes, and a framework document you hand the planner at the start of a build. Everything else a project needs — the roadmap, the limits, the hooks, even the prompt that starts the run — gets generated from those two. Which makes this pair the cleanest demonstration of the line these libraries are built on, running in production: the rules that must hold every time live in the installed file; the thing you say at the start fits in a single paste. The paste is just longer than you were told prompts are allowed to be.
Why it’s built this way
The header is the deepest rule in the file. Behavioral judgment lives here as prose; anything mechanically enforceable lives in generated hooks instead — because instructions erode over a long autonomous run as the context window fills, and hooks don’t. A guardrail that lives only in a prompt is a suggestion. The file governs what requires judgment; code blocks what doesn’t.
BACKLOG.md is scope discipline with a pressure valve. “While I’m here” fixes are how a two-hour phase becomes a two-day excavation. The rule doesn’t suppress the agent’s good ideas — it routes them somewhere they survive without derailing the run.
“Don’t ask clarifying questions” is the autonomy contract. This file exists for runs with nobody watching. Every ambiguity gets a reasonable decision and a paper trail in DECISIONS.md — resolved now, auditable later — instead of a run that stalls at 2am waiting for an answer.
The scratch-to-toolkit graduation is a counting rule. One-off diagnostics are disposable; the second time you reach for one, it graduates — real name, docstring, README entry. That’s a usage threshold deciding what gets maintained, applied to debug scripts. (The same logic decides what belongs in these libraries at all.)
“The files are the memory, not the window” is the context-economy section in one line. State written to disk survives; state held in the window is one auto-compaction away from gone. One phase per context, checkpoint at 70%, clear instead of riding into lossy summarization.
The stopping conditions and the two-retry rule are a ladder, not a contradiction. Fail, fail — refactor (never a third identical attempt). The refactored attempt fails too — stop, write BLOCKED.md with what was tried, and hand it up. The agent gets two swings at a problem and one redesign; after that, persistence is just an expensive way to be stuck.
api_usage.jsonl is the receipts file for machines. Log the call before making it, with an estimated cost — so the money is counted, not felt, and the morning after an overnight run holds no surprises.
Why it’s a skill: it’s the definition. Installed once, loaded automatically, applied whether or not anyone remembers it exists — with refusals (never operate outside the directory), standing limits (two retries, per-item caps), and stopping conditions that hold at hour six of an unattended run. None of that survives as a thing you say.
Make it yours
the Environment section is one person’s machine — Windows 11, uv, Task Scheduler. Swap the contents for your stack; keep the section, because an agent that doesn’t know your environment will confidently write for someone else’s. The working-doc filenames (ROADMAP.md, DECISIONS.md, and friends) are conventions, not requirements — but note the design rule they follow: this file only points at things that exist inside the project directory at runtime, where the agent can actually open them. A config may reference files it can read; it may never lean on documents it can’t.
Then what
The document that generates everything this file works alongside → The Framework. The planning discipline it encodes, as a chatbot skill → The Kickoff. Why “fail twice, then refactor” → The Two-Strike Rule.