---
description: Suivre les changements du rapport des paramètres Claude Code et trouver ce qui doit être mis à jour
argument-hint: [number of versions to check, default 10]
---

# Workflow Changelog — Rapport Settings

Tu es un coordinateur pour le projet claude-code-best-practice. Ta mission consiste à lancer deux agents de recherche en parallèle, attendre leurs résultats, fusionner les constats et présenter un rapport unifié sur la dérive du rapport **Settings Reference** (`best-practice/claude-settings.md`).

**Versions à vérifier :** `$ARGUMENTS` (par défaut : 10 si vide ou non numérique)

Il s’agit d’un workflow **lire puis rapporter**. Lance les agents, fusionne les résultats et produis un rapport. N’agis que si l’utilisateur approuve.

---

## Phase 0 : lancer les deux agents en parallèle

**Immédiatement**, lance les deux agents avec l’outil Task **dans le même message** (lancement parallèle) :

### Agent 1 : workflow-claude-settings-agent

Lance avec `subagent_type: "workflow-claude-settings-agent"`. Donne-lui ce prompt :

> Research the claude-code-best-practice project for settings report drift. Check the last $ARGUMENTS versions (default: 10).
>
> Fetch these 3 external sources:
> 1. Settings Documentation: https://code.claude.com/docs/en/settings
> 2. CLI Reference: https://code.claude.com/docs/en/cli-reference
> 3. Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
>
> Then read the local report file (`best-practice/claude-settings.md`) and the CLAUDE.md file. Analyze differences between what the official docs say about settings keys, permission syntax, hook events, MCP configuration, sandbox options, plugin settings, model aliases, display settings, and environment variables versus what our report documents. Return a structured findings report covering missing settings, changed types/defaults, new settings additions, deprecated settings, permission syntax changes, hook event changes, MCP setting changes, sandbox setting changes, environment variable completeness, example accuracy, settings hierarchy accuracy, and sources validity.

### Agent 2 : claude-code-guide

Lance avec `subagent_type: "claude-code-guide"`. Donne-lui ce prompt :

> Research the latest Claude Code settings system. I need you to find:
> 1. The complete list of all currently supported settings.json keys with their types, defaults, and descriptions
> 2. Any new settings keys introduced in recent Claude Code versions
> 3. Changes to existing settings behavior (e.g. new permission modes, new hook events, new sandbox options)
> 4. Changes to the settings hierarchy (new priority levels, new file locations)
> 5. Changes to permission syntax (new tool patterns, new wildcard behavior)
> 6. New hook events or changes to hook configuration structure
> 7. Changes to MCP server configuration (new matching fields, new settings)
> 8. Changes to sandbox settings (new network options, new commands)
> 9. Changes to plugin configuration (new fields, new marketplace options)
> 10. Changes to environment variables (new vars, deprecated vars, changed behavior)
> 11. Changes to model aliases or model configuration
> 12. Changes to display/UX settings (status line, spinners, progress bars)
> 13. Any deprecations or removals of settings keys
>
> Be thorough — search the web, fetch docs, and provide concrete version numbers and details for everything you find.

Les deux agents s’exécutent indépendamment et retourneront leurs constats.

---

## Phase 0.5 : lire la checklist de vérification

**Pendant que les agents s’exécutent**, lis `changelog/best-practice/claude-settings/verification-checklist.md`. Ce fichier contient les règles de vérification accumulées — chaque règle précise quoi vérifier, à quelle profondeur et contre quelle source. Chaque règle DOIT être exécutée pendant la Phase 2. La checklist est la suite de tests de régression du projet pour la détection de dérive.

---

## Phase 1 : lire les entrées précédentes du changelog

**Avant de fusionner les constats**, lis le fichier `changelog/best-practice/claude-settings/changelog.md` pour obtenir les 25 dernières entrées de changelog. Chaque entrée est séparée par `---`. Analyse les actions prioritaires des entrées précédentes afin de pouvoir les comparer aux constats actuels. Cela permet d’identifier :
- **Éléments récurrents** — problèmes déjà apparus et encore non résolus
- **Éléments nouvellement résolus** — problèmes des exécutions précédentes désormais corrigés
- **Nouveaux éléments** — problèmes apparaissant pour la première fois dans cette exécution

---

## Phase 2 : fusionner les constats et générer le rapport

**Attends que les deux agents terminent.** Une fois que tu as :
- **Constats de workflow-claude-settings-agent** — analyse détaillée du rapport avec lectures de fichiers locaux, récupération de docs externes et détection de dérive
- **Constats de claude-code-guide** — recherche indépendante sur les dernières fonctionnalités et changements des paramètres Claude Code

Croise les deux. L’agent dédié fournit l’analyse de dérive spécifique au rapport, tandis que claude-code-guide peut faire remonter des éléments qu’il a manqués (par exemple des changements très récents, des fonctionnalités non documentées ou du contexte issu de recherches web). Signale toute contradiction entre les deux pour résolution par l’utilisateur.

**Exécute la checklist de vérification :** pour chaque règle dans `changelog/best-practice/claude-settings/verification-checklist.md`, effectue la vérification à la profondeur indiquée en utilisant les constats des agents comme données source. Inclus une section **Verification Log** dans le rapport montrant le résultat de chaque règle :

```text
Verification Log:
Rule # | Category              | Depth         | Result | Notes
1      | Settings Keys         | field-level   | PASS   | All keys match
2      | Permission Syntax     | content-match | FAIL   | New tool pattern added
...
```

**Mets à jour la checklist si nécessaire :** si un constat révèle un nouveau type de dérive qu’aucune règle existante ne couvre (ou couvre à une profondeur insuffisante), ajoute une nouvelle règle à `changelog/best-practice/claude-settings/verification-checklist.md`. La règle doit inclure : catégorie, quoi vérifier, niveau de profondeur, source de comparaison, date d’ajout et origine (l’erreur ayant motivé cette règle). N’ajoute PAS de règles pour des problèmes ponctuels qui ne se reproduiront pas.

Compare aussi les constats actuels aux entrées précédentes du changelog (depuis la Phase 1). Pour chaque action prioritaire, marque-la comme :
- `NEW` — première apparition du problème
- `RECURRING` — déjà apparu lors d’une exécution précédente et encore non résolu (inclure la date de première apparition)
- `RESOLVED` — apparu lors d’une exécution précédente mais désormais corrigé (inclure la date de résolution)

Produis un rapport structuré avec ces sections :

1. **New Settings Keys** — Clés présentes dans la documentation officielle mais absentes du rapport, avec version d’introduction
2. **Changed Setting Behavior** — Paramètres dont le type, la valeur par défaut ou la description a changé
3. **Deprecated/Removed Settings** — Paramètres présents dans le rapport mais absents de la documentation officielle
4. **Permission Syntax Changes** — Nouveaux motifs d’outils, comportement de jokers ou changements de modes de permission
5. **MCP Setting Changes** — Nouvelles clés de configuration MCP, comportement de matching ou paramètres serveur
6. **Sandbox Setting Changes** — Nouvelles options de sandbox, paramètres réseau ou exclusions de commandes
7. **Plugin Setting Changes** — Nouvelles clés de configuration de plugin ou options marketplace
8. **Model Configuration Changes** — Nouveaux alias de modèles, niveaux d’effort ou variables d’environnement de modèles
9. **Display & UX Changes** — Nouveaux champs de status line, options de spinner ou paramètres d’affichage
10. **Environment Variable Completeness** — Variables présentes dans la documentation officielle mais absentes du rapport, ou variables du rapport qui ne sont plus documentées
11. **Settings Hierarchy Accuracy** — Vérifier niveaux de priorité, emplacements de fichiers et comportement de surcharge
12. **Example Accuracy** — Vérifier si l’exemple complet Quick Reference reflète les paramètres actuels
13. **Sources Accuracy** — Vérifier que tous les liens de sources sont valides et pointent vers la bonne documentation
14. **claude-code-guide Agent Findings** — Informations uniques de l’agent non capturées par l’agent dédié. N’inclus que les constats qui ajoutent une nouvelle information. S’il existe des contradictions entre les deux agents, signale-les pour résolution par l’utilisateur. Ne liste PAS les "confirmed agreements".

> **Note :** l’analyse liée aux hooks (événements, propriétés, matchers, codes de sortie, HTTP hooks, variables d’environnement de hooks) est **exclue** de ce workflow. Les hooks sont maintenus dans le dépôt [claude-code-hooks](https://github.com/shanraisshan/claude-code-hooks).

Termine par un tableau récapitulatif priorisé **Action Items**. Chaque élément doit inclure une colonne `Status` indiquant `NEW`, `RECURRING (first seen: <date>)` ou `RESOLVED` :

```text
Priority Actions:
#  | Type                  | Action                                    | Status
1  | New Setting           | Add <key> to <section> table               | NEW
2  | Changed Behavior      | Update <key> description                   | NEW
3  | Deprecated Setting    | Remove <key> from table                    | RECURRING (first seen: 2026-03-05)
4  | Permission Syntax     | Add new tool pattern syntax                | NEW
5  | Env Variable          | Add <var> to environment variables table   | NEW
7  | Example Update        | Update Quick Reference example             | NEW
```

Inclus aussi une section **Resolved Since Last Run** listant les éléments de l’exécution précédente qui ne sont plus des problèmes.

---

## Phase 2.5 : ajouter le résumé au changelog

**Cette phase est OBLIGATOIRE — exécute-la toujours avant de présenter le rapport à l’utilisateur.**

Lis le fichier `changelog/best-practice/claude-settings/changelog.md` existant, puis **ajoute** (ne remplace PAS) une nouvelle entrée à la fin. Le format de l’entrée doit être exactement :

```markdown
---

## [<YYYY-MM-DD HH:MM AM/PM PKT>] Claude Code v<VERSION>

| # | Priority | Type | Action | Status |
|---|----------|------|--------|--------|
| 1 | HIGH/MED/LOW | <type> | <action description> | <status> |
| ... | ... | ... | ... | ... |
```

**Format de statut — DOIT utiliser l’un de ces trois formats :**
- `COMPLETE (reason)` — l’action a été réalisée et résolue avec succès
- `INVALID (reason)` — le constat était incorrect, non applicable ou intentionnel
- `ON HOLD (reason)` — action différée, en attente d’une dépendance externe ou d’une décision utilisateur

Le `(reason)` est obligatoire et doit expliquer brièvement ce qui a été fait ou pourquoi.

**Règles d’ajout :**
- Toujours ajouter — ne jamais écraser ou remplacer les entrées précédentes
- La date et l’heure correspondent à l’exécution de la commande en Pakistan Standard Time (PKT, UTC+5) ; obtiens-les avec `TZ=Asia/Karachi date "+%Y-%m-%d %I:%M %p PKT"`. La version vient des constats de l’agent
- Si `changelog/best-practice/claude-settings/changelog.md` n’existe pas ou est vide, crée-le avec le tableau Status Legend (voir le haut du fichier), puis la première entrée
- Chaque entrée est séparée par `---`
- **Inclure uniquement les éléments de priorité HIGH, MEDIUM ou LOW** — omettre les éléments de priorité NONE (éléments ne nécessitant aucune action)

---

## Phase 2.6 : mettre à jour le badge Last Updated

**Cette phase est OBLIGATOIRE — exécute-la toujours immédiatement après la Phase 2.5, avant de présenter le rapport.**

Mets à jour le badge "Last Updated" en haut de `best-practice/claude-settings.md`. Exécute `TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT"` pour obtenir l’heure, encode-la pour URL (espaces en `%20`, virgules en `%2C`) et remplace la portion date du badge. Mets aussi à jour la version Claude Code dans le badge si elle a changé.

**Ne journalise PAS les mises à jour de badge comme action items dans le changelog ou le rapport.** La synchronisation du badge est une routine de chaque exécution, pas un constat.

---

## Phase 2.7 : valider tous les liens

**Cette phase est OBLIGATOIRE — exécute-la toujours après la Phase 2.6, avant de présenter le rapport.**

Scanne `best-practice/claude-settings.md` pour chaque lien (markdown `[text](url)` et URLs inline). Pour chaque lien :

1. **Liens de fichiers locaux** (chemins relatifs) : vérifier que le fichier existe au chemin résolu avec l’outil Read. Signaler tout lien cassé.
2. **URLs externes** (par exemple `https://code.claude.com/docs/en/settings`) : récupérer chaque URL avec WebFetch et vérifier qu’elle retourne une page valide (pas une 404 ni une redirection vers une page d’erreur). Signaler tout lien mort ou déplacé.
3. **Liens d’ancre** (par exemple `#section-name`) : vérifier que le titre cible existe dans le même fichier.

Inclus un **Hyperlink Validation Log** dans le rapport :

```text
Hyperlink Validation Log:
#  | Type     | Link                                          | Status | Notes
1  | Local    | ../                                            | OK     |
2  | External | https://code.claude.com/docs/en/settings       | OK     |
3  | External | https://www.schemastore.org/claude-code-settings.json | BROKEN | 404
...
```

**Si des liens sont cassés**, ajoute-les comme action items de priorité HIGH dans le rapport. Les liens cassés dégradent l’utilité du rapport et doivent être corrigés avant tout autre changement.

---

## Phase 3 : proposer d’agir

Après avoir présenté le rapport (et confirmé que le changelog et le badge ont été mis à jour), demande à l’utilisateur :

1. **Execute all actions** — Tout traiter (ajouter paramètres manquants, mettre à jour descriptions, corriger exemples)
2. **Execute specific actions** — L’utilisateur choisit les numéros à exécuter
3. **Just save the report** — Aucun changement

Pendant l’exécution :
- **Nouveaux paramètres** : ajouter à la section appropriée du tableau avec type, valeur par défaut et description corrects
- **Comportement modifié** : mettre à jour la description ou la valeur par défaut du paramètre dans le tableau
- **Paramètres dépréciés** : confirmer avec l’utilisateur avant suppression
- **Changements de syntaxe des permissions** : mettre à jour le tableau Permission Syntax avec les nouveaux motifs
- **Changements MCP** : mettre à jour la section MCP Settings
- **Changements sandbox** : mettre à jour la section Sandbox Settings
- **Changements plugin** : mettre à jour la section Plugin Settings
- **Changements de modèles** : mettre à jour la section Model Configuration
- **Changements d’affichage** : mettre à jour la section Display & UX
- **Changements de variables d’environnement** : ajouter/mettre à jour/supprimer des variables dans la section Environment Variables
- **Changements de hiérarchie des paramètres** : mettre à jour le tableau Settings Hierarchy
- **Mises à jour d’exemple** : mettre à jour l’exemple complet Quick Reference pour refléter les paramètres actuels
- **Liens cassés** : corriger ou remplacer les URLs cassées
- Après toutes les actions, relancer la vérification pour confirmer la cohérence

---

## Règles critiques

1. **Lancer les DEUX agents en parallèle** dans un seul message — jamais séquentiellement
2. **Attendre les deux agents** avant de générer le rapport
3. **Ne jamais deviner** les versions ou dates — utiliser les données des agents
4. **Les nouvelles clés de paramètres sont PRIORITAIRES** — elles nécessitent des mises à jour de tableaux et d’exemples
5. **Croiser les nombres de paramètres** — le nombre de paramètres dans chaque tableau doit correspondre à la documentation officielle
6. **Ne pas auto-exécuter** — toujours présenter le rapport d’abord
7. **TOUJOURS ajouter au changelog** — la Phase 2.5 est obligatoire. Ne jamais la sauter. Ne jamais écraser les entrées précédentes.
8. **Comparer avec les exécutions précédentes** — lire les 25 dernières entrées du changelog et marquer chaque action item comme NEW, RECURRING ou RESOLVED.
9. **TOUJOURS exécuter la checklist de vérification** — lire verification-checklist.md et exécuter chaque règle. Inclure un Verification Log dans le rapport. Ajouter de nouvelles règles quand un nouveau type de dérive est découvert.
10. **Les règles de checklist sont append-only** — ne jamais retirer ni affaiblir les règles existantes. Ajouter seulement de nouvelles règles ou augmenter les niveaux de profondeur.
11. **TOUJOURS mettre à jour le badge Last Updated** — la Phase 2.6 est obligatoire. Ne jamais la sauter.
12. **TOUJOURS valider tous les liens** — la Phase 2.7 est obligatoire. Ne jamais la sauter. Les liens cassés sont prioritaires HIGH.
13. **Les variables d’environnement sont réparties entre deux fichiers** — `claude-settings.md` possède les variables configurables via `env` ; `claude-cli-startup-flags.md` possède les variables uniquement au démarrage. Ne PAS signaler une variable env comme manquante si elle appartient au fichier CLI. Croiser avec `best-practice/claude-cli-startup-flags.md` pour vérifier les frontières de responsabilité.
14. **Vérifier la hiérarchie des paramètres** — la chaîne de surcharge à 5 niveaux plus la couche de politique managed doivent correspondre exactement à la documentation officielle.
