◉CLAUDE LABJP
●2.1.301 — Adds the vim % motion, LaTeX math rendering in the VS Code panel, and a retry-watchdog limit for usage-limit waits (10/15)●2.1.299 — Conversations over 200K tokens left idle about 54 minutes get compacted; MCP allow rules now match only the server they name●SONNET 4.5 — Retires on the Claude API on 11/30, 45 days left. Migrate to Sonnet 5.5●WINDOWS — Reports say hooks break silently only on Japanese-locale Windows; check the character encoding first●FAST MODE — Opus 5.5 fast mode is out of research preview and no longer needs the beta header (10/15)●NEW — I Put a Ten-Line Promise File at the To…●2.1.301 — Adds the vim % motion, LaTeX math rendering in the VS Code panel, and a retry-watchdog limit for usage-limit waits (10/15)●2.1.299 — Conversations over 200K tokens left idle about 54 minutes get compacted; MCP allow rules now match only the server they name●SONNET 4.5 — Retires on the Claude API on 11/30, 45 days left. Migrate to Sonnet 5.5●WINDOWS — Reports say hooks break silently only on Japanese-locale Windows; check the character encoding first●FAST MODE — Opus 5.5 fast mode is out of research preview and no longer needs the beta header (10/15)●NEW — I Put a Ten-Line Promise File at the To…
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.md4Claude Code264troubleshooting92configuration10customization4

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-08-25
A One-Letter Typo in settings.json Is Ignored Without a Single Warning
I diffed claude doctor output between a settings.json with misspelled keys and a correct one. There was no difference at all. Here is what actually gets validated, what slips through, and a small check that catches typos before they cost you a day.
⟐ Claude Code2026-10-12
After Moving to SPM, My App Died the Moment It Launched — Reading One dyld Line with Claude Code
Right after moving from CocoaPods to Swift Package Manager, the build passed but the app died on launch. Here is how I traced one dyld line to its cause, the fix, and how to verify it.
⟐ Claude Code2026-10-05
I Wrote "I'll Do the Commits" in CLAUDE.md. The Next Morning git log Had One More Line.
When Claude Code commits despite being told not to: undo with git reset --soft, then stop it physically with permissions.deny plus a PreToolUse hook. Covers the git -c form that deny rules let through, and how to test the hook without starting Claude Code.