AI AI Tools Guidebook
Troubleshooting

Claude Code Doesn't Understand Your Project: 7 Fixes That Actually Work

Claude Code editing the wrong files, duplicating functions that exist, or missing key code? It's almost never the model — it's missing project context. Seven concrete ways to make Claude Code read your repo, verified for June 2026.

Published: Updated: Author: AI Productivity Guide Team 🌐 查看中文版本

When Claude Code performs poorly, the cause is almost never “the model isn’t smart enough.” It’s that the agent doesn’t have your project’s context, so it does what looks productive but is mostly guessing.

Fastest fix: run /init once to auto-generate a CLAUDE.md, then add the 3-5 files you care about directly to your next prompt. Those two moves fix the majority of “Claude ignores my project” complaints. The rest of this guide is the full toolkit, in ROI order.

What “no project context” looks like

  • Edits files but never opens the actual main logic file
  • Creates a function or component that already exists (reinvents the wheel)
  • Asks “where is X defined?” when it’s in your README
  • Auto-applies style changes that break your existing conventions
  • Debugs by patching symptoms instead of going to the root cause

The real reason

Each Claude Code session starts with a fresh context window. It does not auto-read your entire repo. At session start it only sees:

  1. Files you mention explicitly in the prompt
  2. CLAUDE.md files in the directory tree above your working directory (loaded in full at launch)
  3. Auto memory it has written for this repo (the first 200 lines / 25KB of MEMORY.md)
  4. Files it actively discovers via tools (Read, Grep, Glob) during the task

If 1-3 are sparse, it falls back to “guess common patterns.” Next.js? Guess app/page.tsx. Astro? Guess src/pages/. If your project is a monorepo or non-standard, every guess is wrong.

One trap worth knowing: as of June 2026, CLAUDE.md is delivered as a user message after the system prompt, not as enforced configuration. Claude reads it and tries to follow it, but vague or conflicting instructions get followed inconsistently. Specific beats aspirational every time.

Which bucket are you in?

SymptomMost likely causeGo to
Reinvents existing code, wrong file pathsNo CLAUDE.md, no files named in promptFix 1, Fix 2
Works in small repos, fails in your monorepoContext volume overrun; wrong package picked upFix 5, Fix 6 (.claude/rules/, claudeMdExcludes)
Edits generated / vendored dirsNo hard exclusionFix 4 (permissions.deny)
“It ignores my CLAUDE.md”File not loaded, or too long, or too vagueRun /memory, see FAQ
Same mistake every sessionNothing written it downFix 1 + auto memory

7 ways to give Claude Code real project context

1. Generate and refine a CLAUDE.md (highest ROI)

CLAUDE.md is the project handbook Claude reads at the start of every session. Don’t write it from scratch — run /init inside the project. Claude analyzes your codebase and creates a file with the build commands, test commands, and conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.

For a guided setup, run with CLAUDE_CODE_NEW_INIT=1 set: /init then asks which artifacts to create (CLAUDE.md, skills, hooks), explores with a subagent, and shows a reviewable proposal before writing anything.

Then refine by hand. A good CLAUDE.md contains:

  • Tech stack: frameworks, language, version, package manager
  • Directory layout: what each top-level folder is for
  • Key conventions: file naming, state management, routing, CSS approach (write them concrete: “API handlers live in src/api/handlers/”, not “keep files organized”)
  • Run / build / test commands: npm run dev, npm test
  • Local pitfalls: which directories not to touch
  • How to add a new feature / page / component: the actual steps

Two rules that matter as of June 2026:

  • Keep it under ~200 lines. Longer files consume more context and measurably reduce how reliably Claude follows them. CLAUDE.md is loaded in full regardless of length, so length is a real cost.
  • Write specific, verifiable instructions. “Run npm test before committing” works; “test your changes” doesn’t.

Anti-example: a CLAUDE.md full of “project vision / design philosophy.” Claude doesn’t need that. It needs “the 4 steps to add a new page.”

You can also place project memory at ./.claude/CLAUDE.md instead of the root, and you can stack files: ~/.claude/CLAUDE.md for personal cross-project preferences, ./CLAUDE.md committed for the team, and a gitignored ./CLAUDE.local.md for your sandbox URLs and test data. They concatenate (root-down), they don’t replace each other.

2. Name files in the prompt directly

Don’t write “fix the login bug.” Write:

Fix the bug in src/auth/login.ts. Relevant logic is also in src/auth/session.ts and src/lib/cookies.ts. Read these three files first, then propose a fix.

Naming 3-5 files lets the agent skip the “find files” phase and go straight to the real code. This is the single biggest per-prompt lever.

3. Have it scan structure first

The first time the agent enters a project, ask for a structure scan before any edits:

Run ls -la on the root and tree -L 3 -I 'node_modules|.next|dist'. Tell me what kind of project this is and where the entry points are, then begin.

This is the agent’s “boot scan.” Pair it with a confirmation step: ask it to write a one-to-two-sentence summary of the project before doing real work. If the summary is wrong, stop and correct it — that’s the cheapest possible place to catch a misread.

4. Hard-block the directories it must not touch

There are two layers, and people confuse them:

  • .claudeignore (gitignore syntax) is a soft “don’t auto-consume” hint. It keeps files out of automatic context, but as of June 2026 Claude can still reach an ignored file through an explicit Read or search. Useful for noise reduction, not for secrets.
  • permissions.deny in .claude/settings.json is a hard block — Claude gets an error when it tries to read or edit a denied path. Use this for .env, credentials, generated output, or a legacy/ dir you never want rewritten.

Example .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Edit(./generated/**)",
      "Edit(./legacy/**)"
    ]
  }
}

You can still keep human-readable red lines in CLAUDE.md (“Do NOT edit anything in node_modules/, .next/, dist/, generated/, legacy/”), but treat that as guidance, not enforcement. For anything sensitive, the permissions.deny layer is what actually holds.

5. Scope instructions per area with .claude/rules/

For larger projects, don’t cram everything into one CLAUDE.md. Put topic files in .claude/rules/ (e.g. testing.md, api-design.md, security.md). Each can be path-scoped so it only loads when Claude touches matching files:

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

# API Development Rules

- All endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Rules without a paths field load every session at the same priority as .claude/CLAUDE.md. Path-scoped rules trigger only when Claude reads a matching file, which keeps the always-on context lean.

6. For monorepos: per-package files plus claudeMdExcludes

In a monorepo, drop a CLAUDE.md in each sub-package. Files in subdirectories load on demand when Claude reads files there, so a packages/api/CLAUDE.md only costs context when Claude works inside packages/api/.

If Claude is picking up another team’s ancestor CLAUDE.md that’s irrelevant to your work, exclude it in .claude/settings.local.json:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/abs/path/monorepo/other-team/.claude/rules/**"
  ]
}

Patterns match against absolute paths with glob syntax. (Managed-policy CLAUDE.md files can’t be excluded.)

7. Give “how to add an X” checklists and navigation comments

Two cheap, durable wins.

Checklist sections in CLAUDE.md let the agent follow steps verbatim instead of inventing a new convention:

## How to add a new page

1. Create `src/content/articles/[lang]/[category]/[slug].mdx`
2. Use the schema in `src/content/config.ts`
3. Add the slug to internal links from the related category landing
4. Run `npm run audit:content` before commit

And a 3-5 line “what does this file do” header on important files helps both the agent and humans:

// auth/session.ts
// Owns session lifecycle: create, refresh, destroy.
// Reads cookies via lib/cookies.ts. Writes audit logs via lib/log.ts.
// IMPORTANT: do not call this from middleware; use auth/edge-session.ts there.

Let auto memory carry the rest

As of June 2026 (Claude Code v2.1.59+), auto memory is on by default. Claude writes its own notes per repository — build commands, debugging insights, preferences it discovers — into ~/.claude/projects/<project>/memory/MEMORY.md. The first 200 lines (or 25KB) load every session.

You don’t have to manage it, but you can: when you tell Claude “always use pnpm, not npm,” it saves that to auto memory. Run /memory to browse, edit, or delete what it has saved, or to toggle auto memory off (CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 disables it via env var). If Claude keeps repeating the same mistake, that’s the signal to either correct it (so auto memory captures the fix) or write the rule into CLAUDE.md yourself.

Shortest path

In effort order:

  1. Run /init to generate a CLAUDE.md, then trim it to under 200 lines
  2. Name the files in every prompt (3-5 paths)
  3. Add permissions.deny for dirs Claude must never touch
  4. Add navigation comments to key files
  5. For monorepos, per-package CLAUDE.md + .claude/rules/

Steps 1 and 2 alone give immediate, large improvement.

How to confirm it’s fixed

  1. Run /memory and check that your CLAUDE.md (and any CLAUDE.local.md) appears in the loaded list. If a file isn’t listed, Claude can’t see it — it’s in the wrong location or has a typo.
  2. Run /context to see the token breakdown by category (system prompt, tools, memory files, messages, free space). Confirm “Memory files” is non-zero and that you still have meaningful free space.
  3. Ask Claude to summarize the project structure in two sentences and name the entry points. A correct summary means the context landed.
  4. Re-run the task that failed. If it now opens the right files first and stops reinventing existing code, the context was the problem.

When it isn’t a context problem

  • Your project is genuinely messy — even a new human can’t follow it. Refactor first.
  • Same prompt works in a small project but fails in your large monorepo. Context volume is overrunning; check /context and split with .claude/rules/.
  • Agent keeps re-trying the same file. It didn’t get the real path; paste the exact path.
  • Repo has zero documentation. Run /init and add the missing facts.

Easy misjudgments

  • “Claude got dumber.” Your project got bigger. Claude Code can’t read a million lines at once — feed it on demand.
  • “It ignores CLAUDE.md.” Check the filename casing and location with /memory. Remember CLAUDE.md is guidance, not enforcement; for must-run steps use a hook instead.
  • “It hallucinates code.” Usually it didn’t see the real code and was forced to invent. Name the files.
  • “It can’t use tools.” Your prompt didn’t ask it to scan; tell it to tree / grep first.

FAQ

Q: How long should CLAUDE.md be? A: Target under 200 lines. Anthropic’s own docs note that longer files consume more context and reduce how reliably Claude follows them. Order it: tech stack → directories → key commands → “do not” → “how to add new things.” If it’s growing, move detail into .claude/rules/ instead.

Q: CLAUDE.md vs. README — which? A: CLAUDE.md is the agent’s handbook; README is for humans. Content can overlap, but CLAUDE.md emphasizes “what the agent should do.” If you already keep an AGENTS.md for other tools, create a CLAUDE.md with @AGENTS.md at the top so both read the same source — Claude reads CLAUDE.md, not AGENTS.md.

Q: How do I import other files into CLAUDE.md? A: Use @path/to/file.md anywhere in the file (relative or absolute paths; recursion is allowed up to four hops). Imported files still load into context at launch, so it’s for organization, not for saving tokens. To mention a path without importing it, wrap it in backticks.

Q: Does .claudeignore actually stop Claude from reading a file? A: No. As of June 2026 it’s a soft “don’t auto-consume” hint; Claude can still open an ignored file via an explicit read or search. For a real block (secrets, credentials), use permissions.deny in .claude/settings.json.

Q: Can I make Claude Code read the entire project at once? A: Only for small projects. The default context window is 200K tokens (1M on certain plans), so for medium-to-large repos let it read on demand rather than dumping everything in. Use /context to watch usage.

Q: How do I know it has the right context? A: Run /memory to confirm files loaded, /context to see the token breakdown, then ask Claude to summarize the structure before real work. Wrong summary → stop and correct.

External references: Claude Code memory docs and the context window guide.

Tags: #Claude #Claude Code #AI coding #Debug

Related Articles