RC-401h · Module 3

CLAUDE.md as the Top-Level Prompt System Controller

5 min read

DRILL's CC track covers Claude Code integration from a practitioner perspective. This lesson covers it from the prompt systems architecture perspective: CLAUDE.md is not a README. It is the top-level controller of your Claude Code prompt system — the document that governs what Claude knows, how it behaves, what it is permitted to do, and what it must never do across every session in your project.

Every statement in CLAUDE.md is a prompt. The Session Startup section is a prompt that shapes Claude's opening context. The Autonomy section is a prompt that defines permission boundaries. The Gotchas section is a prompt that prevents known failure modes. The Commands section is a prompt that establishes the available action vocabulary. CLAUDE.md is a multi-section prompt system in a single file — and like every other prompt system, it needs the same engineering discipline: versioning, scope definition, and regression testing.

Do This

  • Structure CLAUDE.md as a layered document: always-read (universal) vs. on-demand (task-specific)
  • Define explicit permission boundaries in the Autonomy section — what Claude may do without asking
  • Maintain a Gotchas section that documents known failure modes and their prevention
  • Version CLAUDE.md in git and review changes with the same rigor as application code changes
  • Keep CLAUDE.md DRY by routing detailed standards to linked files — don't duplicate content from SIGNAL-STANDARDS.md inline

Avoid This

  • Use CLAUDE.md as a stream-of-consciousness project log that nobody prunes
  • Leave permission boundaries undefined — "use your judgment" is not an Autonomy policy
  • Duplicate the same instructions in CLAUDE.md and in skills files, creating conflicting sources of truth
  • Treat CLAUDE.md as a one-time setup document that never needs maintenance as the project evolves

The architecture principle for CLAUDE.md is: universal context that applies to every session belongs in CLAUDE.md. Task-specific context belongs in skills files loaded on demand. This separation keeps the always-loaded context lean — minimizing token overhead on every session — while making task-specific context available without loading it when it is not needed. DRILL enforces this in the CC track. The PM track formalizes it here: the always-read / on-demand boundary is a prompt architecture decision with real token-budget implications at production volume.

Change management for CLAUDE.md follows the same library registration process as any other production prompt. A change to CLAUDE.md is a change to the top-level controller. Before merging, run the subset of your regression suite that covers Claude Code sessions — verify that the sessions that worked before the change still work after it, and that the intent of the change is reflected in session behavior. No cowboy CLAUDE.md edits in production.

  1. Audit CLAUDE.md Against the Prompt Systems Checklist Review your current CLAUDE.md with fresh eyes: Is the always-read / on-demand boundary clearly defined? Are permission boundaries explicit? Is the Gotchas section current and actionable? Are there any inline instructions that should be extracted to a skills file? Complete this audit before building on top of the current CLAUDE.md — technical debt in the top-level controller multiplies across every session.
  2. Define the CLAUDE.md Change Gate Establish a change review process for CLAUDE.md: any change requires a description of what is changing and why, a review by at least one other team member, and a note in the git commit message with the specific instruction change and its intended behavioral effect. This is the documentation discipline that makes CLAUDE.md a governable system instead of a living document that nobody understands anymore.
  3. Map CLAUDE.md Sections to Prompt System Roles Annotate each section of CLAUDE.md with its prompt system role: what behavior does this section govern, who owns it, and when was it last validated? This mapping is your audit trail for the top-level controller and makes version diffs meaningful — instead of "we changed some lines in CLAUDE.md," you have "we updated the Permission Boundaries section to add Worker deploy autonomy."