5 CLAUDE.md Rules That Made My AI Stop Asking and Start Doing

#ai #productivity #claudecode #devtools

After months of running Claude Code autonomously, I've learned that most of the interruptions aren't the AI's fault. They're the CLAUDE.md's fault.

Here are 5 rules that eliminated most of my "should I do X?" questions.

1. The irreversibility rule (not the uncertainty rule)

What most CLAUDE.mds say:

"Ask for clarification when uncertain."

What actually works:

"Ask only for: irreversible actions, external credentials, external visibility (publishing, sending emails), costs beyond the subscription."

The difference is significant. Uncertainty is constant — every decision has unknowns. Irreversibility is rare — most code changes can be reverted with git reset.

When I switched from "ask when uncertain" to "ask only when irreversible," the question count dropped by about 80%.

2. Explicit decision framework for common forks

What most CLAUDE.mds say:

"Use your judgment."

What actually works:

| Situation | Action |
|-----------|--------|
| Technical approach unclear | Choose the conventional approach |
| Two valid implementations | Choose the simpler one |
| Error after 3 attempts | Document in blocked.md, switch tasks |
| Ambiguous requirement | Apply most reasonable interpretation, document assumption |

The AI already has good judgment. The table isn't teaching it to think — it's eliminating the meta-question of "should I ask or should I decide?" By stating explicitly that "unclear approach → conventional approach," that decision is pre-made.

3. The pending_for_human.md pattern

What stops most workflows: A step that requires browser authentication, or a credential I don't have. Without a clear protocol, the AI either loops on it or silently skips it.

What works:

"If blocked: document blocker in pending_for_human.md, switch to next available task."

The format I use:

## 2026-02-28: Smithery API key needed
**Why blocked**: Smithery MCP registry requires authentication
**Steps for human**:
1. Go to smithery.ai/account/api-keys
2. Create API key, add to ~/.credentials
**Everything else done**: smithery.yaml added to repo, package published to npm

The key is the last line: "everything else done." The human opens this file in the morning and sees exactly one click they need to do.

4. Explicit syntax check commands

What most CLAUDE.mds say:

"Make sure the code works."

What actually works:

"After every edit: Python → python -m py_compile <file>. TypeScript → tsc --noEmit. Do not move to the next file before fixing errors in the current one."

The "do not move to the next file" part is what matters. Without it, the AI writes 5 files, runs the build, finds 3 errors spread across all of them, and has to context-switch back to each one. With it, each file is clean before the next one starts.

This is the same reason you do git add -p instead of git add ..

5. Context compression protocol

What kills autonomous sessions: Running out of context window mid-task and starting over.

What works:

"When context gets large: write current state to tasks/mission.md. Include: what's done, what's next, what's blocked, any open questions. The next session should be able to continue from tasks/mission.md without reading the full history."

The mission.md should be written as if explaining to someone who knows the project but wasn't in the room. Not a transcript. Not a summary. A briefing.

This creates a natural "checkpoint" that makes context compaction safe.

What these have in common

All 5 rules do the same thing: convert vague expectations into specific protocols.

"Use judgment" forces a meta-decision. "Choose the simpler one" eliminates it. Every meta-decision costs context window and interruption. Eliminating meta-decisions is what makes autonomous operation actually work.

The hooks and templates I run in production are open source: claude-code-hooks — 16 hooks + 6 templates from 700+ hours of autonomous operation.

📖 Claude Code Production Guide (¥800) — lessons from 700+ hours of autonomous operation.

Is your Claude Code setup actually safe? Run npx cc-health-check — a free 20-point diagnostic. Score below 80? The Claude Code Ops Kit fixes everything in one command.

What's in your CLAUDE.md that you wish you'd added earlier?