What happens when you stop adding rules to CLAUDE.md and start building infrastructure instead
TL;DR Highlight
When CLAUDE.md exceeds 100 lines, rule compliance actually drops. This practitioner's guide shows how to migrate from rule files to environment-based infrastructure — hooks, skill files, and campaign files.
Who Should Read
Developers using Claude Code or Claude agents for coding workflow automation. Directly useful if your CLAUDE.md keeps growing and you feel Claude is ignoring your instructions.
Core Mechanics
- CLAUDE.md compliance drops sharply past 100 lines. The author audited their 190-line file and found 40% was duplicate, with contradictory and outdated rules mixed in. Trimming to 123 lines immediately improved compliance.
- The real fix isn't file trimming — it's shifting 'where enforcement happens.' Instead of a rule saying 'always run typecheck,' replace it with a lifecycle hook that auto-runs typecheck on file save. Claude has zero choice in the matter.
- Domain knowledge that was repeatedly explained gets split into skill files (markdown). The agent loads only the skill relevant to the current task, so unused skills cost zero tokens. Things like code review processes that got re-explained every session belong here.
- Context loss between sessions is solved with campaign files. These track what was built, what decisions were made, and what's left in a structured document, eliminating the need to re-explain from scratch when resuming the next day.
- Infrastructure maturity is defined in 5 levels: 1) Raw prompting → 2) CLAUDE.md → 3) Skills (modular expertise) → 4) Hooks (environment-enforced quality) → 5) Orchestration (parallel agents, campaigns). Most projects are fine at Level 2-3.
- The author refined this system through 27 documented failures running 198 agents on a 668K-line codebase and open-sourced it as Citadel. A single /do command auto-routes tasks to the appropriate orchestration level.
Evidence
- Compliance immediately improved after trimming CLAUDE.md from 190 to 123 lines. Removing 40% duplicates and contradictory rules was key.
- After introducing a 'typecheck auto-run on file save' hook, review time dropped significantly. By PR review time, type errors and broken imports were already resolved — only intent and design needed review.
- The system was built through 27 documented failures running 198 agents on a 668K-line real codebase. Each rule derives from something actually breaking.
- Specific hook examples suggest active use: auto-saving state just before session context compaction, and a circuit breaker that terminates agents after 3 consecutive failures on the same issue.
How to Apply
- Open your CLAUDE.md right now and audit it. Find rules that repeat similar things, contradict each other, or are no longer valid. Target under 100 lines — keep only project conventions, tech stack, and your top 5 rules.
- If a rule keeps getting violated, move it from a rule to an environment enforcement. For example, replace 'run lint' rules with pre-save hook scripts, and separate code review processes into dedicated skill markdown files.
- Clone the Citadel repo (https://github.com/SethGammon/Citadel) and reference its skill system, hooks, and campaign file structure. Even without adopting the full system, borrowing just the campaign file pattern immediately reduces cross-session context loss.
Terminology
CLAUDE.mdA config file placed at project root for Claude Code. Claude reads it at session start to learn project conventions and instructions. Like a CONTRIBUTING.md but for AI agents.
lifecycle hookA script that auto-executes when specific events occur (file save, session end, etc.). Like Git's pre-commit hook — runs even if the developer or agent forgets.
context compactionClaude's automatic compression/summarization of earlier conversation content when conversations get long. Important work state or decisions can be lost in this process.
circuit breakerA pattern that automatically stops agent execution when the same problem repeatedly fails. Used to prevent resource waste from infinite loops or repeated failures.