◉CLAUDE LABJP
●FORK — Claude Code 2.1.212 changes what /fork does: it copies your conversation into a new background session with its own row in claude agents, so you can keep working. The old in-session subagent is now /subtask●LIMITS — WebSearch calls are now capped at 200 per session by default, and subagent spawns get the same 200 ceiling, so a runaway search or delegation loop stops on its own●MCPBG — MCP tool calls running past two minutes now move to the background automatically, keeping the session usable. Tune the threshold with CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS●PLANFIX — Fixed plan mode auto-running file-modifying Bash commands such as touch and rm without a permission prompt or an SDK canUseTool callback●SONNET5 — Claude Sonnet 5 is running on introductory pricing of $2 per million input tokens and $10 per million output. After August 31 it moves to $3 and $15●IPO — Bankers are reportedly lining up investor meetings for Anthropic ahead of a possible public listing as soon as October●FORK — Claude Code 2.1.212 changes what /fork does: it copies your conversation into a new background session with its own row in claude agents, so you can keep working. The old in-session subagent is now /subtask●LIMITS — WebSearch calls are now capped at 200 per session by default, and subagent spawns get the same 200 ceiling, so a runaway search or delegation loop stops on its own●MCPBG — MCP tool calls running past two minutes now move to the background automatically, keeping the session usable. Tune the threshold with CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS●PLANFIX — Fixed plan mode auto-running file-modifying Bash commands such as touch and rm without a permission prompt or an SDK canUseTool callback●SONNET5 — Claude Sonnet 5 is running on introductory pricing of $2 per million input tokens and $10 per million output. After August 31 it moves to $3 and $15●IPO — Bankers are reportedly lining up investor meetings for Anthropic ahead of a possible public listing as soon as October
Articles/Claude Code
⟐ Claude Code/2026-04-12Beginner

CLAUDE.md Not Working? A Complete Troubleshooting Guide for Claude Code

Claude Code ignoring your CLAUDE.md settings? This guide covers the most common causes — wrong file location, formatting issues, conflicting configs, and more — with clear fixes for each.

CLAUDE.md2Claude Code197troubleshooting87configuration6customization4

CLAUDE.md Isn't Working — What's Going On?

One of the most common frustrations for Claude Code users is setting up a CLAUDE.md file, only to find that Claude Code seems to completely ignore it. Coding conventions get skipped, project-specific instructions are forgotten, and it feels like all that effort writing the file was wasted.

The good news is that this is almost always caused by one of a handful of fixable issues. This guide walks through each one systematically.

Common symptoms include:

  • Coding conventions you defined aren't being followed
  • Project-specific instructions (library names, naming conventions, etc.) are ignored
  • Settings don't carry over between sessions
  • Global and project-level settings seem to conflict with each other

Let's work through the most common causes in order of frequency.

Cause 1: CLAUDE.md Is in the Wrong Location

This is the single most common cause. CLAUDE.md must be placed in the root of the directory where you launch Claude Code. Here are the most frequent mistakes:

# ❌ Common mistakes
~/Projects/my-app/src/CLAUDE.md        # placed inside src/
~/Projects/my-app/docs/CLAUDE.md       # placed inside docs/
~/Projects/my-app/.claude/CLAUDE.md    # placed in .claude/ (that's for config, not CLAUDE.md)
 
# ✅ Correct placement
~/Projects/my-app/CLAUDE.md            # project root

You can quickly verify this with:

# Run this in the directory where you launch Claude Code
ls -la | grep CLAUDE
# → If CLAUDE.md shows up, you're good

If you launch Claude Code with cd ~/Projects/my-app && claude, then CLAUDE.md must live at ~/Projects/my-app/CLAUDE.md. If you're running from a subdirectory, either place a CLAUDE.md there or change your working directory when starting Claude Code.

Cause 2: Instructions Are Too Vague or Poorly Formatted

Even a correctly placed CLAUDE.md can fail to produce results if the instructions aren't written in a way Claude Code can act on clearly.

What works well:

## Coding Conventions
- Use TypeScript only (no plain JavaScript)
- Function names must use camelCase (e.g., getUserData)
- Write comments in English
- Always wrap async calls in try-catch with proper error messages
 
## Off-limits
- No console.log statements in commits
- No use of the `any` type
- No implementation without corresponding tests
 
## Project Context
This is a Next.js 15 + TypeScript + Supabase SaaS application.
All utility functions should live in src/lib/.

What doesn't work as well:

Please write clean code. Use TypeScript. Handle errors properly.
Make sure to write tests too.

The difference is specificity. Use bullet points, section headers, and concrete examples. Declarative statements ("use X", "don't use Y") work much better than vague suggestions.

Also keep an eye on file size. When CLAUDE.md gets too long, it consumes a significant portion of the context window and important instructions near the bottom may get less attention. Aim for under 500 lines, putting your most critical instructions at the top.

Cause 3: Global and Project Settings Are Conflicting

There are three levels of CLAUDE.md configuration:

  • Global (~/.claude/CLAUDE.md): Applies to all projects
  • Project ({project-root}/CLAUDE.md): Applies to this project only
  • Subdirectory ({subdirectory}/CLAUDE.md): Layered on top when working in that subdirectory

Problems arise when global and project-level settings contradict each other. For example, if your global CLAUDE.md says "write comments in English" and your project CLAUDE.md says "write comments in Japanese," the behavior can be unpredictable.

# Check your global settings
cat ~/.claude/CLAUDE.md
 
# Check your project settings
cat ./CLAUDE.md

The safest approach is to keep your global CLAUDE.md minimal — just broad preferences that apply everywhere — and put all project-specific instructions in the project-level CLAUDE.md. This avoids conflicts and makes your setup easier to reason about.

Cause 4: You Edited CLAUDE.md Without Restarting Claude Code

If you edit CLAUDE.md while a Claude Code session is already running, the changes won't be picked up until you restart. CLAUDE.md is read when the session begins.

The fix is straightforward:

# After editing CLAUDE.md, restart Claude Code
exit
 
# Then start a new session
claude

Alternatively, the /clear command within a session may trigger a context reset that re-reads CLAUDE.md, depending on your version of Claude Code. However, restarting the session is the most reliable way to ensure changes take effect.

Cause 5: Context Compaction Is Diluting Your Instructions

During long sessions, Claude Code automatically compacts older parts of the context window when it fills up. While CLAUDE.md content is generally preserved, instructions from the beginning of a long session can gradually carry less weight as the session grows.

Here's how to handle this:

# Ask Claude Code to re-read your instructions mid-session
# Type this in the Claude Code prompt:
# "Please review the CLAUDE.md instructions and apply them going forward."
 
# Or use /compact to manually trigger context cleanup
/compact
 
# Start a fresh session to reset everything cleanly
/new

Placing your most critical instructions at the top of CLAUDE.md helps ensure they survive compaction and remain prominent throughout the session.

Quick Diagnostic Checklist

Run through these steps in order when CLAUDE.md doesn't seem to be working:

Step 1: Confirm the file exists in the right place

ls -la $(pwd)/CLAUDE.md
# → File not found? Create it or move it to the current directory

Step 2: Review the content

cat CLAUDE.md | head -50
# → Check that key instructions are near the top

Step 3: Check for global setting conflicts

cat ~/.claude/CLAUDE.md 2>/dev/null || echo "No global CLAUDE.md found"
# → Look for anything that contradicts your project settings

Step 4: Restart Claude Code

# After any CLAUDE.md edit, restart the session
exit && claude

Following these steps in order resolves the issue in the vast majority of cases.

Looking back

When CLAUDE.md doesn't seem to be working, the cause usually falls into one of five categories: wrong file location, vague or poorly formatted instructions, conflicts between global and project settings, not restarting after edits, or context compaction during long sessions.

Work through the diagnostic checklist above and you'll identify the culprit quickly in most cases. Getting CLAUDE.md right pays dividends over the lifetime of a project — Claude Code will consistently follow your conventions without you having to repeat them in every prompt.

For a deeper look at what you can put in CLAUDE.md and how to structure it well, check out the CLAUDE.md and AGENTS.md Complete Guide.

Share

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

⟐ Claude Code2026-05-11
Claude Code MCP Server Won't Start — How to Fix "spawn npx ENOENT" and PATH Issues
You configured an MCP server in Claude Code's settings.json, but it never starts — just "spawn npx ENOENT" or "spawn uvx ENOENT" errors. The culprit is a PATH mismatch between your shell and Claude Code's spawning environment. Here's how to diagnose and fix it.
⟐ Claude Code2026-03-27
Claude Code Statusline — Displaying Rate Limits and Building Custom Scripts
Learn how to customize Claude Code's statusline to display real-time rate_limits usage. Covers settings.json configuration, custom script creation, and community tools for monitoring your usage.
⟐ Claude Code2026-03-20
Claude Code Output Styles Guide — Customize Responses to Maximize Development Efficiency
Master Claude Code's output styles feature. Learn how to use built-in styles, create custom styles, and distribute team-wide configurations through plugins to transform your AI pair programming experience.
📚RECOMMENDED BOOKS
Build a Large Language Model (From Scratch)
Sebastian Raschka
LLM Dev
Prompt Engineering for LLMs
Berryman & Ziegler
Prompting
AI Engineering
Chip Huyen
AI Eng
* Contains affiliate links
See all →