How to configure Claude Code for Opus 5 and Fable 5

The best CLAUDE.md is not the one that describes your entire engineering process. It is the smallest file that stops Claude from making the same important mistakes.

That distinction matters more with Opus 5 and Fable 5. Anthropic says it removed more than 80% of Claude Code's system prompt for advanced models without a measurable loss on its coding evaluations. The lesson is not “give Claude no instructions.” It is: keep durable context small, state the real constraints clearly, and load specialized procedures only when they are needed.

A good Claude Code setup separates five kinds of information:

• Always-needed instructions go in CLAUDE.md.
• Path-specific constraints go in .claude/rules/ or a nested CLAUDE.md.
• Repeatable procedures go in skills.
• Deterministic controls go in hooks, permissions, and settings.
• Changing project state goes in a roadmap, issue, or implementation plan.

Once those layers are separated, Claude receives less noise and the instructions that remain carry more weight.

Source: Anthropic — The new rules of context engineering for Claude 5 generation models

How Claude Code loads instructions

Claude Code can read CLAUDE.md at several levels:

• Managed policy: organization-wide instructions installed by IT.
• User: ~/.claude/CLAUDE.md, applied across your projects.
• Project: ./CLAUDE.md or ./.claude/CLAUDE.md, normally committed to Git.
• Local project: ./CLAUDE.local.md, for personal project-specific preferences and normally ignored by Git.
• Nested: a CLAUDE.md inside a subdirectory, loaded when Claude reads files under that directory.

Files above the working directory are loaded in full at launch. Files below it are loaded on demand when Claude reads files in those directories.

The layers are additive. A project instruction appears later in context than a user instruction, but this is not a reliable inheritance system where every conflict resolves cleanly. Anthropic warns that when instructions contradict each other, Claude may choose one arbitrarily. Remove the conflict instead of trying to win it through repetition.

Use /context to see which instruction files loaded. /init can generate a starting project file; review it and keep only durable, non-obvious facts.

Anthropic recommends targeting fewer than 200 lines per CLAUDE.md. Treat that as a ceiling, not a goal. A dense 150-line operating manual can still be too much.

Source: Claude Code docs — How Claude remembers your project

What belongs in your user CLAUDE.md

Your user file is loaded across projects, so every line should be genuinely cross-project. Good candidates are:

• preferred response length and progress-update cadence;
• how independently Claude should make routine, reversible decisions;
• when Claude should ask rather than act;
• your normal scope and side-effect boundaries;
• stable safety or authorization rules;
• personal terminology or shorthand used across repositories;
• a compact delegation limit if your usual model delegates too readily.

Do not put project commands, framework conventions, repository architecture, current milestones, plugin inventories, temporary model-routing rules, or a complete review process here. Those details do not apply everywhere and will consume context everywhere.

A practical user file can be this small:

# Communication
- Lead with the outcome.
- Keep progress updates to important findings or changes of direction.
- Match document length to the task. Do not add filler sections or duplicate summaries.

# Autonomy and scope
- Make routine, reversible decisions independently.
- Briefly flag a material flaw or false premise, then continue with the requested task.
- Complete the task at its intended scope. Stop before unrequested external or irreversible actions.

# Authorization
- Treat commit, push, merge, deploy, publication, destructive cleanup, and credential use as separate actions unless I explicitly bundle them.

# Delegation
- Delegate only substantial, genuinely independent work. Do not create subagents for small tasks or merely to double-check your own work.

This is an example, not a universal template. Keep only rules that describe how you work and that are useful in almost every repository.

What belongs in the project CLAUDE.md

The project file should orient Claude quickly and expose the few facts it cannot safely infer from the repository.

Include:

1. Purpose

One or two sentences explaining what the repository is and what it is not.

2. Sources of truth

Point to the authoritative files for architecture, API contracts, product scope, generated code, or current plans. Use a plain path when Claude should read a large document only when relevant.

3. Exact commands

List the canonical commands and their working directory:

• focused test command;
• full test command when different;
• typecheck;
• lint or formatting check;
• build;
• one safe real-path smoke test, if the project has one.

Concrete acceptance commands are useful. Repeating “verify your work,” “double-check everything,” and “spawn a verification agent” is not.

4. A short architecture map

Name the major boundaries and where responsibilities live. Do not narrate the complete file tree.

5. Non-obvious invariants and traps

This is often the highest-value section. Examples:

• generated files must not be edited directly;
• a migration is append-only;
• a service requires a specific working directory;
• one package owns a shared schema;
• tests pass locally but need an additional runtime check;
• a seemingly unused file is loaded dynamically.

6. Definition of done

State the observable evidence that matters for this repository: named commands, generated artifacts, required review gates, or an authorized smoke test. Keep it specific and short.

A compact project file might look like this:

# Repository purpose
This service accepts billing events and writes normalized ledger entries. The public API contract lives in `docs/api-contract.md`.

# Commands
Run from the repository root:
- Focused tests: `pnpm test --filter billing`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`
- Production build: `pnpm build`

# Architecture
- `src/http/` owns request parsing and authentication.
- `src/ledger/` owns business rules and database writes.
- `packages/schema/` is the source of truth for shared event types.

# Invariants
- Do not edit files under `src/generated/`; run `pnpm generate`.
- Database migrations are append-only after merge.
- All ledger writes must remain idempotent by event ID.

# Current work and detailed procedures
- Current scope: `docs/ROADMAP.md`
- Release procedure: use the `release` skill.
- API-specific rules: `.claude/rules/api.md`

The final section is important: it points to detail without copying that detail into always-loaded context.

Nested CLAUDE.md or path-scoped rules?

Use a nested CLAUDE.md when a coherent subtree has its own local conventions. A frontend package, infrastructure directory, or mobile app inside a monorepo may each benefit from one.

Use .claude/rules/*.md when a constraint follows file patterns or cuts across several directories. A rule can use paths frontmatter:

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.test.ts"
---

# API rules
- Validate external input with the shared schema package.
- Return errors through the standard API error envelope.
- Keep handlers free of direct database access.

Rules without paths load unconditionally. Path-scoped rules load when Claude reads matching files, which keeps unrelated instructions out of the session.

A useful split is:

• Nested CLAUDE.md: conventions owned by one directory or subsystem.
• Path-scoped rule: a constraint tied to file types or patterns across the repository.

Source: Claude Code docs — CLAUDE.md and .claude/rules/

Use skills for procedures

A skill is the right home for a reusable workflow such as:

• reviewing a pull request;
• investigating a production incident;
• publishing a release;
• performing a database migration;
• running a security review;
• generating a particular artifact.

Team-shared project skills live inside the repository at <repo>/.claude/skills/<skill-name>/SKILL.md. Commit them to Git so everyone using the repository gets the same workflow. Personal cross-project skills live at ~/.claude/skills/<skill-name>/SKILL.md.

Each skill is a directory with a required SKILL.md. Put a specific description in YAML frontmatter, followed by the Markdown instructions. Scripts, templates, examples, and reference files are optional. Claude Code normally lists the skill's name and description for discovery, subject to its listing budget, then loads the full instructions when the skill is used. In a monorepo, a package can own skills under <package>/.claude/skills/; those become available after Claude reads or edits a file in that subtree.

This is real progressive disclosure. Keep a short trigger or pointer in CLAUDE.md, then put the procedure, scripts, references, templates, verification steps, and pitfalls in the skill.

Do not copy the same release checklist into the project CLAUDE.md, a skill, and a roadmap. Duplication creates drift and contradictory instructions.

Source: Claude Code docs — Extend Claude with skills

Use hooks and settings for enforcement

CLAUDE.md is context, not an enforcement mechanism. Claude reads it and tries to follow it, but Anthropic explicitly says compliance is not guaranteed.

Use hooks, permissions, or settings when the behavior must be deterministic. Good uses include:

• block a dangerous shell command before it runs;
• run a formatter after edits;
• log tool activity;
• trigger a notification when a long task finishes;
• allow or deny specific tools or command patterns;
• run a fixed validation script at a lifecycle event.

Hooks can run shell commands, HTTP requests, prompts, or subagents at defined lifecycle events. For a simple deterministic safeguard, prefer a command hook or permission rule over a paragraph asking Claude to remember the safeguard.

Hook output can still be returned to Claude, so hooks are not automatically free of context cost. Hooks reliably fire when their configured event and matcher apply. A command or HTTP handler can enforce fixed behavior; a prompt or agent hook still uses a model and can vary. That is different from hoping Claude remembers a prose rule at the right moment.

Sources: Claude Code hooks reference and Claude Code settings

Keep roadmaps and plans out of CLAUDE.md

A roadmap answers “what are we doing now?” CLAUDE.md answers “what should Claude know every time?” Those are different questions.

Put changing information in a durable project artifact such as:

• docs/ROADMAP.md for milestones and current scope;
• an issue tracker for work ownership and status;
• an implementation plan for a substantial multi-phase change;
• a handoff or checkpoint section in that plan when work must continue in a fresh context.

The project CLAUDE.md should name the authoritative artifact, not duplicate its contents. This avoids stale milestones, old task lists, obsolete commit hashes, and yesterday's decisions appearing as permanent instructions.

The same rule applies after compaction or a fresh session: point Claude to the current plan and exact next phase instead of pasting the entire history back into the prompt.

@ imports organize context; they do not defer it

CLAUDE.md supports imports such as:

See @README.md and @docs/git-instructions.md.

Imports can make a file easier to maintain, but imported content is expanded and loaded alongside the CLAUDE.md file that references it. An import does not create another on-demand boundary: when the containing instruction file loads, its imports load too.

If a large document is only occasionally useful, write its path in backticks and tell Claude when to read it. Use a skill or path-scoped rule when you need actual conditional loading.

Source: Claude Code docs — Import additional files

Let auto memory record discoveries, not policy

Claude Code also maintains auto memory: notes Claude writes from corrections, debugging discoveries, and confirmed working patterns. It is separate from CLAUDE.md and stored per repository.

Use auto memory for lessons Claude discovers while working. Use CLAUDE.md for rules you deliberately want to own and review. Do not rely on auto memory for security policy, authorization boundaries, or team standards.

Anthropic currently documents that the first 200 lines or 25 KB of auto memory load into each session. That is another reason to keep it curated rather than treating it as an activity log.

Source: Claude Code docs — Auto memory

Prompt the outcome, not every movement

For current Claude models, a strong task prompt normally defines:

• Outcome: what must exist or be true.
• Why: intent that changes trade-offs.
• Starting evidence: relevant symptoms, logs, or known state.
• References: the code, specification, design, or plan that is authoritative.
• Scope: what may change and what must not change.
• Settled decisions: choices Claude should not reopen without contradictory evidence.
• Acceptance: commands, artifacts, behavior, or review evidence that proves completion.
• Side effects: whether commit, push, deploy, publication, or destructive cleanup is authorized.
• Return: the level of detail you want in the final response.

This is a complete specification. It does not mean every prompt needs a form, nor does it mean ordered steps are always bad.

Use step-by-step instructions when order is load-bearing: migrations, incident response, regulated workflows, risky state changes, or a process that must produce complete coverage. For ordinary implementation, specify the interfaces and gates, then leave room for Claude to inspect the code and choose the route.

Anthropic's general prompting guidance still recommends numbered steps when sequence or completeness matters. The improvement is not “goals instead of steps.” It is goals and constraints by default; procedures only where the procedure carries real value.

Source: Anthropic — Prompting best practices

Calibrate for Opus 5

For Claude Code, Anthropic's Opus 5 guidance translates into four practical changes:

• Remove generic re-verification. Opus 5 self-verifies without being told. Repeated instructions to double-check, perform a final verification pass, or spawn a verifier can cause over-verification and waste tokens.
• Keep concrete acceptance criteria. Exact commands and required artifacts define what “done” means. They are different from generic reminders to check again.
• Bound delegation. Opus 5 delegates more readily than earlier models. Reserve subagents for substantial, genuinely independent work and cap fan-out where cost matters.
• Constrain scope and visible length. Opus 5 may widen narrow tasks and tends to produce longer progress updates and documents. State the intended scope, stop boundary, update cadence, and desired document length.

These instructions can be compact. Do not replace an old verification manual with a new anti-verification manual.

Source: Anthropic — Prompting Claude Opus 5

Calibrate for Fable 5

Claude Code's model guide says routine reminders to test or check are usually unnecessary because Fable 5 already verifies its work more often than smaller models. For long-running work, however, Anthropic's Fable 5 prompting guide recommends additional scaffolding:

• make periodic, specification-grounded checks explicit;
• use fresh-context verifier subagents when independent verification adds value;
• ground progress claims in real tool output;
• delegate genuinely independent tracks asynchronously;
• let long-lived subagents keep useful context;
• review inherited prompts and skills for old-model choreography that has become too prescriptive;
• define checkpoints before irreversible actions, material scope changes, or inputs only a human can provide.

Do not put this full long-run pattern into every prompt. A small Fable task does not need an autonomous-program management system. Use the extra scaffolding when the work horizon and risk justify it.

Sources: Claude Code docs — Model configuration and Anthropic — Prompting Claude Fable 5

Do not put contradictory model-specific defaults in a shared user CLAUDE.md. Keep stable preferences, scope, and authorization global; put Opus- or Fable-specific behavior in the relevant skill, workflow, or harness configuration.

A clean configuration layout

A mature repository might use this structure:

~/.claude/
├── CLAUDE.md                    # Personal cross-project preferences
├── rules/                       # Personal rules used across projects
└── skills/                      # Personal reusable workflows

project/
├── CLAUDE.md                    # Small team-shared project orientation
├── CLAUDE.local.md              # Personal project notes; gitignored
├── .claude/
│   ├── settings.json            # Shared permissions, hooks and settings
│   ├── rules/
│   │   ├── api.md               # Path-scoped API constraints
│   │   └── migrations.md        # Path-scoped migration constraints
│   └── skills/
│       ├── release/SKILL.md      # Committed team release workflow
│       └── review-pr/SKILL.md    # Committed team review workflow
├── packages/
│   └── frontend/
│       └── CLAUDE.md            # Frontend-only conventions, loaded on demand
└── docs/
    ├── ROADMAP.md                # Current milestones and status
    └── architecture.md           # Detailed reference, read when needed

The root CLAUDE.md is the index and the set of durable invariants. It is not the entire operating system.

The five-minute CLAUDE.md audit

Review each line and ask:

1. Does this apply in almost every session at this level?
2. Can Claude infer it reliably from the repository?
3. Is it current, concrete, and non-conflicting?
4. Is it an instruction, a procedure, an enforcement rule, or changing state?
5. Would removing it repeatedly cause a real mistake?

Then relocate aggressively:

• occasional procedure → skill;
• file-pattern constraint → .claude/rules/;
• subsystem convention → nested CLAUDE.md;
• deterministic block or automation → hook, permission, or setting;
• milestone, status, history, or current task → roadmap, issue, or plan;
• large optional reference → plain path pointer, loaded when needed.

Finally, run /context to confirm the intended files loaded and remove contradictions across the stack.

The practical rule

Configure Claude the way you would design a good software interface: a small stable core, clear boundaries, exact acceptance signals, and specialized capabilities loaded only when needed.

With Opus 5, trust native self-verification and control scope, delegation, and visible length. For long-running Fable 5 work, add periodic evidence-based checks and independent verification where the horizon justifies it. In either case, keep mutable project state out of permanent instructions.

A shorter CLAUDE.md is not automatically better. A more selective one usually is.