Writing a good Claude.md

Who Should Read

Developers using Claude Code (or similar coding agents) who want to maximize the agent's effectiveness and reduce repetitive context-setting.

Core Mechanics

• Claude Code starts each session without persistent memory of previous sessions — it re-reads the codebase each time
• CLAUDE.md acts as the agent's 'long-term memory': architecture overviews, coding conventions, known gotchas, and workflow instructions
• Well-maintained CLAUDE.md significantly reduces the number of clarifying questions and wrong-path attempts
• Recommended structure: project overview, tech stack, directory layout, coding conventions, common commands, do's and don'ts
• Treat CLAUDE.md as a living document updated whenever you correct the agent's behavior

Evidence

• Developer community experience reports comparing session quality with and without CLAUDE.md
• Anthropic's own documentation recommending CLAUDE.md best practices
• Anecdotal but consistent reports of 30–50% reduction in agent errors with good CLAUDE.md

How to Apply

• Create a CLAUDE.md at your project root with: project purpose, tech stack, directory structure, key conventions, and common pitfalls.
• When the agent makes a mistake due to missing context, add that context to CLAUDE.md immediately — not just correct it for this session.
• Keep CLAUDE.md concise; aim for <500 lines. Overly long files dilute attention on the most critical constraints.

Code Example

# CLAUDE.md Table of Contents Style Example

## Documentation References

- For CSS work: docs/ADDING_CSS.md
- For adding assets: docs/ADDING_ASSETS.md
- For working with user data: docs/STORAGE_MANAGER.md

## Stack
- Runtime: Bun (not Node)
- Tests: `bun test`
- Typecheck: `bun tsc --noEmit`

Terminology

Related Papers

• Claude-real-video － any LLM can watch a video

  YouTube URL이나 로컬 영상 파일에서 장면 변화 기반으로 핵심 프레임만 추출하고 음성 전사까지 해서 LLM에게 넘겨주는 오픈소스 도구. Claude는 영상 파일을 못 받고, ChatGPT는 자막만 읽고, Gemini는 고정 1fps 샘플링이라는 한계를 모두 우회한다.

• ReContext: Recursive Evidence Replay as LLM Harness for Long-Context Reasoning

  128K 토큰 컨텍스트에서 모델 내부 attention 신호로 핵심 증거만 추출해 재주입하면 추론 정확도가 24.6% 오른다.

• Single and Multi Truth Data Fusion using Large Language Models

  여러 소스의 충돌하는 데이터를 GPT-4o-mini 프롬프트로 병합하면 기존 비지도 방법보다 일관되게 F1 점수가 높다.

• Multilingual Reasoning Cascades Need More Context

  번역 cascade 파이프라인에서 원본 질문을 마지막까지 유지하면 추가 학습 없이 다국어 성능이 크게 오른다.

• Less Back-and-Forth: A Comparative Study of Structured Prompting

  체크리스트 형식으로 프롬프트를 구조화하면 LLM 답변 품질도 높아지고 토큰도 적게 쓴다.

• Training-Free Cultural Alignment of Large Language Models via Persona Disagreement

  재학습 없이 각 나라의 도덕적 가치관에 맞게 LLM 출력을 조정하는 추론 시점 기법 DISCA 제안

• Using Claude Code: The unreasonable effectiveness of HTML

Related Resources

• https://www.humanlayer.dev/blog/writing-a-good-claude-md
• https://www.anthropic.com/engineering/claude-code-best-practices
• https://gist.github.com/scpedicini/179626cfb022452bb39eff10b...
• https://gist.github.com/ctoth/d8e629209ff1d9748185b9830fa4e7...