The Markdown Files That Power Claude Code: A Developer's Complete Guide

The Markdown Files That Power Claude Code:
A Developer's Complete Guide

Every .md file in Claude Code's ecosystem — what it does, how it loads, and how to write it well.

Claude Code uses markdown files as its primary configuration, memory, and extensibility layer. Unlike tools that rely on JSON configs or database records, Claude Code turns plain markdown into first-class citizens of the developer experience.

The mental model is layered:

CLAUDE.md files always load in their scope — every conversation, every session

SKILL.md bodies load when a skill triggers or is invoked by the user

references/ files load only when the skill body explicitly directs Claude to them

Memory files accumulate knowledge that outlasts individual conversations

Plan files capture pre-execution architecture for a specific task

CLAUDE_CODE_SIMPLE=true disables all context loading — CLAUDE.md, skills, memory, agents, hooks, and MCP tools. Use this in automated pipelines for predictable behavior.

CLAUDE.md — The Project Brain

What CLAUDE.md Does

CLAUDE.md is injected into every conversation in its scope. It is the primary mechanism for giving Claude persistent, session-to-session knowledge about your codebase. It competes with the codebase for context window space — density beats verbosity.

The Four Tiers of CLAUDE.md

Additive Loading in Monorepos

Loading is additive, not replacing. Claude concatenates global + project root + subdirectory CLAUDE.md files. Subdirectory files should only add scope-specific context — never repeat what is already in a parent file.

What Belongs in CLAUDE.md

1. Commands — npm run dev, npm run build, deploy commands, test runners
2. Architecture — directory structure, provider hierarchy, key entry points
3. Non-obvious patterns — "Two data-fetching patterns coexist; prefer TanStack Query for new code"
4. Gotchas — "Dev server runs on port 8080. Kill old processes on 8080–8082 before starting."
5. Code style conventions — path aliases, utility imports, TypeScript settings
6. Deployment — hosting provider, backend, domain, config file locations

Context Window Budget

• CLAUDE.md all levels combined: under 2,000 words
• MEMORY.md index: under 200 lines (silently truncated beyond this)
• Individual skill body: under 2,000 words, 3,000 absolute max

Keeping CLAUDE.md Current

• # shortcut: Press during any session to capture learnings into CLAUDE.md
• /revise-claude-md: Reflects on the full session and drafts additions as diffs
• Quality scoring: The claude-md-improver skill scores on 6 axes — commands, architecture, patterns, conciseness, currency, actionability

The Decision Framework: CLAUDE.md vs. Memory

SKILL.md — Packaged Expertise

What a Skill Is

A skill is a modular, self-contained expertise package with progressive disclosure: metadata always in context, SKILL.md body loads on trigger, references/ files load on demand.

The Description Field — The Trigger Mechanism

The description field is the single most important line in any SKILL.md. The entire loading mechanism depends on semantic matching between it and what users type.

Invocation Control

context: fork — Isolated Execution

When set, the skill runs as an isolated subagent with no inherited conversation context. Use for parallel review workflows and independent analyzers. Do not use for skills that need to see current conversation state.

Skill Troubleshooting

1. Description too vague: Add specific trigger phrases from actual user queries
2. Wrong scope: Project-level skill not visible from outside that project
3. YAML syntax error: Silently prevents loading — validate the frontmatter
4. user-invocable: false: Trying to invoke via slash command but it's Claude-only

Memory Files — Persistent Cross-Session Context

Architecture

Project Path Encoding

The encoded path is your absolute path with forward slashes replaced by hyphens: /Users/sumit/my-project → -Users-sumit-my-project

If you move your project directory, memory files are orphaned. Fix: rename the directory in ~/.claude/projects/ to match the new encoded path.

The Four Memory Types

Feedback Type — Full Example

---
name: prefer-tanstack-query
description: User prefers TanStack Query over useState/useEffect
type: feedback
---

Always use useQuery and useMutation from TanStack Query, not useState + useEffect.

**Why:** Two coexisting patterns exist. useState/useEffect was flagged as legacy.

**How to apply:** Reference useMemberProfile.ts as the template for new hooks.

Memory files are per-developer, per-machine. There is no cloud sync. To share context with teammates, use CLAUDE.md (checked into git).

Plan Files — Session-Scoped Architecture

Created during plan mode, stored at ~/.claude/plans/{adjective}-{verb}-{name}.md. Names reference CS history (Moore, Kahn, Catmull, Naur, Eich). Plan files are not auto-deleted — they accumulate indefinitely and serve as an archive of architectural decisions.

Anatomy of a Good Plan File

1. Context: Why this plan exists and the intended outcome
2. Implementation steps: Specific files, schema changes, sequenced phases
3. Critical files: Every file that will be touched
4. Reuse callouts: Existing utilities to use, not reinvent
5. Verification steps: How to confirm success end-to-end

Reference Files and Supporting Docs

Debugging and Troubleshooting

When CLAUDE.md Is Ignored

1. Wrong location: Must be at {project}/CLAUDE.md, not .claude/CLAUDE.md
2. Silent truncation: Content past the limit is dropped — front-load critical info
3. Local override conflict: .claude.local.md takes precedence
4. CLAUDE_CODE_SIMPLE=true: Disables all CLAUDE.md loading

When Memory Files Are Missing

# Project was moved? Rename the encoded directory:
mv ~/.claude/projects/-Users-sumit-old-name ~/.claude/projects/-Users-sumit-new-name

Using CLAUDE_CODE_SIMPLE=true as a Diagnostic

Set it and re-run. If behavior changes, a context file was influencing results. Re-enable CLAUDE.md, then skills, then memory — one at a time — to isolate the source.

Keep Each File Type Doing Its One Job

Project orientation — architecture, commands, permanent gotchas

Reusable expertise — packaged workflows that load when needed

Cross-session knowledge — preferences, decisions, external resources

Pre-execution architecture — scope, phases, verification

The files get better. The conversations get more useful. The ramp-up time on returning to a project shrinks toward zero.