# Claude Code - Des slash commands à un workflow en couches > Comment le dossier .claude/ de ce blog est passé d'une poignée de slash commands à un ensemble de commands, hooks, skills, agents et rules qui travaillent ensemble — un parcours d'apprentissage concret, et les cas où un script déterministe bat une question posée à l'IA. ---  **TL;DR** Le dossier `.claude/` de ce blog est passé, en quelques mois, d'une poignée de slash commands à un système à cinq couches : des commands que vous tapez, des hooks qui bloquent ou approuvent automatiquement de façon déterministe, des skills qui encodent ce que « bon » veut dire, des agents qui le vérifient dans un contexte isolé, et des rules qui imposent la version courte automatiquement. Cet article suit l'ordre dans lequel tout a réellement été construit, à quoi sert chaque couche, un exemple réel de chacune, et pourquoi un simple script Bash — sans la moindre IA — est parfois la meilleure brique possible. Comme tout débutant, mes premières sessions Claude Code sur ce blog commençaient toutes de la même façon, jour après jour : je réexpliquais, dans le chat, à quoi ressemble un bon script Bash ici, ce qu'un Dockerfile ne doit jamais faire, ou comment numéroter un nouveau fichier TODO sans entrer en collision avec un existant. Claude faisait le travail, mais c'était moi qui portais le règlement — retapé, session après session. Mon dossier `.claude/` ne ressemble plus du tout à ce qu'il était. Aujourd'hui, il contient 15 slash commands, 4 agents reviewers en lecture seule, 10 skills, 3 rules toujours actives, et quelques scripts Bash qui ne touchent jamais à l'IA. Rien n'est arrivé d'un coup — chaque couche est apparue pour résoudre un problème que la précédente ne savait pas traiter. ## À quoi ressemblent ces cinq couches en pratique {#what-five-layers-look-like-in-practice} Cinq ingrédients rendent tout cela possible, et chacun a sa propre section plus bas — voici juste la version courte, pour que la démo qui suit ne ressemble pas à une soupe d'acronymes : **Cinq mots à garder en tête** * **Command** — ce que vous tapez vous-même (`/quelquechose`). * **Skill** — une checklist que Claude lit de lui-même, sans qu'on la lui demande. * **Agent** — exécute cette checklist dans sa propre fenêtre séparée et restreinte, loin de votre conversation principale. * **Rule** — se charge automatiquement dès qu'un fichier correspondant est ouvert. * **Hook** — peut bloquer une action net, sans négociation possible. Deux de ces cinq n'attendent jamais un humain : une **rule** se charge à l'instant où un fichier correspondant s'ouvre, et un **hook** se déclenche à chaque appel d'outil correspondant — rien à taper, et Claude n'a pas voix au chapitre. Les trois autres se déclenchent à la main, et s'enchaînent comme le montre la démo ci-dessous : vous tapez une **command**, la command appelle un **agent**, et l'agent applique une **skill** pour rendre le verdict — sachant, comme expliqué plus loin, qu'une skill peut aussi se charger toute seule quand sa description colle à la tâche en cours, sans aucune command dans la boucle. Voici à quoi ressemble aujourd'hui une lecture critique d'un article de blog, une fois les cinq couches en place, avant même sa publication : > */review:reader git-precommit* On n'a plus besoin de réexpliquer à Claude ce que « bon » veut dire pour un article de ce blog — la skill `reader-first-docs` le détaille déjà, et `/review:reader` l'applique directement : quelle part de l'article se trouve entre `` et la première vraie preuve — une sortie de commande réelle, pas seulement une étape d'installation ? > `git-precommit` — sortie réelle dix lignes après ``, soit environ 7 % du corps > de l'article. Largement sous le seuil vert de 15 %, rien d'installé ni d'expliqué avant. > Verdict : OK, rien à restructurer. Cette checklist — mettre la valeur en avant, marquer les approfondissements comme optionnels, garder l'installation hors de la première moitié — n'a jamais eu à être retapée, des mois après avoir été écrite une première fois. Et un détail à souligner avant tout le reste : toutes les commands de ce workflow ne reposent pas sur Claude. `/todos:add`, la command qui ajoute une nouvelle entrée au backlog, a d'abord besoin du prochain ID libre — un pur problème de comptage. Plutôt que de demander au modèle de parcourir `.todos/` et de compter, elle appelle un simple script : ```bash $ .claude/scripts/todo_next_id.sh .todos 0105 ``` > **Bonne pratique : un script vaut mieux qu'un prompt:** > > Dès qu'une étape relève de la pure logique — compter des fichiers, incrémenter un ID, parser une > date, vérifier un verrou — écrivez-la comme un simple script et faites-le appeler par la command. > C'est déterministe (la même entrée donne toujours la même sortie), ça coûte zéro token, et ça se > teste tout seul, sans modèle dans la boucle. Gardez l'IA pour les étapes qui demandent vraiment du > jugement. ## Pourquoi une organisation en couches fonctionne {#why-a-layered-setup-works} * **Une seule couche se tape.** Les slash commands sont le seul élément auto-découvrable — l'autocomplétion les trouve. Skills, rules, agents et hooks restent invisibles jusqu'à ce que quelque chose les déclenche ; ils façonnent *la manière* dont Claude travaille sans alourdir ce que vous devez penser à invoquer. * **Chaque couche répond à une question différente.** Une skill décide *ce que* « bon » veut dire. Un agent décide *qui* le vérifie, et dans quel isolement. Une rule décide *quand* la version courte s'applique automatiquement. Un hook décide *ce qui est tout simplement interdit* — aucun jugement, aucune façon de faire changer le modèle d'avis. * **Les agents en lecture seule gardent le bruit de review hors de la conversation qui compte.** C'est une économie de tokens qui vient de l'architecture, pas de la discipline de prompting — un bon complément aux astuces de gestion de session de [une précédente série de conseils pour économiser des tokens](/blog/claude-ia-spare-tokens), centrée sur `/clear`, `/compact` et la taille de `CLAUDE.md`. * **Une rule n'est volontairement pas une explication complète.** C'est un extrait compressé DO/DON'T de la skill sœur, chargé uniquement quand un fichier correspondant est réellement ouvert — le raisonnement complet reste à un clic, pas dans chaque fenêtre de contexte. * **La couche la moins chère de toutes n'appelle pas le modèle.** Un simple script, comme ci-dessus, est le socle sur lequel tout le reste se construit. ## Commencez ici : votre première slash command {#start-here-your-first-slash-command} Les slash commands ont été le point d'entrée facile, et elles le restent — un fichier Markdown avec un petit en-tête frontmatter, détecté automatiquement dès qu'il atterrit dans `.claude/commands/`. Par exemple, créez simplement le fichier `.claude/commands/pr-description.md` dans votre projet avec ce contenu : **.claude/commands/pr-description.md** ```markdown --- description: Draft a pull-request description from the current branch's diff against main argument-hint: "[base-branch] (optional — defaults to main)" allowed-tools: Bash(git diff*), Bash(git log*), Read --- # PR description Look at `git diff $ARGUMENTS...HEAD` and `git log $ARGUMENTS...HEAD --oneline`. Draft a pull-request description: a one-paragraph summary of the "why", then a bulleted "what changed". Do not include a test plan unless the diff touches test files. ``` Tapez maintenant `/pr-description` dans une session Claude Code, et ce prompt s'exécute avec le diff courant déjà sous les yeux — rien à retenir, rien à réexpliquer. Deux détails du fichier ci-dessus comptent plus qu'ils n'y paraissent : * **`argument-hint`** est ce que l'autocomplétion affiche avant même que vous ayez fini de taper la command — de la documentation à bas prix pour votre futur vous. * **`allowed-tools`** limite le rayon d'action avant que la command ne s'exécute. Celle-ci peut lire l'historique Git et des fichiers, et rien d'autre — elle ne peut rien modifier, même par erreur. Trois commands réelles issues du dossier `.claude/commands/` de ce blog montrent la même forme à différentes tailles. `/review:bash` est à peine plus qu'un pointeur vers l'agent traité plus loin dans cet article : **.claude/commands/review/bash.md** ```markdown --- description: Audit this project's Bash scripts against the bash-best-practices skill (read-only) argument-hint: "[path] (optional — defaults to the whole project)" allowed-tools: Agent --- # Bash review Invoke the `bash-best-practices-reviewer` agent to audit **$ARGUMENTS** (or the whole project if no argument is given) against the `bash-best-practices` skill, and against this project's own bash-conventions rule/skill too, if it ships one. Read-only: the agent reports violations with file:line, it never edits. ``` `/links` maintient la convention de maillage interne de ce blog — 2 à 4 liens inline par article, plus un lien réciproque dans l'article plus ancien vers lequel il pointe : **.claude/commands/links.md** ````markdown --- description: Add missing internal links to an article (inline, in the prose) and the reciprocal link in the older post. argument-hint: "[path or slug of an article — omit to use the articles changed in the working tree]" allowed-tools: Read, Glob, Grep, Bash, Edit --- # Add internal links to an article The blog's cross-linking rule lives in `AGENTS.md` ("Blog Content Guidelines" → Internal links): every article carries **2 to 4 internal links, inline in the prose**, plus a reciprocal link in the older article when it makes sense. The `internal-links` job of `.github/workflows/quality.yml` flags articles that link nowhere; this command is the fix. ## 1. Decide which articles to work on `$ARGUMENTS` may be an article folder (`blog/2026/07/27/reactions`), an `index.md`, a slug (`reactions`), or a `.unpublished/` draft. A slug has to be resolved first: ```bash grep -rl "^slug: $ARGUMENTS$" blog .unpublished --include=index.md --include=index.mdx ``` If `$ARGUMENTS` is empty, work on the articles currently modified or added in the working tree: ```bash git status --porcelain -- 'blog/**/index.md*' '.unpublished/**/index.md*' | awk '{print $NF}' ``` If that is empty too, fall back to the last commit (`git diff --name-only --diff-filter=ACM HEAD~1 HEAD -- 'blog/**/index.md*' '.unpublished/**/index.md*'`) and, before editing anything, tell the user which articles you picked. ## 2. Run the check ```bash yarn links:check ``` It prints the internal links already present, marks with `!!` any link pointing to no published article (a wrong slug — fix those), and lists candidate targets ranked by score. When the local AnythingLLM instance answers, the output carries a second signal, **meaning**: - each word-based candidate gets a `meaning: close (0.xx)` or `meaning: not close` line, and the close ones are listed first — a `not close` candidate matched on words only ("command line", "file") and is usually noise; - a final list, *Close in meaning, not linked*, names articles about the same topic that the word-based pass missed, with the section of this article they relate to — the place a link would go. If that block is missing, AnythingLLM is off: the lexical list alone is still valid. A stale index (`ai-index` not run since the latest posts) can miss recent articles as targets. ## 3. Choose the links — judgment, not the score **The candidate list is a hint, not a spec.** It ranks on shared words and tags, so it happily proposes four unrelated posts that merely say "docker image", while missing the one link the prose is begging for. The meaning signal narrows that gap; it does not close it. So: - Read the article. Look for the moments where it *names* something covered elsewhere: a tool, a prerequisite, a concept explained in an earlier post, a natural follow-up. - Cross-check the memory blog map (`/home/node/.claude/projects/-opt-docusaurus/memory/project_blog_map.md`) for same-`mainTag` and same-series posts the script may have scored too low. - Aim for 2 to 4 links. Prefer few and relevant over many and weak — a link the reader does not need is noise, and this rule exists to help readers, not to satisfy a counter. - If the article genuinely has no relevant neighbour, say so instead of forcing a link. ## 4. Insert them - Inline, **at the first place the term appears in the prose**. Never a "See also" list at the end: the `RelatedPosts` grid already covers the bottom of the page. - Use the globally registered component, no import needed: `the natural words already in the sentence`. - Do not rewrite the sentence around the link, and do not add a sentence just to host one. If no sentence can host it naturally, that link was not the right one. - Never link inside a fenced code block, a heading, or frontmatter. - Add the **reciprocal link** in the older article when it fits its prose — that is what keeps old posts alive. Same rules apply there. ## 5. Verify ```bash yarn links:check # for each article touched, including the reciprocal ones ``` Every link must point to an existing slug (no `!!` lines). If several articles were edited, or if any doubt remains on a slug, run `npx docusaurus build` — it fails on broken internal links. ## 6. Report For each article: the links added, with the anchor text and the target slug, and where the reciprocal link went. Mention explicitly any article you deliberately left with fewer than two links, and why. ```` Et `/todos:add` est la command derrière le script `todo_next_id.sh` vu plus haut — sa ligne `allowed-tools` nomme explicitement le script, si bien que la command peut l'appeler mais rien d'autre : **.claude/commands/todos/add.md** ````markdown --- description: Capture a new task into the .todos/ backlog as one well-formed NNNN-slug.md file argument-hint: allowed-tools: Bash(ls*), Bash(find*), Bash(.claude/scripts/todo_next_id.sh*), Read, Write --- # Add a TODO to the backlog Capture the task described in **$ARGUMENTS** as a single, well-formed backlog file. Do NOT implement anything — this only creates the entry. The header bullets below follow the **`todo-authoring`** skill's contract — load it if any field's meaning is unclear (e.g. what counts as a valid `Depends` value). ## Procedure 1. **Resolve the description.** - If `$ARGUMENTS` is empty, ask the user for a one-line task description and stop until you have it. - Derive a concise Title (imperative, ≤ ~10 words) and a kebab-case `slug` (lowercase, alphanumerics + dashes, no leading article, ≤ ~6 words). 2. **Locate the backlog.** - Use `.todos/` at the repository root. If it doesn't exist, create it. 3. **Dedupe (cheap guard).** - List existing `.todos/*.md` and read their Titles (first `# ` heading). - If the new task clearly duplicates an existing entry, STOP and tell the user which file already covers it — don't create a second one. 4. **Compute the next ID.** - Run `.claude/scripts/todo_next_id.sh .todos` — it scans every `.todos/*.md` file (including status subfolders and any numeric-prefixed name like `000_...`) and prints `max + 1`, zero-padded to 4 digits (`NNNN`). Never compute this by hand, and never reuse an existing ID. (Legacy 3-digit IDs from before this width change stay as they are — never rename them.) 5. **Write `.todos/NNNN-.md`** with the skeleton below. The filename is an **identity**: never encode priority, status, or batch in it. ```markdown # NNNN —