Cours Vibe coding avec Claude Code · Module 15: Claude Code avancé
Règles de l'équipage : CLAUDE.md pour l'équipe, règles par chemin et réglages
Dans cette leçon9
Treasure Map grandit et son CLAUDE.md avec lui. Après quelques semaines d'ajouts, il dépasse cent lignes : la moitié décrit les dossiers, les règles des routes d'API sont coincées entre celles des composants, et hier Claude a écrit une route sans vérifier la session, alors que cette règle se trouvait à la ligne 112. Et quelqu'un d'autre rejoint le projet : tu ne veux pas qu'il reçoive tes notes sur ta base locale. Un seul long fichier n'est plus une carte, c'est un tas de parchemins.
Ce que tu sais déjà
Dans la leçon 1_7, tu as généré CLAUDE.md avec /init, importé AGENTS.md par la ligne @AGENTS.md et appris que la suite du travail consiste surtout à rayer. Dans la leçon 8_4, tu as fermé .env par une règle deny dans .claude/settings.json, et dans la leçon 10_5 tu as ajouté des règles ask pour les déploiements. Dans les leçons 14_1 et 14_2, tu as écrit des scripts avec claude -p. Maintenant, tu mets le même ordre au service de l'équipage : qui lit quelles règles, quand, et depuis le fichier de qui.
Quatre niveaux de mémoire
Claude Code cherche les fichiers d'instructions à quatre endroits. Les voici, de la portée la plus large à la plus étroite :
/Library/Application Support/ClaudeCode/CLAUDE.md # politique de l'organisation (macOS), déployée par le service IT
~/.claude/CLAUDE.md # toi, dans tous les projets
treasure-map/CLAUDE.md # tout l'équipage, dans le dépôt
treasure-map/CLAUDE.local.md # toi, ce projet seulement, hors de GitLes fichiers ne s'écrasent pas : ils sont mis bout à bout en un seul texte, les plus larges d'abord, et CLAUDE.local.md à la fin de son niveau. Quand deux fichiers se contredisent, Claude peut choisir n'importe quelle version, donc la cohérence, c'est ton travail. La politique de l'organisation, tu ne peux pas la désactiver chez toi, mais Treasure Map n'en a pas, car elle concerne les ordinateurs d'entreprise. Un CLAUDE.md dans un sous-dossier, par exemple app/api/CLAUDE.md, ne se charge que lorsque Claude touche un fichier de ce dossier.
Demande pour Claude Code
Le rangement, tu le commandes, tu ne le fais pas à la main. Dans une session ouverte dans le dossier treasure-map, écris :
Relis @CLAUDE.md. Supprime les lignes que tu pourrais lire dans le code ou dans package.json,
y compris la description des dossiers. Déplace les règles de app/api vers .claude/rules/api.md
et celles de components/ vers .claude/rules/components.md, chacune avec un en-tête paths.
Déplace mes notes sur la base locale vers CLAUDE.local.md et ajoute-le à .gitignore.
C'est fini quand CLAUDE.md fait moins de 30 lignes. À la fin, liste ce que tu as supprimé et où tu as déplacé le reste.La demande nomme trois cibles et donne la mesure de la fin : Claude sait quand s'arrêter, et toi, tu sais quoi vérifier.
Ce que Claude a écrit : un CLAUDE.md court
Ouvre CLAUDE.md dans Cursor. Chez nous, après le rangement, il est resté ce fichier :
@AGENTS.md
# Commandes de vérification
- Un seul fichier de tests : `npm run test -- --run lib/pins.test.ts`
- Tous les tests : `npm run test -- --run`
- Types : `npx tsc --noEmit`, lint : `npm run lint`
# Pièges
- La base lancée avec `npx prisma dev` démarre à part ; sans elle, les routes de app/api renvoient 500.
- `getCurrentUserId()` de `lib/session.ts` est une fausse connexion par le cookie `demo-user`.
# Décisions
- On ne modifie pas les migrations de `prisma/migrations/` ; un changement de schéma est une nouvelle migration.Chaque ligne dit quelque chose que Claude ne verra pas dans le code : comment vérifier le travail, où le code trompe et ce que l'équipage a décidé. La description des dossiers et la liste des bibliothèques ont disparu, car Claude lit de toute façon le dépôt. L'import @AGENTS.md est resté en haut, comme dans la leçon 1_7. Souviens-toi seulement qu'un import range mais n'allège pas : le fichier importé est chargé avec CLAUDE.md et occupe autant de place dans le contexte.
Ce que Claude a écrit : des règles par chemin
Les règles qui concernent une partie du code sont allées dans le dossier .claude/rules/. Une règle est un simple fichier Markdown avec un frontmatter, c'est-à-dire des réglages entre deux lignes ---, comme dans le skill de la leçon 6_1 :
---
paths:
- "app/api/**/*.ts"
---
# Routes d'API
- Toute route qui modifie des données appelle d'abord `getCurrentUserId()` : pas de session, c'est 401 ; le tableau d'un autre, c'est 403.
- Les données d'entrée passent par un schéma Zod de `lib/`, jamais par un `typeof` écrit à la main.
- Le test d'une route se trouve à côté d'elle et mocke `@/lib/session`.paths est le seul champ que Claude Code lit dans une règle. Le motif se compte depuis le dossier du projet : ** veut dire "à n'importe quelle profondeur", et *.ts n'importe quel fichier TypeScript. Selon la documentation, une telle règle n'entre dans le contexte que lorsque Claude lit, écrit ou modifie un fichier correspondant, alors qu'une règle sans paths se charge au démarrage, comme CLAUDE.md. Nous l'avons vérifié : Claude a lu app/api/boards/[id]/pins/route.ts, api.md est apparue dans le contexte, et components.md non. Il a aussi remarqué tout de suite que cette route vérifie pinId par un typeof écrit à la main, contre la deuxième règle.
Les notes personnelles sont allées dans CLAUDE.local.md, et .gitignore a reçu une ligne avec le nom de ce fichier :
CLAUDE.local.mdClaude lit ce fichier comme n'importe quel autre CLAUDE.md, mais Git ne le voit pas, donc tes notes ne partiront pas vers l'équipage.
La revue du capitaine
Ouvre le diff de CLAUDE.md dans le panneau Source Control et vérifie :
- Le test de chaque ligne. Claude le trouverait-il dans le code ? Si oui, la ligne est à rayer.
- Le motif attrape des fichiers.
app/api/**/*.tscorrespond aux routes de Treasure Map. Un motifsrc/app/api/**copié d'un autre projet ne correspond à rien, car ici il n'y a pas de dossiersrc, et la règle ne se chargera jamais, sans un bruit. Demande à Claude de lire une route et demande-lui quelles règles de.claude/rulesil a maintenant dans son contexte. - Le fichier privé est privé.
git check-ignore -v CLAUDE.local.mdaffiche la ligne de.gitignorequi le cache. Une réponse vide veut dire que le fichier partira dans le commit.
Une erreur typique de l'agent : en "rangeant", Claude rajoute une section du genre # Structure du projet avec l'arbre de app/, lib/ et components/. Tu la reconnais dans le diff à son arbre de dossiers tout en vert. Les bonnes pratiques officielles le disent sans détour : tu ne décris ni l'architecture ni la disposition des fichiers, car Claude lit le dépôt tout seul. Pour la revue périodique, il y a /doctor prompt-audit : Claude cherche dans CLAUDE.md, les règles, les skills et les agents des instructions périmées ou contradictoires, et ne change rien tant que tu ne le demandes pas.
Les réglages : qui a le dernier mot
La mémoire dit à Claude comment travailler, et les réglages disent à Claude Code ce qu'il peut se permettre. Les fichiers de réglages aussi sont plusieurs. Quand la même clé se trouve dans deux fichiers, le plus haut gagne, en comptant depuis le plus haut :
- les réglages gérés de l'organisation ;
- la ligne de commande, c'est-à-dire
--settingsau démarrage ; .claude/settings.local.json: toi, ce projet ;.claude/settings.json: l'équipage, dans le dépôt ;~/.claude/settings.json: toi, tous les projets.
Les listes, comme permissions.allow, ne s'écrasent pas, elles fusionnent. Voici le fichier de l'équipage dans Treasure Map :
{
"permissions": {
"allow": ["Bash(npm run test *)", "Bash(npm run lint)", "Bash(npx tsc --noEmit)"],
"ask": ["Bash(npx prisma migrate *)", "Bash(git push *)"],
"deny": ["Read(./.env)", "Read(./.env.*)"]
}
}allow laisse passer les tests, le lint et les types sans question, ask impose de demander pour les migrations et le push, et deny, celui de la leçon 8_4, ferme les secrets. Pour chaque appel, Claude Code examine les règles dans le même ordre : d'abord deny, puis ask, enfin allow, quel que soit le fichier d'où elles viennent. Quand aucune règle ne correspond, c'est le mode de permissions qui décide. Ton allow pour git push dans les réglages utilisateur ne l'emportera donc pas sur le ask de l'équipage, et un deny venu de n'importe quel fichier l'emporte sur tout allow. Tes exceptions, tu les gardes dans le fichier local :
{
"permissions": {
"allow": ["Bash(npx prisma studio)"]
}
}C'est aussi là que Claude Code enregistre la réponse "Yes, and don't ask again", et à la première écriture il protège lui-même ce fichier contre le commit. Un fichier créé à la main, ajoute-le toi-même à .gitignore. Encore une règle pour l'équipage : les règles allow de .claude/settings.json ne fonctionnent qu'après que tu as accepté la fenêtre de confiance du dossier, tandis que deny et ask agissent tout de suite, car elles ne font que restreindre. Notre exécution de claude -p dans un dossier non approuvé a affiché : Ignoring 3 permissions.allow entries from .claude/settings.json: this workspace has not been trusted.
Quand une règle agit autrement que tu ne le pensais, tape /permissions : cette commande montre chaque règle avec le fichier d'où elle vient. /status montre seulement quels fichiers de réglages ont été chargés.
Scripts avec arguments : $1 et "$*"
Les règles de l'équipage servent aussi dans les scripts de la leçon 14_2. Un argument est un mot tapé après le nom du script : Bash met le premier dans $1, et tous ensemble dans "$*". Un générateur de composants a besoin d'un seul nom :
NAME=$1
if [ -z "$NAME" ]; then
echo "Donne le nom du composant, par ex. : bash scripts/generate-component.sh BoardBadge"
exit 1
fiAprès bash scripts/generate-component.sh BoardBadge, la variable NAME vaut BoardBadge, et sans argument le script s'arrête avant que tu paies pour une exécution à vide. Ensuite, le nom entre dans la commande :
claude -p "Crée le composant React $NAME en TypeScript dans components/$NAME.tsx et un test Vitest dans components/$NAME.test.tsx. Respecte les règles de .claude/rules/components.md." \
--model sonnet --allowedTools "Write" --max-turns 6Pourquoi la demande désigne-t-elle la règle en toutes lettres ? Une règle par chemin se charge à la lecture, à l'écriture ou à la modification d'un fichier correspondant, et le nouveau composant n'existe pas tant que Claude ne l'a pas écrit. --allowedTools "Write" approuve l'écriture de nouveaux fichiers, comme dans la leçon 14_1. Dans l'exercice de l'éditeur, tu ajouteras un troisième fichier, .stories.tsx pour Storybook, l'outil qui montre les composants isolés.
Le moteur de recherche dans le code, lui, a besoin de toute la phrase, donc il prend tous les arguments :
QUERY="$*"
claude -p "Trouve dans le projet le code qui concerne : $QUERY. Réponds par une liste : fichier:ligne et une phrase sur ce qui s'y passe." \
--model sonnet --tools "Read,Grep,Glob" --max-turns 6Après bash scripts/ai-search.sh où vérifie-t-on le propriétaire du tableau, un script avec $1 transmettrait à Claude le seul mot "où", alors qu'avec "$*" il transmet toute la phrase. Les guillemets sont une bonne habitude : quand $* sans guillemets se retrouve comme argument d'une commande, Bash découpe le texte en mots et remplace une étoile de la question par la liste des fichiers. Sur un faux claude, la question où * vérifie-t-on est devenue chez nous "où AGENTS.md CLAUDE.local.md CLAUDE.md README.md app ...". Les outils Read,Grep,Glob suffisent, car en mode -p Claude lit sans demander.
Étape suivante
Ajoute une troisième règle et vérifie-la tout de suite :
Ajoute .claude/rules/testing.md avec les règles des tests Vitest et des paths sur *.test.ts et *.test.tsx.
Ensuite lis lib/pins.test.ts et liste les règles de .claude/rules que tu as maintenant dans ton contexte.Demande un commit, par exemple "Règles de l'équipage : CLAUDE.md court, règles et réglages", et vérifie dans Source Control qu'il ne contient ni CLAUDE.local.md ni .claude/settings.local.json. Dans l'éditeur à côté, tu choisiras un fichier de Treasure Map et tu verras quels fichiers de mémoire et quelles règles entrent alors dans le contexte, et pour une commande choisie, quelle règle de permission en décide et de quel fichier elle vient.
N'oublie pas : sur la carte de l'équipage, tu marques les récifs, pas chaque vague.
Code de cette leçon : App.tsx
// Carte des règles de l’équipage : quelles instructions Claude voit pour un fichier et quelle règle décide d’une commande
import { useState } from 'react';
export interface MemoryFile {
path: string;
scope: string;
paths?: string[];
}
export const MEMORY: MemoryFile[] = [
{ path: '~/.claude/CLAUDE.md', scope: 'toi, tous les projets' },
{ path: 'CLAUDE.md', scope: 'équipage, dans le dépôt' },
{ path: 'CLAUDE.local.md', scope: 'toi, ce projet, hors de Git' },
{ path: '.claude/rules/api.md', scope: 'règle par chemin', paths: ['app/api/**/*.ts'] },
{ path: '.claude/rules/components.md', scope: 'règle par chemin', paths: ['components/**/*.tsx'] },
{ path: '.claude/rules/testing.md', scope: 'règle par chemin', paths: ['**/*.test.ts', '**/*.test.tsx'] },
];
export const FILES = [
'app/api/pins/route.ts',
'app/api/boards/[id]/pins/route.ts',
'components/PinCard.tsx',
'lib/pins.ts',
'lib/pins.test.ts',
'prisma/schema.prisma',
];
const SPECIAL = '.+?^$()[]{}|\\';
export function globToRegExp(glob: string): RegExp {
let re = '';
for (let i = 0; i < glob.length; i++) {
const ch = glob[i];
if (ch === '*' && glob[i + 1] === '*') {
if (glob[i + 2] === '/') {
re += '(?:.*/)?';
i += 2;
} else {
re += '.*';
i += 1;
}
} else if (ch === '*') {
re += '[^/]*';
} else if (SPECIAL.includes(ch)) {
re += '\\' + ch;
} else {
re += ch;
}
}
return new RegExp('^' + re + '$');
}
export interface Loaded {
path: string;
scope: string;
status: 'start' | 'file' | 'no';
note: string;
}
export function loadedFor(file: string, apiPattern: string): Loaded[] {
return MEMORY.map((m) => {
if (!m.paths) {
return { path: m.path, scope: m.scope, status: 'start', note: 'se charge au démarrage de la session' };
}
const patterns = m.path === '.claude/rules/api.md' ? [apiPattern] : m.paths;
const hit = patterns.some((p) => globToRegExp(p).test(file));
return hit
? { path: m.path, scope: m.scope, status: 'file', note: 'se charge quand Claude lit, écrit ou modifie ce fichier (paths : ' + patterns.join(', ') + ')' }
: { path: m.path, scope: m.scope, status: 'no', note: 'ne correspond pas à ' + patterns.join(', ') };
});
}
export type Decision = 'deny' | 'ask' | 'allow';
export interface Rule {
decision: Decision;
pattern: string;
source: string;
}
export const RULES: Rule[] = [
{ decision: 'allow', pattern: 'Bash(git push *)', source: '~/.claude/settings.json' },
{ decision: 'allow', pattern: 'Bash(npm run test *)', source: '.claude/settings.json' },
{ decision: 'allow', pattern: 'Bash(npm run lint)', source: '.claude/settings.json' },
{ decision: 'ask', pattern: 'Bash(npx prisma migrate *)', source: '.claude/settings.json' },
{ decision: 'ask', pattern: 'Bash(git push *)', source: '.claude/settings.json' },
{ decision: 'deny', pattern: 'Read(./.env)', source: '.claude/settings.json' },
{ decision: 'allow', pattern: 'Bash(npx prisma studio)', source: '.claude/settings.local.json' },
];
export const COMMANDS = [
'npm run test -- --run',
'npm run lint',
'npx prisma migrate dev',
'git push origin main',
'cat .env',
'npx prisma studio',
'npm install',
];
export function ruleMatches(pattern: string, command: string): boolean {
const m = /^(\w+)\((.*)\)$/.exec(pattern);
if (!m) return false;
const tool = m[1];
const arg = m[2];
if (tool === 'Read') {
const parts = command.split(' ');
return parts[0] === 'cat' && parts[1] === arg.replace(/^\.\//, '');
}
if (arg.endsWith(' *')) {
const prefix = arg.slice(0, -2);
return command === prefix || command.startsWith(prefix + ' ');
}
return command === arg;
}
export interface Verdict {
decision: Decision | 'mode';
rule?: Rule;
text: string;
}
export function decide(command: string, rules: Rule[], trusted: boolean): Verdict {
const order: Decision[] = ['deny', 'ask', 'allow'];
let skipped = false;
for (const decision of order) {
for (const r of rules) {
if (r.decision !== decision || !ruleMatches(r.pattern, command)) continue;
if (decision === 'allow' && !trusted && r.source === '.claude/settings.json') {
skipped = true;
continue;
}
const texts: Record<Decision, string> = {
deny: 'Refus. deny est examinée en premier et l’emporte sur tout allow, de n’importe quel fichier.',
ask: 'Claude Code demande l’accord. ask passe avant allow, donc un allow ne l’emportera pas.',
allow: 'Sans question.',
};
return { decision, rule: r, text: texts[decision] };
}
}
return {
decision: 'mode',
text: skipped
? 'La règle allow de .claude/settings.json attend la confiance du dossier, donc c’est le mode de permissions qui décide.'
: 'Aucune règle ne correspond, donc c’est le mode de permissions qui décide.',
};
}
const STATUS_CLASS: Record<Loaded['status'], string> = {
start: 'text-sky-300',
file: 'text-emerald-400',
no: 'text-slate-500',
};
const DECISION_CLASS: Record<Verdict['decision'], string> = {
deny: 'text-rose-400',
ask: 'text-amber-400',
allow: 'text-emerald-400',
mode: 'text-slate-300',
};
export default function App() {
const [file, setFile] = useState(FILES[1]);
const [apiPattern, setApiPattern] = useState('app/api/**/*.ts');
const [command, setCommand] = useState(COMMANDS[3]);
const [trusted, setTrusted] = useState(true);
const loaded = loadedFor(file, apiPattern);
const verdict = decide(command, RULES, trusted);
return (
<div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
<h1 className="text-xl font-bold">Règles de l’équipage dans Treasure Map</h1>
<section className="space-y-2">
<h2 className="font-semibold">Mémoire et règles pour un fichier</h2>
<label className="block text-sm">
Claude travaille sur le fichier{' '}
<select className="rounded bg-slate-800 p-1" value={file} onChange={(e) => setFile(e.target.value)}>
{FILES.map((f) => (
<option key={f} value={f}>{f}</option>
))}
</select>
</label>
<label className="block text-sm">
paths dans .claude/rules/api.md{' '}
<input className="rounded bg-slate-800 p-1 font-mono" value={apiPattern} onChange={(e) => setApiPattern(e.target.value)} />
</label>
<ul className="space-y-1 text-sm">
{loaded.map((l) => (
<li key={l.path} className="rounded border border-slate-800 p-2">
<strong className={STATUS_CLASS[l.status]}>{l.path}</strong> ({l.scope}): {l.note}
</li>
))}
</ul>
</section>
<section className="space-y-2">
<h2 className="font-semibold">Qui décide d’une commande</h2>
<div className="flex flex-wrap items-center gap-3 text-sm">
<select className="rounded bg-slate-800 p-1 font-mono" value={command} onChange={(e) => setCommand(e.target.value)}>
{COMMANDS.map((c) => (
<option key={c} value={c}>{c}</option>
))}
</select>
<label className="flex items-center gap-2">
<input type="checkbox" checked={trusted} onChange={(e) => setTrusted(e.target.checked)} />
j’ai accepté la fenêtre de confiance du dossier
</label>
</div>
<p role="status" className="rounded border border-slate-700 p-2 text-sm">
<strong className={DECISION_CLASS[verdict.decision]}>{verdict.decision}</strong>{' '}
{verdict.rule ? verdict.rule.pattern + ' du fichier ' + verdict.rule.source + '. ' : ''}
{verdict.text}
</p>
<ul className="font-mono text-xs text-slate-400">
{RULES.map((r, i) => (
<li key={i}>{r.decision} {r.pattern} ({r.source})</li>
))}
</ul>
</section>
</div>
);
}Tu as repéré une erreur dans cette leçon ?
Teste tes connaissances
Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.
1. Ces règles ne concernent que les routes de app/api de Treasure Map. Où les écrire pour que Claude ne les ait dans son contexte que lorsqu'il travaille sur ces fichiers ?
2. Quelle ligne vaut-il mieux supprimer du CLAUDE.md de Treasure Map ?
Voici 2 des 10 questions de cette leçon. Réponds aux autres dans le jeu.
Tâches pratiques dans le jeu
- Tri vertical
Ordonne les lignes du fichier .claude/rules/api.md de haut en bas, comme dans la leçon :
- Tri vertical
Ordonne les parties du CLAUDE.md court de Treasure Map de haut en bas : d'abord l'import, puis comment vérifier le travail, puis les pièges, et à la fin les décisions de l'équipage :
- Éditeur de code
Dans commands.sh, écris le script smart-commit.sh : prends le diff en staging (git diff --cached), demande à claude -p un message au format Conventional Commits, affiche-le, demande une confirmation (read) puis lance git commit -m.
- Tri vertical
Ordonne les fichiers CLAUDE.md de la portée la plus large à la plus étroite, c'est-à-dire dans l'ordre où Claude Code les met bout à bout dans le contexte :
- Éditeur de code
Dans commands.sh, écris le script generate-component.sh : prends le nom du composant dans $1 et demande à claude -p trois fichiers dans src/components : <Nom>.tsx, <Nom>.test.tsx et <Nom>.stories.tsx (Storybook).
- Tri vertical
La même clé se trouve dans plusieurs fichiers de réglages. Ordonne les sources de celle qui gagne à celle qui perd :
- Éditeur de code
Dans commands.sh, écris le script ai-search.sh : prends la requête dans les arguments du script ($1 ou "$*") et passe-la à claude -p pour que Claude trouve lui-même le code correspondant et indique les fichiers et les numéros de ligne.
- Tri vertical
Ordonne l'ordre dans lequel Claude Code examine les règles de permission pour un seul appel d'outil :
- Tri horizontal
Compose la règle ask qui oblige Claude Code à demander l'accord pour chaque commande de migration de Prisma :
- Clique dans l'ordre
Clique sur les éléments dans l'ordre pour vérifier quelle ligne de .gitignore cache tes notes privées :
- Clique dans l'ordre
Clique sur les éléments dans l'ordre pour composer un motif paths qui correspond à chaque fichier .ts de app/api, y compris dans les sous-dossiers :
Exercices après cette leçon
- QuestionQuiz : Règle pour les routes d'API
- Remets dans l'ordreTri : Fichier de règle avec chemins
- Remets dans l'ordreTri : Les parties du CLAUDE.md de Treasure Map
- Exercice de codePratique : générateur de messages de commit
- QuestionQuiz : Ligne à rayer de CLAUDE.md
- Remets dans l'ordreTri : Niveaux de mémoire du plus large
- Exercice de codePratique : générateur de composants
- QuestionQuiz : Notes privées dans le projet
- QuestionQuiz : Import et taille du contexte
- Remets dans l'ordreTri : Priorité des fichiers de réglages
- Exercice de codePratique : chercher du code avec une phrase
- QuestionQuiz : Règle ask et allow d'un autre fichier
- Remets dans l'ordreTri : Ordre d'examen des règles
- Remets dans l'ordreTri : Règle ask pour les migrations
- QuestionQuiz : Règle personnelle dans le projet
- Clique dans l'ordreClic dans l'ordre : Le fichier privé est-il caché
- QuestionQuiz : Source d'une règle de permission
- QuestionQuiz : Règles allow et confiance du dossier
- Clique dans l'ordreClic dans l'ordre : Motif paths pour les routes
- QuestionQuiz : Quand se charge une règle avec chemins
- QuestionQuiz : $1 et "$*" dans un script