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.

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.

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):

## 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.