How CLAUDE.md Works
CLAUDE.md is the project instructions file you write for Claude. Every time you launch Claude Code in this project, the file is auto-loaded as part of the system prompt, and Claude sees its contents for the whole session. Anything about this paper that must not be lost across sessions belongs here.
How CLAUDE.md Loads
Why you need this file
Claude's conversation history disappears when the session ends. The terminology locks, file structure, citation style you set today are gone tomorrow — next session you'd have to spell them out again.
CLAUDE.md is how you write that down once. On launch, Claude Code reads the project-root CLAUDE.md and injects its contents into the system prompt. Every session in this project starts with those rules in place.
Even more important: CLAUDE.md is not affected by context compression. When a long session triggers auto-compact, the earlier conversation gets summarized away, but CLAUDE.md stays intact. The rules you put here survive any session length. Anchoring critical agreements in CLAUDE.md is far more reliable than keeping them in the conversation.
How it gets loaded
On launch, Claude Code walks from the current directory up to root looking for every CLAUDE.md along the way. Starting in ~/papers/pc-esg/05_分析代码/, it picks up 05_分析代码/CLAUDE.md, pc-esg/CLAUDE.md, and ~/.claude/CLAUDE.md. All discovered CLAUDE.md files get stitched together into the system prompt.
Stitch order: user global (~/.claude/CLAUDE.md) → parent dirs → project root → subdirs. Later-loaded rules override earlier rules with the same key. Project-level CLAUDE.md takes precedence over the user global one.
The layering lets you separate concerns. User global: 'all my projects use Times New Roman for English'. Project root: '14-term protected list + A2 primary measure + 6 working-discipline rules'. Subdir: 'every .do file under 05_分析代码 is numbered do0–do10'.
Priority and load order
| Layer | Path | Effect |
|---|---|---|
| User global | ~/.claude/CLAUDE.md | Defaults shared across all your projects. Figure font rules, commit message style, personal preferences. |
| Project root | ~/papers/pc-esg/CLAUDE.md | Rules unique to this empirical project. 14-term protected list, PC_A2 primary measure, Huazheng ESG 0-1 normalization, 6 working-discipline rules. |
| Subdir | ~/papers/pc-esg/05_分析代码/CLAUDE.md | Rules that only apply to this subdir. Like 'all .do files are numbered do0–do10' or 'cd here before running stata-mcp'. |
Sample CLAUDE.md from the Patient Capital → ESG project
Below is the actual CLAUDE.md (excerpted) used in the running example. Every rule is a thing 'you don't want to repeat to Claude every session.' You can copy this directly as a template.
# CLAUDE.md
This file is the project's persistent context, auto-loaded by Claude Code at the start of each session.
## 1. Research direction
Topic: Patient Capital's effect on corporate ESG performance and its mechanisms.
Sample: Chinese A-share listed firms, 2009–2023.
Primary BeS: Huazheng ESG continuous score (0–1 normalized).
Primary PC measure: A2 (Daifei 2025) = stable equity + relationship debt.
Mechanism variable: MDA-version managerial myopia (Hu Nan et al. 2021 word-frequency).
Financing-constraint variable: KZ index (project has no WW data; uses KZ as substitute, disclosed in footnote).
## 2. Protected term list (no synonym substitution allowed)
The following terms must be preserved verbatim across all text output:
耐心资本 / 稳定型机构投资者 / 战略型机构投资者 / 交易型机构投资者 /
关系型债权 / 机构投资者异质性 / ESG 表现 / 漂绿 /
管理者短视主义 / 双元创新 / 新质生产力 / 全要素生产率 /
融资约束 / 两权分离率
## 3. Writing discipline
- Academic Chinese; avoid colloquialisms
- Anti-AI: no parallel structures, no empty evaluative phrases, no listing-style metaphors, no summary-style platitudes
- 4–8 sentences per paragraph; no empty wrap-up paragraphs
- Citations follow GB/T 7714; switch to APA/Chicago after target journal is fixed
## 4. Working discipline (hard constraint; AI may not skip)
1. State the plan before any edit — for vague instructions ("clean up", "tidy"), spell out "what changes / what stays" and wait for user approval
2. cp a timestamped backup before touching any .docx
3. Re-read the protected-term list before any cross-file rewrite
4. For batch tasks (≥ 30 items), pilot on 3–5 samples first
5. Before changing any core claim, scan the paper for all linked positions and confirm with user
6. Before handoff, run the hard checklist: terms / citations / data / figures / cross-refs / AIGC self-check
## 5. Do not
- Do not draft paper sections, abstracts, or body paragraphs for me
- Do not polish or rewrite text I have already written
- Do not bulk-edit 07_论文写作/; produce an audit report first, I decide before any edit
- Do not git commit on my behalf — I commit manuallyHow to write a good CLAUDE.md
Write it in plain English (or your working language), like you would brief a new research assistant on the rules of the project. Avoid abstract directives ('follow academic conventions'); write the concrete requirement ('citation style is APA').
After writing, test it: launch Claude Code, give an instruction that touches one of the rules, and see if the response reflects what's in CLAUDE.md. When a rule is forgotten, it usually means the rule is too abstract — add a concrete example.
Keep CLAUDE.md under git like the rest of the project. When you switch machines or hand the project off to a collaborator, CLAUDE.md travels with everything else and new sessions pick it up automatically.
Beginner traps
Too long, Claude loses the thread
Aim for under 200 lines. Beyond that, the system prompt gets bloated and the model has trouble prioritizing. Push less-critical rules into per-chapter mini-CLAUDE.md files; keep the project-root one lean.
Conflicting rules that go unnoticed
If one section says "always use outcome variable" and another says "match the advisor's style which is dependent variable", Claude will pick one at random. Cross-check each new rule against existing rules.
Treating CLAUDE.md as a notebook
CLAUDE.md is for long-lived rules, not session notes. Ad-hoc notes ("today we discussed X, next week do Y") belong in a file under notes/. Stuffing CLAUDE.md with session flow makes Claude think those notes are active rules.
Not retiring stale rules
Rules change as the paper progresses. Draft phase allows structural changes; final phase locks the structure. When a rule expires, update CLAUDE.md; do not leave outdated rules around for the model to obey.