Using Claude

How to Write a CLAUDE.md (with a Copy-Paste Template)

How to write an effective CLAUDE.md that Claude Code reads every session. Principles (short, specific, the why, emphasis), what to include or cut, and a ready-to-copy starter template.

🌐 This article was machine-translated and may contain inaccuracies. Refer to the Korean original if in doubt.

CLAUDE.md is a project-context file that Claude Code reads automatically at the start of every session. It tells Claude things it can't infer from code alone — build commands, code style, workflow rules — so Claude works the way your project expects. This article covers the principles and a ready-to-copy template. (As of May 2026. Check the official docs for exact behavior.)

Where it goes

Usually at the project root, named CLAUDE.md, in markdown format. We recommend running /init to generate a starter based on your current project structure, then refining it.

Writing principles

  • Keep it short and concise: it loads in full every session, so a long file buries the rules that matter. For each line, ask: "Would removing this cause Claude to make a mistake?" If not, cut it.
  • Be specific: instead of "write clean code" (aspirational), write "server components by default; add 'use client' only when truly needed" (testable).
  • Explain the why: stating the reason behind a rule helps Claude judge edge cases.
  • Use emphasis: marking must-follow items with "IMPORTANT" or "YOU MUST" improves adherence.

CLAUDE.md is advisory — Claude is said to follow it about 80% of the time. For things that must be enforced every time without exception (formatting, linting, security checks), use a hook rather than CLAUDE.md. Also, for domain knowledge or workflows needed only sometimes, prefer skills (loaded on demand) over bloating every conversation via CLAUDE.md.

What to include

  • Build/test commands (e.g., npm run build, how to run a single test)
  • Code style (e.g., import style, naming conventions)
  • Workflow rules (e.g., typecheck after changes, commit conventions)
  • Project structure / architecture decisions that aren't obvious from code
  • Gotchas

Conversely, don't include what's already in the README or package.json, anything that changes weekly, or things Claude already does well on its own (that's just noise).

Ready-to-copy starter template

Here's a starting point for a general web project. Trim and adapt it to your project.

# Project overview
[One or two sentences: what the project does, core stack]

# Commands
- Dev server: [e.g., npm run dev]
- Build: [e.g., npm run build]
- Typecheck: [e.g., npm run typecheck]
- Test (single): [e.g., npm test -- path/to/test]  # prefer single tests over the whole suite

# Code style
- [e.g., Use ES modules (import/export), not CommonJS (require)]
- [e.g., Server components by default; add 'use client' only when truly needed]

# Workflow
- IMPORTANT: always typecheck after finishing a set of changes
- [e.g., commit messages in English, separate commits per file]

# Gotchas
- [Pitfalls you can't see from the code, with the reason why]

Operating tips

Treat CLAUDE.md like code — version it, review it when things go wrong, and prune it regularly. After adding a rule, check in a fresh session whether Claude's behavior actually changes. If Claude asks questions already answered in CLAUDE.md, the wording is probably ambiguous; if it ignores a rule, the file may be too long and the rule is getting lost.

This article is for general guidance only. Claude Code's features and behavior may change by version. Check the official docs (code.claude.com/docs) for the latest recommendations. (As of May 2026)