---
description: Produce a ready-to-paste CLAUDE.md through guided discovery. Interviews you on who you are, your stack, your conventions, and your hard rules, then outputs a tight briefing file and tells you where to save it. Use when you just moved from the chat to Claude Code and Claude keeps forgetting your context.
allowed-tools: Read, Write, Glob, Grep
---

# Setup CLAUDE.md

Build a CLAUDE.md, the permanent briefing Claude Code loads at the start of every session, through a short guided interview. This skill is a discovery, not a blind generator: it asks the right questions, applies context-hygiene rules, and hands you a file you can paste in and use immediately.

## When to use

- You just moved from the chat to Claude Code and keep re-explaining the same context every session.
- Claude produces generic output because it does not know your product, audience, tone, or hard rules.
- You want a first CLAUDE.md but do not know what belongs in it (versus what belongs in a Skill).

For encapsulating a repeatable multi-step workflow instead, use `skill-create`.

## Input

An optional argument naming the level: `global`, `project`, or `local`. If none is given, ask in Phase 3.

## The boundary you must hold

Before collecting anything, make the frontier explicit to the user. It decides what goes in the file.

- **CLAUDE.md = the permanent brief.** Loaded automatically, every session. Who you are, your stack, your conventions, your hard rules. Facts that are true all the time.
- **Skill = a one-off method.** Loaded on demand when invoked. The steps, criteria, and output format of a specific recurring task.

Rule of thumb: a one-line convention that is always true ("informal tone, no jargon") is CLAUDE.md. A multi-step procedure with a fixed output ("write a creative brief in this structure") is a Skill. If the user describes a workflow, tell them it is a Skill and point them to `skill-create`.

## Workflow

### Phase 1 — Read the ground (optional)

If you are inside a project the user can share, skim it first: existing content, README, config, prior drafts. You are good at deducing tone and conventions from what already exists. What you cannot deduce: the hard rules, positioning nuances, and business logic. Those come from the interview. Never invent them.

### Phase 2 — Collect the four blocks

Interview the user. Batch questions into one message when the answers are simple; ask one at a time only when a block is fuzzy. Propose a recommended answer with each question so the user reacts instead of staring at a blank page. Keep every answer to the point: you are collecting rules, not essays.

1. **Who you are / what you work on.** The product or project, the audience, the positioning. Only what changes Claude's answers (if it writes sales copy, it needs the pricing; if it writes a post, it needs the positioning).
2. **Stack and tools.** Languages, frameworks, services, where things get published, the tools Claude should assume are in play.
3. **Conventions and ways of working.** Tone, formats, naming, process. The section that kills the most repeat corrections.
4. **Constraints and hard rules.** What Claude must never do. Often more useful than the do's, because default mistakes are predictable. Capture forbidden words, forbidden actions, guardrails. Write these as `JAMAIS ...` / `NEVER ...` in caps: Claude weights capitalized rules more heavily.

If a block has nothing meaningful, leave it out. An empty section is noise.

### Phase 3 — Pick the level and the location

Claude Code loads instructions from three places, and they stack. Ask which one fits, and recommend based on the answers:

- **Global** (`~/.claude/CLAUDE.md`): your preferences everywhere. Conversation language, personal style, universal rules. No project context. Recommend when the rules are about *you*, across all projects.
- **Project** (`./CLAUDE.md` at the repo root): the project's rules, committed and shared with the team. Recommend for product, audience, tone, conventions tied to one project. This is the default.
- **Local** (the per-project user file, uncommitted): notes you do not want to commit but Claude should know ("launch slipped to June", "landing B is paused").

The more specific level wins on conflict. For where these files physically live and what is safe to touch, point the user to the article [Le terminal et tes fichiers, sans flipper](/blog/demarrer-ou-vivent-tes-fichiers).

### Phase 4 — Apply context hygiene

Before you output, run the draft against three rules drawn from the discipline of context management:

- **Stay short.** 20 to 50 lines is the target. Past that, the important rules drown in the noise and Claude loses the hierarchy. If a block is growing past a few lines of procedure, it is a Skill, not CLAUDE.md.
- **Cut the noise.** No tool documentation Claude already knows, no decision history, no explanatory paragraphs, no "this client is difficult". Keep only actionable, checkable rules.
- **Move workflows out.** Any multi-step procedure with a fixed output belongs in a Skill (`skill-create`), not in a file loaded on every session for an occasional use.

Deeper reasoning on why context is a resource, not a dump: [Le mur du quota](/blog/gerer-contexte).

### Phase 5 — Output

Produce two things.

**1. The file, in a copyable markdown block.** Structured with `#` and `-`, grouped by the four blocks, hard rules in caps. Dense, no filler. Show the user exactly what to paste, and remind them of the path chosen in Phase 3.

**2. A maintenance checklist.** A CLAUDE.md drifts the moment you stop looking at it: the product moves, a convention changes, a rule goes stale. Hand the user a 30-minute monthly ritual (a nod to the [éloge de la maintenance](/blog/eloge-maintenance)):

```markdown
## CLAUDE.md — revue mensuelle (30 min)
- [ ] Relire ligne par ligne : chaque règle est-elle encore vraie ?
- [ ] Supprimer les règles mortes (produit qui a bougé, convention abandonnée)
- [ ] Repérer les corrections répétées ce mois-ci → une nouvelle ligne chacune
- [ ] Toute procédure qui a gonflé au-delà de 2-3 lignes → la sortir en Skill
- [ ] Vérifier que le fichier tient toujours sous ~50 lignes
```

## Rules

- Write the CLAUDE.md content in the user's language; keep this skill's own instructions in English.
- Never invent hard rules, positioning, or business logic. Ask.
- A rule you cannot verify objectively ("professional but accessible") is useless. Push for the checkable version.
- Do not pad the file to look thorough. Every line must kill a category of mistakes.
- Stop and ask when a call is the user's to make (level, tone, a forbidden word). Do not guess.