If Claude Code has felt less capable lately — giving one-sentence answers where it used to reason through edge cases, refusing to explain its decisions, skipping the exploration you relied on — you are not imagining it, and the model has not degraded. The cause is architectural: a structural tension between Claude Code’s built-in system prompt and your project-level instructions.

How Claude Code Processes Instructions

The Instruction Hierarchy

Claude Code assembles its context from several distinct layers before generating any response. Understanding the order matters because when two layers contradict each other, position determines which one wins:

Claude Code Instruction Priority (highest → lowest)
┌──────────────────────────────────────────────────────────┐
│  1. Built-in System Prompt                               │
│     (Anthropic-controlled, injected by Claude Code CLI)  │
│     • "Lead with the answer, not the reasoning"          │
│     • "If you can say it in one sentence, don't use 3"  │
│     • "Only make changes directly requested"             │
│     • "Skip filler words, preamble, transitions"         │
├──────────────────────────────────────────────────────────┤
│  2. Session-level injected context                       │
│     (output style modes, --system-prompt flag)           │
├──────────────────────────────────────────────────────────┤
│  3. CLAUDE.md files                                      │
│     (global ~/.claude/CLAUDE.md + project CLAUDE.md)    │
│     Injected as context, NOT as system prompt            │
├──────────────────────────────────────────────────────────┤
│  4. User messages / conversation turns                   │
└──────────────────────────────────────────────────────────┘

Claude Code’s Built-In Directives

The Claude Code CLI injects a set of behavioral directives at the system-prompt level that are designed for efficiency in agentic loops. These include:

• Lead with the answer or action, not the reasoning — Claude skips the analytical preamble and gives you the result first.
• If you can say it in one sentence, don’t use three — Responses are compressed by default.
• Only make changes directly requested or clearly necessary — Claude avoids expanding scope unless instructed.
• Skip filler words, preamble, and unnecessary transitions — No “Great question!” or “Let me think through this carefully.”
• Don’t add features, refactor code, or make improvements beyond what was asked — Strict minimal-change behavior.

These exist for good reasons. In an agentic loop running 50 file edits, you want the AI to act, not narrate. For exploratory developer conversations, though, the same directives make Claude feel shallow and unhelpful.

Why CLAUDE.md “Loses” on Tone Conflicts

Positional Weight in Context Windows

CLAUDE.md files are injected into the conversation as context — not as system prompt. This distinction is not cosmetic. In transformer models, instructions injected at the system-prompt level carry stronger positional weight during attention than instructions that arrive later as context.

When two instructions conflict:

CLAUDE.md:  "Always explain your reasoning before giving an answer."
System prompt: "Lead with the answer or action, not the reasoning."

The system prompt wins. Not because Claude is ignoring your CLAUDE.md, but because the architecture resolves conflicts in favor of earlier, higher-priority injections.

This Is By Design

Anthropic designed this hierarchy intentionally. The system prompt enforces Claude Code’s core contract: be an efficient, minimal-footprint agentic tool. If any CLAUDE.md could override that contract, users could accidentally make Claude Code nondeterministic or verbose in automated pipelines where brevity is critical.

The consequence is that tone, verbosity, and reasoning-style directives in CLAUDE.md are largely ignored when they conflict with the built-in system prompt. Project-specific behavioral rules that don’t conflict — those work fine, and we’ll cover them below.

Workarounds and Solutions

Output Style Modes (System-Prompt Level)

Claude Code ships with named output style modes that are injected at the session-prompt level — above CLAUDE.md but below or alongside the core system prompt. Two modes are particularly useful:

Explanatory mode instructs Claude to provide educational insights alongside its work, explaining the reasoning behind implementation choices.

Learning mode combines interactivity with explanation, prompting Claude to involve you in meaningful decisions rather than doing everything silently.

These modes win over the brevity directives because they are injected at session-prompt level rather than CLAUDE.md level. To activate them, check your Claude Code documentation for the /output-style or equivalent command for your version.

The practical effect: with explanatory mode active, Claude will annotate its decisions, surface trade-offs, and explain why it chose a particular approach — even though the default system prompt says “don’t explain.”

The --system-prompt CLI Flag

The cleanest solution for persistent verbosity and reasoning behavior is the --system-prompt flag, which injects your directives at the highest available level (session system prompt), giving them the same weight as the built-in directives.

# Launch Claude Code with custom verbosity and reasoning directives
claude --system-prompt "When explaining code changes, describe the reasoning behind each decision. Surface edge cases and trade-offs. If multiple valid approaches exist, briefly describe them before choosing one."

# For a more structured development session
claude --system-prompt "You are helping design a production Go service. Before making any significant implementation choice, explain the alternatives considered and why you chose this approach. Flag any assumptions that could be wrong."

# Combining with project context
claude --system-prompt "Explain your reasoning on architecture decisions. This is an exploratory session, not an agentic pipeline — verbosity is appropriate." --add-dir ./

Trade-offs to consider:

The --system-prompt flag requires you to re-specify on every session start, but it gives you maximum control. Consider wrapping it in a shell alias or a Makefile target for your exploratory development workflow:

# ~/.bashrc or ~/.zshrc
alias claude-verbose='claude --system-prompt "Explain reasoning on significant decisions. Describe alternatives before choosing. Surface edge cases."'

# Or in a project Makefile
.PHONY: ai-explore
ai-explore:
	claude --system-prompt "Exploratory session: explain reasoning, describe trade-offs, flag assumptions. Not an agentic pipeline."

Targeted CLAUDE.md Improvements

CLAUDE.md is highly effective for instructions that don’t conflict with the system prompt’s tone and efficiency directives. The key distinction:

CLAUDE.md works well for — specific, additive rules about project behavior:

# Project Rules (effective in CLAUDE.md)

## Git Workflow
- Never commit directly to the main branch
- Always run `make test` before marking a task complete
- Use conventional commit format: feat/fix/chore/docs

## Kubernetes Conventions
- Use Helm chart version 3.12.x for this project
- Target namespace: production-east, not default
- ConfigMaps must use the app.kubernetes.io/managed-by: Helm label

## Code Standards
- All Go functions returning errors must be checked — no blank assignments
- Database migrations must include a rollback in the same PR
- Test files must use table-driven test patterns

## Tool Preferences
- Prefer kubectl over helm for read-only inspection
- Use dlv for Go debugging, not fmt.Println

CLAUDE.md does NOT reliably work for — tone, verbosity, and reasoning-style overrides:

# These directives are largely ineffective in CLAUDE.md:

- "Always explain your reasoning before giving an answer"   ← loses to system prompt
- "Be verbose and thorough in all responses"                ← loses to system prompt
- "Don't skip steps when explaining concepts"               ← loses to system prompt
- "Always consider edge cases even if not asked"            ← loses to system prompt

The mental model: CLAUDE.md wins on what to do, loses on how much to say and how to say it.

What CLAUDE.md Is Actually Good For

Specific Behavioral Rules That Add, Not Override

The most effective CLAUDE.md entries are specific, verifiable, and additive — they tell Claude to do something it wouldn’t do by default, rather than trying to change the character of every response.

Examples that consistently work:

## Deployment Safety
- Before suggesting any kubectl delete or helm uninstall command,
  confirm with me explicitly. These are irreversible in production.
- Never suggest force-pushing to main, origin/main, or any branch
  matching *-release.

## Testing Requirements
- Any change to a Go handler must include or update a corresponding
  _test.go file in the same directory.
- Integration tests in /tests/integration/ require the DATABASE_URL
  environment variable — remind me to set it if tests fail with a
  connection error.

## Context Preservation
- When working on the authentication subsystem, always read
  pkg/auth/middleware.go before suggesting changes.
- The Helm chart values are split across values/ — check values/base.yaml
  and values/production.yaml before assuming a value is missing.

These instructions are specific (exact file paths, exact conditions), additive (they add a check or require a file read, not change overall verbosity), and unambiguous (no subjective judgment about what counts as “thorough”).

They don’t compete with the system prompt’s efficiency directives because they’re not asking Claude to be more verbose — they’re asking Claude to take a specific action or check a specific thing before proceeding.

Putting It Together

The “Claude Code feels dumber” experience is a collision between two legitimate design goals: Anthropic’s goal of an efficient, minimal-footprint agentic tool, and developers’ need for exploratory, reasoning-visible conversations during design and debugging.

The architecture resolves that collision in favor of efficiency by default. Your CLAUDE.md can’t change that for tone and verbosity — but the --system-prompt flag and output style modes can, because they operate at the correct priority level.

The practical takeaway:

• Use --system-prompt or output style modes for exploratory sessions where you want reasoning and depth.
• Use CLAUDE.md for project-specific behavioral rules, conventions, and safety checks — things that are specific, additive, and don’t compete with tone directives.
• Treat the built-in system prompt as immutable for the purposes of CLAUDE.md design: work with the hierarchy, not against it.

The model hasn’t degraded. The architecture is just doing exactly what it was designed to do.