[FEATURE] Compaction-protected Rulebook — standing behavioral rules as a counterpart to Skills

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code has Skills for reusable task procedures and CLAUDE.md for project context — but there's no mechanism for standing behavioral rules that must persist unconditionally through compaction.

CLAUDE.md serves well as a flexible, session-adaptive instruction file. It participates in conversation context, can be influenced by dialogue ("let's switch to TypeScript for this session"), and is designed for continuity within a single session. This flexibility is its strength.

But some instructions aren't meant to flex:

• "All work starts from a GitHub issue — no commit without an issue number"
• "Never use var in JavaScript"
• "Follow conventional commits format"
• "Run tests before creating a PR"

These are standing rules, not session context. They don't change through dialogue — if you want to change them, you edit the rulebook file itself. Yet today, they must live in CLAUDE.md, where they compete with conversation history for context space and degrade through compaction.

The workaround is re-injecting rules via hooks every turn (UserPromptSubmit), but this:

• Wastes tokens on repeated injection
• Is unavailable in Cowork/Desktop (no hook support)
• Adds setup complexity to every project

Proposed Solution

Introduce a Rulebook — a compaction-protected instruction layer that complements Skills:

| Concept | Purpose | Invocation | Persistence | Mutable during session? |
|---------|---------|-----------|-------------|------------------------|
| Skills | Task procedures ("how to do X") | On demand / implicit match | Normal | N/A |
| Rulebook 🆕 | Standing behavioral rules ("what principles to always follow") | Always active | Compaction-protected | No — edit the file to change |
| CLAUDE.md | Project context, preferences, flexible guidance | Always loaded | Re-injected after compaction | Yes — adapts through dialogue within a session |

Key design constraints:

1. Trust priority stays at CLAUDE.md level (user-provided). Rulebook content must NOT be elevated to system prompt trust level. Prompt injection in a rulebook is handled the same way as in CLAUDE.md. This is a critical difference from proposals that inject user content into the system prompt.

1. Persistence is protected. During compaction, rulebook content is excluded from summarization and re-injected verbatim. Only conversation history is compressed.

1. Immutable during session. Unlike CLAUDE.md, which can be influenced by dialogue, rulebook content is fixed for the session duration. To change rules, edit the rulebook file and start a new session (or trigger a reload).

1. Distributable. Rulebooks can be packaged and shared — similar to how Skills are distributed via plugins. Teams can version and share behavioral policies.

Implementation could be as simple as:

• Recognize files in .claude/rulebook/ (or a single .claude/RULEBOOK.md)
• At compaction time, exclude rulebook content from the summarization input
• Re-inject rulebook verbatim alongside the compacted conversation summary
• No model/API changes required — this is purely a harness-level feature

Alternative Solutions

• Hook-based re-injection (current workaround): Works in Claude Code CLI but unavailable in Cowork/Desktop. Wastes tokens by re-injecting every turn. Adds project setup complexity.
• Larger context windows: Delays the problem but doesn't solve it. Compaction still happens eventually.
• Keeping CLAUDE.md short: Mitigation, not a solution. Rules still degrade over long sessions.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

1. A team maintains a rulebook with workflow policies: "All work starts from a GitHub issue," "No commit without issue number," "PR titles follow conventional commits"
2. A developer installs the team's rulebook package into their project
3. In a 3-hour coding session with multiple compactions, the rules persist at full fidelity — no degradation, no re-injection overhead
4. A teammate suggests changing the commit format → they update the rulebook file, not the conversation. The change takes effect in the next session
5. CLAUDE.md continues to hold flexible, in-session context: "We're focusing on the auth module today," "Use the staging API endpoint" — things that naturally evolve through dialogue within the current session

Additional Context

Related issues (similar problem space, different approaches):

• #34716 — [INVARIANT.md] Proposes injecting user content at the system prompt trust level. This solves persistence but changes the trust boundary — user-provided content gains system-level authority, which has prompt injection implications. Our proposal keeps trust at CLAUDE.md level and only elevates persistence. Complementary problem analysis, fundamentally different solution.
• #29760 — [Two-Tier Context Architecture] Proposes the agent autonomously promoting important information to a persistent tier. This is an agent intelligence feature. Our proposal is about user-declared standing rules — the user decides what's immutable, not the AI. Different mechanism, different ownership model.
• #11629 — CLAUDE.md Persistence Through Context Compression Cycles
• #34556 — Persistent Memory Across Context Compactions

The architectural gap: Claude Code currently has mechanisms for "how to do things" (Skills) and "flexible project context" (CLAUDE.md), but no mechanism for "what principles to always follow" (Rulebook). This three-part separation — procedures, context, and rules — would provide a complete foundation for harness engineering.

The distinction matters because Skills and Rulebooks serve fundamentally different cognitive roles: Skills are invoked to execute a procedure, while Rulebooks are internalized as standing behavioral constraints. An AI that "follows a skill" is executing steps; an AI that "follows a rulebook" is exhibiting consistent character and judgment.