codev

Le développement piloté par les specs pour Claude Code.

codev ajoute une fine couche de spécifications à un dépôt, pour que vous et votre agent de code vous accordiez sur ce qu’il faut construire avant d’écrire la moindre ligne — et pour que les décisions d’architecture, une fois prises, cessent d’être remises en débat à chaque change.

L’outil se compose de deux moitiés :

codev init installe les skills dans .claude/skills/. Dès lors, vous travaillez surtout dans le chat, et les skills pilotent la CLI à votre place.

codev n’appelle jamais de modèle de langage. Il gère des fichiers Markdown, le graphe de dépendances entre les artefacts de planification, la validation et la fusion des modifications de specs. Votre agent rédige ; codev lui indique quoi écrire, où, et sous quelles contraintes.

Pourquoi codev

Dans un dépôt sans specs, l’intention n’existe que dans la tête des gens. Le code s’écrit d’un côté, se relit de l’autre, et six mois plus tard quelqu’un fouille l’historique des commits pour retrouver pourquoi un comportement existe. codev inverse la démarche : pour chaque change significatif, vous commencez par écrire ce que vous voulez, vous le relisez, puis vous l’implémentez.

Ce que codev vous apporte :

• Un cycle explicite. Chaque change passe par quatre étapes : propose, apply, sync et archive. Chaque étape a son artefact et sa skill Claude Code dédiée. Voir Le workflow.
• Des deltas de specs, fusionnés avec précision. Un change ne réécrit jamais une spec en entier. Il déclare des exigences ADDED, MODIFIED, REMOVED ou RENAMED, que codev fusionne dans les specs principales à l’archivage du change, sans toucher au reste du fichier. C’est ce qui rend codev utilisable sur du code existant, et pas seulement sur des projets neufs.
• Des décisions d’architecture immuables. Les décisions acceptées (ADR) sont scellées par une empreinte de leur contenu. codev validate signale toute réécriture silencieuse. On ne modifie pas une décision : on la remplace par une nouvelle.
• Des conventions partagées entre dépôts. Un projet peut hériter du contexte, des règles et des décisions d’un autre dépôt, en lecture seule, épinglés sur un commit git. Voir Sources héritées.
• La langue de votre équipe. Les artefacts sont rédigés dans la langue définie dans la configuration, tandis que leur structure reste lisible par la machine. Voir Langue des artefacts.
• Un binaire natif unique. Aucun environnement d’exécution à installer. Des binaires précompilés pour macOS, Linux et Windows, vérifiés par SHA-256 à l’installation.

Origines

codev s’inspire d’OpenSpec (MIT), l’outil TypeScript qui a popularisé un cycle de développement piloté par les specs pour les agents de code. codev en reprend l’ossature, la reconstruit en Rust et fait ses propres choix par-dessus.

Ce que codev doit à OpenSpec :

• Le cycle propose → apply → archive, et l’idée que le change est l’unité de travail.
• Les deltas de specs et leurs quatre opérations lisibles — ADDED, MODIFIED, REMOVED, RENAMED.
• La notion de capacité, qui regroupe un comportement observable plutôt que des fichiers ou des modules.
• Des workflows et des templates traités comme des données, et non comme du code.

Ce que codev fait autrement :

• Un binaire Rust plutôt qu’un paquet Node.js. Un exécutable précompilé, sans environnement d’exécution.
• Un dossier _codev/ visible. Les artefacts de planification sont des fichiers sources à part entière : vous les lisez, les comparez et les relisez. Le tiret bas initial laisse le dossier visible pour des outils comme ripgrep et fd, qui ignorent par défaut les répertoires cachés.
• Un cœur pur et une coquille impérative. La bibliothèque centrale n’effectue aucune entrée-sortie ; chacune de ses décisions se teste sans disque. Voir Architecture.
• Une seule cible, bien servie. codev cible uniquement Claude Code, là où OpenSpec prend en charge de nombreux outils.

Ce qui est propre à codev :

• Des décisions d’architecture scellées, avec remplacement, écarts locaux par rapport aux décisions héritées, et promotion d’une décision de design en ADR.
• Des sources héritées en lecture seule, épinglées par commit git dans _codev/codev.lock.
• Une intégration MCP côté skills : /codev-propose détecte un identifiant de ticket comme PROJ-123 et récupère le ticket via le serveur MCP Jira configuré pour le projet.
• Un contrat JSON versionné sur chaque commande, pour que les skills puissent s’appuyer sur un format de sortie stable.
• Une documentation embarquée dans le binaire (codev docs), consultable hors ligne.

Développé avec codev

codev est développé avec codev : chaque évolution de son dépôt est planifiée, relue et archivée avec l’outil lui-même. Son dossier _codev/ est un exemple réel que vous pouvez parcourir :

• les specs vivantes, qui décrivent ce que fait codev aujourd’hui ;
• les changes archivés, chacun avec son proposal, ses deltas de spec, son design et ses tâches ;
• un compte rendu de revue, avec les remarques, leurs preuves, les réponses de l’auteur et la façon dont chacune a été tranchée ;
• les décisions d’architecture, scellées.

Pour aller plus loin

• Vous découvrez codev ? Commencez par l’Installation, puis le Démarrage rapide.
• Vous voulez comprendre le modèle ? Lisez Le workflow et Concepts.
• Vous cherchez une option ou une clé ? Consultez la référence de la CLI et la référence de la configuration.

Installation

codev est un binaire unique. Des binaires précompilés sont publiés sur GitHub Releases pour les plateformes suivantes :

Il existe quatre façons de l’installer. Les deux premières sont les plus rapides et ne nécessitent pas Rust.

macOS et Linux : install.sh

curl -sSL https://raw.githubusercontent.com/mairistem/codev/main/install.sh | sh

Le script détecte votre système et votre architecture, télécharge l’archive correspondante et le fichier SHA256SUMS depuis la dernière GitHub Release, vérifie l’empreinte SHA-256 de l’archive et installe le binaire dans ~/.local/bin/codev. Il refuse d’installer si l’empreinte ne correspond pas, et crée ~/.local/bin si nécessaire.

Si ~/.local/bin n’est pas dans votre PATH, le script affiche la ligne exacte à ajouter à ~/.zshrc ou ~/.bashrc :

export PATH="$HOME/.local/bin:$PATH"

Pour installer une version précise, définissez CODEV_VERSION :

curl -sSL https://raw.githubusercontent.com/mairistem/codev/main/install.sh | CODEV_VERSION=0.6.1 sh

Le script nécessite curl, tar, ainsi que sha256sum ou shasum.

Windows : install.ps1

Dans PowerShell 5.1 ou ultérieur (PowerShell 7 compris) :

iwr -useb https://raw.githubusercontent.com/mairistem/codev/main/install.ps1 | iex

Le script télécharge l’archive .zip et SHA256SUMS, vérifie l’archive avec Get-FileHash et copie codev.exe dans %LOCALAPPDATA%\Programs\codev\.

Il ne modifie pas votre PATH. Si le dossier est absent du PATH de votre utilisateur, il affiche la commande pour l’y ajouter :

[Environment]::SetEnvironmentVariable('PATH', [Environment]::GetEnvironmentVariable('PATH', 'User') + ";$env:LOCALAPPDATA\Programs\codev", 'User')

Cette commande ne modifie que le PATH utilisateur. Évitez setx PATH "$env:PATH;..." : cette commande tronque les valeurs de plus de 1 024 caractères et recopie le PATH de la machine dans le PATH utilisateur. Ouvrez ensuite une nouvelle fenêtre PowerShell pour que la modification prenne effet.

Pour installer une version précise :

$env:CODEV_VERSION = '0.6.1'
iwr -useb https://raw.githubusercontent.com/mairistem/codev/main/install.ps1 | iex

Sous Windows, seule l’architecture x86_64 (AMD64) est disponible en binaire précompilé. Sur ARM64, compilez depuis les sources.

Téléchargement manuel depuis GitHub Releases

Si vous préférez ne pas exécuter un script directement dans votre shell, téléchargez vous-même les fichiers depuis la dernière release. Chaque release contient une archive par cible, nommée codev-<version>-<target>.tar.gz (.zip sous Windows), ainsi qu’un fichier SHA256SUMS.

macOS et Linux. Téléchargez votre archive et SHA256SUMS dans le même dossier, puis :

# Vérifier l'empreinte — sur macOS : shasum -a 256 -c SHA256SUMS --ignore-missing
sha256sum -c SHA256SUMS --ignore-missing

tar -xzf codev-*.tar.gz
mkdir -p ~/.local/bin
cp codev-*/codev ~/.local/bin/
chmod 755 ~/.local/bin/codev

Windows. Téléchargez codev-<version>-x86_64-pc-windows-msvc.zip et SHA256SUMS, puis dans PowerShell :

# Vérifier l'empreinte
$zip = Get-Item codev-*-x86_64-pc-windows-msvc.zip
$expected = (Select-String -Path SHA256SUMS -Pattern $zip.Name).Line.Split(' ')[0]
$actual = (Get-FileHash $zip -Algorithm SHA256).Hash.ToLower()
if ($actual -ne $expected) { throw "SHA-256 mismatch" }

# Extraire et installer
Expand-Archive $zip -DestinationPath .
$dst = "$env:LOCALAPPDATA\Programs\codev"
New-Item -ItemType Directory -Path $dst -Force | Out-Null
Copy-Item codev-*\codev.exe $dst

Ajoutez ensuite le dossier au PATH de votre utilisateur comme indiqué plus haut.

Depuis les sources : cargo install

Avec une chaîne d’outils Rust (1.89 ou ultérieure), vous pouvez compiler codev à partir d’un clone du dépôt. C’est la voie à suivre pour les contributeurs et pour les plateformes sans binaire précompilé.

git clone https://github.com/mairistem/codev.git
cd codev
cargo install --path crates/codev-cli

Le binaire est installé dans ~/.cargo/bin/codev.

Vérifier l’installation

codev --version

Sous macOS et Linux, command -v codev indique quel binaire votre shell exécute. Sous Windows, utilisez Get-Command codev. Si la commande est introuvable, le dossier d’installation n’est pas dans votre PATH ; reportez-vous aux instructions ci-dessus pour votre plateforme.

Complétion du shell

codev completions <SHELL> écrit sur la sortie standard un script de complétion pour bash, zsh, fish, powershell ou elvish :

# bash
codev completions bash > ~/.local/share/bash-completion/completions/codev

# zsh — puis lancez `compinit`
codev completions zsh > "${fpath[1]}/_codev"

# fish
codev completions fish > ~/.config/fish/completions/codev.fish

# PowerShell, session en cours
codev completions powershell | Out-String | Invoke-Expression

Prérequis

• Claude Code, pour utiliser les skills. La CLI elle-même fonctionne sans.
• git, uniquement pour les sources héritées hébergées dans un dépôt git.

Mise à jour

Lancez codev self-update :

codev self-update                  # demande confirmation dans un terminal
codev self-update --check          # indique seulement la version installée et la plus récente
codev self-update --version 0.5.0  # une version précise, rétrogradation comprise

La commande télécharge la release la plus récente pour votre plateforme, vérifie son SHA-256 avec le SHA256SUMS de la release — comme le font les installateurs — et remplace le binaire sur place. Ensuite, dans un projet codev, elle lance codev update avec le nouveau binaire. Elle a besoin de curl et de tar, fournis par macOS, la plupart des distributions Linux et Windows 10 ou ultérieur.

codev self-update ne remplace qu’un binaire installé par install.sh, install.ps1 ou à la main. Si codev a été installé avec cargo install, compilé depuis un clone ou installé par un gestionnaire de paquets, elle affiche la commande qui le met à jour et ne modifie rien. Elle ne rétrograde jamais, sauf si vous passez --version. Sous Windows, l’ancien binaire est conservé sous le nom codev.old.exe à côté du nouveau, jusqu’à ce que la commande codev suivante le supprime.

codev status vous signale l’existence d’une release plus récente, au plus une fois par jour ; voir codev vérifie-t-il les mises à jour ? pour le désactiver.

Vous pouvez toujours relancer l’installateur ou télécharger une release plus récente. Ensuite, dans chaque projet, régénérez les skills pour qu’elles correspondent à la nouvelle version :

codev update

codev update rafraîchit aussi les sections gérées par codev dans CLAUDE.md et dans le modèle de pull request, ainsi que la version de codev épinglée dans .github/workflows/codev.yml, là où codev init les a écrites. Consultez codev update pour savoir comment sont traitées les skills modifiées à la main, et codev doctor pour vérifier le résultat.

Démarrage rapide

Ce chapitre vous mène d’un dépôt vide à votre premier change archivé en cinq minutes environ. Il suppose que codev est installé et que vous utilisez Claude Code.

Chaque étape présente d’abord la méthode Claude Code (recommandée), puis son équivalent en CLI pure, pour que vous voyiez ce que font les skills en coulisses. Les sorties de commandes ci-dessous sont réelles ; seul le chemin du projet a été raccourci en /home/you/acme-app.

1. Initialiser le projet

À la racine de votre dépôt :

codev init

Dans un terminal, codev init pose au plus deux questions — quels workflows installer, et un contexte libre destiné aux skills — puis écrit les fichiers. Passez --yes pour accepter toutes les valeurs par défaut sans question, comme dans l’exécution suivante :

codev init --yes --language fr

codev initialized in /home/you/acme-app

  Structure   _codev/ — specs, decisions, changes, schemas
  Skills      codev-propose, codev-explore, codev-onboard, codev-apply, codev-sync, codev-archive, codev-update, codev-configure → .claude/skills/

  Repository integration
    + CLAUDE.md                          created
    + .github/workflows/codev.yml        created
    + .github/PULL_REQUEST_TEMPLATE.md   created

  17 file(s) created, 0 updated

→ Recommended next step: in Claude Code, run /codev-configure.
  Claude will analyze the project and enrich _codev/config.yaml
  (context, per-artifact rules) — ~30 seconds.

Or skip this step and run /codev-propose <an-idea> directly.

Run `codev doctor` to see the 2 setup check(s) still to fix.

Ce dépôt a un remote GitHub : codev a donc aussi écrit un workflow de CI et un modèle de pull request ; voir l’étape 5 ci-dessous.

Redémarrez Claude Code (ou ouvrez une nouvelle session) pour qu’il découvre les nouvelles skills.

Ce que fait codev init

1. Il sonde l’environnement, sans rien afficher : manifestes du projet (Cargo.toml, package.json, pyproject.toml, go.mod, pom.xml), fichier de licence, présence de .github/workflows/, votre locale, et les serveurs MCP déclarés dans .mcp.json, .claude/settings.json et ~/.claude.json. --no-detect désactive cette détection.

2. Il pose au plus deux questions lorsqu’il s’exécute dans un terminal : quels workflows installer (complet, minimal ou personnalisé), et un contexte libre pour les skills. Une réponse vide à la question du contexte ouvre $EDITOR sur un squelette. Un serveur MCP Jira détecté est simplement confirmé, sans question. Avec --yes, ou lorsque l’entrée standard n’est pas un terminal (CI, pipes), aucune question n’est posée.

3. Il crée l’arborescence _codev/ — specs/, decisions/, changes/, changes/archive/, schemas/ — ainsi qu’un fichier _codev/config.yaml dans lequel chaque valeur détectée est accompagnée d’un commentaire indiquant sa provenance :

   # codev configuration — generated by `codev init`.
   # Hand-editable: each non-trivial field carries its source as a comment.
   
   schema: spec-driven
   
   # Language of the prose skills write in artifacts (proposal, design,
   # tasks, specs). Structural keywords such as `## Why` or
   # `### Requirement:` always stay in English.
   # set with `codev init --language`
   language: fr
   
   workflows:
     - propose
     - explore
     - onboard
     - apply
     - sync
     - archive
     - update
     - configure
   

4. Il installe les skills dans .claude/skills/codev-<workflow>/SKILL.md.

5. Il intègre codev au dépôt, sauf si vous le refusez :

   • une section codev dans CLAUDE.md, créé s’il n’existe pas, qui indique à Claude Code que les specs font foi et que tout changement de comportement passe par /codev-propose puis /codev-apply ;
   • sur GitHub, .github/workflows/codev.yml, qui exécute codev validate --strict à chaque push et pull request ;
   • sur GitHub, une section codev dans le modèle de pull request.

   Le texte de codev se trouve entre les marqueurs <!-- codev:begin --> et <!-- codev:end --> et ne remplace jamais le vôtre. --no-claude-md, --no-ci, --no-pr-template et --no-integration écartent ces fichiers. Voir Intégration au dépôt et codev doctor.

6. Il déclare les sources héritées passées avec --inherit, et épingle aussitôt les sources git. Voir Sources héritées.

Si _codev/config.yaml existe déjà, codev init n’y touche pas : il se contente d’installer ou de rafraîchir les skills et l’intégration au dépôt.

codev doctor liste ensuite ce qui manque encore à l’installation — ici, des règles et une première spec — avec la commande ou la skill qui corrige chaque point :

codev doctor

codev doctor — /home/you/acme-app

Configuration
  ✗ config.rules     no rules: in _codev/config.yaml
      fix: /codev-configure
  ✓ config.language  language: is set
  ✓ config.keys      no unknown key in _codev/config.yaml
  ✓ config.roles     active roles: analyst, investigator, product, qa, architect, lead, tracer, skeptic, developer, newcomer; on domain: security (security), privacy (personal-data), accessibility (user-interface), performance (performance), ops (operations), migration (migration); disabled: none
  ✓ skills           8 skill(s) installed and current
  ✓ sources          no inherited git source
  ✓ codev_version    no newer codev release known

Planning
  ✗ specs            no main spec in _codev/specs/
      fix: /codev-propose <a change> — documenting existing behavior is planned work too
  ! decisions        no accepted decision (not every project needs one)
      fix: codev decision new "<title>"
  ✓ validate         codev validate reports no issue

Repository
  ✓ claude_md        CLAUDE.md has the codev section
  ✓ ci               .github/workflows/codev.yml runs codev validate
  ✓ pr_template      the pull request template has the codev section
  ! changelog        no CHANGELOG.md
      fix: codev changelog --write

14 check(s), 2 to fix, 2 warning(s)

Remarque L’étape suivante recommandée, /codev-configure, laisse Claude lire votre README, votre guide de contribution et un échantillon de votre code, puis proposer un context: plus riche et des rules: par artefact pour la configuration. La skill affiche un diff et n’écrit rien sans votre confirmation.

2. Proposer un change

Dans Claude Code, décrivez ce que vous voulez :

/codev-propose add a dark mode that follows the system preference

La skill choisit un nom en kebab-case (ici add-dark-mode), crée le change, puis rédige ses quatre artefacts de planification dans l’ordre des dépendances : proposal.md, les deltas de specs sous specs/, design.md et tasks.md. Elle ne modifie aucun code et s’arrête dès que le plan est prêt à être relu.

En coulisses, elle commence par :

codev new change add-dark-mode --goal "Let users switch the UI to a dark theme"

Change `add-dark-mode` created
  Location  /home/you/acme-app/_codev/changes/add-dark-mode
  Schema    spec-driven

Next step: `codev instructions --change add-dark-mode` shows the artifact to write.

codev status indique quels artefacts existent et lesquels attendent d’autres artefacts :

Change: add-dark-mode
Schema: spec-driven

  [ ] proposal
  [-] specs (waiting on: proposal)
  [-] design (waiting on: proposal)
  [-] tasks (waiting on: specs, design)

Planning: 0/4 artifacts
Next:     proposal

Pour chaque artefact, la skill demande à codev tout ce dont elle a besoin pour le rédiger — l’instruction du schéma, le template, le contexte et les règles du projet, la langue, et les fichiers dont l’artefact dépend :

codev instructions proposal --change add-dark-mode

Artifact: proposal (change `add-dark-mode`, schema spec-driven)
Write to: /home/you/acme-app/_codev/changes/add-dark-mode/proposal.md
Language: fr — prose only; template keywords stay in English

Instruction:

Write the document that establishes WHY this change is needed.
…

Les skills appellent la même commande avec --json et reçoivent à la place un document stable.

3. Relire le plan

Une fois la skill terminée, lisez les artefacts dans _codev/changes/add-dark-mode/. Le delta de spec est le cœur du plan : il énonce, sous forme d’exigences testables, le comportement qu’apporte le change.

## Purpose

Permettre aux utilisateurs de choisir le thème de couleurs de l'interface.

## ADDED Requirements

### Requirement: Le thème suit par défaut la préférence du système

L'application SHALL s'afficher avec le jeu de couleurs du système d'exploitation tant que l'utilisateur n'a pas choisi de thème.

#### Scenario: Aucun thème encore choisi

- **GIVEN** un utilisateur qui n'a jamais modifié le réglage du thème
- **WHEN** son système d'exploitation est en mode sombre
- **THEN** l'application s'affiche avec le thème sombre

Demandez des ajustements à Claude avec /codev-update, ou modifiez les fichiers vous-même. Vérifiez ensuite que la planification est complète et que le change est valide :

codev status

Change: add-dark-mode
Schema: spec-driven

  [x] proposal
  [x] specs
  [x] design
  [x] tasks

Planning: 4/4 artifacts
Planning is complete.

codev validate add-dark-mode

change add-dark-mode — _codev/changes/add-dark-mode
  ✓ no issues

1 item(s) validated, no issues.

Remarque Un change sans aucun delta de spec échoue à la validation avec zero_delta_without_marker. C’est voulu : cela évite d’oublier les specs. Un change réellement sans impact sur le comportement — refactorisation, outillage, documentation — déclare skip_specs: true dans son change.yaml.

4. Implémenter

/codev-apply add-dark-mode

La skill lit tasks.md, traite dans l’ordre chaque tâche non cochée, lance la vérification indiquée par chaque tâche, puis coche la case. Elle s’arrête au premier blocage ou à la première ambiguïté pour vous consulter. C’est la seule skill codev qui modifie du code en dehors de _codev/.

5. Archiver

Une fois les tâches terminées :

/codev-archive add-dark-mode

Ou avec la CLI :

codev archive --change add-dark-mode

Archived change `add-dark-mode`

Created:
  /home/you/acme-app/_codev/specs/ui/theme/spec.md

Moved to: /home/you/acme-app/_codev/changes/archive/2026-09-30-add-dark-mode

L’archivage valide le change, fusionne ses deltas dans les specs principales — ici, il crée _codev/specs/ui/theme/spec.md, puisque ui/theme est une nouvelle capacité — et déplace le dossier du change dans l’archive datée. Commitez le résultat : les specs principales décrivent désormais le comportement que vous venez de livrer.

Et ensuite

• Tous les changes suivants suivent le même cycle, de la correction d’une ligne à la réécriture d’une capacité. Le workflow détaille chaque étape.
• Concepts explique les deltas, les capacités et les décisions.
• /codev-onboard propose une visite guidée, en lecture seule, de codev et de l’état actuel de votre projet, avec une action recommandée pour la suite.

Le workflow

Dans un projet codev, chaque change passe par les quatre mêmes étapes. Chaque étape dispose d’une skill Claude Code et — sauf l’implémentation — d’une commande CLI qui effectue le travail sous-jacent.

┌───────────┐    ┌───────────┐    ┌───────────┐    ┌───────────┐
│  propose  │───▶│   apply   │───▶│   sync    │───▶│  archive  │
│ planifier │    │ construire│    │ fusionner │    │  classer  │
│           │    │           │    │ les deltas│    │           │
└───────────┘    └───────────┘    └───────────┘    └───────────┘

Deux autres skills accompagnent le cycle : /codev-explore, pour mûrir une idée avant de proposer quoi que ce soit, et /codev-update, pour réviser un plan déjà rédigé. Voir Les skills Claude Code.

À chaque étape, l’agent tient un rôle défini — product owner, analyste QA, architecte, tech lead, relecteur sceptique, développeur — avec des critères qu’il vérifie avant de passer à la suite, et s’arrête là où vous décidez. Voir Rôles.

Propose

L’étape propose crée le dossier d’un change et rédige ses artefacts de planification. Avec le schéma par défaut spec-driven, un change compte quatre artefacts :

Les dépendances forment un graphe : specs et design peuvent être rédigés dès que la proposal existe, et tasks une fois ces deux artefacts terminés. codev status présente chaque artefact comme terminé ([x]), prêt à être rédigé ([ ]), bloqué par une dépendance ([-]) ou ignoré ([~]). Cet état se déduit uniquement des fichiers présents : codev ne tient aucun fichier d’état.

Dans Claude Code, /codev-propose fait tout en une seule passe :

1. Si votre demande mentionne un identifiant de ticket comme PROJ-123 et qu’un serveur MCP Jira est configuré, la skill récupère d’abord le ticket. Voir Jira et autres serveurs MCP.
2. Elle crée le change avec codev new change <name>.
3. Pour chaque artefact prêt, elle lance codev instructions <artifact> --change <name> --json, étudie le code concerné et rédige le fichier en suivant le template.
4. Elle vérifie la traçabilité entre proposal, specs et tâches, puis relit le plan en relecteur sceptique : elle écrit chaque constat dans le compte rendu de revue du change, corrige ce qui ne fait pas de doute et liste jusqu’à cinq points à challenger. Voir Propose.
5. Elle s’arrête lorsque la planification est complète et présente le plan. Elle ne commence jamais l’implémentation dans le même tour.

Lorsqu’elle rédige design.md, la skill reçoit les décisions d’architecture en vigueur, afin que le design les respecte — ou propose explicitement d’en remplacer une. Voir Décisions.

Un change sans impact sur le comportement — refactorisation, montée de version d’une dépendance, documentation — déclare skip_specs: true dans son change.yaml. L’artefact specs est alors ignoré, et la validation accepte l’absence de deltas.

Apply

/codev-apply <name> implémente le plan. La skill lit tasks.md, traite chaque tâche - [ ] non cochée dans l’ordre du fichier, lance la vérification indiquée par la tâche (un test, une commande, un comportement observable), et ne coche la case qu’une fois la vérification réussie. Les tests suivent d’abord votre suite de tests existante, puis les conventions de votre langage et vos rules. Une fois toutes les tâches cochées, la skill relit le code touché par le change comme le ferait un nouvel arrivant sur le projet, rejointe par les experts qu’activent les domaines de la proposal, simplifie ce qui ne fait pas de doute sans élargir le périmètre, et liste au plus cinq notes de relecture dans son résumé. Chaque constat est conservé dans le compte rendu de revue du change, avec la réponse de l’auteur et la vérification du relecteur ; ce que vous seul pouvez trancher est listé à la fin. Elle lance ensuite une fois la suite de tests complète.

Elle s’arrête au premier blocage ou à la première ambiguïté pour vous consulter plutôt que de deviner. Elle ne modifie que le change désigné, n’archive jamais et ne synchronise jamais : ces étapes restent des demandes explicites de votre part.

apply est la seule skill autorisée à exécuter des commandes shell arbitraires, parce qu’elle doit lancer vos tests. Elle n’a pas d’équivalent en CLI : l’implémentation est le travail de l’agent.

Sync

codev sync --change <name>

La synchronisation fusionne les deltas du change dans les specs principales sous _codev/specs/, sans déplacer le change. Utilisez-la lorsqu’un autre change en cours a besoin de voir une nouvelle capacité dans les specs principales, ou pour relire la fusion avant l’archivage.

La synchronisation est idempotente : la relancer indique que les specs sont inchangées. Dans le cas courant, vous pouvez sauter cette étape : l’archivage synchronise pour vous.

Comme l’archivage, la synchronisation valide d’abord le change et refuse de continuer si la validation signale une erreur : rien n’est écrit, et codev validate <name> affiche les constats.

Archive

codev archive --change <name>

L’archivage clôt un change :

1. Il valide le change et refuse de continuer si la validation signale une erreur, en vous renvoyant vers codev validate <name> pour le détail.
2. Il vérifie le compte rendu de revue et refuse de continuer (review_blocked) s’il manque pour une étape où des rôles de relecture étaient actifs, ou si un constat de gravité haute est encore ouvert ou contesté ; codev review --change <name> montre ce qui reste.
3. Il fusionne les deltas dans les specs principales, exactement comme sync.
4. Il déplace le dossier du change, compte rendu compris, dans _codev/changes/archive/<YYYY-MM-DD>-<name>/.

La fusion complète est calculée et vérifiée avant l’écriture du premier fichier : un change invalide ou un delta inapplicable — par exemple une exigence MODIFIED absente de la spec principale — est signalé avant toute modification sur le disque.

Après l’archivage, les specs principales décrivent le comportement que vous avez livré, et le dossier archivé conserve la trace du pourquoi et du comment. Commitez les deux — et, si le change a une note de version, lancez codev changelog --write pour l’ajouter à CHANGELOG.md (voir Notes de version et CHANGELOG).

Choisir le change

codev status, codev instructions, codev sync et codev archive acceptent --change <name>. Lorsque le projet compte exactement un change actif, vous pouvez l’omettre. S’il y en a plusieurs, codev vous demande de choisir :

error: several active changes: add-audit-log, rework — specify which one
help: `--change add-audit-log`

Les noms de changes sont en kebab-case : lettres minuscules, chiffres et tirets, par exemple add-user-auth.

Valider

codev validate

Sans argument, codev validate vérifie chaque change actif, chaque spec principale et les sceaux des décisions. Passez le nom d’un change ou d’une capacité pour ne vérifier qu’un élément, ou --changes / --specs pour ne vérifier qu’une famille. Les erreurs font sortir la commande avec le code 1 ; avec --strict, les avertissements aussi. Utilisez cette option en CI :

codev validate --strict

Les vérifications portent sur la structure des specs et des deltas (chaque exigence emploie SHALL ou MUST — ou DOIT ou DOIVENT — et comporte au moins un #### Scenario:), sur la cohérence interne d’un delta (aucune exigence à la fois ajoutée et modifiée, aucun renommage en conflit avec un ajout), sur la règle du delta vide, et sur l’intégrité des décisions scellées. Voir Formats de fichiers pour les règles que chaque fichier doit respecter.

Les skills Claude Code

codev fournit huit workflows. codev init et codev update convertissent chacun d’eux en skill Claude Code dans .claude/skills/codev-<workflow>/SKILL.md. Claude Code découvre les skills automatiquement, et vous pouvez aussi en invoquer une directement en tapant son nom comme commande slash, par exemple /codev-propose.

Permissions des outils

Chaque skill déclare les outils qu’elle peut utiliser dans le champ allowed-tools de son frontmatter. Ces permissions font partie de l’engagement de chaque skill : une skill qui ne doit pas écrire de fichiers ne reçoit pas les outils pour le faire.

Bash(codev:*) permet à une skill de lancer des commandes codev, et rien d’autre. Seule codev-apply obtient un accès général à Bash, parce qu’elle doit lancer vos tests et vos commandes de build. codev-sync et codev-archive ne peuvent écrire aucun fichier : toutes leurs modifications passent par la CLI.

Agent est l’outil de sous-agent de Claude Code. codev-propose et codev-apply ne le demandent que lorsque _codev/config.yaml définit review: { mode: isolated } (Revue en ligne ou isolée) : chaque rôle relecteur travaille alors comme sous-agent. Aucune autre skill ne le demande jamais. Après avoir changé de mode, lancez codev update ; codev doctor signale skills_review_mode tant que vous ne l’avez pas fait. Les deux skills décrivent la revue isolée dans les deux modes, car le change.yaml d’un change peut remplacer le mode du projet : sans l’outil pré-autorisé, Claude Code demande avant de lancer un sous-agent, et s’il ne peut pas en lancer, les rôles relisent en ligne.

Annonce des mises à jour

/codev-propose, /codev-apply, /codev-update, /codev-sync et /codev-archive lisent les objets update et versionRequirement de leur premier codev status --json. Lorsque le codev_version du projet n’est pas satisfait, ou qu’un codev plus récent est disponible et n’est pas en sourdine, la skill le signale en une ligne, avec le lien de la release, et vous demande Update now ou Later avant toute autre chose :

• Update now lance codev self-update --yes, puis reprend l’action ;
• Later lance codev self-update --snooze — 7 jours de silence pour cette version — puis reprend l’action. Pour un codev_version non satisfait, rien n’est mis en sourdine : c’est l’équipe qui l’a demandé.

La question est posée une fois par action, jamais au milieu : /codev-apply la pose avant la première tâche. /codev-explore, /codev-onboard et /codev-configure ne la posent jamais ; /codev-onboard relaie codev doctor, dont la vérification codev_version dit la même chose. Aucune skill n’a besoin de plus que Bash(codev:*) pour cela.

Les skills en détail

Propose (/codev-propose)

Transforme une demande en plan complet : proposal, deltas de specs, design et tâches. La skill lit le code concerné avant d’écrire, fonde le périmètre sur ce qu’elle y trouve, et signale les contradictions avec les specs existantes au lieu de les trancher seule. Elle rédige la prose dans la langue des artefacts du projet.

Une fois la proposition écrite, les instructions qu’elle lit listent les exigences existantes que le change touche probablement. La skill les lit et modifie celles que le change altère au lieu d’en ajouter de nouvelles à côté ; la liste est un point de départ, pas une liste complète.

La demande n’autorise que la planification, même si elle dit « construis » ou « corrige » : la skill s’arrête une fois les artefacts rédigés et attend votre retour.

Chaque artefact a un rôle explicite, déclaré par le schéma et renvoyé par codev instructions — product owner pour la proposal, analyste QA pour les specs, architecte pour le design, tech lead pour les tâches — avec des critères « Done when » que l’agent vérifie avant de passer à la suite. Les critères du tech lead exigent que la documentation concernée soit mise à jour dans une tâche, et que chaque scénario soit couvert par un test automatisé qui suit les conventions de test de votre projet. Le product owner rédige la note de version de la proposal pour les utilisateurs, classée par catégorie, ou None pour un change interne. Un schéma personnalisé définit les siens.

À chaque étape, elle demande codev roles --at <step> les rôles de l’étape et applique leurs critères, y compris les critères ajoutés par votre projet ; une étape dont votre configuration désactive le rôle est sautée, et le résumé le signale (voir Configurer les rôles).

Avant de présenter le plan, la skill le relit en deux étapes :

1. Traçabilité — chaque capacité a son fichier de spec, chaque exigence un scénario nominal et un scénario d’erreur ou de cas limite, chaque scénario une tâche dont la vérification le couvre par un test automatisé, une tâche met à jour la documentation lorsque la section Impact touche un comportement documenté, et la note de version de la proposal concorde avec le plan — chaque élément incompatible de What Changes, et chaque exigence supprimée ou modifiée de façon incompatible, a son élément BREAKING. Les manques sont corrigés dans les artefacts.
2. Relecture contradictoire — la skill relit le plan en relecteur sceptique : besoin, périmètre, specs, décisions, hypothèses, tâches, et si ## Domains coche chaque domaine que le plan touche, ainsi que les rules de votre projet. Le skeptic ne relit lui-même aucun domaine : sécurité, données personnelles, migration, exploitation, performance et accessibilité reviennent à leurs experts. Les experts dont la proposal coche le domaine dans ## Domains — sécurité, données personnelles, accessibilité, performance, exploitation, migration — rejoignent cette relecture avec leurs propres connaissances. Avant d’écrire ## Domains, la skill lit les domaines que suggère le diff du change et coche chacun ou le garde non coché avec une raison ; le skeptic consigne un constat pour chacun resté unticked. Chaque constat est écrit dans le compte rendu de revue du change, avec sa gravité et sa preuve citée ; l’auteur le corrige ou le conteste, le relecteur vérifie chaque réponse une fois, et la relecture n’élargit jamais le périmètre. En mode isolé, le contrôleur de traçabilité et chaque relecteur travaillent comme des sous-agents distincts qui ne voient jamais la conversation, et la skill fusionne leurs constats avant de les consigner.

Le résumé se termine par les points à challenger : au plus cinq points d’une ligne, tous rôles confondus, classés par gravité et marqués du rôle qui les a relevés — identifiant du constat, statut, quoi, pourquoi c’est important, quel artefact — ou la mention qu’aucun point n’a été relevé, puis par À décider : les contestations que le relecteur a maintenues et les constats de gravité haute encore ouverts. Commencez votre relecture par là.

Si la demande mentionne un identifiant de ticket correspondant à [A-Z]{2,}-\d+ et qu’un outil MCP Jira est configuré, la skill récupère le premier ticket — en lecture seule, en un seul appel — et le cite en tête de la proposal. Voir Jira et autres serveurs MCP.

Rôles : analyste, enquêteur, product owner, analyste QA, architecte, tech lead, contrôleur de traçabilité et contradicteur — voir Rôles intégrés.

Explore (/codev-explore)

Un partenaire de réflexion pour les demandes floues, les investigations et les comparaisons d’approches. La skill lit le code et les specs, mais ne crée ni change, ni artefact, ni fichier. Une fois l’idée claire, elle suggère /codev-propose.

Posture : partenaire de réflexion.

Onboard (/codev-onboard)

Une visite guidée en lecture seule pour qui découvre codev : ce que fait l’outil, ce que contient le projet actuel (specs, changes actifs, décisions), et l’action à mener ensuite — par exemple /codev-configure sur un projet fraîchement initialisé. Elle lance aussi codev doctor --json et liste jusqu’à cinq éléments manquants de l’installation avec leur correction, sans en exécuter aucune.

Posture : guide.

Configure (/codev-configure)

Lit le README, le guide de contribution, la documentation et un échantillon du code source, puis rédige un bloc context: et des rules: par artefact pour _codev/config.yaml. La skill affiche le diff et n’écrit qu’après votre confirmation. Elle ne touche jamais à schema, language, workflows, mcp ni inherits, et préserve les commentaires existants.

Ses règles tasks comprennent des règles de test pour votre langage : framework, emplacement des tests, nommage, commandes — tirées de vos tests existants. C’est seulement lorsque le projet n’a encore aucun test qu’elle se rabat sur les conventions courantes de Rust, TypeScript/JavaScript, Python, Go ou Java.

Tant que la configuration ne comporte aucune rules:, codev init et codev status recommandent de la lancer.

Posture : analyste de configuration.

Apply (/codev-apply)

Implémente un change planifié. La skill vérifie que la planification est complète, puis traite dans l’ordre chaque tâche non cochée de tasks.md, la vérifie et ne la coche qu’une fois la vérification réussie. Elle écrit les tests à la manière de votre suite de tests existante, puis selon les conventions de votre langage et vos rules. Elle prend la commande de test dans votre configuration, votre manifeste ou votre CI, et vous la demande si elle n’en trouve aucune. Une fois toutes les tâches cochées, elle relit le code touché par le change comme le ferait un nouvel arrivant, rejointe par les experts qu’activent les domaines de la proposal : elle simplifie ce qui ne fait pas de doute, sans élargir le périmètre, et signale au plus cinq notes de relecture, chacune marquée de son rôle — un constat de sécurité ou de données personnelles de gravité haute est toujours signalé. Chaque constat va dans le compte rendu de revue et suit la même boucle de réponse que ceux du plan — en mode isolé, après que chaque relecteur a travaillé seul comme sous-agent et que la skill a fusionné leurs constats —, et le résumé liste ce qu’il vous revient de décider — y compris tout domaine que le code suggère désormais et que la proposal ne coche ni ne justifie : cochez-le et son expert relit le code, ou justifiez-le. Un expert corrige un défaut manifeste dans le périmètre du change, avec un test, et signale tout autre changement de comportement au lieu de le faire. Elle tire les critères et les connaissances de ces deux étapes de codev roles ; lorsqu’aucun rôle n’est actif à la relecture, celle-ci est sautée et le résumé le signale. Elle lance ensuite une fois la suite de tests complète. Elle s’arrête au premier blocage ou à la première ambiguïté. Elle ne modifie jamais un autre change, ne synchronise jamais et n’archive jamais.

Rôles : développeur, nouvel arrivant et experts.

Update (/codev-update)

Révise un artefact existant — par exemple une exigence d’un delta de spec après relecture — puis recherche dans les autres artefacts les répercussions éventuelles et les signale. La skill ne crée pas les artefacts manquants (c’est le rôle de /codev-propose), ne modifie pas le code (celui de /codev-apply) et ne touche pas aux changes archivés. Elle se termine par codev validate.

Posture : éditeur.

Sync (/codev-sync)

Lance codev sync pour un change et indique quelles specs principales ont été créées, mises à jour ou laissées inchangées.

Posture : mainteneur des specs vivantes.

Archive (/codev-archive)

Lance codev archive pour un change. Si la validation signale des erreurs, la skill s’arrête et vous renvoie vers codev validate au lieu de chercher à les contourner. Si le compte rendu de revue bloque l’archivage (review_blocked), elle vous renvoie vers codev review et ne consigne jamais une décision à votre place.

Posture : mainteneur des specs vivantes.

Choisir les skills à installer

Par défaut, les huit skills sont installées. Pour en installer moins, choisissez le préréglage minimal à l’initialisation — propose, explore, onboard et configure — ou listez les workflows souhaités dans _codev/config.yaml :

workflows:
  - propose
  - explore
  - apply
  - archive

Lancez ensuite codev update. Un nom de workflow inconnu produit un avertissement et est ignoré. codev update ne supprime pas les skills qui ne sont plus listées : supprimez vous-même leurs dossiers dans .claude/skills/.

Modifier une skill générée

Chaque SKILL.md généré enregistre la version de codev qui l’a produit et une empreinte (checksum) de son propre contenu. Si vous modifiez une skill à la main, son contenu ne correspond plus à son empreinte : codev update détecte la modification et laisse le fichier en place :

  Left in place because edited by hand — rerun with --force to overwrite:
    /home/you/acme-app/.claude/skills/codev-apply/SKILL.md

codev update --force l’écrase avec la version générée. Les skills issues d’une autre version de codev sont toujours régénérées, tout comme les skills de cette version que codev a rendues lui-même — une compilation antérieure, ou l’autre mode de revue —, puisqu’elles correspondent encore à leur empreinte. Une skill de cette version générée avant les empreintes est préservée comme une modification : lancez une fois codev update --force pour lui donner son empreinte — vérifiez d’abord git diff, car il écrase aussi vos vraies modifications, puis réappliquez-les.

Rôles

Une skill codev est un seul agent, mais il n’aborde pas chaque étape dans le même état d’esprit. Chaque étape reçoit un rôle : une question dont il a la charge, et des critères « Done when » que l’agent vérifie avant de passer à la suite. Vous et votre équipe validez à des moments définis — l’agent ne décide jamais à votre place.

Les rôles sont des critères, pas un jeu de rôle. L’agent ne se fait pas passer pour un product owner : il vérifie la proposal à l’aide de la liste du product owner. Un rôle dont les critères sont remplis est terminé, quel que soit le ton de la prose. Certains rôles portent aussi des connaissances — les signaux concrets, les pièges par langage et les références dont ils ont besoin pour bien vérifier leurs critères — voir Experts et domaines.

Les rôles sont des données, pas de la prose enfouie dans les skills. codev les sert : à chaque étape, les skills demandent codev roles --at <step> et appliquent ce qui leur revient, et codev instructions transmet à l’agent le rôle de chaque artefact. Votre projet peut désactiver un rôle, ajouter ses propres critères et changer l’activation pour un seul change — voir Configurer les rôles.

Rôles intégrés

Les rôles d’étape et les experts sont intégrés à codev. Les rôles d’artefact viennent du schéma par défaut spec-driven, qui déclare un rôle par artefact ; un schéma personnalisé déclare les siens, ou aucun.

Pour lire les critères « Done when » d’un rôle, interrogez codev — c’est la liste que reçoit l’agent :

codev roles --at plan.challenge

Sans --at, codev roles liste tous les rôles avec leur activation ; ajoutez --knowledge pour lire aussi les connaissances d’un rôle. Voir codev roles.

Étapes

La procédure de chaque étape — ce qu’il faut écrire, les plafonds, les garde-fous — reste dans la skill. Les critères et les connaissances viennent du rôle.

Experts et domaines

Six experts rejoignent les étapes de relecture lorsqu’un change touche leur domaine. Chacun est actif à plan.challenge — le design traite-t-il le domaine ? — et à code.review — l’implémentation le respecte-t-elle ?

Domaines. La proposal liste les domaines que touche le change dans sa section ## Domains — les six ci-dessus, à cocher, ou la seule ligne None :

## Domains

- [x] security
- [ ] personal-data
- [ ] user-interface
- [ ] performance
- [x] operations — nouveau worker en arrière-plan
- [ ] migration

Le product owner vérifie que chaque domaine touché par le change est coché. codev validate signale un domaine inconnu (unknown_domain) ou une section mal formée (domains_invalid) comme une erreur, et une section absente sur un change actif (domains_missing) comme un avertissement — voir Formats de fichiers.

Activation on_domain. Un expert n’est actif à ses étapes que lorsque la proposal du change coche son domaine. Sans change — codev roles sans --change — ou tant que la proposal n’a pas de section ## Domains, il est inactif. codev roles --json indique pourquoi chaque rôle actif l’est dans activatedBy : always, project, change ou domain:<nom>. Vous pouvez toujours forcer un expert, pour le projet ou pour un change — voir Configurer les rôles.

Connaissances. Les connaissances d’un expert se répartissent en cinq sections, toujours dans cet ordre :

• Scope — ce qu’il examine, ce qu’il laisse de côté, et ce qu’il ne signale pas — par exemple, l’expert exploitation ne réclame pas d’interrupteur quand redéployer la version précédente annule le change, et l’expert performance ne signale pas un gain d’un facteur constant ;
• Signals — des motifs concrets à repérer, chacun avec un exemple d’une ligne ;
• By stack — les pièges en Rust, TypeScript/JavaScript, Python, Go et Java ; codev sert la partie qui concerne les langages de votre projet (voir Filtre par stack) ;
• References — les référentiels qui font autorité, comme l’OWASP Top 10, les WCAG 2.2, le RGAA 4 ou le RGPD ;
• Reporting — comment signaler un constat, avec sa gravité, et ce qu’il doit nommer : la panne que subit l’exploitant, l’attaque, la donnée et qui la reçoit, le fichier ou le consommateur existant qui casse.

Le newcomer porte des signaux de complexité par langage, et regroupe en un seul constat ce qui rend une fonction difficile à suivre ; il juge la lisibilité, non la justesse, et les tests que le change contient, non ceux qui lui manquent. Le skeptic porte des signaux de planification fragile : il conteste la logique et les preuves du plan — besoin, périmètre, specs, décisions, hypothèses, tâches, et étapes sans retour possible — et laisse chaque domaine à son expert, en vérifiant seulement que la section ## Domains de la proposal coche chaque domaine que le plan touche, pour que son expert le relise. Les autres rôles d’étape n’en portent pas. Les connaissances ne sont servies qu’aux rôles actifs : un expert inactif ne coûte rien à l’agent. Lisez-les avec codev roles --at code.review --change <nom> --knowledge.

Les déclencheurs et les domaines suggérés

Cocher les domaines est un jugement porté pendant la planification, avant que le code existe. Pour qu’un domaine que le change finit par toucher ne soit pas oublié en silence, chaque expert porte des déclencheurs — des indices qu’un change touche son domaine — et codev les confronte au diff du change.

Trois sortes de déclencheurs, en groupes qui nomment chacun le domaine qu’ils suggèrent :

• paths — des globs sur les fichiers modifiés, relatifs à la racine du projet, sans tenir compte de la casse : **/auth/**, **/*.tsx. * reste dans un dossier, ** traverse les dossiers ;
• manifests — des noms de manifestes de dépendances, à toute profondeur : Cargo.toml, package.json, go.mod ;
• patterns — des expressions régulières sur les lignes que le diff ajoute : (?i)\b(ALTER|DROP)\s+(TABLE|COLUMN)\b.

Les motifs intégrés privilégient la précision : access_token plutôt que token (un analyseur lexical a des tokens), street_address plutôt qu’address (une socket en a une). Ce qu’ils manquent pour votre projet, ajoutez-le avec triggers: dans _codev/config.yaml.

Le diff. codev demande à git, localement, ce que la branche a changé depuis qu’elle a quitté la branche par défaut — origin/HEAD, sinon main, sinon master —, commité ou non, plus les fichiers non suivis, dans le seul dossier du projet. Il ne contacte jamais de dépôt distant. Hors de git, sans commit ou sans branche par défaut — ou dans un clone superficiel de CI sans la base commune ; utilisez-y fetch-depth: 0 —, il n’y a pas de diff : codev le dit et ne suggère rien, et aucune commande n’échoue pour autant.

Certains fichiers échappent à tout déclencheur : le dossier de planification _codev/ et les skills codev (planning), les dépendances embarquées — node_modules, vendor, third_party (vendored) —, les fichiers de verrouillage comme Cargo.lock ou package-lock.json (lockfile), et les fichiers générés comme *.min.js ou *.pb.go (generated). Les fichiers binaires, la prose (.md, .txt…) et les très gros fichiers ne sont confrontés que par leur chemin (binary, prose, large). L’analyse s’arrête à 2000 fichiers, 5000 lignes ajoutées par fichier, 1 Mio par fichier non suivi et 2 Mio de lignes ajoutées au total, et ignore les lignes de plus de 2000 caractères ; le diff indique alors qu’il a été tronqué.

Les suggestions. codev roles --change <nom> présente le diff et chaque domaine suggéré avec son état :

• ticked — la proposal le coche ;
• justified — la proposal le laisse décoché avec une raison sur sa ligne ;
• unticked — ni l’un ni l’autre : la proposal doit y répondre.

## Domains

- [x] security
- [ ] personal-data — the fields matched are test fixtures

codev validate signale chaque suggestion unticked par l’avertissement domain_suggested, à la ligne du domaine, en nommant le déclencheur et le fichier concernés ; codev validate --strict échoue alors. codev archive et codev doctor ne lisent pas le diff. Le diff est celui de l’arbre de travail : deux changes actifs sur une même branche le partagent. Un rôle réglé sur never n’apporte aucune suggestion.

/codev-propose lit les suggestions avant d’écrire ## Domains, et le skeptic consigne un constat pour chacune restée unticked. Avant que le code existe, le diff est en général vide : c’est la revue qui tranche. /codev-apply liste chaque suggestion encore unticked sous To decide — cochez-la, et son expert relit le code, ou justifiez-la.

Filtre par stack. codev détecte les langages de votre projet à partir de ses manifestes de dépendances — à la racine et jusqu’à trois dossiers en dessous, si bien qu’un monorepo obtient toutes ses stacks — et la partie By stack des connaissances qu’il sert ne garde que ces langages. codev roles --json les indique dans stacks ; sans aucun manifeste, tout est conservé. codev roles --all-stacks sert tous les langages.

Gravité, confiance et compte rendu de revue

Ce que trouvent les rôles de relecture — le contradicteur et les experts à plan.challenge, le nouvel arrivant et les experts à code.review — est écrit dans le compte rendu de revue du change, _codev/changes/<name>/review.md, avant d’être corrigé ou signalé. Chaque constat cite sa preuve mot pour mot, à un emplacement que codev peut vérifier, et porte une gravité et une confiance sur une échelle commune :

Un constat de confiance basse reste dans le compte rendu et reçoit une réponse comme les autres, mais il ne vous est présenté que si l’on vous demande de le trancher.

Tous les rôles de relecture notent de la même façon. Un constat medium ou high qui vous est présenté avec une confiance high cite la ligne qu’il vise et décrit le scénario qui échoue ; une inquiétude qui dépend de ce que le relecteur n’a pas pu voir — la charge, un appelant, une configuration — et une préférence sans défaillance sont notées avec une confiance low. Un rôle ne signale pas une question qui relève d’un autre rôle, du code ou des données que le change ne touche pas, ce que le plan exclut explicitement, un test manquant que ses critères ne demandent pas, ni une affaire de goût. Chaque défaut est signalé une fois, ses conséquences dans sa recommandation ; deux défauts qui demandent deux corrections restent deux constats.

L’équipe travaille ensuite comme une équipe : l’auteur — le rôle qui possède l’artefact, ou le développeur pour le code — corrige chaque constat ou le conteste avec un argument ; le relecteur vérifie chaque réponse une fois, en validant la correction, en acceptant la contestation (rejected) ou en la maintenant ; ce qui reste contesté vous revient, avec les deux arguments, sous À décider. Vous seul acceptez un risque ou reportez un constat de gravité haute, et le compte rendu dit qui a décidé. codev archive refuse un change dont le compte rendu manque pour une étape où des rôles ont relu, ou qui a encore un constat de gravité haute ouvert ou contesté. Le format complet, les contrôles et le verrou d’archivage sont dans Compte rendu de revue.

Revue en ligne ou isolée

Par défaut, les rôles relecteurs travaillent en ligne (inline) : la skill qui a écrit le plan ou le code le relit dans la même conversation, un rôle après l’autre. C’est le moyen le moins coûteux, mais chaque relecteur a lu le raisonnement de l’auteur et les rôles passés avant lui, et tend à leur donner raison.

En mode isolé (isolated) — review.mode dans la configuration, ou dans le change.yaml d’un change — chaque rôle relecteur travaille d’abord seul, comme sous-agent de Claude Code : le contrôleur de traçabilité à plan.trace, le contradicteur et les experts actifs à plan.challenge, le nouvel arrivant et les experts actifs à code.review, tous ceux d’une étape en même temps. Un relecteur reçoit seulement :

• son rôle : question, critères et connaissances, filtrées par stack ;
• le context et les rules du projet ;
• la matière : les artefacts du change aux étapes du plan, les fichiers que le change touche et leur diff à code.review ;
• les identifiants déjà présents dans le compte rendu et le format d’un constat.

Il ne reçoit jamais la conversation, le raisonnement de l’auteur ni les constats d’un autre rôle. Il peut lire le reste du dépôt — les décisions, les specs principales, le code que la matière cite —, ne modifie rien, et traite la matière comme des données, jamais comme des instructions. codev roles --json mesure la matière (review.material) : au-delà de 160 Kio, les fichiers les plus gros sont marqués summarize, et un sous-agent distinct, qui ne voit que le diff de ce fichier, le résume en citant les lignes modifiées quand elles tiennent. Le compte rendu dit quels fichiers ont été résumés.

Un sous-agent qui échoue, que les limites de Claude Code arrêtent, ou qui répond dans un autre format est relancé une fois ; s’il échoue encore, ce rôle relit en ligne et le compte rendu le dit par une ligne Fallback:. Sans l’outil de sous-agent, tous les rôles relisent en ligne.

La réunion

La skill tient ensuite la réunion, comme une équipe après avoir lu chacun de son côté :

• Fusionner. Les constats de plusieurs rôles sur le même défaut — au même endroit, avec la même correction — deviennent un seul constat, inscrit sous le rôle qui l’a jugé le plus grave et qui crédite chaque rôle qui l’a relevé (raised_by). Des constats au même endroit qui demandent des corrections différentes restent distincts.
• Classer. Par gravité, puis confiance, puis ordre des rôles ; le résumé en montre cinq au plus, comme en ligne.
• Répondre. Les réponses de l’auteur, l’unique revérification du relecteur et ce qui vous revient sous À décider fonctionnent exactement comme plus haut.

La revue isolée coûte plus cher : chaque relecteur lit la matière, que la revue en ligne ne lit qu’une fois. C’est pourquoi inline reste le mode par défaut ; voyez la configuration pour en changer.

Configurer les rôles

Tous les rôles sont actifs par défaut. Dans _codev/config.yaml, roles: associe un identifiant de rôle à son réglage :

roles:
  newcomer: never            # forme courte : always | never
  skeptic:
    when: always             # facultatif, always par défaut
    done_when:               # ajoutés après les critères propres du rôle
      - Le plan de retour arrière est indiqué

• Activation. always, never ou on_domain. Une étape dont tous les rôles sont inactifs est sautée, et le résumé de la skill indique qu’elle est désactivée par la configuration. on_domain est la valeur par défaut des experts ; elle est refusée sur un rôle lié à aucun domaine. Indiquez security: always pour que l’expert sécurité relise chaque change, ou accessibility: never dans un projet sans interface utilisateur.

• Critères supplémentaires. Les entrées de done_when s’ajoutent après les critères propres du rôle, sans jamais les remplacer. Elles portent l’origine project, comme votre context et vos rules.

• Par change. Le change.yaml d’un change peut changer l’activation pour ce change seulement :

  roles:
    newcomer: always
  

• Ce qui ne peut pas être désactivé. Les rôles d’artefact (product, qa, architect, lead), l’analyst — le garde-fou contre un plan bâti sur un malentendu — et le developer : leur artefact est toujours rédigé, la demande toujours comprise, leurs tâches toujours implémentées. Leurs critères peuvent être complétés.

• Les sources héritées n’apportent aucun rôle : seul le roles: de votre projet est lu.

codev validate signale un identifiant de rôle inconnu (unknown_role), une activation autre que always, never ou on_domain, ou on_domain sur un rôle sans domaine (invalid_role_activation), et never sur un rôle qui ne peut pas être désactivé (role_not_disableable) ; codev status, codev instructions et codev roles échouent avec le même code. codev doctor liste les rôles actifs, les rôles actifs selon le domaine avec leurs domaines, et les rôles désactivés.

Implémenter un change (/codev-apply)

Développeur (/codev-apply)

Implémente les tâches d’un change planifié, dans l’ordre du fichier. Done when, pour chaque tâche :

• les fichiers concernés sont lus avant d’écrire ;
• le code, les tests, la configuration et la documentation que la tâche demande sont écrits — rien de plus ;
• les tests sont écrits à la manière de la suite existante du projet, puis selon les conventions de son langage et les rules du projet ;
• la vérification citée par la tâche est lancée et réussit — la commande de test vient de context, des rules, du manifeste ou de la configuration de CI, et la skill vous la demande si elle n’en trouve aucune ;
• alors seulement, la case est cochée.

Elle s’arrête sur une ambiguïté importante ou un blocage technique sans cocher la tâche, et décrit les options. Une fois toutes les cases cochées, et après la relecture, elle lance une fois la suite de tests complète du projet ; un échec est signalé à la place du résumé. Elle ne contourne jamais un test en échec, ne touche jamais un autre change, ne synchronise jamais et n’archive jamais.

Nouvel arrivant et experts (/codev-apply)

Une fois toutes les tâches cochées, et avant la suite de tests complète, relit uniquement le code que le change a ajouté ou modifié : le nouvel arrivant, comme un développeur qui rejoint le projet sans avoir vu ni le plan ni la conversation, et les experts qu’activent les domaines du change, chacun à l’aide de ses critères et de ses connaissances. Chaque constat va d’abord dans le compte rendu de revue. Ce qui ne fait pas de doute est simplifié et les tests concernés sont relancés ; le reste devient au plus cinq notes de relecture dans le résumé final — chacune marquée de son rôle et de l’identifiant du constat : quoi, où, pourquoi — ou la mention qu’aucune n’a été relevée, suivies de ce qu’il vous revient de décider. Un constat de sécurité ou de données personnelles de gravité haute est toujours listé, même au-delà de cinq.

La relecture n’élargit jamais le périmètre du change et ne touche jamais au code que le change n’a ni ajouté ni modifié. Le nouvel arrivant ne change jamais le comportement. Un expert ne le change jamais en silence : une correction qui change le comportement devient une note de relecture, sauf s’il s’agit d’un défaut manifeste dans le périmètre du change, alors corrigé avec un test et mentionné dans le résumé.

Les autres skills

Les autres skills gardent une posture fixe, écrite dans la skill elle-même. Ces postures ne sont pas des rôles : elles ne figurent pas au catalogue et ne se configurent pas.

Partenaire de réflexion (/codev-explore)

Explore une idée, un problème ou un besoin, sans engager quoi que ce soit. Done when :

• ce que le dépôt sait déjà passe en premier — specs, changes en cours, décisions en vigueur, code concerné — de sorte qu’on ne vous demande jamais ce que le code peut dire ;
• les questions posées portent sur une dépendance, une contrainte ou un compromis, chacune avec une réponse recommandée par défaut et sa raison ;
• deux ou trois options sont comparées, chacune avec ce qu’elle coûte et ce qu’elle exclut, et une recommandation est faite ;
• une direction qui s’écarte d’une décision acceptée est signalée tôt ;
• les hypothèses sont présentées comme des hypothèses ;
• l’exploration se termine de l’une de trois façons, nommée : elle se cristallise (problème, approche, périmètre, et la proposition de lancer /codev-propose), une information manque (laquelle, et qui peut la fournir), ou la piste ne valait pas la peine.

Elle n’écrit aucun fichier, ne crée aucun change et n’implémente pas, même si on le lui demande.

Mainteneur des specs vivantes (/codev-sync, /codev-archive)

Veille à ce que _codev/specs/ décrive le système. /codev-sync fusionne les deltas d’un change sans le déplacer ; /codev-archive les fusionne et déplace le change dans _codev/changes/archive/<date>-<name>/. Done when :

• la planification est complète — sinon rien n’est lancé ;
• la fusion passe par codev sync ou codev archive, jamais par un fichier que la skill écrirait elle-même ;
• les specs créées, mises à jour et inchangées sont indiquées (et, pour l’archivage, l’endroit où le change a été déplacé).

Sur une erreur de validation, les deux refusent : elles répondent que le change comporte des erreurs et renvoient vers codev validate <name>, sans réessayer ni corriger le change elles-mêmes. Toute autre erreur est relayée telle que la CLI l’a écrite.

Éditeur (/codev-update)

Révise un artefact de planification qui existe déjà dans un change actif. Done when :

• l’artefact et les autres qu’il peut affecter sont lus sur le disque avant d’écrire ;
• la révision respecte le contrat de l’artefact — sections attendues, format des scénarios, cases à cocher ;
• les répercussions sont annoncées : un fichier de spec orphelin ou manquant après une modification de la proposal, une tâche qui cite une exigence supprimée ou un scénario renommé, une décision du design qui ne correspond plus, une tâche qui contredit une exigence — avec une action suivante suggérée, appliquée seulement après votre confirmation ;
• codev validate a été lancé et son rapport est relayé.

Elle refuse de créer un artefact manquant, de toucher à un change archivé ou de modifier le code.

Guide (/codev-onboard)

Présente codev à qui le découvre. Done when elle a affiché trois blocs : ce qu’est codev, l’état du projet (nombre de specs, de décisions et de changes, et jusqu’à cinq éléments d’installation manquants signalés par codev doctor, avec leur correction), et exactement une action recommandée, citée sous la forme de la commande à taper. Elle est strictement en lecture seule : elle ne lance aucune correction, pas même codev init.

Analyste de configuration (/codev-configure)

Propose le context: et les rules: par artefact de _codev/config.yaml à partir du projet lui-même. Done when :

• la lecture reste dans son budget — README et CONTRIBUTING en entier, au plus 5 fichiers de documentation, 8 fichiers source et 3 fichiers de test ;
• context: compte 2 à 5 lignes factuelles qui complètent la pile détectée ;
• rules: compte 1 à 2 règles pour specs, design et tasks, chacune formulée positivement, vérifiable en relecture et fondée sur ce que fait le projet, plus des règles de test tirées des tests existants du projet ;
• le diff est affiché et votre accord est demandé avant toute écriture.

Elle n’écrit qu’après votre oui, ne modifie que context: et rules:, préserve tous les autres champs et commentaires, et refuse d’agir si _codev/config.yaml n’existe pas.

Mesurer les rôles

Le dépôt de codev mesure ses rôles de revue intégrés — le sceptique, le traceur, le nouvel arrivant et les six experts — avec une suite d’évaluation, evals/. Chaque cas est un petit projet avec un change planifié : soit ensemencé de défauts que le rôle devrait trouver, chacun avec sa gravité et son emplacement attendus, soit témoin propre, sans aucun défaut. La suite fait exécuter à Claude Code une étape de skill sur chaque cas, avec le rôle évalué seul, puis note le compte rendu de revue qu’il a écrit :

• vrais positifs et manqués — les défauts ensemencés trouvés ou non. Un constat compte pour un défaut quand son rôle, son emplacement (deux lignes de tolérance, le même titre du plan, ou un autre endroit que le cas admet) et sa catégorie concordent : chaque défaut ensemencé nomme une catégorie de problème, comme access-control ou keyboard-trap, reconnue à ses termes dans le titre ou la recommandation du constat. Un constat sur un problème voisin, deux lignes plus loin, ne tient pas lieu du défaut ;
• faux positifs — les constats de confiance haute qui ne correspondent à aucun défaut ensemencé, dans un témoin ou à côté du défaut ; le rapport signale ceux qui se trouvent à l’endroit d’un défaut mais nomment un autre problème. Les constats de confiance basse, qui ne vous sont jamais présentés, sont comptés à part ;
• validité des preuves — la part des constats dont la citation est retrouvée par codev review aux lignes indiquées ;
• accord de gravité — la gravité trouvée est celle attendue.

Le traceur, qui corrige le plan au lieu d’enregistrer des constats, est noté sur le plan qu’il laisse : la tâche manquante ajoutée, un plan complet laissé intact.

Les cas sont écrits pour qu’un relecteur inattentif passe à côté : des défauts subtils à côté d’un code qui fait la même chose correctement (une autorisation vérifiée sur la liste mais pas sur le détail, des données personnelles qui atteignent les journaux par un message d’erreur), des cas à deux défauts de gravités différentes, et des témoins dont le code paraît suspect mais est juste (une requête assemblée à partir d’une liste autorisée, aux valeurs liées ; des journaux d’identifiants qui ne sont pas des données personnelles). Le plan d’un cas ne cite que des fichiers et des tests que son projet contient, pour qu’une lacune du cas ne soit jamais comptée contre le rôle.

Les scores de référence sont la ligne de base versionnée, evals/baseline/report.md : cinq exécutions de chaque cas, avec le modèle par défaut de Claude Code à la date qu’elle indique, chaque score étant la médiane des cinq. Un modèle ne répond pas deux fois de la même façon : une modification d’un fichier de rôle se juge donc avec codev-evals compare --quality-only face à la ligne de base, avec le même modèle ; la médiane de chaque rôle doit rester dans l’écart couvert par les exécutions de la ligne de base. La suite ne tourne jamais dans la CI habituelle et ne fait pas partie du binaire codev.

Fiabilité des rôles présente ces scores, rôle par rôle, avec les seuils que chaque rôle respecte ou dépasse et les limites de la mesure.

Là où vous décidez

L’agent s’arrête et vous passe la main à ces moments :

• Questions de clarification. /codev-propose vous interroge avant de créer un change lorsqu’une ambiguïté changerait sensiblement le résultat, et de nouveau lorsqu’un artefact demande une décision ou qu’une Open Question change ce qu’il faut construire. /codev-explore pose les questions auxquelles le code ne peut pas répondre. /codev-apply s’arrête sur une ambiguïté ou un blocage et vous laisse décider.
• Valider le plan. /codev-propose s’arrête une fois les artefacts rédigés. Commencez votre relecture par les points à challenger, ce qui reste à décider et les Open Questions du design ; quand le plan vous convient, demandez /codev-apply. Pour modifier d’abord un artefact, utilisez /codev-update.
• Accepter les décisions. Un design suit les décisions en vigueur ou propose explicitement d’en remplacer une. Une décision ne prend effet que lorsque vous lancez codev decision accept.
• Confirmer la configuration. /codev-configure n’écrit qu’après votre oui à son diff.
• Appliquer une répercussion. /codev-update signale ce que la révision affecte par ailleurs ; vous acceptez, refusez ou reportez chaque suite.
• Mettre à jour codev. Lorsqu’un codev plus récent est disponible ou que le projet exige une autre version, la skill demande Update now ou Later avant d’agir (voir Annonce des mises à jour).
• Configurer les rôles. Les rôles de relecture qui s’exécutent, et les critères qu’ils ajoutent, relèvent du choix de votre projet dans roles: — voir Configurer les rôles.
• Trancher la revue. Une contestation que le relecteur a maintenue, ou un constat de gravité haute que personne n’a pu corriger, vous revient sous À décider : le corriger, en accepter le risque avec une justification, ou le reporter vers un autre change ou un ticket. La skill consigne votre décision avec votre nom ; elle n’accepte jamais un risque à votre place. codev review montre ce qui reste.
• Archiver. /codev-apply n’archive jamais : une fois l’implémentation relue, en commençant par ses notes de relecture, lancez /codev-archive ou codev archive.

Fiabilité des rôles

Les rôles de revue de codev sont mesurés, pas supposés. Cette page montre leurs scores lors de la dernière exécution de la suite d’évaluation, celle que le dépôt conserve comme ligne de base. Elle est générée à partir de cette ligne de base et change avec elle.

Ce que la suite mesure

La suite est un ensemble de petits projets, chacun avec un change planifié. Un cas ensemencé cache des défauts qu’un rôle devrait trouver, chacun avec sa gravité, son emplacement et sa catégorie de problème ; un témoin propre n’en cache aucun. Claude Code exécute une étape de skill sur chaque cas avec un seul rôle, et la suite note le compte rendu de revue que le rôle écrit : les défauts trouvés et manqués, les constats qui ne correspondent à aucun défaut (faux positifs), si chaque preuve citée se trouve vraiment aux lignes indiquées, et si la gravité concorde avec celle attendue. Mesurer les rôles en donne les règles.

Ce qu’elle ne mesure pas

Ce n’est ni un banc d’essai de modèles, ni la promesse qu’un rôle trouve chaque défaut de votre projet. Elle ne mesure pas l’utilité pour vous d’un constat juste. Le plan n’est mesuré que dans son ensemble, sur les cas de planification ci-dessous, par ce qu’il modifie, pas rôle par rôle. Un score décrit ces cas, avec ce modèle, le jour de l’exécution.

L’exécution

• Date : 2026-10-15
• Modèle : celui de Claude Code par défaut
• Claude Code : 2.1.289
• codev : 0.6.1
• Cas : 65 (25 ensemencés, 15 témoins propres, 25 de planification)
• Répétitions de chaque cas : 5
• Coût : 276,46 USD pour les 5 exécutions de chaque cas (55,07 USD pour une exécution de la suite)

En bref

Rappel

1,0039 défauts ensemencés trouvés sur 39

Validité des preuves

1,0069 citations sur 69 retrouvées aux lignes citées

Faux positifs

90,2 par cas ; un rôle échoue au-delà de 2

Rôles dans les seuils

8 sur 9▲ 1 en dépassent au moins un

L’exécution ne respecte pas ses propres seuils. 1 rôles sur 9 signalent plus de 2 faux positifs : skeptic. La précision est le point faible des rôles : ils signalent des problèmes plausibles que le cas ne contient pas. Réduire ces faux positifs sans perdre ce que les rôles trouvent est le prochain travail prévu sur les rôles. Chaque défaut ensemencé a été trouvé : avec ce modèle, le rappel ne distingue pas les rôles, et les différences se lisent dans les faux positifs et l’accord de gravité.

Faux positifs par rôle

Rappel et accord de gravité par rôle

Tous les rôles

Le tableau donne toutes les valeurs que les graphiques dessinent. Cas : ensemencés et témoins propres ; trouvés : défauts ensemencés trouvés sur ceux attendus ; preuves : part des citations vérifiées retrouvées aux lignes citées ; gravité : défauts trouvés dont la gravité est celle attendue.

La planification

25 cas de planification rejouent une demande sur le dépôt tel qu’il était avant un change archivé, et notent le plan qu’écrit /codev-propose face à ce que ce change a vraiment fait : le rappel principal est la part des exigences visées par la demande que le plan modifie, le rappel collatéral la part de celles que le vrai change a modifiées au passage ; un doublon probable est une exigence ajoutée là où il fallait en modifier une. Chaque chiffre est la médiane sur les répétitions, avec son écart.

Ce que consomme une exécution

• Une exécution de la suite : 55,07 USD
• Entrée par appel, en tokens : 63465
• Sortie par appel, en tokens : 696

Chaque appel au modèle est enregistré. Les tokens qu’un appel écrit dans le cache — ce qui est entré dans son contexte depuis l’appel précédent, l’essentiel du coût d’une exécution — sont répartis entre ce qui les a apportés : la lecture de la skill, chaque sous-commande codev, les fichiers, les recherches, la sortie du modèle lui-même ; prompt est le prompt propre de Claude Code et la demande. Par cas la médiane sur ses exécutions, sommée sur les cas.

Les seuils

Un rôle échoue quand son rappel est inférieur à 0,50, quand il signale plus de 2 faux positifs, ou quand moins de 0,80 de ses preuves vérifiées sont valides — les valeurs par défaut de la suite, --min-recall, --max-false-positives et --min-evidence. Un rôle sans cas ensemencé n’a pas de rappel, et un rôle sans constat vérifié pas de validité des preuves : aucun des deux n’échoue sur cette mesure.

• ▲ skeptic dépasse : faux positifs 4 > 2
• ✓ Dans tous les seuils : accessibility, migration, newcomer, ops, performance, privacy, security, tracer

Les limites

• 5 exécutions par cas. Un modèle ne répond pas deux fois de la même façon : chaque score est la médiane de 5 exécutions de chaque cas, et une modification se compare à l’écart qu’elles couvrent, avec le même modèle, pas d’un jour ou d’un modèle à l’autre.
• Seulement ce que les cas couvrent. 65 cas, dont 25 ensemencés de 39 défauts. Un type de défaut qu’aucun cas n’ensemence n’est pas mesuré : un rappel de 1,00 signifie que ces défauts-là ont été trouvés, pas tous les défauts.
• Un contexte maîtrisé. Chaque cas est un petit projet relu par un seul rôle, avec un budget et un temps fixés. Votre projet est plus grand, et les rôles le relisent ensemble.
• Pas une garantie. Les scores décrivent les rôles avec ce modèle et cette version de Claude Code. Un autre modèle peut obtenir d’autres scores. Lisez ce que les rôles signalent avant d’agir.
• La planification rejoue un historique public. Les cas de planification rejouent des demandes sur des états passés de codev, que le modèle a pu lire : leurs chiffres comparent deux versions des skills sur les mêmes cas, ils ne disent pas comment codev planifie un projet qu’il n’a jamais vu.

L’exécuter vous-même

Depuis un clone du dépôt, avec Claude Code installé et connecté. Une exécution appelle un modèle : celle-ci a coûté 276,46 USD pour les 5 exécutions de chaque cas (55,07 USD pour une exécution de la suite).

cargo build --bin codev
cargo run -p codev-evals -- run --out target/evals/mine
cargo run -p codev-evals -- score target/evals/mine

Les observations, les rapports et les métadonnées de l’exécution sont dans evals/baseline. Le guide de contribution explique comment se mesure une modification d’un rôle.

Concepts

codev conserve trois types d’enregistrements dans le dépôt : les specs disent ce que fait le système, les décisions expliquent pourquoi il est construit ainsi, et les changes sont le travail en cours qui modifie les unes et les autres.

_codev/
├── config.yaml     # configuration du projet
├── specs/          # contrats de comportement — CE QUE fait le système
├── decisions/      # décisions d'architecture — POURQUOI il est construit ainsi
├── changes/        # travail en cours, qui modifie les deux dossiers ci-dessus
│   ├── <name>/     #   proposal.md, design.md, tasks.md, specs/** (deltas)
│   └── archive/    #   changes terminés, datés
├── schemas/        # schémas de workflow personnalisés (facultatif)
└── codev.lock      # sources git héritées et épinglées (le cas échéant)

codev trouve ce dossier en remontant l’arborescence depuis le répertoire courant : chaque commande fonctionne donc depuis n’importe quel sous-répertoire du projet.

Capacité

Une capacité est une unité de comportement observable qu’offre le système — l’authentification des utilisateurs, le réglage du thème, la commande validate. Une capacité est identifiée par un chemin de segments en kebab-case, comme ui/theme ou identity/user-auth, qui indique aussi l’emplacement de sa spec. Regroupez les capacités selon l’organisation de votre domaine métier, et non selon celle de votre code.

Spec

La spec principale d’une capacité se trouve dans _codev/specs/<capability>/spec.md. Elle comporte une section ## Purpose — une ou deux phrases sur la raison d’être de la capacité — et une section ## Requirements :

# Theme Specification

## Purpose

Permettre aux utilisateurs de choisir le thème de couleurs de l'interface.

## Requirements

### Requirement: Le thème suit par défaut la préférence du système

L'application SHALL s'afficher avec le jeu de couleurs du système d'exploitation tant que l'utilisateur n'a pas choisi de thème.

#### Scenario: Aucun thème encore choisi

- **GIVEN** un utilisateur qui n'a jamais modifié le réglage du thème
- **WHEN** son système d'exploitation est en mode sombre
- **THEN** l'application s'affiche avec le thème sombre

Chaque exigence est normative (elle emploie SHALL ou MUST, ou DOIT ou DOIVENT dans une spec en français) et comporte au moins un scénario décrivant un comportement observable. Une spec décrit un comportement, jamais une implémentation : si le code peut changer sans que le comportement change, la spec ne doit pas changer non plus.

On ne modifie jamais directement une spec principale. Elle n’évolue que lorsqu’un change est synchronisé ou archivé, ce qui rend son historique lisible.

Change

Un change est un dossier _codev/changes/<name>/ qui porte une évolution du système : une proposal, des deltas de specs, un design et une liste de tâches, ainsi qu’un fichier change.yaml contenant ses métadonnées. Les artefacts que comporte un change sont définis par son schéma ; le schéma par défaut, spec-driven, est décrit dans Le workflow.

Un change est actif tant qu’il se trouve dans _codev/changes/<name>/. L’archivage le déplace dans _codev/changes/archive/<YYYY-MM-DD>-<name>/, où il devient la trace du pourquoi et du comment de l’évolution des specs.

Delta

Un delta est la partie d’un change qui modifie une spec. Il se trouve dans _codev/changes/<name>/specs/<capability>/spec.md — le même chemin de capacité que la spec principale qu’il cible — et s’organise en quatre opérations au plus :

Voici un delta qui modifie une exigence et en renomme une autre :

## MODIFIED Requirements

### Requirement: Le thème suit par défaut la préférence du système

L'application SHALL s'afficher avec le jeu de couleurs du système d'exploitation tant que l'utilisateur n'a pas choisi de thème, et SHALL basculer en direct lorsque cette préférence change.

#### Scenario: Aucun thème encore choisi

- **GIVEN** un utilisateur qui n'a jamais modifié le réglage du thème
- **WHEN** son système d'exploitation est en mode sombre
- **THEN** l'application s'affiche avec le thème sombre

## RENAMED Requirements

- FROM: Le thème choisi est mémorisé
- TO: Le thème choisi suit l'utilisateur

Un bloc MODIFIED remplace l’exigence tout entière : copiez donc le bloc complet depuis la spec principale — scénarios compris — avant de le modifier. Tout contenu omis est perdu lors de la fusion. Si vous ajoutez un comportement sans modifier l’existant, utilisez ADDED.

La fusion ne touche que les exigences nommées dans le delta. Tout le reste de la spec principale — autres exigences, sections libres, commentaires — reste tel quel.

Le delta d’une nouvelle capacité commence par sa propre section ## Purpose ; sa fusion crée la spec principale. Supprimer entièrement une capacité — un delta REMOVED qui vide une spec — exige retire_capabilities: true dans change.yaml, car cette suppression ne peut être annulée que depuis git.

La syntaxe exacte figure dans Formats de fichiers.

Décision

Une décision, ou ADR (architecture decision record), est un fichier _codev/decisions/NNNN-<slug>.md qui consigne un choix d’architecture : son contexte, la décision elle-même, ses conséquences et les alternatives envisagées.

codev decision new "Use PostgreSQL for persistence"
codev decision accept 0001

Une décision a l’un des cinq statuts suivants : accepted, superseded, proposed, deprecated ou rejected. Toutes les commandes qui créent une décision — codev decision new, supersede, deviate et promote — la créent proposed, afin que vous puissiez la rédiger librement ; codev decision accept la passe à accepted une fois son texte définitif. L’acceptation est la seule étape qui fait entrer une décision en vigueur : une décision proposed ne remplace encore rien et ne s’écarte encore de rien. Une décision est en vigueur lorsqu’elle est accepted et qu’aucune autre ne la remplace. Les décisions en vigueur sont transmises à l’agent chaque fois qu’il rédige un design.md, afin que les designs les respectent au lieu de les remettre en débat.

Chaque décision possède un identifiant court (0007) et un identifiant qualifié qui indique sa provenance : project/0007 pour une décision du projet lui-même, path:~/shared/0100 ou git:git@github.com:acme/shared.git/0100 pour une décision héritée d’un autre dépôt.

Sceau

Une décision acceptée est immuable. Lorsqu’une décision devient acceptée par une commande codev decision — accept, ou new --status accepted — codev enregistre une empreinte SHA-256 du contenu de la décision dans _codev/decisions/seal.yaml ; codev decision seal fait de même pour une décision que vous avez acceptée à la main. codev validate compare le contenu de chaque décision locale accepted ou superseded à son empreinte, et signale une modification par l’erreur decision_seal_mismatch et un sceau manquant par l’avertissement decision_unsealed. Une décision proposed n’est pas scellée.

Le frontmatter n’est pas couvert par le sceau : un statut peut donc passer de accepted à superseded sans le briser.

Remarque Scellez une décision lorsque son texte est définitif : rédigez d’abord la décision proposed, puis lancez codev decision accept <ID>, qui change le statut et enregistre le sceau en une seule étape. Si vous avez modifié volontairement une décision scellée, codev decision seal <ID> --force enregistre le nouveau contenu ; pour changer ce que dit une décision acceptée, remplacez-la plutôt.

Remplacement

Pour changer une décision, remplacez-la plutôt que de la modifier :

codev decision supersede 0001 "Use SQLite for persistence"

codev crée une nouvelle décision proposed dont le frontmatter indique supersedes: ["0001"], et ne touche pas à 0001 : elle reste accepted, et en vigueur, pendant que vous rédigez la nouvelle. Accepter la nouvelle décision marque 0001 comme superseded dans la même étape :

codev decision accept 0002

Le contenu de l’ancienne décision reste strictement identique : son sceau reste valide et l’historique du raisonnement est préservé. Seule une décision accepted peut être remplacée : si une autre décision a remplacé 0001 entre-temps, codev decision accept refuse avec predecessor_not_accepted et n’écrit rien.

Écart

Une décision héritée ne peut pas être remplacée depuis votre projet, puisque vous ne pouvez pas écrire dans sa source. Consignez plutôt un écart local :

codev decision deviate path:~/shared/0100 "Services log in logfmt"

Cette commande crée une décision locale proposed dont le champ deviates_from pointe vers la décision héritée. L’écart entre en vigueur lorsque vous l’acceptez avec codev decision accept : la décision héritée reste alors visible dans codev decision list, mais elle n’est plus en vigueur pour votre projet et n’est plus transmise à l’agent lorsqu’il rédige des designs. D’ici là, la décision héritée reste en vigueur.

Promotion

Un design contient souvent une décision qui mérite de survivre au change. Rédigez-la dans design.md sous la forme d’un bloc ### Decision: <title>, puis promouvez-la :

codev decision promote add-audit-log "Append-only audit table"

codev crée un ADR proposed dont la section ## Decision reprend tel quel le contenu du bloc, et remplace le contenu du bloc par une référence au nouvel ADR. Relisez-le et répartissez le texte promu dans les sections de l’ADR, puis acceptez-le avec codev decision accept, qui le scelle — idéalement avant d’archiver le change.

Source héritée

Un projet peut hériter, en lecture seule, du contenu d’autres dépôts codev — un dossier partagé sur votre machine (path:) ou un dépôt git épinglé sur un commit (git:). Chaque source apporte son context:, ses rules: et ses décisions. Rien d’exécutable n’est jamais hérité, et rien n’est lu depuis une branche mouvante : les sources git sont épinglées dans _codev/codev.lock. Voir Sources héritées.

Schéma

Un schéma définit les artefacts que comporte un change, les prérequis de chacun, ainsi que les instructions et les templates que suit l’agent pour les rédiger. codev embarque un schéma, spec-driven. Un projet peut définir les siens dans _codev/schemas/. Voir Schémas personnalisés.

Dans spec-driven, chaque instruction s’ouvre sur le rôle qui porte l’artefact et ses critères « Done when » : product owner pour la proposal (pourquoi et quoi), analyste QA pour les specs (comportement observable), architecte pour le design (comment), tech lead pour les tâches (ordonnancement et vérification).

Sources héritées

Les équipes qui maintiennent plusieurs dépôts partagent en général des conventions : la façon dont les services journalisent, la base de données à utiliser, le versionnement des API. Grâce aux sources héritées, ces conventions vivent dans un seul dépôt codev, et chaque projet qui en hérite les reçoit — sans rien copier.

Ce qu’apporte une source

Une source héritée est un autre projet codev, doté de son propre _codev/config.yaml. Votre projet y lit trois choses :

• son context:, placé avant votre propre contexte dans les instructions de chaque artefact ;
• ses rules:, placées avant vos propres règles pour le même artefact ;
• ses décisions, issues de son dossier _codev/decisions/, qui sont transmises à l’agent avec les vôtres lorsqu’il rédige un design.md.

Les sources sont en lecture seule. codev n’y écrit jamais, et n’y lit que des fichiers Markdown et YAML : rien d’exécutable n’est hérité.

Lorsque l’agent reçoit le contexte et les règles, chaque bloc indique sa provenance, du plus général (les sources, dans l’ordre de déclaration) au plus spécifique (votre projet). Lorsque deux blocs se contredisent, le dernier l’emporte, et les skills ont pour consigne de signaler la contradiction plutôt que de la trancher en silence.

L’héritage n’est pas transitif : si une source déclare elle-même inherits:, ces sources sont ignorées et codev vous en avertit. Déclarez directement dans votre projet toutes les sources dont vous avez besoin.

Déclarer les sources à l’initialisation

Le plus rapide pour démarrer un projet sur des conventions partagées est de nommer les sources dès l’initialisation, une par --inherit :

codev init --yes --inherit /home/you/acme-standards.git@main

codev initialized in /home/you/acme-api

  Structure   _codev/ — specs, decisions, changes, schemas
  Skills      codev-propose, codev-explore, codev-onboard, codev-apply, codev-sync, codev-archive, codev-update, codev-configure → .claude/skills/
  Inherits    /home/you/acme-standards.git @main → pinned 8dc995327621
…

codev init les écrit sous inherits: dans le nouveau _codev/config.yaml :

# set with codev init --inherit
inherits:
  - git: /home/you/acme-standards.git
    ref: main

Une valeur qui commence par git@, https://, http://, ssh:// ou file://, ou qui se termine par .git, est une source git ; @<ref> choisit la branche ou le tag, et main s’applique en son absence. Toute autre valeur est un dossier local, qui doit exister ; un dossier relatif est écrit en chemin absolu, avec des barres obliques / sur toutes les plateformes, pour que le fichier soit identique quelle que soit la machine qui a lancé codev init. Une valeur manifestement fausse — vide, un dossier absent, une URL git terminée par @ — est refusée avec invalid_inherit avant toute écriture.

Les sources git sont épinglées aussitôt, exactement comme le ferait codev sources update. Si cela échoue — pas de réseau, identifiants manquants, ref inexistante —, le projet est tout de même initialisé et la source déclarée, mais elle reste non épinglée :

warning: git source `https://git.example.com/acme/codev-standards.git` has no locked SHA — run `codev sources update` to resolve it
warning: the inherited git source(s) could not be pinned: https://git.example.com/acme/codev-standards.git is invalid: ls-remote for `https://git.example.com/acme/codev-standards.git` failed: fatal: unable to access 'https://git.example.com/acme/codev-standards.git/': Could not resolve host: git.example.com
help: run codev sources update

Corrigez la cause, puis lancez codev sources update. codev init ne déplace jamais un épinglage existant et ne modifie jamais un config.yaml existant : sur un projet déjà initialisé, ajoutez les sources sous inherits: à la main.

Sources locales

Une source path: est un dossier de votre machine — en général un clone du dépôt partagé de votre équipe :

# _codev/config.yaml
inherits:
  - path: ~/src/acme-standards

Le chemin peut être absolu ou commencer par ~. Il est lu directement : les modifications apportées à ce dossier sont donc visibles immédiatement. Les sources path: sont pratiques pendant que vous rédigez des conventions partagées ; pour tous les autres, préférez une source git épinglée.

Sources git

Une source git: est un dépôt distant, épinglé sur un commit :

inherits:
  - git: git@github.com:acme/codev-standards.git
    ref: main

ref est obligatoire : une branche ou un tag. Utilisez subpath lorsque le projet codev se trouve dans un sous-dossier du dépôt :

inherits:
  - git: git@github.com:acme/platform.git
    ref: v2
    subpath: standards

Une source git n’est utilisée qu’une fois verrouillée. Résolvez-la et téléchargez-la avec :

codev sources update

Changes:
  + git@github.com:acme/codev-standards.git @main  → 12958274cbed0eb66985f57d3272c6d3134b672d

codev.lock updated.

Cette commande résout chaque ref en commit avec git ls-remote, récupère ce commit dans un cache local et l’enregistre dans _codev/codev.lock :

version = 1

[[source]]
git = "git@github.com:acme/codev-standards.git"
ref = "main"
commit = "12958274cbed0eb66985f57d3272c6d3134b672d"
resolved_at = "2026-09-30"

Commitez codev.lock. Toutes les personnes qui travaillent sur le projet lisent alors exactement le même commit, et un changement d’épinglage apparaît en revue comme n’importe quel autre diff.

codev sources update et codev init --inherit sont les seules commandes qui accèdent au réseau, et seule codev sources update déplace un épinglage. Toutes les autres lisent le commit verrouillé depuis le cache, hors ligne. Relancez codev sources update pour déplacer les épinglages vers le commit actuel de chaque ref ; la commande indique pour chaque source si elle est ajoutée (+), déplacée (~, avec l’ancien et le nouveau commit) ou inchangée (=).

Le cache se trouve dans $XDG_CACHE_HOME/codev/, ou dans ~/.cache/codev/ lorsque XDG_CACHE_HOME n’est pas défini. Les sources git nécessitent git dans votre PATH, avec un accès au dépôt : codev utilise vos identifiants git existants.

Inspecter les sources

codev sources list

Inherited sources:
  git git@github.com:acme/codev-standards.git  [locked]
      commit: 12958274cbed0eb66985f57d3272c6d3134b672d
      path:   /home/you/.cache/codev/content/12958274cbed0eb66985f57d3272c6d3134b672d

Chaque source se trouve dans l’un des états suivants :

codev sources show <TARGET> affiche une source, désignée par son chemin ou son URL, et liste les fichiers qu’elle expose.

Décisions héritées

Les décisions héritées apparaissent dans codev decision list à côté des vôtres. Leur identifiant qualifié indique la source dont elles proviennent, telle que déclarée dans votre configuration :

path:~/src/acme-standards/0100
git:git@github.com:acme/codev-standards.git/0100

Si une décision locale porte le même identifiant court qu’une décision héritée, la décision locale l’emporte et codev émet l’avertissement decision_id_collision.

Vous ne pouvez ni modifier ni remplacer une décision héritée depuis votre projet. Lorsque votre projet doit s’en écarter, consignez un écart :

codev decision deviate path:~/src/acme-standards/0100 "Services log in logfmt"

La nouvelle décision locale référence la décision héritée dans deviates_from. Elle est créée proposed, non scellée : rédigez pourquoi votre projet s’écarte, puis acceptez-la, ce qui la scelle :

codev decision accept 0003

L’écart n’entre en vigueur qu’une fois accepté. D’ici là, la décision héritée reste en vigueur et figure toujours dans les instructions de l’artefact design. Une fois l’écart accepté, la décision héritée reste listée, ce qui rend l’écart visible, mais elle n’est plus en vigueur pour votre projet. Voir Écart.

Ce qui n’est pas hérité

• Les specs. Chaque projet possède ses propres specs de comportement.
• schema, language, workflows et mcp. Ces clés relèvent du projet et des personnes qui y travaillent.
• Les sources de la source, comme expliqué plus haut.

Intégration au dépôt et codev doctor

Les specs et les skills ne suffisent pas : Claude Code doit savoir que le dépôt fonctionne avec codev, la CI doit repérer une spec invalide, et les relecteurs doivent voir quel change une pull request met en œuvre. codev init met tout cela en place, codev update le tient à jour, et codev doctor vous dit ce qui manque encore.

Ce qu’écrit codev init

CLAUDE.md

Claude Code lit CLAUDE.md au début de chaque session. codev init le crée, ou ajoute une section au vôtre, pour que Claude ne modifie pas un comportement sans change codev :

<!-- codev:begin — managed by codev; `codev update` rewrites this block, edit outside it -->
## Spec-driven development with codev

This repository follows spec-driven development with codev.

- `_codev/specs/` describes the current behavior and is authoritative.
- `_codev/decisions/` holds accepted architecture decisions: follow them, do not re-debate them.
- For any change of behavior, start with `/codev-propose`, then implement it with `/codev-apply`. Do not modify behavior without a codev change.
- Trivial fixes (typos, documentation wording) are exempt.
- Run `codev validate` before committing.

Installed skills: `/codev-propose`, `/codev-explore`, `/codev-onboard`, `/codev-apply`, `/codev-sync`, `/codev-archive`, `/codev-update`, `/codev-configure`.
<!-- codev:end -->

La section est en anglais quelle que soit la language: du projet : elle s’adresse à l’agent. Lorsque /codev-apply n’est pas installée, elle demande de mettre en œuvre en suivant le tasks.md du change.

Workflow de CI

Sur un dépôt GitHub — doté d’un dossier .github/, ou d’un remote git sur github.com —, codev init crée .github/workflows/codev.yml :

# codev:managed — generated by `codev init`, refreshed by `codev update`.
# Delete this first line to take the file over: codev will then leave it alone.
name: codev

on:
  push:
  pull_request:

jobs:
  validate:
    name: codev validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Install codev 0.6.1
        run: |
          curl -sSL https://raw.githubusercontent.com/mairistem/codev/main/install.sh | CODEV_VERSION=0.6.1 sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Validate specs and changes
        run: codev validate --strict

L’installateur est épinglé sur la version de codev qui a écrit le fichier : la CI valide avec les mêmes règles que votre machine. codev n’écrit pas ce fichier lorsque :

• un autre workflow de .github/workflows/ exécute déjà codev validate — toute ligne qui nomme codev puis validate compte, comme cargo run --bin codev -- validate ;
• .github/workflows/codev.yml existe et n’a pas été écrit par codev (sa première ligne n’est pas # codev:managed).

codev ne modifie jamais aucun autre fichier de workflow. Sur un dépôt GitLab — un fichier .gitlab-ci.yml, ou un remote sur GitLab —, il ne touche pas à .gitlab-ci.yml et affiche à la place un job à coller :

  Repository integration
    + CLAUDE.md                          created
    - .gitlab-ci.yml                     skipped: codev never edits .gitlab-ci.yml — add the job below to run codev validate

        codev:
          image: debian:stable-slim
          before_script:
            - apt-get update -qq && apt-get install -y -qq curl ca-certificates
            - curl -sSL https://raw.githubusercontent.com/mairistem/codev/main/install.sh | CODEV_VERSION=0.6.1 sh
          script:
            - ~/.local/bin/codev validate --strict

    - pull request template              skipped: not a GitHub repository

Ailleurs, l’étape est écartée avec une indication : ajoutez codev validate --strict à votre pipeline.

Modèle de pull request

Sur GitHub, codev init ajoute une section à votre modèle de pull request — le premier pull_request_template.md trouvé dans .github/, à la racine du projet ou dans docs/, quelle que soit la casse — ou crée .github/PULL_REQUEST_TEMPLATE.md :

<!-- codev:begin — managed by codev; `codev update` rewrites this block, edit outside it -->
## codev

- codev change: <!-- folder under `_codev/changes/`, or "trivial fix, no change" -->
- [ ] `codev validate --strict` passes.
<!-- codev:end -->

Sections gérées

Le texte de codev dans CLAUDE.md et dans le modèle de pull request se trouve entre deux commentaires HTML, invisibles une fois le markdown affiché :

<!-- codev:begin — managed by codev; `codev update` rewrites this block, edit outside it -->
…
<!-- codev:end -->

• Tout ce qui se trouve hors des marqueurs vous appartient et n’est jamais modifié. Une section ajoutée à un fichier existant se place à la fin, après une ligne vide ; vous pouvez déplacer le bloc entier où vous voulez.
• codev update réécrit ce qui se trouve entre les marqueurs, et rien d’autre : vos modifications à l’intérieur du bloc sont perdues à la prochaine mise à jour.
• Lorsque les marqueurs sont déséquilibrés ou répétés, le fichier est laissé tel quel et l’avertissement managed_section_malformed le nomme.

Le fichier de workflow appartient entièrement à codev. codev update le réécrit, ce qui aligne sa version épinglée après une mise à jour, tant que sa première ligne est # codev:managed. Supprimez cette ligne pour reprendre la main sur le fichier : codev n’y touche plus.

codev update ne rafraîchit que ce qui existe. Il ne crée jamais CLAUDE.md, le workflow ou le modèle, et n’ajoute jamais de section à un fichier qui n’en a pas.

Refuser l’intégration

Ces options valent pour une exécution de codev init. Un codev init ultérieur sans elles écrit les fichiers ; codev update, jamais.

codev doctor

codev doctor vérifie l’ensemble de l’installation et donne, pour chaque manque, la commande ou la skill qui le comble. La commande est en lecture seule et fonctionne hors ligne ; pour la vérification changelog, elle demande au dépôt git local quels changes ont été archivés depuis le dernier tag :

codev doctor

codev doctor — /home/you/acme-app

Configuration
  ✗ config.rules     no rules: in _codev/config.yaml
      fix: /codev-configure
  ✓ config.language  language: is set
  ✓ config.keys      no unknown key in _codev/config.yaml
  ✓ config.roles     active roles: analyst, investigator, product, qa, architect, lead, tracer, skeptic, developer, newcomer; on domain: security (security), privacy (personal-data), accessibility (user-interface), performance (performance), ops (operations), migration (migration); disabled: none
  ✓ skills           8 skill(s) installed and current
  ✓ sources          no inherited git source
  ✓ codev_version    no newer codev release known

Planning
  ✗ specs            no main spec in _codev/specs/
      fix: /codev-propose <a change> — documenting existing behavior is planned work too
  ! decisions        no accepted decision (not every project needs one)
      fix: codev decision new "<title>"
  ✓ validate         codev validate reports no issue

Repository
  ✓ claude_md        CLAUDE.md has the codev section
  ✓ ci               .github/workflows/codev.yml runs codev validate
  ✓ pr_template      the pull request template has the codev section
  ✓ changelog        CHANGELOG.md matches the archived changes

14 check(s), 2 to fix, 1 warning(s)

✗ signale un élément manquant, ! un avertissement — un projet peut très bien n’avoir aucune décision acceptée. La vérification pr_template n’apparaît que pour un dépôt GitHub. La vérification changelog, simple avertissement, compare la section [Unreleased] de CHANGELOG.md avec ce que génère codev changelog ; la correction est codev changelog --write — voir Notes de version et CHANGELOG. La vérification codev_version est manquante lorsque le codev en cours ne satisfait pas le codev_version du projet, et devient un avertissement lorsque le cache de vérification connaît une release plus récente ; la correction est codev self-update, ou codev self-update --version <X.Y.Z> lorsque le codev en cours est plus récent que ce que l’exigence autorise. La vérification config.keys signale les clés de _codev/config.yaml que ce codev ne connaît pas — voir Clés inconnues. La liste complète des vérifications se trouve dans la référence de la CLI.

codev init et codev status se terminent par une ligne d’indication lorsqu’il manque quelque chose, et /codev-onboard liste les éléments manquants avec leur correction.

En CI, codev doctor --strict sort avec le code 1 lorsqu’une vérification manque ; les avertissements ne font jamais échouer la commande. codev doctor --json fournit le même rapport aux scripts, avec des identifiants et des codes stables — voir Sortie JSON.

Notes de version et CHANGELOG

Chaque change archivé dit déjà pourquoi il a été fait et ce qui a changé. codev en tire les notes de version : chaque proposal porte une courte section ## Release note destinée aux utilisateurs, et codev changelog rassemble les notes des changes archivés depuis la dernière version. Le choix du numéro de version, le tag et la publication restent entre vos mains et celles de vos outils de release.

Rédiger la note de version avec la proposal

/codev-propose rédige la section avec le reste de la proposal, après ## Impact :

## Release note

- Added: `--format json` pour `codev export`.
- Changed: **BREAKING** `codev export` écrit sur stdout par défaut ; passez
  `--output <PATH>` pour écrire un fichier.

Chaque élément s’écrit - <Category>: <texte>, avec l’une des six catégories de Keep a Changelog : Added, Changed, Deprecated, Removed, Fixed, Security. Les catégories restent en anglais ; le texte suit la langue des artefacts. Écrivez pour les personnes qui utilisent le produit, pas pour celles qui le construisent. Un élément incompatible commence par **BREAKING**. Un change que personne ne remarquera — un refactoring, un test, un réglage de CI — écrit la seule ligne None.

codev validate contrôle la section sur les changes actifs : une section absente donne un avertissement (release_note_missing), une catégorie inconnue, un élément sans texte ou une section vide une erreur (release_note_invalid). Le format complet figure dans Formats de fichiers.

Générer les notes

codev changelog

## [Unreleased]

### Added

- `--format json` pour `codev export`.

### Changed

- **BREAKING** `codev export` écrit sur stdout par défaut ; passez `--output <PATH>` pour écrire un fichier.

C’est git qui décide de l’intervalle : les changes dont le dossier se trouve dans _codev/changes/archive/ aujourd’hui et ne s’y trouvait pas au dernier tag v*. Utilisez --since <ref> et --until <ref> pour un autre intervalle — par exemple les notes d’une version passée :

codev changelog --until v1.4.0 --format markdown

--until v1.4.0 commence après le tag de version juste en dessous, v1.3.x. --format markdown retire le titre de version, ce qui convient au texte d’une release ; --format json fournit les éléments aux scripts (voir Sortie JSON).

Les changes archivés avant l’existence des notes de version n’ont pas de ## Release note : les puces de leur section What Changes sont listées sous Changed, et un avertissement release_note_missing nomme chacun d’eux pour que vous puissiez en relire la formulation. Un change dont les specs suppriment des exigences sans élément Removed ni BREAKING reçoit un avertissement release_note_inconsistent.

Tenir CHANGELOG.md à jour

codev changelog --write

--write place le bloc [Unreleased] dans CHANGELOG.md, entre les marqueurs de codev, juste après l’en-tête du fichier — le fichier est créé avec un en-tête standard s’il n’existe pas :

# Changelog

All notable changes to this project are documented in this file.

<!-- codev:begin — generated by `codev changelog --write` from the archived changes; edit outside this block -->
## [Unreleased]

### Added

- `--format json` pour `codev export`.
<!-- codev:end -->

## [1.3.0] - 2026-09-30
…

Les versions publiées, le texte écrit à la main et les liens en bas du fichier restent tels quels. Relancer la commande sans rien de nouveau laisse le fichier inchangé. codev doctor signale un avertissement changelog lorsque la section est en retard sur l’archive, ou lorsque CHANGELOG.md n’existe pas.

Remarque Si CHANGELOG.md a déjà un titre ## [Unreleased] écrit à la main, le premier --write le reprend : la section gérée remplace ce titre, et les entrées que vous avez écrites en dessous restent à leur place, dans la même section.

Publier une version

Juste avant de poser le tag :

codev changelog --release 1.4.0 --write

Le bloc généré devient ## [1.4.0] - <aujourd'hui> (ou --date YYYY-MM-DD), hors des marqueurs, et une nouvelle section ## [Unreleased] vide prend sa place dans la section gérée. Commitez, puis posez aussitôt le tag v1.4.0 : tant que le tag n’existe pas, codev changelog compte encore ces changes comme non publiés.

Sur GitHub, le workflow de release peut reprendre les mêmes notes pour le texte de la release, produites par le codev du commit tagué :

codev changelog --until "$GITHUB_REF_NAME" --format markdown > release-notes.md

L’adopter dans un projet existant

Si votre CHANGELOG.md décrit déjà des changes archivés sans note de version, listez-les sous changelog.exclude dans _codev/config.yaml, pour qu’ils ne soient pas listés une seconde fois :

changelog:
  exclude:
    - 2026-09-30-legacy-import

Une fois la version suivante taguée, ils sortent de l’intervalle et la liste peut être vidée. Voir Configuration.

Compte rendu de revue

Quand le contradicteur et les experts challengent un plan, ou que le nouvel arrivant et les experts relisent le code, ce qu’ils trouvent ne reste pas dans la conversation. Tout va dans le compte rendu de revue du change, _codev/changes/<name>/review.md : chaque constat avec sa gravité, la preuve sur laquelle il repose, et chaque réponse qu’il a reçue — qui l’a corrigé, qui l’a contesté et pourquoi, qui en a accepté le risque. codev vérifie ce qui peut l’être, et codev archive ne clôt pas un change dont la revue n’est pas tranchée.

Ce que contient un constat

## code.review

### security

#### R-security-1 The session lookup concatenates the token

```yaml
severity: high
confidence: high
location: "src/auth/session.rs:42-44"
evidence: |
  let query = format!("SELECT * FROM sessions WHERE token = '{}'", token);
recommendation: Bind the token as a query parameter.
history:
  - status: open
    by: security
```

• L’identifiant, R-security-1, est stable pendant toute la vie du change : l’identifiant du rôle et le prochain numéro libre. Il n’est jamais renuméroté ni réutilisé, si bien qu’une discussion peut le citer.
• La gravité dit à quel point c’est grave si le relecteur a raison, et la confiance à quel point il en est sûr — voir les échelles dans Rôles. Un constat de confiance basse est conservé et reçoit une réponse, mais il ne vous est présenté que si vous devez le trancher.
• L’emplacement est path:line ou path:start-end depuis la racine du projet pour le code, ou <file>#<heading> depuis le dossier du change pour le plan ("design.md#Decision: Sessions live in the database"). Mettez-le entre guillemets : YAML lit : comme une nouvelle clé.
• La preuve est le texte cité, copié mot pour mot — des lignes entières ou le fragment qui compte. Un relecteur prouve ce qu’il avance.

Le format complet est dans Formats de fichiers. Les titres, les clés et les valeurs du bloc restent en anglais : codev les lit.

Les revues isolées

En mode isolé, le compte rendu dit aussi comment l’étape s’est déroulée, et qui a relevé quoi :

## code.review

Mode: isolated.
Summarized: src/generated/schema.rs — over the material limit.

### security

#### R-security-1 The session lookup concatenates the token

```yaml
severity: high
confidence: high
location: "src/auth/session.rs:42-44"
evidence: |
  let query = format!("SELECT * FROM sessions WHERE token = '{}'", token);
recommendation: Bind the token as a query parameter.
raised_by: [security, newcomer]
history:
  - status: open
    by: security
```

### newcomer

Fallback: the sub-agent was stopped twice by its time limit.

No finding.

• Mode: — inline ou isolated, sous le titre de l’étape.
• Summarized: — une ligne par fichier que les relecteurs ont reçu sous forme de résumé plutôt qu’en entier, parce que la matière dépassait sa limite.
• raised_by — lorsque plusieurs relecteurs ont trouvé le même défaut, le constat est écrit une seule fois, sous le rôle qui l’a jugé le plus grave, et liste chaque rôle qui l’a relevé, le sien en premier. C’est ce rôle qui revérifie les réponses. Un rôle dont tous les constats ont été fusionnés indique No finding. ; codev review le montre crédité sur le constat partagé.
• Fallback: — le sous-agent du rôle a échoué deux fois et le rôle a relu en ligne, dans la conversation.

codev validate signale un Mode: autre que inline ou isolated, une deuxième ligne Mode: ou Fallback:, et un raised_by qui n’est pas une liste d’identifiants de rôles distincts commençant par le rôle du constat (review_invalid). Un codev antérieur à ces lignes les ignore, et signale raised_by comme champ inconnu (review_unknown_field).

La boucle de réponse

Un constat commence open. Ensuite :

1. L’auteur répond. Le rôle qui possède l’artefact cité à plan.challenge — product owner, analyste QA, architecte, tech lead — ou le développeur à code.review le corrige (fixed, avec ref : le commit ou la modification de fichier) ou le conteste (disputed, avec note : l’argument).
2. Le relecteur vérifie la réponse, une fois. Une correction est validée (fixed à nouveau, par le relecteur) ou rouverte (open, avec la raison). Une contestation est acceptée (rejected) ou maintenue (disputed, avec la raison).
3. Ce qui reste vous revient. Le résumé de la skill liste, sous À décider, chaque contestation que le relecteur a maintenue et chaque constat de gravité haute encore ouvert, avec les deux arguments. Vous le corrigez, en acceptez le risque (accepted-risk, avec une justification) ou le reportez (deferred, avec to : le change ou le ticket où il part). La skill consigne votre décision sous la forme by: human:<votre nom> ; elle ne décide jamais à votre place.

accepted-risk, deferred et rejected sont définitifs : pour revenir sur l’un d’eux, ouvrez un nouveau constat.

Ce que codev vérifie

codev validate lit le compte rendu de chaque change actif. Il ne juge jamais un constat — un constat open est l’état normal d’une revue — mais il vérifie tout ce qui ne demande pas de jugement :

• Le format : les titres, un bloc yaml par constat, les champs, les identifiants, les emplacements (review_invalid), et un champ inconnu (review_unknown_field, un avertissement).
• L’historique : la première entrée est open par le rôle du constat, chaque transition figure dans le tableau ci-dessus (review_invalid), et chaque entrée porte ce que son statut exige, décidée par qui doit la décider (review_decision_incomplete).
• La preuve, pour les constats open, disputed, accepted-risk et deferred, face aux fichiers tels qu’ils sont maintenant : le fichier, la ligne ou le titre existe (review_location_missing) ; chaque ligne citée se retrouve dans des lignes consécutives du fichier, espaces et fins de ligne ignorés, à 5 lignes au plus des lignes citées (review_evidence_not_found, ou review_evidence_moved quand elle est plus loin). Un constat fixed ou rejected n’est pas comparé : son code devait changer. Un fichier qui n’est pas du texte UTF-8, contient des octets NUL ou dépasse 4 Mio n’est pas comparé (review_evidence_unchecked).
• Les sections : quand le compte rendu contient une étape, chaque rôle actif à cette étape pour le change a sa section (review_role_missing). Un rôle désactivé peut écrire Disabled by configuration..

Aucun contrôle n’utilise git ni le réseau : ils lisent l’arbre de travail.

codev review

codev review --change add-sessions

Affiche le compte rendu étape par étape — chaque rôle, chaque constat avec sa gravité, son statut et son emplacement —, qui doit agir ensuite sur chacun (author, reviewer ou human), les défauts du compte rendu, et si la revue permet d’archiver le change. Les skills lisent cette sortie telle qu’elle s’affiche pour reprendre une revue interrompue et vérifier le compte rendu ; --json produit le document ReviewV1, pour les scripts. La commande sort avec 1 seulement quand le compte rendu contient une erreur.

Archiver

codev archive vérifie la revue après la validation. Il refuse, avec le code review_blocked, quand :

• des rôles étaient actifs à plan.challenge ou code.review et que le compte rendu n’existe pas (review_record_missing), ou n’a pas de section pour cette étape (review_step_missing) ;
• un constat high est encore open ou disputed (review_unresolved) ;
• le compte rendu vient d’un codev plus récent (review_format_unsupported).

Une étape sans rôle actif n’a pas besoin de section. codev sync ne regarde pas le compte rendu.

Les changes commencés avant le compte rendu

Un change planifié avec un codev antérieur n’a pas de compte rendu : son archivage est donc refusé. Relancez les étapes de relecture — /codev-apply relit le code et écrit le compte rendu — ou dites explicitement que le change n’a pas été relu en désactivant ses rôles de relecture dans son change.yaml :

roles:
  skeptic: never
  newcomer: never

Une équipe qui n’utilise pas du tout les skills fait de même dans _codev/config.yaml. Pour que tout le monde utilise un codev qui applique le verrou, relevez codev_version à la version qui l’apporte : un codev plus ancien ignore review.md et archive quand même.

Cas particuliers

• Relancer une étape complète le compte rendu ; un constat déjà consigné n’est pas relevé à nouveau, et une étape ou un rôle écrit deux fois est une erreur.
• Une session interrompue reprend à partir du compte rendu : awaiting dit qui doit répondre ensuite.
• Un change de documentation seule, ou encore sans code, a tout de même ses sections de relecture — No finding. est une réponse valide.
• Les fichiers générés, vendorisés ou binaires peuvent être cités ; les fichiers binaires et très volumineux ne sont pas comparés.
• Windows : \ dans un emplacement se lit /, et les fins de ligne \r\n sont ignorées dans le compte rendu comme dans les fichiers cités.
• Monorepos : les chemins sont relatifs à la racine du projet codev ; un fichier hors de cette racine ne peut pas être cité.

Jira et autres serveurs MCP

Les skills de codev peuvent puiser du contexte dans des systèmes externes via les serveurs MCP connectés à votre session Claude Code. La CLI elle-même ne communique jamais avec eux : ce sont les skills qui détectent dans votre demande ce dont elles ont besoin et qui appellent directement l’outil MCP.

Une intégration est disponible aujourd’hui : /codev-propose lit un ticket Jira.

Jira

Lorsque votre demande à /codev-propose contient un identifiant de ticket — toute chaîne correspondant à [A-Z]{2,}-\d+, comme PROJ-123 — et qu’un outil MCP Jira est configuré, la skill :

1. appelle une seule fois l’outil configuré, pour le premier identifiant trouvé ;

2. utilise le titre, la description, le statut et le type du ticket comme contexte pour le plan ;

3. cite le ticket en tête de la proposal :

   # Proposal: Ajouter un mode sombre
   
   > Source: ticket **PROJ-123** — "Mode sombre pour le tableau de bord" (In Progress)
   
   ## Why
   

L’intégration est strictement en lecture seule : un appel à l’unique outil configuré, jamais de recherche, de commentaire ni de transition. Si la demande mentionne plusieurs tickets, seul le premier est récupéré ; les autres sont listés sous la citation, pour la traçabilité.

Si un ticket est mentionné mais que le serveur MCP n’est pas disponible dans la session, la skill le signale, rédige la proposal à partir de votre seule demande et cite le ticket avec la mention « contenu non récupéré ».

Configurer l’intégration

Le nom de l’outil Jira dépend de la façon dont le serveur MCP est enregistré dans votre installation de Claude Code ; il se configure donc projet par projet :

# _codev/config.yaml
mcp:
  jira_tool: mcp__atlassian__getJiraIssue

codev init le renseigne pour vous lorsqu’il trouve, dans .mcp.json, .claude/settings.json ou ~/.claude.json, un serveur dont le nom, la commande ou l’URL mentionne Jira ou Atlassian :

  ✓ Jira MCP detected: mcp__atlassian__getJiraIssue
    (source: .mcp.json → server "atlassian")

Le nom de l’outil suit la convention de Claude Code, mcp__<server name>__getJiraIssue, où les espaces et les points du nom du serveur sont remplacés par des tirets bas — par exemple, un connecteur nommé claude.ai Atlassian Rovo donne mcp__claude_ai_Atlassian_Rovo__getJiraIssue. Si le vôtre diffère, cherchez le nom exact dans la liste des outils d’une session Claude Code et renseignez-le à la main.

À l’installation, codev ajoute l’outil aux allowed-tools de codev-propose : la skill peut ainsi l’appeler, et rien d’autre sur ce serveur. Après avoir modifié mcp:, régénérez les skills :

codev update --force

Sans mcp.jira_tool, la détection de tickets reste inactive : la skill se comporte exactement comme dans un projet sans intégration MCP.

Remarque mcp: n’est jamais repris d’une source héritée : les noms d’outils dépendent de l’installation de Claude Code de chacun, et non d’un dépôt partagé.

Ajouter une autre intégration MCP

Les intégrations MCP font partie de codev lui-même : chacune consiste en une clé de configuration et un emplacement réservé dans un workflow. En ajouter une — par exemple pour une page Confluence ou un outil de design — relève donc de la contribution à codev, et non du paramétrage. Le principe est le même que pour Jira :

1. Ajoutez une clé sous mcp: dans la configuration du projet (crates/codev-engine/src/config.rs).
2. Transmettez-la au contexte de rendu des skills et substituez un emplacement réservé comme {{JIRA_MCP_TOOL}} à la fois dans les allowed-tools et dans le corps du workflow qui l’utilise (crates/codev-agents/src/claude.rs).
3. Décrivez la détection et l’appel dans le fichier du workflow sous assets/workflows/, avec un repli propre lorsque la clé est absente.

On enrichit la skill existante plutôt que de la dupliquer : il n’existe qu’une seule /codev-propose, quelle que soit l’origine de la demande. Consultez CONTRIBUTING.fr.md pour en proposer une.

Langue des artefacts

codev lui-même s’exprime en anglais : ses commandes, ses messages, ses skills et ses templates sont en anglais. Les artefacts de planification que votre équipe lit et approuve — proposals, specs, designs, tâches — peuvent en revanche être rédigés dans n’importe quelle langue.

Définir la langue

La clé language: de _codev/config.yaml définit la langue de la prose des artefacts, sous la forme d’un code ISO 639 :

language: fr

Les valeurs acceptées sont un code de langue en minuscules de deux ou trois lettres, éventuellement suivi d’une sous-étiquette, telle qu’une région ou une écriture : en, fr, de, pt-BR, zh-Hant. Toute autre valeur rend la configuration invalide. En l’absence de la clé, la langue est l’anglais (en).

Comment codev init la choisit

codev init écrit la clé language: pour vous, avec un commentaire indiquant la provenance de la valeur. Il retient, dans l’ordre :

1. l’option --language <CODE> ;
2. à défaut, votre locale — la première des variables LC_ALL, LC_MESSAGES et LANG qui désigne une langue. C et POSIX sont ignorées : LC_ALL=C ne masque donc pas une variable LANG pertinente ;
3. à défaut, en.

codev init --language pt-BR

# set with `codev init --language`
language: pt-BR

La détection ne conserve que la partie langue de la locale — fr_FR.UTF-8 donne fr —, sauf lorsque la région change la langue écrite : pt_BR donne pt-BR, zh_TW et zh_HK donnent zh-Hant, zh_CN et zh_SG donnent zh-Hans. Passez --language pour enregistrer toute autre région. --no-detect désactive la détection de la locale en même temps que le reste de l’analyse de l’environnement.

Sur un projet qui possède déjà un _codev/config.yaml, codev init ne touche pas au fichier. Pour changer de langue par la suite, modifiez la clé.

Ce qui est traduit, et ce qui ne l’est pas

Les skills rédigent chaque phrase dans la langue configurée, quelle que soit la langue dans laquelle vous échangez avec Claude : les fichiers constituent la mémoire de l’équipe, et la langue est le choix de l’équipe.

Les skills écrivent la structure des fichiers en anglais : titres des templates (# Proposal:, ## Why, ## What Changes, ## Context, # Tasks…), structure des specs et des deltas (## Purpose, ### Requirement:, #### Scenario:…), mots-clés des scénarios et mots-clés normatifs (**WHEN**, **THEN**, SHALL, MUST).

codev lit cette structure en anglais comme en français, quelle que soit la valeur de language: : une équipe peut donc aussi rédiger ses specs entièrement en français. Chaque mot-clé a son texte dans chaque langue du catalogue de mots-clés de codev :

Une exigence rédigée entièrement en français se présente donc ainsi :

### Exigence : Le thème suit la préférence du système

L'application DOIT s'afficher avec le thème du système tant que l'utilisateur n'en a pas choisi.

#### Scénario : Aucun thème choisi

- **GIVEN** un utilisateur qui n'a jamais modifié le thème
- **WHEN** son système est en mode sombre
- **THEN** l'application s'affiche avec le thème sombre

Comment codev les lit et les écrit :

• Les mots-clés français tolèrent la casse, les accents et l’espace — ordinaire ou insécable — avant les deux-points : ### Exigence: X et #### Scenario : Y sont lus eux aussi. Les mots-clés anglais sont lus exactement comme avant.
• Les mots-clés normatifs ne comptent qu’en majuscules, dans les deux langues : doit en minuscules est de la prose ordinaire, et l’exigence échoue à la validation.
• Un document peut mélanger les deux langues.
• Quand codev sync ou codev archive modifie une spec, il en écrit les mots-clés dans la langue de cette spec ; une nouvelle spec prend la langue du delta qui la crée.
• Le changelog affiche les catégories de la note de version en anglais, quelle que soit la langue dans laquelle elles ont été écrites.
• Les noms de domaines (security, migration…) et les marqueurs du registre de revue restent en anglais. codev ne lit pas les lignes **GIVEN** / **WHEN** / **THEN**, que les skills écrivent en anglais.

Attention Une version de codev antérieure à ce catalogue refuse les mots-clés français. Avant que votre équipe ne les écrive, relevez codev_version dans _codev/config.yaml jusqu’à la première version dont le changelog les annonce : chaque contributeur utilisera ainsi un codev qui les lit. Un titre dans une langue que codev ne connaît pas, comme ### Requisito:, est signalé dans une section de delta (delta_unexpected_heading), et la synchronisation comme l’archivage refusent le change.

Quelles skills l’utilisent

codev instructions --json expose la langue dans son champ language. /codev-propose et /codev-update rédigent la prose des artefacts dans cette langue, et /codev-configure y rédige également le context: et les rules: qu’il propose. Le template d’ADR utilisé par les commandes codev decision a des titres de sections en anglais ; rédigez-en le contenu dans la langue de votre équipe.

Schémas personnalisés

Un schéma définit le workflow de planification d’un change : les artefacts qu’il comporte, leurs dépendances mutuelles, ainsi que l’instruction et le template que suit l’agent pour chacun. codev embarque un schéma, spec-driven — proposal, specs, design, tasks —, qui convient à la plupart des projets. Lorsque ce n’est pas le cas, vous pouvez définir le vôtre, sous forme de simples fichiers de données : ni code, ni recompilation.

Emplacement des schémas

Un schéma de projet est un dossier situé sous _codev/schemas/ :

_codev/schemas/
└── lite/
    ├── schema.yaml
    └── templates/
        ├── brief.md
        ├── spec.md
        └── tasks.md

codev schemas liste les schémas disponibles :

Available schemas:
  lite (project)
    brief → specs → tasks
  spec-driven (built-in)
    proposal → specs → design → tasks

Un schéma de projet nommé spec-driven remplace le schéma intégré, sans rien changer d’autre.

Le nom d’un schéma est son dossier : --schema lite, schema: lite et change.yaml désignent tous _codev/schemas/lite/. Gardez le name: de schema.yaml identique au dossier ; s’il diffère, codev utilise tout de même le nom du dossier et codev schemas signale un avertissement schema_name_mismatch.

Écrire un schéma

# _codev/schemas/lite/schema.yaml
name: lite
description: Small changes — a short brief, spec deltas and a task list
artifacts:
  - id: brief
    generates: brief.md
    description: What changes, and why
    template: brief.md
    instruction: |
      Explain in a few sentences what changes and why.
  - id: specs
    generates: "specs/**/*.md"
    description: Spec deltas
    template: spec.md
    requires: [brief]
  - id: tasks
    generates: tasks.md
    template: tasks.md
    requires: [specs]
apply:
  requires: [tasks]
  tracks: tasks.md

Les clés inconnues sont rejetées : une faute de frappe ne peut donc pas produire en silence un workflow qui se comporte autrement que ce que vous avez écrit. codev rejette également un schéma dont les dépendances font référence à un artefact inexistant ou forment un cycle, en nommant les artefacts concernés. codev schemas liste malgré tout les autres schémas, et signale celui qui est refusé par un avertissement schema_unusable qui en donne la raison.

Un artefact est terminé lorsque son fichier existe — ou, pour un motif glob, lorsqu’au moins un fichier correspond. Il est prêt lorsque tous les artefacts dont il dépend sont terminés.

Déclarer les rôles des artefacts

Un artefact peut déclarer le rôle qui en a la charge. L’agent le reçoit dans le champ role de codev instructions et vérifie ses critères avant de passer à la suite ; codev roles --at plan.write le liste.

  - id: brief
    generates: brief.md
    role:
      id: editor
      name: { en: Editor, fr: Rédacteur }
      question: Is the brief clear?
      done_when:
        - One page at most
        - The why comes first

Un projet complète les critères sous roles: avec l’identifiant du rôle ; un rôle d’artefact ne peut pas être désactivé. Un artefact sans role: n’en a pas, et son instruction est utilisée telle quelle.

Utiliser un schéma

Choisissez un schéma pour un change donné :

codev new change quick-fix --schema lite

ou faites-en le schéma par défaut du projet dans _codev/config.yaml :

schema: lite

Le schéma est enregistré dans le change.yaml de chaque change, sous le nom de son dossier : modifier le schéma par défaut n’affecte donc pas les changes déjà en cours.

Les skills fonctionnent avec n’importe quel schéma : /codev-propose rédige les artefacts prêts, dans l’ordre des dépendances, au moyen de codev instructions. Les rules: par artefact de la configuration sont indexées par identifiant d’artefact : des règles écrites pour brief s’appliquent donc à l’artefact brief du schéma lite.

Comportements liés à des conventions

Quelques comportements reposent sur des conventions plutôt que sur la configuration. Gardez-les à l’esprit lorsque vous concevez un schéma :

• Les deltas de specs sont des fichiers situés sous specs/. La validation, la synchronisation et l’archivage lisent les deltas dans le dossier specs/ du change. Un artefact qui écrit ailleurs n’est pas fusionné dans les specs principales.
• skip_specs: true ignore tout artefact dont le generates commence par specs/, quel que soit son identifiant.
• Les décisions sont injectées dans l’artefact dont l’identifiant est design. Nommez votre artefact de design design si vous voulez que l’agent reçoive les décisions en vigueur au moment de le rédiger.

Interface en ligne de commande

Ce chapitre documente chaque commande codev. L’aide de chaque commande est reproduite telle que l’affiche codev <command> --help ; lancez cette commande pour consulter l’aide de la version que vous avez installée.

codev --help

codev adds a thin layer of specs to a repository so that you and your agent agree on what must be built before a single line of code is written.

The commands below run in your terminal. The workflows are invoked in the Claude Code chat: /codev-propose, /codev-explore.

Usage: codev <COMMAND>

Commands:
  init          Initialize codev in a project and install the Claude Code skills
  update        Regenerate the skills, and refresh codev's managed sections, after a codev upgrade
  self-update   Download and install the latest codev release, verified
  doctor        Check what the project's codev setup still lacks, and how to fix it
  new           Create a new item
  list          List active changes, or specified capabilities with --specs
  search        Search the requirements and decisions that match a query
  show          Print one requirement, or the requirement names of a capability
  status        Show the state of a change's artifacts
  instructions  Print everything needed to write an artifact
  roles         List the roles active at a workflow step, with their criteria
  schemas       List the available workflow schemas
  decision      Create, accept, inspect and supersede architecture decisions
  sources       Manage inherited sources (local paths and remote git repositories)
  sync          Merge a change's deltas into the main specs without archiving
  review        Show a change's review record and what is left to decide
  archive       Merge, then move a change to the dated archive
  changelog     Generate release notes from the archived changes
  docs          Open the codev documentation in the browser
  completions   Generate a shell completion script for local installation
  validate      Check changes and specs for structural errors and consistency
  help          Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Conventions

Ces règles valent pour toutes les commandes, sauf docs et completions, qui ne lisent pas le projet :

• Découverte du projet. codev cherche _codev/ dans le répertoire courant, puis dans chacun des répertoires parents. Lancez les commandes depuis n’importe quel endroit du projet. En dehors d’un projet, les commandes échouent avec no_codev_root.
• --json. Toute commande qui lit ou écrit le projet accepte --json. La sortie standard contient alors exactement un document JSON — y compris en cas d’échec — et les messages destinés aux humains ne sont pas affichés. Voir Sortie JSON.
• Code de sortie. 0 en cas de succès, 1 en cas d’échec. Pour codev validate, voir la section dédiée.
• Erreurs. En mode lisible, les erreurs sont écrites sur la sortie d’erreur sous la forme error: …, souvent suivies d’une ligne help: … qui indique la correction.
• Choix du change. Les commandes qui acceptent --change <CHANGE> le déduisent lorsque le projet compte exactement un change actif, et échouent avec ambiguous_change lorsqu’il y en a plusieurs.

Projet

codev init

Initialize codev in a project and install the Claude Code skills

Usage: codev init [OPTIONS] [PATH]

Arguments:
  [PATH]
          Project folder (default: the current folder)

Options:
      --force
          Rewrite skills even if they were edited by hand

  -y, --yes
          Accept all defaults without prompting (defaults + detected values)

      --no-detect
          Disable the environment probe (useful for reproducible tests)

      --preset <PRESET>
          Preselect the answer to the workflows question

          Possible values:
          - full:    All 8 workflows
          - minimal: propose, explore, onboard, configure
          - custom:  Pick the workflows one by one

      --language <CODE>
          Language of the prose skills write in artifacts, as an ISO 639 code (`en`, `fr`, `pt-BR`…). Default: detected from the locale, otherwise `en`

      --inherit <SOURCE>
          Inherit conventions from a source, written under `inherits:` (repeatable). A git URL (`git@…`, `https://…`, `ssh://…`, `file://…`, or ending in `.git`), optionally suffixed with `@<ref>` (default `main`), or a local folder. Git sources are pinned in `_codev/codev.lock` right away

      --no-claude-md
          Do not write codev's section in `CLAUDE.md`

      --no-ci
          Do not write `.github/workflows/codev.yml`

      --no-pr-template
          Do not write codev's section in the pull request template

      --no-integration
          Skip all repository integration: same as `--no-claude-md --no-ci --no-pr-template`

      --json


  -h, --help
          Print help (see a summary with '-h')

Initialise codev dans PATH (par défaut, le dossier courant) : crée l’arborescence _codev/, écrit _codev/config.yaml et installe les skills dans .claude/skills/. Voir Ce que fait codev init pour la détection et les questions.

• --yes saute toutes les questions et applique les valeurs par défaut et les valeurs détectées. Lorsque l’entrée standard n’est pas un terminal (CI, pipes), --yes est implicite.
• --preset répond à la question des workflows : full installe les huit workflows, minimal installe propose, explore, onboard et configure, et custom vous laisse les choisir un par un (avec un repli sur full en l’absence de terminal).
• --language définit la clé language:. Sans cette option, la langue est déduite de la locale, à défaut en. Voir Langue des artefacts.
• --no-detect désactive la détection des manifestes, de la licence, de la CI, de la locale et des serveurs MCP.
• --inherit <SOURCE> déclare une source héritée sous inherits:, une fois par source. Une valeur qui commence par git@, https://, http://, ssh:// ou file://, ou qui se termine par .git, est une source git ; un suffixe @<ref> choisit la branche ou le tag (…/conventions.git@v2), main à défaut. Toute autre valeur est un dossier local, qui doit exister ; un chemin relatif est écrit sous forme absolue. Les sources git sont aussitôt épinglées dans _codev/codev.lock, comme le ferait codev sources update ; si cela échoue (réseau, identifiants, ref inconnue), init réussit quand même, avertit avec inherit_pin_failed et affiche help: run codev sources update. Une valeur invalide échoue avec invalid_inherit avant toute écriture. Voir Sources héritées.
• --no-claude-md, --no-ci et --no-pr-template écartent chacun un fichier d’intégration ; --no-integration écarte les trois. Voir Intégration au dépôt et codev doctor.

Sauf refus de votre part, codev init écrit aussi la section de codev dans CLAUDE.md et, sur GitHub, .github/workflows/codev.yml et une section dans le modèle de pull request. Le récapitulatif indique pour chaque fichier s’il a été créé, complété, rafraîchi, laissé à jour ou écarté, avec la raison ; pour un dépôt GitLab, il affiche un job à coller dans .gitlab-ci.yml, que codev ne modifie jamais. La dernière ligne suggère codev doctor lorsqu’il manque encore quelque chose.

Si _codev/config.yaml existe déjà, il reste intact : codev init se contente de créer les dossiers manquants, d’installer ou de rafraîchir les skills, et d’ajouter ou de rafraîchir les fichiers d’intégration. Les sources --inherit ne sont alors pas écrites ; l’avertissement inherit_not_written les nomme pour que vous les ajoutiez à la main. Les skills que vous avez modifiées à la main sont préservées, sauf si vous passez --force.

codev update

Regenerate the skills, and refresh codev's managed sections, after a codev upgrade

Usage: codev update [OPTIONS]

Options:
      --force  Rewrite skills even if they were edited by hand
      --json
  -h, --help   Print help

Régénère les skills listées par workflows: dans la configuration (les huit en l’absence de la clé), par exemple après une mise à jour de codev ou une modification de la configuration mcp:. codev update réécrit une skill marquée d’une autre version ; parmi les skills marquées de sa propre version, il réécrit celle dont le contenu correspond encore à son checksum — un rendu de codev, d’une compilation antérieure ou pour l’autre mode de revue — et préserve celle qui n’y correspond plus, modifiée à la main, sauf si vous passez --force. Une skill sans checksum, rendue avant leur existence, est préservée quand elle porte la marque de cette version et diffère du rendu par plus que le mode de revue : lancez une fois codev update --force pour la doter d’un checksum — il écrase aussi une skill que vous avez réellement modifiée : vérifiez d’abord git diff, puis réappliquez vos modifications. Une skill préservée est signalée. Les skills retirées de workflows: ne sont pas supprimées. Un nom de workflow inconnu est ignoré avec un avertissement unknown_workflow. Les dossiers manquants de _codev/ et un _codev/config.yaml manquant sont recréés ; aucun fichier existant n’est jamais écrasé.

codev update rafraîchit aussi les sections gérées par codev dans CLAUDE.md et dans le modèle de pull request, ainsi que .github/workflows/codev.yml lorsque sa première ligne est # codev:managed — ce qui aligne sa version épinglée sur celle qui s’exécute. Il ne rafraîchit que ce qui existe : il ne crée jamais ces fichiers et n’ajoute aucune section, si bien qu’un projet initialisé avec --no-integration reste tel quel.

codev self-update

Download and install the latest codev release, verified

Downloads the release archive for this platform from GitHub, verifies its SHA-256 against the release's `SHA256SUMS`, replaces this binary atomically, then runs the new binary's `codev update` in the current project, if any. Never downgrades unless `--version` asks for it. A binary installed by cargo, a cargo build or a package manager is left alone: the command that upgrades it is printed instead.

Usage: codev self-update [OPTIONS]

Options:
      --version <X.Y.Z>
          Install this version (`X.Y.Z`) instead of the latest; allows a downgrade

      --check
          Only report the running and latest versions (exit code 0 whether or not an update is available)

      --snooze
          Silence the update notice for the latest known version, for 7 days

  -y, --yes
          Do not ask for confirmation

      --json
          JSON output; implies `--yes`

  -h, --help
          Print help (see a summary with '-h')

Installe un codev plus récent à la place de celui qui s’exécute, en une commande et jamais dans votre dos :

1. détermine la version cible — --version, ou la release la plus récente, demandée à GitHub sur le moment, quels que soient le cache, CI ou CODEV_NO_UPDATE_CHECK ;
2. dans un terminal, demande confirmation, sauf avec --yes ;
3. télécharge codev-<version>-<target>.tar.gz (.zip sous Windows) et SHA256SUMS depuis la release GitHub, puis vérifie le SHA-256 de l’archive ;
4. écrit le nouveau binaire à côté de celui qui s’exécute, puis le renomme à sa place, si bien que le chemin du binaire contient toujours un binaire complet ;
5. dans un projet codev, lance codev update avec le nouveau binaire.

Un binaire installé par cargo install, compilé dans un dossier target/ de cargo ou installé par un gestionnaire de paquets (Homebrew, Nix, Scoop, /usr/bin) n’est pas touché : la commande qui le met à jour est affichée et le code de sortie vaut 0. Une release plus ancienne que le binaire en cours est refusée (update_downgrade_refused), sauf si vous la demandez avec --version.

--check affiche la version installée et la plus récente, rafraîchit le cache de vérification et sort avec 0, qu’une mise à jour soit disponible ou non. --snooze fait taire, pendant 7 jours, l’annonce de codev status et des skills pour la dernière version connue ; une release plus récente est de nouveau annoncée.

Tout échec laisse le binaire installé intact. Lorsque codev update échoue dans le projet après une mise à jour réussie, la commande avertit update_project_refresh_failed et sort tout de même avec 0 : lancez codev update dans ce projet. Pour --json, voir Sortie JSON.

codev doctor

Check what the project's codev setup still lacks, and how to fix it

Read-only and offline: configuration, skills, inherited sources, the running codev version against `codev_version` and the cached update check, specs, decisions, `CLAUDE.md`, CI and pull request template, `codev validate`, and whether `CHANGELOG.md` matches the archived changes. Each check is ok, missing or a warning, with the command or skill that fixes it.

Usage: codev doctor [OPTIONS]

Options:
      --strict
          Exit with code 1 when a check is missing (warnings never fail)

      --json


  -h, --help
          Print help (see a summary with '-h')

Liste ce qui manque encore à l’installation de codev dans le projet, regroupé sous Configuration, Planning et Repository, avec la commande ou la skill qui corrige chaque point. La commande n’écrit rien et n’a pas besoin du réseau ; la vérification changelog lance des requêtes git locales, en lecture seule.

La vérification codev_version lit le cache que tient codev status ; elle ne contacte jamais le réseau.

Chaque ligne affiche ✓ (ok), ✗ (manquant) ou ! (avertissement) ; la dernière ligne compte les vérifications et celles qui restent à corriger. Le code de sortie vaut 0, sauf avec --strict lorsqu’une vérification manque : les avertissements ne font jamais échouer la commande. Voir Intégration au dépôt et codev doctor et, pour --json, Sortie JSON.

codev docs

Open the codev documentation in the browser

Three forms:

- default: writes `codev-docs-<version>.html` to the system temp folder and opens it in the browser; - `--write <PATH>`: writes the HTML to the given path, opens nothing (for sharing — email, Confluence, shared drive); - `--print`: prints the markdown source to stdout (to pipe into `less`, `bat` or an LLM).

Usage: codev docs [OPTIONS]

Options:
      --print
          Print the markdown source to stdout (does not open anything)

      --write <PATH>
          Write the HTML to the given path (does not open anything)

      --lang <LANG>
          Language of the documentation

          Possible values:
          - en: English
          - fr: French

          [default: en]

  -h, --help
          Print help (see a summary with '-h')

Produit cette documentation sous la forme d’une page HTML autonome — CSS intégré, aucun accès réseau — et l’ouvre dans votre navigateur. La page est écrite dans codev-docs-<version>.html, dans le dossier temporaire du système. --write l’écrit ailleurs sans l’ouvrir, pour la partager ; --print affiche la source Markdown. --lang choisit l’édition anglaise (en, par défaut) ou française (fr). codev docs fonctionne partout, y compris en dehors d’un projet codev.

--print est fait pour être redirigé : lorsque le lecteur s’arrête avant la fin, comme dans codev docs --print | head, la commande s’arrête sans message et renvoie le code 0. Dans la page, remarques et avertissements gardent leur sens : une remarque porte un filet vert, un avertissement un filet corail.

codev docs --lang fr --write ~/Downloads/codev-manual-fr.html

codev completions

Generate a shell completion script for local installation

The output goes to stdout — redirect it to your shell's completions folder. Typical setups:

- bash: `codev completions bash > ~/.local/share/bash-completion/completions/codev` - zsh: `codev completions zsh > "${fpath[1]}/_codev"`, then `compinit` - fish: `codev completions fish > ~/.config/fish/completions/codev.fish` - powershell: `codev completions powershell | Out-String | Invoke-Expression`

The command touches no file; it does not read `_codev/` either and works in any directory.

Usage: codev completions <SHELL>

Arguments:
  <SHELL>
          Target shell: bash, zsh, fish, powershell, elvish

          [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -h, --help
          Print help (see a summary with '-h')

Voir Complétion du shell.

Changes

codev new change

Create a change

Usage: codev new change [OPTIONS] <NAME>

Arguments:
  <NAME>  Name in kebab-case (`add-user-auth`)

Options:
      --schema <SCHEMA>  Workflow schema to use
      --goal <GOAL>      Goal, kept in the change's metadata
      --json
  -h, --help             Print help

Crée _codev/changes/<NAME>/ avec un change.yaml qui enregistre le schéma, la date de création et l’objectif, s’il est fourni. Le nom doit être en kebab-case : lettres minuscules, chiffres et tirets simples, ni en tête ni en fin ; il peut commencer par un chiffre. archive est réservé au dossier des changes archivés et refusé. Par défaut, le schéma est celui de la clé schema: de la configuration, à défaut spec-driven ; change.yaml enregistre le nom sous lequel le schéma a été trouvé — le nom du dossier pour un schéma du projet. Échoue sans rien écrire avec invalid_change_id — en nommant la règle que le nom enfreint —, avec change_exists si le change existe déjà, et avec schema_not_found si le schéma n’existe pas.

codev new change add-dark-mode --goal "Let users switch the UI to a dark theme"

codev list

List active changes, or specified capabilities with --specs

Usage: codev list [OPTIONS]

Options:
      --specs
      --json
  -h, --help   Print help

Liste les changes actifs ou, avec --specs, les capacités qui possèdent une spec principale : chaque dossier de _codev/specs/ contenant un fichier nommé exactement spec.md, dossiers imbriqués compris. Les autres fichiers, comme un README.md ou notes/myspec.md, ne sont pas des specs et sont ignorés, par codev validate également.

codev search

Search the requirements and decisions that match a query

Usage: codev search [OPTIONS] <QUERY>...

Arguments:
  <QUERY>...  Words naming the behavior, in the language the specs are written in

Options:
      --limit <LIMIT>  Results to print, from 1 to 50 [default: 10]
      --archive        Also list the matching archived changes, in a section of their own
      --json
  -h, --help           Print help

Classe les exigences des specs principales — chacune avec sa description et ses scénarios — et les décisions, héritées comprises, selon leur correspondance avec la requête, et affiche les meilleures : le type, l’identifiant (<capacité>::<exigence>, ou l’identifiant et le titre de la décision avec son statut et si elle est en vigueur) et un extrait. La casse, les accents et les mots vides sont ignorés, et les mots se rapprochent par leur racine dans la langue des specs : écrivez la requête dans cette langue, ainsi decisions trouve decision. La sortie contient 10 résultats, sauf si --limit en demande de 1 à 50, quelle que soit la taille du projet. --archive ajoute les changes archivés qui correspondent, dans une section à part, jamais classés avec les exigences. Une requête qui ne trouve rien le dit et se termine avec le code 0 ; une requête faite seulement de mots vides échoue avec search_query_empty, et un --limit hors limites avec search_limit_invalid. La commande ne fait que lire.

codev search create a decision from the command line
codev search "decision seal" --archive

codev show

Print one requirement, or the requirement names of a capability

Usage: codev show [OPTIONS] <TARGET>

Arguments:
  <TARGET>  `<capability>::<requirement name>`, or `<capability>` for its index

Options:
      --json
  -h, --help  Print help

codev show <capacité>::<nom de l'exigence> affiche cette exigence telle que sa spec principale la contient — titre, description et scénarios, à l’identique — et rien d’autre de la spec ; le nom est comparé sans tenir compte de la casse ni des espaces. codev show <capacité> affiche l’objectif de la capacité et les noms de ses exigences, sous la forme <capacité>::<nom> que la commande accepte. La capacité doit être l’une de celles que nomme codev list --specs : toute autre valeur échoue avec unknown_capability, et une exigence que la capacité ne contient pas avec unknown_requirement, qui liste celles qu’elle contient.

codev show decisions
codev show "decisions::Creating a decision through the CLI"

codev status

Show the state of a change's artifacts

Usage: codev status [OPTIONS]

Options:
      --change <CHANGE>  Change name (inferred when there is only one)
      --json
  -h, --help             Print help

Affiche l’état de chaque artefact d’un change — terminé [x], prêt [ ], bloqué [-] avec les artefacts qu’il attend, ou ignoré [~] — puis Planning: <n>/<total> artifacts et le prochain artefact à rédiger, ou Planning is complete.. Échoue avec no_active_change lorsque le projet n’a aucun change actif. Dans les deux cas, lorsque codev doctor signalerait une vérification manquante, une dernière ligne hint: sur stderr suggère de le lancer. Un --change qui nomme un change inexistant échoue avec unknown_change ; --change archive échoue avec invalid_change_id, car ce nom est réservé aux changes archivés.

Lorsqu’une release plus récente de codev est connue et que vous ne l’avez pas mise en sourdine, stderr porte aussi codev X.Y.Z is available (you have A.B.C) — run `codev self-update` . Pour le savoir, codev status demande à GitHub la dernière release au plus une fois toutes les 24 heures, avec un délai de 2 secondes, et garde la réponse en cache dans ~/.cache/codev/update-check.json. Il ne vérifie jamais lorsque CI est défini ou avec CODEV_NO_UPDATE_CHECK=1, et une vérification qui échoue reste silencieuse. Aucune autre commande ne vérifie. Avec --json, la même information figure dans l’objet update — voir Sortie JSON.

codev instructions

Print everything needed to write an artifact

Usage: codev instructions [OPTIONS] [ARTIFACT]

Arguments:
  [ARTIFACT]  Artifact identifier (default: the next one to write)

Options:
      --change <CHANGE>
      --json
  -h, --help             Print help

Affiche tout ce dont un agent a besoin pour rédiger un artefact : où l’écrire, l’instruction du schéma, le template, la langue des artefacts, le contexte et les règles du projet avec leur provenance, les dépendances à lire au préalable, et ce que l’artefact débloque. Pour l’artefact design, la commande liste aussi les décisions d’architecture en vigueur, et le rôle de l’artefact avec ses critères. Sans ARTIFACT, elle choisit le premier artefact prêt à être rédigé. Elle n’écrit aucun fichier.

Une fois la proposition du change écrite, les instructions des artefacts qui la requièrent directement — specs et design — listent aussi les exigences existantes que le change touche probablement, classées par rapport au Why et au What Changes de la proposition, au plus 10, chacune avec un extrait, et indiquent qu’on en lit une avec codev show <capacité>::<exigence> et qu’une exigence que le change altère se modifie au lieu d’être ajoutée de nouveau. Une spec illisible est écartée avec un avertissement spec_unreadable.

Pour un artefact désactivé par skip_specs, elle indique qu’il ne doit pas être créé, avec un avertissement artifact_skipped. Elle échoue avec unknown_artifact lorsque ARTIFACT n’est pas un artefact du schéma du change, avec no_artifact_ready lorsque ARTIFACT est omis et qu’aucun artefact n’est prêt, et avec template_not_found lorsqu’un schéma du projet déclare un fichier de template qu’il ne contient pas, et avec unknown_role, invalid_role_activation ou role_not_disableable lorsqu’un réglage de rôle est invalide — comme codev status.

Les skills l’appellent avec --json ; voir codev instructions.

codev sync

Merge a change's deltas into the main specs without archiving

Usage: codev sync [OPTIONS]

Options:
      --change <CHANGE>  Change name (inferred when there is only one)
      --json
  -h, --help             Print help

Valide le change, refuse de continuer si la validation signale une erreur, puis fusionne ses deltas dans les specs principales, sans déplacer le change. Relancée, la commande indique que les specs sont inchangées. Voir Sync.

codev review

Show a change's review record and what is left to decide

Reads `_codev/changes/<name>/review.md`: per step and per role, the findings with their severity, status and location, and who must act next (author, reviewer or human). Lists the record's defects, as `codev validate` does, and whether the review lets the change be archived. Exits with 1 when the record has an error.

Usage: codev review [OPTIONS]

Options:
      --change <CHANGE>
          Change name (inferred when there is only one)

      --json


  -h, --help
          Print help (see a summary with '-h')

Lit le compte rendu de revue du change et l’affiche par étape et par rôle, avec, pour chaque constat, qui doit agir, les défauts du compte rendu (les codes review_* de codev validate) et si la revue permet d’archiver le change. Sans compte rendu, la commande le dit et réussit. Le verrou d’archivage ne change pas le code de sortie : c’est codev archive qui l’applique. JSON : review.

codev archive

Merge, then move a change to the dated archive

Usage: codev archive [OPTIONS]

Options:
      --change <CHANGE>  Change name (inferred when there is only one)
      --json
  -h, --help             Print help

Valide le change, refuse de continuer si la validation signale une erreur, puis vérifie son compte rendu de revue et refuse avec review_blocked s’il manque pour une étape où des rôles de relecture étaient actifs ou si un constat de gravité haute est encore ouvert ou contesté ; fusionne ensuite ses deltas dans les specs principales et le déplace, compte rendu compris, dans _codev/changes/archive/<YYYY-MM-DD>-<name>/. Voir Archive.

codev changelog

Generate release notes from the archived changes

Lists the release-note items of the changes archived after `--since` (default: the highest `v*` tag) and up to `--until` (default: the working tree), by category, breaking items first. A change archived without a release note falls back on its What Changes bullets, with a warning. `--write` keeps the `[Unreleased]` section of `CHANGELOG.md` up to date, in a managed section; with `--release`, it becomes a dated version block.

Usage: codev changelog [OPTIONS]

Options:
      --since <REF>
          Git ref the range starts after (default: the highest `v*` tag below `--until`)

      --until <REF>
          Git ref the range ends at (default: the working tree)

      --format <FORMAT>
          Output format

          Possible values:
          - keep-a-changelog: `## [Unreleased]` (or the release) and `### <Category>` sections
          - markdown:         The same without the version heading, for a release body
          - json:             The JSON contract v1

          [default: keep-a-changelog]

      --release <VERSION>
          Title the block `## [<VERSION>] - <DATE>` instead of `## [Unreleased]`

      --date <DATE>
          Release date, `YYYY-MM-DD` (default: today)

      --write
          Update `CHANGELOG.md` (created if missing); text outside codev's managed section is kept

  -h, --help
          Print help (see a summary with '-h')

Liste les éléments de note de version des changes archivés dans un intervalle git. Un change en fait partie lorsque son dossier se trouve dans _codev/changes/archive/ à --until et ne s’y trouvait pas à --since : c’est git qui en décide, pas les dates. Par défaut, --since est le tag v* le plus élevé dans l’ordre des versions — inférieur à --until lorsque --until est un tag de version — et, sans aucun tag, tous les changes archivés sont listés. Hors d’un dépôt git, tous les changes archivés sont listés, avec un avertissement.

Les éléments sont regroupés par catégorie dans l’ordre de Keep a Changelog, les éléments incompatibles en premier, puis dans l’ordre d’archivage. Un change dont la note vaut None n’ajoute rien. Un change archivé sans note de version apporte les puces de sa section What Changes sous Changed, avec un avertissement release_note_missing ; un change dont les deltas suppriment des exigences sans élément Removed ni élément incompatible reçoit un avertissement release_note_inconsistent. Les avertissements vont sur stderr et ne changent jamais le code de sortie. Les changes listés sous changelog.exclude sont laissés de côté.

codev changelog --since v1.3.0 --format markdown

### Added

- `--format json` pour `codev export`.

### Fixed

- `codev export` ne perd plus la dernière ligne.

Avec --write, la commande met à jour CHANGELOG.md au lieu d’afficher le texte : le bloc [Unreleased] vit dans une section gérée, juste après l’en-tête du fichier, et le reste du fichier n’est jamais réécrit. Avec --release X.Y.Z, le bloc devient ## [X.Y.Z] - <date> sous une nouvelle section [Unreleased] vide. --write est refusé avec --format markdown. Voir Notes de version et CHANGELOG.

codev validate

Check changes and specs for structural errors and consistency

Usage: codev validate [OPTIONS] [ITEM]

Arguments:
  [ITEM]  Name of a specific change or spec capability

Options:
      --all      Validate all active changes and all main specs
      --changes  Validate all active changes
      --specs    Validate all main specs
      --strict   Treat any finding (warnings included) as a reason for a non-zero exit code. Useful for CI and automation
      --json
  -h, --help     Print help

Sans ITEM ni option, valide tout : chaque change actif, chaque spec principale et les sceaux des décisions. ITEM est le nom d’un change actif ou le chemin d’une capacité (ui/theme).

Code de sortie :

change add-dark-mode — _codev/changes/add-dark-mode
  error   _codev/changes/add-dark-mode/change.yaml:1: zero_delta_without_marker — no delta file under `specs/` and `skip_specs: true` is not declared; add a delta or set `skip_specs: true` in change.yaml

decisions decisions — _codev/decisions
  ✓ no issues

2 item(s) validated, 1 finding(s) including 1 error(s).

Chaque constat porte un code stable. Voir Codes de validation.

codev roles

List the roles active at a workflow step, with their criteria

With `--at`, the roles active at that step and their "done when" criteria, each with its origin (`built-in`, `schema:<name>`, `project`). Without it, every role with its activation. The roles come from codev's built-in catalog and the schema in use, with the project's `roles:` applied, and, with `--change`, the change's `change.yaml` and the domains its proposal ticks, which activate the experts. With `--change`, also the change's diff since the default branch and the domains its experts' triggers suggest. The `By stack` part of the knowledge keeps the languages detected in the project.

Usage: codev roles [OPTIONS]

Options:
      --at <STEP>
          The workflow step: plan.understand, plan.investigate, plan.write, plan.trace, plan.challenge, code.implement or code.review

      --change <CHANGE>
          Apply this change's schema, `change.yaml` and domains

      --knowledge
          Also print each role's knowledge (always in the JSON, for active roles)

      --all-stacks
          Serve the knowledge's `By stack` part for every language, not only the languages detected in the project

      --json


  -h, --help
          Print help (see a summary with '-h')

Liste les rôles qu’une skill applique à une étape du workflow : avec --at, les rôles actifs à cette étape, chacun avec sa question et ses critères « Done when » précédés de leur origine ; sans --at, une ligne par rôle avec ses étapes ou son artefact et son activation — never (project) lorsque votre configuration le désactive, on_domain: <domaine> pour un expert, cannot be disabled pour les rôles d’artefact, l’analyst et le developer. --knowledge affiche aussi les connaissances de chaque rôle après ses critères, précédées d’une ligne qui nomme les langages pour lesquels leur partie By stack est filtrée. Une étape dont tous les rôles sont inactifs affiche No role is active at <step>: skip this step. Elle n’écrit aucun fichier.

Avec --change, elle affiche d’abord le diff du change — la branche par défaut dont il part, les fichiers modifiés et lus, les fichiers écartés par catégorie — ou la raison de son absence, puis une ligne par domaine suggéré : son état (ticked, justified, unticked), son premier déclencheur avec sa source, et le fichier concerné. La lecture du diff n’exécute que des commandes git locales ; hors de git, elle le signale et poursuit.

La partie By stack des connaissances garde les langages détectés à partir des manifestes de dépendances du projet ; --all-stacks sert tous les langages. Sans aucun manifeste, tout est servi.

Sans --change, elle applique le schéma configuré du projet et son roles: ; contrairement aux autres commandes, elle ne déduit pas de change. Avec --change, elle applique le schéma du change, son change.yaml et les domaines que coche sa proposal, qui activent les experts ; sans lui, les experts restent inactifs. Elle échoue avec unknown_step lorsque --at n’est pas une des étapes, et avec unknown_role, invalid_role_activation ou role_not_disableable lorsqu’un réglage de rôle est invalide — voir Configurer les rôles. Avec --at, une dernière ligne nomme les rôles de l’étape que la configuration a désactivés, chacun avec le fichier dont le réglage l’a fait (project ou change). Les skills l’appellent avec --json ; voir codev roles.

codev schemas

List the available workflow schemas

Usage: codev schemas [OPTIONS]

Options:
      --json
  -h, --help  Print help

Liste les schémas du projet, issus de _codev/schemas/, ainsi que le schéma intégré spec-driven, avec l’ordre de leurs artefacts. Un schéma du projet nommé spec-driven remplace le schéma intégré. Un schéma du projet inutilisable est écarté de la liste avec un avertissement schema_unusable qui en donne la raison ; les autres restent listés. Un schéma du projet porte le nom de son dossier : celui dont le name: indique autre chose est listé sous le nom de son dossier, avec un avertissement schema_name_mismatch. Voir Schémas personnalisés.

Décisions

codev decision

Create, accept, inspect and supersede architecture decisions

Usage: codev decision <COMMAND>

Commands:
  list       List local and inherited decisions
  show       Show a specific decision
  new        Create a new local decision
  accept     Accept a proposed decision: set its status to `accepted` and seal it
  supersede  Create a proposed decision that will supersede an accepted one
  seal       Add or rewrite the seal of a local decision
  deviate    Record a local deviation from an inherited decision
  promote    Promote a `### Decision: <title>` block of a `design.md` to an ADR
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Les décisions sont désignées par leur identifiant court (0007) ou leur identifiant qualifié (project/0007, path:~/shared/0100, git:git@github.com:acme/shared.git/0100). Voir Décision.

codev decision list

List local and inherited decisions

Usage: codev decision list [OPTIONS]

Options:
      --json
  -h, --help  Print help

Liste les décisions locales et héritées avec leur statut. Les décisions en vigueur sont marquées •, les autres – ; une décision remplacée indique celle qui l’a remplacée.

codev decision show

Show a specific decision

Usage: codev decision show [OPTIONS] <ID>

Arguments:
  <ID>  Short (`0007`) or qualified (`path:~/shared/0100`) identifier

Options:
      --json
  -h, --help  Print help

Affiche un en-tête — l’identifiant court et qualifié, le titre, le statut, la date, puis les tags, Supersedes et Superseded by lorsqu’ils sont renseignés, et le chemin du fichier, relatif au projet ou absolu pour une source héritée située en dehors — suivi du contenu du fichier. Échoue avec unknown_decision_id lorsqu’aucune décision ne correspond, et avec ambiguous_decision_id, en listant les candidates, lorsqu’un identifiant court en désigne plusieurs : utilisez alors l’identifiant qualifié.

codev decision new

Create a new local decision

The decision is created `proposed` and unsealed, so its body can be written freely; `codev decision accept` then accepts and seals it.

Usage: codev decision new [OPTIONS] <TITLE>

Arguments:
  <TITLE>
          Free-form title — slugified for the file name

Options:
      --status <STATUS>
          Initial status; `accepted` seals the body right away, `proposed` leaves it editable until `codev decision accept`

          [default: proposed]

      --json


  -h, --help
          Print help (see a summary with '-h')

Crée _codev/decisions/NNNN-<slug>.md à partir du template d’ADR, avec le prochain numéro libre. Avec le statut par défaut proposed, la décision n’est pas scellée : rédigez son contenu, puis lancez codev decision accept pour l’accepter et la sceller. --status accepted la scelle immédiatement, pour une décision dont le texte est déjà définitif.

codev decision accept

Accept a proposed decision: set its status to `accepted` and seal it

Rewrites the frontmatter status of a local `proposed` decision and records the hash of its body in `seal.yaml`, in the same plan — all writes happen or none does. The body is left untouched. The decisions listed in its `supersedes` are marked `superseded` in the same plan; each must still be `accepted`. This is how a decision created by `new`, `supersede`, `deviate` or `promote` takes effect. Inherited decisions and decisions that are not `proposed` are refused.

Usage: codev decision accept [OPTIONS] <ID>

Arguments:
  <ID>
          Short identifier (`0007`) — inherited ones (`path:` / `git:`) are refused

Options:
      --json


  -h, --help
          Print help (see a summary with '-h')

Passe le statut d’une décision locale proposed à accepted et enregistre l’empreinte SHA-256 de son contenu dans _codev/decisions/seal.yaml, dans le même plan : les deux sont écrits, ou aucun. Seul le frontmatter change. Une décision héritée est refusée avec cannot_accept_inherited, une décision qui n’est pas proposed avec decision_not_proposed ; pour remplacer une décision acceptée, utilisez codev decision supersede.

C’est la seule commande qui fait entrer une décision en vigueur, quelle que soit la commande qui l’a créée. Quand la décision liste des prédécesseurs dans supersedes — comme celle que crée codev decision supersede —, le même plan passe chacun d’eux à superseded ; leur contenu, et donc leur sceau, n’est pas modifié. Un prédécesseur qui n’est plus accepted, par exemple parce qu’une autre décision l’a remplacé entre-temps, est refusé avec predecessor_not_accepted, et rien n’est écrit.

codev decision accept 0002

✓ Accepted 0002 — sealed (sha256:c8873b83c178dbf8434045f43a722911b9d9913ee9f13915ccda893539b788c1)
  File: /home/you/acme-app/_codev/decisions/0002-use-sqlite.md
  Superseded: project/0001 (status: superseded)

codev decision supersede

Create a proposed decision that will supersede an accepted one

The new decision is created `proposed` and unsealed, with the old one in its `supersedes`. The old decision is not modified and stays in effect until `codev decision accept` accepts the new one, which marks the old one `superseded` in the same step.

Usage: codev decision supersede [OPTIONS] <OLD_ID> <NEW_TITLE>

Arguments:
  <OLD_ID>
          Identifier of the decision to supersede (short or qualified)

  <NEW_TITLE>
          Title of the new decision

Options:
      --json


  -h, --help
          Print help (see a summary with '-h')

Crée une nouvelle décision proposed, non scellée, dont le champ supersedes pointe vers OLD_ID. L’ancienne décision n’est pas modifiée : elle reste accepted, et en vigueur, jusqu’à ce que vous acceptiez la nouvelle avec codev decision accept, qui la passe alors à superseded dans la même étape. OLD_ID doit être une décision locale accepted ; sinon, la commande refuse avec predecessor_not_accepted. Pour vous écarter d’une décision héritée, utilisez codev decision deviate.

codev decision supersede 0001 "Use SQLite"

✓ Decision `0002 Use SQLite` created (proposed), to supersede `project/0001`
  New ADR:     /home/you/acme-app/_codev/decisions/0002-use-sqlite.md
  Old ADR:     /home/you/acme-app/_codev/decisions/0001-use-postgresql.md (unchanged, still in effect)

Open the new file to write the Context, Decision and Consequences sections,
then run `codev decision accept 0002` to accept and seal it.
Accepting it marks `project/0001` superseded; until then it stays in effect.

codev decision seal

Add or rewrite the seal of a local decision

Without `--force`: refuses if a seal exists and the body has changed. With `--force`: rewrites the seal (use after a deliberate edit of the body).

Usage: codev decision seal [OPTIONS] <ID>

Arguments:
  <ID>
          Short identifier (`0007`) — inherited ones (`path:` / `git:`) are refused

Options:
      --force
          Rewrite an existing seal even if the body has changed

      --json


  -h, --help
          Print help (see a summary with '-h')

Enregistre l’empreinte SHA-256 du contenu de la décision dans _codev/decisions/seal.yaml. Sceller une décision déjà scellée et inchangée n’a aucun effet.

codev decision deviate

Record a local deviation from an inherited decision

Creates a local `proposed` ADR, unsealed, that explicitly references the inherited decision being departed from. The deviation takes effect once `codev decision accept` accepts it: the inherited decision then stays visible in `codev decision list`, but disappears from the instructions injected into the `design` artifact. To deviate from a local decision, use `codev decision supersede`.

Usage: codev decision deviate [OPTIONS] <TARGET> <NEW_TITLE>

Arguments:
  <TARGET>
          Qualified identifier of the inherited decision to set aside

          Example: `path:~/shared/0100` or `git:git@github.com:acme/shared.git/0100`.

  <NEW_TITLE>
          Free-form title of the local deviation — slugified

Options:
      --json


  -h, --help
          Print help (see a summary with '-h')

L’écart est créé proposed : la décision héritée reste en vigueur jusqu’à ce que vous acceptiez l’écart avec codev decision accept. Voir Décisions héritées.

codev decision promote

Promote a `### Decision: <title>` block of a `design.md` to an ADR

Extracts the block's content into a `proposed` local ADR, unsealed, and replaces the block's body with a textual reference to the new ADR. Review and rework the ADR, then accept and seal it with `codev decision accept`. Refuses an archived change.

Usage: codev decision promote [OPTIONS] <CHANGE> <TITLE>

Arguments:
  <CHANGE>
          Name of the active change whose `design.md` holds the block

  <TITLE>
          Exact title of the block to promote (what follows `Decision: `)

Options:
      --json


  -h, --help
          Print help (see a summary with '-h')

L’ADR est créé proposed, avec le texte du bloc repris tel quel sous ## Decision et des emplacements à compléter pour les autres sections. Retravaillez-le, puis acceptez-le et scellez-le avec codev decision accept :

codev decision promote add-audit-log "Append-only audit table"

✓ Decision `Append-only audit table` promoted to proposed ADR 0004
  File:    /home/you/acme-app/_codev/decisions/0004-append-only-audit-table.md
  Source:  /home/you/acme-app/_codev/changes/add-audit-log/design.md

Review the ADR promoted from change `add-audit-log`: split its body into Context,
Decision, Consequences and Alternatives considered,
then run `codev decision accept 0004` to accept and seal it.

Héritage

codev sources

Manage inherited sources (local paths and remote git repositories)

Usage: codev sources <COMMAND>

Commands:
  list    List all declared sources with their state
  update  Resolve refs, download, and update `_codev/codev.lock`
  show    Show the details of a specific source
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Voir Sources héritées.

codev sources list

List all declared sources with their state

Usage: codev sources list [OPTIONS]

Options:
      --json
  -h, --help  Print help

codev sources show

Show the details of a specific source

Usage: codev sources show [OPTIONS] <TARGET>

Arguments:
  <TARGET>  URL (`git:` source) or path (`path:` source)

Options:
      --json
  -h, --help  Print help

codev sources update

Resolve refs, download, and update `_codev/codev.lock`

Usage: codev sources update [OPTIONS]

Options:
      --json
  -h, --help  Print help

La seule commande qui accède au réseau. Nécessite git.

Configuration

Un projet codev se configure dans _codev/config.yaml. Toutes les clés sont facultatives : un projet peut même fonctionner sans ce fichier. Une clé que codev ne connaît pas est signalée, par un avertissement au premier niveau, dans mcp et dans review, par une erreur ailleurs : une faute de frappe ne passe donc jamais inaperçue. Voir Clés inconnues.

codev init génère le fichier avec les valeurs qu’il a détectées, chacune précédée d’un commentaire indiquant sa provenance. Vous pouvez le modifier à la main à tout moment. Après avoir modifié workflows, mcp ou review, lancez codev update pour que les skills reflètent la modification.

Exemple complet

schema: spec-driven

language: en

workflows:
  - propose
  - explore
  - onboard
  - apply
  - sync
  - archive
  - update
  - configure

context: |
  TypeScript monorepo: a Next.js web app and a Node.js API.
  Errors are typed; never throw raw strings.

rules:
  specs:
    - Describe observable behavior, never implementation.
  design:
    - Cite the decisions in _codev/decisions/ that constrain the approach.
  tasks:
    - "Each task states how to verify it: a named test, a command, or an observable behavior."

inherits:
  - path: ~/src/acme-standards
  - git: git@github.com:acme/codev-standards.git
    ref: main
    subpath: standards

mcp:
  jira_tool: mcp__atlassian__getJiraIssue

changelog:
  exclude:
    - 2026-03-02-legacy-import

codev_version: ">=0.5"

roles:
  newcomer: never
  skeptic:
    done_when:
      - Le plan de retour arrière est indiqué

triggers:
  - domain: personal-data
    paths: ["src/billing/**"]

review:
  mode: isolated

schema

Le schéma de workflow utilisé par les nouveaux changes. Valeur par défaut : spec-driven, le schéma embarqué dans codev. Le nom d’un schéma défini sous _codev/schemas/ est également accepté. Un change enregistre son schéma dans son propre change.yaml : modifier cette clé n’affecte donc pas les changes en cours. Voir Schémas personnalisés.

language

La langue dans laquelle les skills rédigent la prose des artefacts, sous la forme d’un code ISO 639 : deux ou trois lettres minuscules, éventuellement suivies d’une sous-étiquette (en, fr, pt-BR, zh-Hant). Valeur par défaut : en. Les skills écrivent les mots-clés structurels en anglais ; codev les lit en anglais comme en français, quel que soit ce réglage. Voir Langue des artefacts.

workflows

Les workflows à installer comme skills Claude Code, désignés par leur identifiant : propose, explore, onboard, configure, apply, sync, archive, update. En l’absence de la clé, les huit sont installés. Un identifiant inconnu produit l’avertissement unknown_workflow et est ignoré. Voir Les skills Claude Code.

context

Texte libre transmis à l’agent avec les instructions de chaque artefact : votre stack, vos conventions, vos contraintes — tout ce qui ne peut pas se déduire du code. C’est une contrainte imposée à l’agent, jamais un contenu à recopier dans les fichiers. /codev-configure peut le rédiger pour vous.

rules

Les règles propres à un artefact, sous la forme d’une table associant un identifiant d’artefact à une liste de chaînes. Avec le schéma spec-driven, les identifiants sont proposal, specs, design et tasks. Chaque règle n’est transmise à l’agent que lorsqu’il rédige l’artefact correspondant.

Dans un scalaire simple, YAML interprète key: value comme une table : mettez donc entre guillemets toute règle contenant un deux-points suivi d’une espace, comme la règle tasks ci-dessus.

/codev-propose applique les règles une seconde fois lorsqu’elle relit le plan terminé : rules est donc aussi le moyen d’ajouter un angle de relecture propre à votre projet :

rules:
  design:
    - "Évaluer l'impact sur l'accessibilité (RGAA) de toute modification de l'interface utilisateur."

Les règles de test se placent sous tasks : /codev-propose rédige le plan en les respectant, et /codev-apply les suit lorsqu’elle écrit les tests. Décrivez ce que font vos tests existants — /codev-configure en rédige la règle à partir d’eux :

rules:
  tasks:
    # Une règle pour votre pile, par exemple :
    # Rust
    - "Tests unitaires dans un #[cfg(test)] mod tests à côté du code, tests d'intégration dans tests/ ; cargo test, cargo clippy -- -D warnings, cargo fmt --check."
    # TypeScript
    - "Vitest, *.test.ts à côté du code, Testing Library pour les composants ; tsc --noEmit et le linter en CI."
    # Python
    - "pytest, tests/ reproduisant l'arborescence du paquet, fixtures et parametrize ; ruff check."
    # Go
    - "Tests pilotés par table dans des fichiers _test.go du même paquet ; go test ./..., go vet."
    # Java
    - "JUnit 5 sous src/test/java, à l'image du paquet principal, Mockito seulement aux frontières ; mvn verify."

Tant que rules est vide, codev init et codev status suggèrent de lancer /codev-configure.

inherits

Les sources en lecture seule dont hériter le contexte, les règles et les décisions, dans l’ordre du plus général au plus spécifique. Chaque entrée est soit un dossier local, soit un dépôt git :

Une entrée déclare exactement une clé parmi path et git ; ref et subpath sont rejetées sur une entrée path. Les sources git sont épinglées dans _codev/codev.lock par codev sources update. Voir Sources héritées.

codev init --inherit <SOURCE> écrit cette clé pour vous lorsqu’il crée la configuration, une entrée par option, sous un commentaire # set with codev init --inherit, et épingle aussitôt les sources git :

codev init --yes --inherit git@github.com:acme/codev-standards.git@v2 --inherit ~/src/acme-standards

# set with codev init --inherit
inherits:
  - git: git@github.com:acme/codev-standards.git
    ref: v2
  - path: ~/src/acme-standards

mcp

Les noms des outils MCP que les skills peuvent appeler. Ils sont propres à chaque installation de Claude Code et ne sont donc jamais hérités.

Voir Jira et autres serveurs MCP.

changelog

Les réglages de codev changelog. Propres au projet, jamais hérités.

Utilisez-la pour adopter codev changelog dans un projet dont le CHANGELOG.md décrit déjà des changes archivés sans note de version, afin qu’ils ne soient pas listés deux fois. Voir Notes de version et CHANGELOG.

codev_version

Les versions de codev que l’équipe accepte, sous forme d’exigence de version sémantique dans la syntaxe de Cargo : ">=0.5", "^0.6", ">=0.5, <0.8". Mettez la valeur entre guillemets, car YAML interprète > à sa façon. Propre au projet, jamais héritée.

Lorsque le codev en cours ne la satisfait pas, codev doctor signale la vérification codev_version comme manquante et les skills proposent de mettre à jour avant d’agir. La correction est codev self-update quand le codev en cours est trop ancien. Quand il est trop récent — au-delà d’une borne supérieure comme <0.7 — un simple codev self-update refuserait de rétrograder : la correction nomme donc une version, codev self-update --version 0.6.4, prise dans la dernière version publiée que connaît le cache de mise à jour si elle satisfait l’exigence, sinon dans l’exigence elle-même (<=0.6.2 donne 0.6.2, ^0.5 donne 0.5.0). Une valeur qui n’est pas une exigence fait échouer toutes les commandes avec invalid_codev_version.

codev 0.5 et les versions antérieures ne connaissent pas cette clé et rejettent le fichier : ajoutez-la une fois que tout le monde utilise une version qui la connaît.

roles

Les rôles qui s’exécutent, et les critères que votre projet leur ajoute. Propre au projet, jamais hérité. Chaque clé est un identifiant de rôle ; sa valeur est soit une activation, soit une table :

roles:
  newcomer: never            # forme courte
  security: always           # l'expert sécurité relit chaque change
  skeptic:
    when: always
    done_when:
      - Le plan de retour arrière est indiqué

Les identifiants sont ceux des rôles d’étape intégrés (analyst, investigator, tracer, skeptic, developer, newcomer), ceux des experts (security, privacy, accessibility, performance, ops, migration — voir Experts et domaines) et ceux des rôles d’artefact du schéma utilisé (product, qa, architect, lead avec spec-driven). Les rôles d’artefact, l’analyst et le developer ne peuvent pas être désactivés ; leurs critères peuvent être complétés. Le change.yaml d’un change peut changer l’activation pour ce change seulement — voir change.yaml.

codev validate signale un identifiant inconnu par unknown_role, une activation autre que always, never ou on_domain — ou on_domain sur un rôle lié à aucun domaine — par invalid_role_activation, et never sur un rôle qui ne peut pas être désactivé par role_not_disableable — des erreurs de l’élément config, à la ligne du rôle. codev status, codev instructions et codev roles échouent avec le même code. Toute autre clé dans la table d’un rôle, comme un done-when mal orthographié, fait échouer chaque commande avec invalid : l’ignorer ferait disparaître des critères sans bruit.

triggers

Les déclencheurs propres à votre projet : les chemins et les motifs que seule votre équipe sait sensibles. Propre au projet, jamais hérité. Une liste de groupes, qui nomment chacun le domaine qu’ils suggèrent et contiennent au moins l’une des clés paths, manifests ou patterns :

triggers:
  - domain: personal-data
    paths: ["src/billing/**", "src/crm/**"]
    patterns: ['\bcustomer_id\b']
  - domain: migration
    paths: [api/public.yaml]

Mettez entre guillemets un glob qui commence par * : en YAML, * ouvre un alias. Leurs correspondances ont la source project, et ils sont évalués quels que soient vos réglages roles:. Les expressions s’exécutent en temps linéaire, quelle que soit leur forme, et leur taille compilée est plafonnée.

codev validate signale, à la ligne de triggers:, une erreur invalid_trigger pour un groupe sans domain connu, sans aucun déclencheur, ou avec un glob ou une expression qui ne compile pas — le groupe est alors ignoré par toutes les commandes, qui le signalent dans leur status —, et un avertissement invalid_trigger pour une clé qu’il ne connaît pas, ignorée tandis que le reste du groupe s’applique.

codev 0.6 et les versions antérieures ne connaissent pas cette clé : elles émettent l’avertissement unknown_config_key, qui fait échouer leur codev validate --strict. Lorsque vous l’ajoutez, relevez codev_version jusqu’à la version qui l’a introduite.

review

La manière dont les rôles relecteurs travaillent. Propre au projet, jamais héritée.

review:
  mode: isolated

Un change peut la remplacer dans son change.yaml, avec la même clé : review: { mode: inline } pour corriger une coquille dans un projet isolé, ou isolated pour un change sensible dans un projet en ligne. codev roles --json donne le mode en vigueur et son origine (review.mode, review.origin). Toute autre valeur fait échouer chaque commande avec invalid_review_mode, qui nomme inline et isolated ; une clé inconnue sous review est un avertissement unknown_config_key (review.<clé>).

Changer de mode. Définissez la clé, puis lancez codev update : en mode isolé, les skills /codev-propose et /codev-apply demandent l’outil Agent de Claude Code, en mode en ligne elles ne le demandent pas, et codev doctor signale skills_review_mode tant qu’elles n’ont pas été régénérées. Une skill que vous avez modifiée à la main est conservée ; codev update --force la réécrit.

Pourquoi inline par défaut. La revue isolée multiplie la lecture de la matière par le nombre de rôles, et son bénéfice n’est pas encore mesuré : les évaluations des rôles de codev font travailler un rôle à la fois, sans conversation d’écriture, et ne peuvent donc pas comparer les deux modes. Voir Revue en ligne ou isolée.

codev 0.6 et les versions antérieures ne connaissent pas cette clé : elles émettent l’avertissement unknown_config_key — qui fait échouer leur codev validate --strict — et refusent un change.yaml qui la définit. Lorsque vous la définissez, relevez codev_version jusqu’à la version qui l’a introduite, pour que chaque codev qui lit le dépôt, CI comprise, la comprenne.

Clés inconnues

Une version plus récente de codev peut ajouter des clés qu’une version plus ancienne ne connaît pas. Pour qu’un codev plus ancien continue de fonctionner sur une configuration plus récente et vous dise ce dont il a besoin, les clés inconnues sont traitées selon ce que produirait le fait de les ignorer :

L’avertissement nomme la clé, indique que le projet demande peut-être une version plus récente de codev, cite codev_version quand le fichier la définit et renvoie à codev self-update ; l’erreur fait de même quand codev_version est définie. L’avertissement apparaît :

• dans la sortie de codev status, codev new change, codev init et codev update, et dans le tableau status de leur sortie --json ;
• dans codev validate, comme constat warning d’un élément config, à la ligne de la clé : codev validate --strict — le cas de la CI — échoue donc, tandis que codev validate seul réussit ;
• dans codev doctor, comme vérification config.keys.

Les clés de la configuration d’une source héritée ne sont pas signalées : seuls son context et ses rules sont lus.

Cette tolérance commence avec la version de codev qui l’a introduite : codev 0.5 et les versions antérieures rejettent toute clé inconnue, à tout niveau. Lorsque vous ajoutez une clé que seules les versions récentes connaissent, relevez aussi codev_version : les membres de l’équipe restés sur un codev plus ancien apprendront par codev doctor et les skills quelle version installer.

Variables d’environnement

Formats de fichiers

Les fichiers de codev sont du Markdown et du YAML destinés à être rédigés par des personnes et des agents, puis analysés par codev. Ce chapitre en donne les règles exactes, avec les mots-clés anglais. codev lit aussi leurs équivalents français (### Exigence :, ## Exigences AJOUTÉES, DOIT…), présentés dans Langue des artefacts.

Tout ce qui figure dans des blocs de code délimités et dans des commentaires HTML est ignoré par les analyseurs : les templates peuvent donc contenir des consignes dans des commentaires <!-- … -->.

Spec principale

Chemin : _codev/specs/<capability>/spec.md, où <capability> est formé d’un ou plusieurs segments en kebab-case (ui/theme). Seul un fichier nommé exactement spec.md est une spec principale : les autres fichiers de _codev/specs/, comme un README.md, sont ignorés par codev list --specs et codev validate.

# Theme Specification

## Purpose

Permettre aux utilisateurs de choisir le thème de couleurs de l'interface.

## Requirements

### Requirement: Le thème suit par défaut la préférence du système

L'application SHALL s'afficher avec le jeu de couleurs du système d'exploitation tant que l'utilisateur n'a pas choisi de thème.

#### Scenario: Aucun thème encore choisi

- **GIVEN** un utilisateur qui n'a jamais modifié le réglage du thème
- **WHEN** son système d'exploitation est en mode sombre
- **THEN** l'application s'affiche avec le thème sombre

• ## Purpose est obligatoire.
• Les exigences sont des titres ### Requirement: <name> placés dans ## Requirements. Le nom identifie l’exigence dans les deltas : veillez à ce qu’il soit unique au sein de la spec.
• La description d’une exigence contient un mot-clé normatif en majuscules : SHALL ou MUST, ou DOIT ou DOIVENT.
• Chaque exigence comporte au moins un #### Scenario: <name>, avec exactement quatre caractères #. Les étapes d’un scénario sont des lignes à puces utilisant **GIVEN**, **WHEN**, **THEN** et **AND**.
• Les autres sections ## sont autorisées et préservées lors des fusions.
• Les titres de delta (## ADDED Requirements…) sont interdits dans une spec principale.

Lorsque l’archivage crée la spec principale d’une nouvelle capacité, il la titre d’après le dernier segment du chemin de la capacité (# Theme Specification) et recopie la section ## Purpose du delta.

Delta de spec

Chemin : _codev/changes/<name>/specs/<capability>/spec.md, avec le même chemin de capacité que la spec principale qu’il modifie.

## ADDED Requirements

### Requirement: Le thème choisi est mémorisé

L'application SHALL restaurer le dernier thème choisi par l'utilisateur, sur chacun des appareils depuis lesquels il se connecte.

#### Scenario: Utilisateur de retour

- **GIVEN** un utilisateur qui a choisi le thème sombre sur son ordinateur portable
- **WHEN** il se connecte depuis son téléphone
- **THEN** l'application s'affiche avec le thème sombre

## MODIFIED Requirements

### Requirement: Le thème suit par défaut la préférence du système

<l'exigence complète, scénarios compris, telle qu'elle doit se lire après le change>

## REMOVED Requirements

### Requirement: Ancien sélecteur de couleurs

**Reason**: Remplacé par le réglage du thème.
**Migration**: Les couleurs personnalisées des utilisateurs sont abandonnées ; le thème par défaut s'applique.

## RENAMED Requirements

- FROM: Le thème suit par défaut la préférence du système
- TO: Le thème suit la préférence du système jusqu'au choix de l'utilisateur

Dans RENAMED, écrivez après FROM: et TO: soit le nom seul de l’exigence, comme ci-dessus, soit le titre complet entre accents graves, comme le fait le template : - FROM: `### Requirement: <old name>`.

Règles vérifiées par la validation :

• Une exigence figure dans une seule section au plus parmi ADDED, MODIFIED et REMOVED (cross_section_conflict), et au plus une fois par section (duplicate_requirement).
• Dans une section de delta, chaque titre ### est un ### Requirement: (delta_unexpected_heading) ; une section sans aucune entrée fait l’objet d’un avertissement (delta_section_empty).
• La source d’un RENAMED doit exister dans la spec principale (rename_source_missing, sauf si le renommage a déjà été appliqué par une synchronisation antérieure) ; la cible d’un RENAMED ne peut pas figurer aussi dans ADDED (rename_target_collision) ; et MODIFIED emploie le nouveau nom d’une exigence renommée, et non l’ancien (modified_uses_old_name).
• Les noms cités dans MODIFIED et REMOVED doivent exister dans la spec principale ; cette vérification a lieu lors de la fusion du delta (modified_target_missing).
• Nouvelle capacité : commencez le delta par ## Purpose. Pour une capacité existante, omettez cette section : le Purpose de la spec principale est conservé.
• Un delta REMOVED qui laisserait une spec sans aucune exigence est refusé (would_leave_spec_without_requirement), sauf si le change déclare retire_capabilities: true ; la spec principale est alors supprimée.

proposal.md

Le template du schéma spec-driven :

# Proposal: <change title>

## Why

## What Changes

## Capabilities

### New Capabilities

### Modified Capabilities

### Removed Capabilities

## Impact

## Domains

## Release note

Chaque capacité listée sous New Capabilities ou Modified Capabilities reçoit son propre fichier de delta dans specs/<capability>/spec.md. Les changements incompatibles sont signalés par BREAKING dans What Changes. Une capacité listée sous Removed Capabilities exige retire_capabilities: true.

Release note

Ce que les utilisateurs liront dans le changelog, construit par codev changelog. Soit un ou plusieurs éléments :

## Release note

- Added: `--format json` pour `codev export`.
- Changed: **BREAKING** `codev export` écrit sur stdout par défaut ; passez
  `--output <PATH>` pour écrire un fichier.

soit, pour un change que les utilisateurs ne remarqueront pas, la seule ligne :

## Release note

None

Chaque élément s’écrit - <Category>: <texte>, la catégorie étant l’une de Added, Changed, Deprecated, Removed, Fixed et Security — les catégories de Keep a Changelog. Un élément peut s’étendre sur plusieurs lignes. Un élément incompatible commence son texte par **BREAKING**. Le texte suit la langue des artefacts du projet. codev validate signale une section absente par un avertissement, et une catégorie inconnue, un élément sans texte ou une section vide par une erreur, sur les changes actifs uniquement.

Domains

Les domaines que touche le change, qui activent leurs experts. Le modèle liste les six domaines non cochés ; cochez ceux que touche le change :

## Domains

- [x] security
- [ ] personal-data
- [ ] user-interface
- [ ] performance
- [x] operations — un nouveau worker en arrière-plan
- [ ] migration

ou, lorsqu’il n’en touche aucun, écrivez la seule ligne None.

- [x] <domaine> ou - <domaine> coche un domaine, - [ ] <domaine> le laisse non coché, et le texte qui suit le nom du domaine est un commentaire libre. Les domaines sont security, personal-data, user-interface, performance, operations et migration. codev validate signale, sur les changes actifs uniquement, un domaine inconnu (unknown_domain) et une ligne qui n’est ni un élément ni None, ou None à côté d’un domaine coché (domains_invalid), par une erreur, et une section absente (domains_missing) par un avertissement.

Ce commentaire est aussi la façon de répondre à un domaine suggéré que le change ne touche pas : un domaine non coché suivi d’une raison est justified — - [ ] security — only renames a variable. Les tirets, deux-points et espaces de tête ne font pas partie de la raison ; None ne justifie rien. codev validate signale chaque domaine suggéré ni coché ni justifié par domain_suggested, un avertissement à la ligne du domaine.

design.md

# Design: <change title>

## Context

## Goals / Non-Goals

## Decisions

### Decision: <the choice>

**Alternatives considered**:

## Risks / Trade-offs

## Migration Plan

## Open Questions

Chaque bloc ### Decision: <title> peut être promu en ADR avec codev decision promote <change> "<title>". Risks / Trade-offs suit la forme [Risk] → Mitigation. Migration Plan et Open Questions sont supprimées lorsqu’elles ne s’appliquent pas.

tasks.md

# Tasks

## 1. Jetons de thème

- [ ] 1.1 Déplacer chaque couleur dans une propriété CSS personnalisée, vérifié par un diff visuel de la page des réglages
- [ ] 1.2 Ajouter le jeu de jetons sombres, vérifié par `npm test -- theme`

Les tâches sont regroupées sous des titres ## numérotés et s’écrivent - [ ] X.Y <task> ; /codev-apply les coche sous la forme - [x]. Chaque tâche indique comment la vérifier.

change.yaml

Chemin : _codev/changes/<name>/change.yaml. Écrit par codev new change. <name> n’est jamais archive, le dossier des changes archivés.

schema: spec-driven
created: 2026-09-30
goal: Let users switch the UI to a dark theme

Les clés inconnues sont rejetées — dans review aussi. Un codev antérieur à review refuse un change.yaml qui la définit : relevez le codev_version du projet jusqu’à la version qui l’a introduite avant de l’utiliser. Un dossier de change dépourvu de change.yaml utilise le schéma du projet. Une entrée invalide de roles est signalée par codev validate comme une erreur du change (unknown_role, invalid_role_activation, role_not_disableable).

Les artefacts d’un schema.yaml peuvent déclarer leur rôle comme une donnée, sous role: — voir Schémas personnalisés.

review.md

Chemin : _codev/changes/<name>/review.md. Le compte rendu de revue du change, écrit par /codev-propose (plan.challenge) et /codev-apply (code.review), ou à la main. Ce n’est pas un artefact de planification : codev status l’ignore, codev sync le laisse en place, codev archive le déplace avec le change.

# Review record: add-sessions

<!-- codev-review: 1 -->

## plan.challenge

### skeptic

No finding.

### security

#### R-security-1 Session tokens are stored in clear

```yaml
severity: high
confidence: high
location: "design.md#Decision: Sessions live in the database"
evidence: |
  The session token is stored in the `sessions` table.
recommendation: Store a SHA-256 of the token and compare digests.
history:
  - status: open
    by: security
  - status: fixed
    by: architect
    ref: design.md, the decision now stores a digest
  - status: fixed
    by: security
    note: verified
```

## code.review

### newcomer

Disabled by configuration.

Les titres et les lignes No finding. et Disabled by configuration. restent en anglais : codev les lit.

Un champ que ce codev ne connaît pas est un avertissement, review_unknown_field, et il est ignoré : un codev ultérieur peut ajouter des champs facultatifs sans changer de format. Un nouveau statut, une nouvelle étape ou un nouveau champ obligatoire relève au contraire le marqueur de format, qu’un codev plus ancien refuse de vérifier. Les transitions et les contrôles sont dans Compte rendu de revue.

Décision (ADR)

Chemin : _codev/decisions/NNNN-<slug>.md. Chaque fichier .md de ce dossier est analysé comme une décision.

---
id: "0003"
title: "Use SQLite for persistence"
status: accepted
date: 2026-09-30
tags: [storage]
supersedes: ["0001"]
---

## Context

## Decision

## Consequences

## Alternatives considered

Le frontmatter est délimité par des lignes --- placées tout au début du fichier. Le contenu est découpé en sections ## ; les quatre sections du template relèvent de la convention, et non de l’obligation. Seules les décisions accepted qui ne sont ni remplacées ni l’objet d’un écart sont en vigueur, et supersedes comme deviates_from ne prennent effet que sur une décision accepted : un remplacement ou un écart proposed ne change rien avant codev decision accept.

Les fichiers enregistrés avec des fins de ligne Windows (CRLF) sont lus comme les autres. Lorsque codev réécrit le statut d’une décision — codev decision accept, ou un prédécesseur passé en superseded —, il conserve les fins de ligne du fichier et laisse le corps identique à l’octet près : le sceau reste valide.

seal.yaml

Chemin : _codev/decisions/seal.yaml. Maintenu par codev ; ne le modifiez pas à la main.

version: 1
seals:
- id: '0001'
  bodySha256: sha256:fad1f272bf13eb44f97aba1bc22f36f294503d1a2471bf12ab4bfc6ee7b4d7f6
  sealedAt: 2026-09-30

Chaque entrée enregistre l’empreinte SHA-256 du contenu d’une décision — tout ce qui suit le --- fermant du frontmatter, octet pour octet — et la date de son scellement. Commitez ce fichier avec vos décisions.

codev.lock

Chemin : _codev/codev.lock. Écrit uniquement par codev sources update, au format TOML.

version = 1

[[source]]
git = "git@github.com:acme/codev-standards.git"
ref = "main"
commit = "12958274cbed0eb66985f57d3272c6d3134b672d"
resolved_at = "2026-09-30"

Une entrée [[source]] par source git:, avec la ref qu’elle suit, le commit sur lequel elle est épinglée et, le cas échéant, son subpath. Commitez ce fichier.

SKILL.md

Chemin : .claude/skills/codev-<workflow>/SKILL.md. Généré par codev init et codev update :

---
name: codev-explore
description: "Explore an idea, investigate a problem or clarify a need before creating a codev change. …"
allowed-tools: "Bash(codev:*), Read, Glob, Grep"
license: MIT
metadata:
  generator: codev
  version: "0.6.1"
  checksum: "8d676b09…"
---

<workflow instructions>

metadata.checksum est l’empreinte SHA-256 de toute la skill, hors de cette ligne. Avec metadata.version, c’est ce qui permet à codev update de distinguer les rendus de codev de vos modifications. codev update réécrit une skill marquée d’une autre version ; parmi les skills marquées de sa propre version, il réécrit celle dont le contenu correspond encore à son checksum — un rendu de codev, d’une compilation antérieure ou pour l’autre mode de revue — et préserve celle qui n’y correspond plus, modifiée à la main, sauf si vous passez --force. Une skill sans checksum, rendue avant leur existence, est préservée quand elle porte la marque de cette version et diffère du rendu par plus que le mode de revue : lancez une fois codev update --force pour la doter d’un checksum — il écrase aussi une skill que vous avez réellement modifiée : vérifiez d’abord git diff, puis réappliquez vos modifications ; une modification faite ensuite est préservée, puisqu’elle ne correspond plus au checksum.

Codes de validation

Chaque constat signalé par codev validate porte un code stable. Les messages peuvent être reformulés d’une version à l’autre ; les codes, non.

Sortie JSON

Toute commande qui agit sur un projet accepte --json. La sortie constitue un contrat public et versionné — la version 1 — sur lequel s’appuient les skills, et que vous pouvez utiliser dans vos scripts et votre CI.

Garanties

• Un seul document. La sortie standard contient exactement un document JSON, indenté, y compris lorsque la commande échoue. Rien d’autre n’est écrit sur la sortie standard.
• Un tableau status. Chaque document comporte un tableau status, vide lorsque tout s’est bien passé, et qui liste sinon les avertissements et les erreurs.
• La même forme en cas d’échec. Une commande en échec renvoie la forme de sa sortie nominale, avec des champs vides ou null, plus l’erreur dans status. Un consommateur analyse les deux cas avec le même code.
• Des noms stables. Les noms de champs sont en camelCase. Les codes sont stables et faits pour être testés ; les messages sont faits pour être lus et peuvent être reformulés.
• Des chemins portables. Tous les chemins, absolus ou relatifs, utilisent le séparateur / sur tous les systèmes — sous Windows, C:/work/acme-app. Les chemins figurant dans les constats sont relatifs à la racine du projet.
• Une évolution par ajout. Au sein de la version 1, des champs peuvent être ajoutés, jamais renommés ni supprimés. Certains champs facultatifs sont omis lorsqu’ils sont vides, comme indiqué ci-dessous.

Le code de sortie suit les mêmes règles qu’en mode lisible : 0 en cas de succès, 1 en cas d’échec et, pour codev validate, 1 en présence d’erreurs (ou de tout constat avec --strict).

Le tableau status

{
  "status": [
    {
      "level": "error",
      "code": "ambiguous_change",
      "message": "several active changes: add-audit-log, rework — specify which one"
    }
  ]
}

Codes d’erreur courants :

Les avertissements reprennent le code de la situation qu’ils signalent, par exemple inherit_unresolved, git_source_unlocked, unknown_workflow ou artifact_skipped.

Documents par commande

init et update

codev init --json et codev update --json :

{
  "root": "/home/you/acme-app",
  "created": ["…"],
  "updated": ["…"],
  "untouched": ["…"],
  "preserved": ["/home/you/acme-app/.claude/skills/codev-apply/SKILL.md"],
  "skills": ["codev-propose", "codev-explore", "…"],
  "integration": [
    {
      "step": "claude_md",
      "action": "appended",
      "path": "CLAUDE.md",
      "reason": null
    },
    {
      "step": "ci",
      "action": "skipped",
      "path": ".github/workflows/codev.yml",
      "reason": ".github/workflows/ci.yml already runs codev validate"
    },
    {
      "step": "pr_template",
      "action": "created",
      "path": ".github/PULL_REQUEST_TEMPLATE.md",
      "reason": null
    }
  ],
  "status": []
}

preserved liste les skills laissées en place parce qu’elles ont été modifiées à la main. integration compte une entrée par étape d’intégration au dépôt : step vaut claude_md, ci ou pr_template ; action vaut created, appended, refreshed, unchanged ou skipped ; path est relatif au projet, ou null ; reason explique une étape écartée, ou vaut null. codev update ne liste que les fichiers gérés qu’il a trouvés. L’indication codev doctor et le job GitLab n’apparaissent que dans la sortie humaine.

Avertissements propres à init : inherit_not_written (--inherit alors que config.yaml existe), inherit_pin_failed (une source git n’a pas pu être épinglée) et managed_section_malformed (marqueurs codev déséquilibrés ; le fichier reste intact). Une valeur --inherit invalide échoue avec invalid_inherit.

doctor

codev doctor --json :

{
  "root": "/home/you/acme-app",
  "checks": [
    {
      "id": "config.rules",
      "group": "configuration",
      "status": "missing",
      "code": "rules_missing",
      "message": "no rules: in _codev/config.yaml",
      "fix": "/codev-configure"
    },
    {
      "id": "config.language",
      "group": "configuration",
      "status": "ok",
      "code": "ok",
      "message": "language: is set",
      "fix": null
    },
    "…"
  ],
  "summary": {
    "total": 14,
    "missing": 2,
    "warnings": 1
  },
  "status": []
}

Chaque vérification a un id stable, son group, un status (ok, missing ou warning), un code stable (ok lorsque la vérification réussit), un message et un fix — la commande ou la skill à lancer — ou null lorsque le statut est ok. Les vérifications suivent l’ordre du tableau ci-dessous ; pr_template n’apparaît que pour un dépôt GitHub. summary.missing détermine le code de sortie de --strict.

changelog

codev changelog --format json (le --json de cette commande) :

{
  "root": "/home/you/acme-app",
  "since": "v1.3.0",
  "until": null,
  "release": null,
  "entries": [
    {
      "category": "Added",
      "text": "`--format json` pour `codev export`.",
      "breaking": false,
      "change": "2026-10-02-export-json",
      "archivePath": "_codev/changes/archive/2026-10-02-export-json",
      "source": "release_note"
    }
  ],
  "markdown": "## [Unreleased]\n\n### Added\n\n- `--format json` pour `codev export`.\n",
  "written": null,
  "status": []
}

• since — la référence après laquelle commence l’intervalle, explicite ou le tag par défaut ; null lorsque tous les changes archivés en font partie. until — null pour l’arbre de travail.
• release — { "version", "date" } avec --release, sinon null.
• entries — dans l’ordre d’affichage. text est l’élément tel qu’écrit, marqueur **BREAKING** compris. source vaut release_note, ou what_changes pour un change archivé sans note de version.
• markdown — les éléments mis en forme au format Keep a Changelog.
• written — avec --write, { "path", "action" }, action valant created, updated ou unchanged ; sinon null.

Avertissements dans status : release_note_missing, release_note_invalid, release_note_inconsistent, not_a_git_repository, archived_change_unreadable. Codes d’erreur : unknown_ref, not_a_git_repository (avec --since ou --until hors de git), invalid_release_version, invalid_date, invalid_argument, changelog_malformed.

new change

{
  "changeName": "add-audit-log",
  "schemaName": "spec-driven",
  "changeRoot": "/home/you/acme-app/_codev/changes/add-audit-log",
  "created": [
    "/home/you/acme-app/_codev/changes/add-audit-log/change.yaml"
  ],
  "status": []
}

list

{
  "changes": ["add-audit-log"],
  "root": "/home/you/acme-app",
  "status": []
}

Avec --specs, le tableau s’appelle specs et liste des chemins de capacités.

search

codev search --json :

{
  "root": "/home/you/acme-app",
  "query": "decision seal",
  "language": "en",
  "results": [
    {
      "kind": "requirement",
      "id": "decisions::Body seal recorded by the CLI",
      "capability": "decisions",
      "requirement": "Body seal recorded by the CLI",
      "excerpt": "The CLI SHALL maintain a `_codev/decisions/seal.yaml` file…"
    },
    {
      "kind": "decision",
      "id": "project/0003",
      "decision": "0003",
      "title": "The planning folder is hidden",
      "origin": "project",
      "status": "superseded",
      "inEffect": false,
      "supersededBy": "project/0009",
      "excerpt": "…"
    }
  ],
  "archived": [
    { "change": "2026-09-09-enforce-decision-immutability", "excerpt": "…" }
  ],
  "status": []
}

language est la langue dans laquelle les mots ont été réduits à leur racine. Un résultat ne porte que les champs de son type ; archived n’est présent qu’avec --archive. Dans un résultat, status est le statut de la décision, pas le tableau des erreurs de la racine.

show

codev show --json :

{
  "root": "/home/you/acme-app",
  "capability": "decisions",
  "requirement": {
    "name": "Creating a decision through the CLI",
    "text": "### Requirement: Creating a decision through the CLI\n\n…"
  },
  "status": []
}

codev show <capacité> porte requirements, les noms des exigences, et purpose au lieu de requirement. Un échec porte capability: null et son code dans status.

status

{
  "changeName": "add-audit-log",
  "schemaName": "spec-driven",
  "planningHome": "/home/you/acme-app",
  "changeRoot": "/home/you/acme-app/_codev/changes/add-audit-log",
  "applyRequires": ["tasks"],
  "isPlanningComplete": false,
  "artifacts": [
    {
      "id": "proposal",
      "outputPath": "proposal.md",
      "status": "ready",
      "requires": [],
      "missingDeps": []
    },
    {
      "id": "specs",
      "outputPath": "specs/**/*.md",
      "status": "blocked",
      "requires": ["proposal"],
      "missingDeps": ["proposal"]
    }
  ],
  "update": {
    "current": "0.5.0",
    "latest": "0.6.0",
    "url": "https://github.com/mairistem/codev/releases/tag/v0.6.0",
    "available": true,
    "snoozed": false
  },
  "versionRequirement": {
    "requirement": ">=0.5",
    "satisfied": true
  },
  "status": []
}

Le status d’un artefact vaut done, ready, blocked ou skipped. planningHome est la racine du projet ; les skills s’en servent plutôt que de supposer le répertoire courant.

update est présent lorsque la dernière release de codev est connue : current est la version en cours, latest la dernière release, url sa page, available indique si latest est plus récente, et snoozed si codev self-update --snooze l’a mise en sourdine. Il est absent lorsque la vérification est désactivée (CI, CODEV_NO_UPDATE_CHECK=1) ou n’a encore jamais réussi. versionRequirement est présent lorsque _codev/config.yaml définit codev_version : requirement est sa valeur, satisfied indique si la version en cours la respecte. Ces deux objets s’ajoutent sans rien changer : un consommateur qui les ignore lit le document comme avant.

self-update

codev self-update --json, qui implique --yes :

{
  "current": "0.5.0",
  "latest": "0.6.0",
  "url": "https://github.com/mairistem/codev/releases/tag/v0.6.0",
  "action": "updated",
  "installMethod": "standalone",
  "path": "/home/you/.local/bin/codev",
  "hint": null,
  "projectUpdated": true,
  "status": []
}

action vaut updated, up_to_date, available (avec --check), snoozed, nothing_to_snooze ou managed_elsewhere. installMethod vaut standalone, cargo, build ou package_manager ; pour les trois derniers, hint contient la commande qui met codev à jour. latest et url valent null lorsqu’ils sont inconnus. Les échecs gardent cette forme et portent leur code dans status — voir les codes.

instructions

{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "artifact": "design",
  "description": "Technical approach and decisions",
  "resolvedOutputPath": "/home/you/acme-app/_codev/changes/add-dark-mode/design.md",
  "instruction": "Write the document that explains HOW to implement the change.\n…",
  "template": "# Design: <change title>\n…",
  "language": "en",
  "context": [
    { "origin": "path:~/src/acme-standards", "text": "All services log in JSON." },
    { "origin": "project", "text": "TypeScript monorepo." }
  ],
  "rules": [
    { "origin": "project", "text": "Cite the decisions that constrain the approach." }
  ],
  "dependencies": [
    { "id": "proposal", "path": "/home/you/acme-app/_codev/changes/add-dark-mode/proposal.md", "done": true }
  ],
  "unlocks": ["tasks"],
  "decisions": [
    {
      "id": "0003",
      "qualifiedId": "project/0003",
      "title": "Use SQLite for persistence",
      "status": "accepted",
      "tags": [],
      "path": "_codev/decisions/0003-use-sqlite-for-persistence.md",
      "origin": "project"
    }
  ],
  "related": [
    {
      "capability": "decisions",
      "requirement": "Creating a decision through the CLI",
      "excerpt": "`codev decision new <title>` SHALL create a new ADR in the project…"
    }
  ],
  "skipped": false,
  "role": {
    "id": "architect",
    "name": "Architect",
    "kind": "artifact",
    "at": "plan.write",
    "steps": ["plan.write"],
    "artifact": "design",
    "domains": [],
    "question": "How will it be built?",
    "when": "always",
    "whenOrigin": "default",
    "activatedBy": "always",
    "disableable": false,
    "knowledge": null,
    "doneWhen": [
      { "origin": "schema:spec-driven", "text": "each decision names the alternative it rejects and why" },
      "…"
    ]
  },
  "status": []
}

Un échec conserve cette forme, avec language toujours renseigné — la langue configurée, ou en lorsque la configuration ne peut pas être lue — et les autres champs à null ou vides.

validate

{
  "root": "/home/you/acme-app",
  "items": [
    {
      "kind": "change",
      "name": "add-audit-log",
      "path": "_codev/changes/add-audit-log",
      "findings": [
        {
          "path": "_codev/changes/add-audit-log/change.yaml",
          "line": 1,
          "severity": "error",
          "code": "zero_delta_without_marker",
          "message": "no delta file under `specs/` and `skip_specs: true` is not declared; add a delta or set `skip_specs: true` in change.yaml"
        }
      ]
    }
  ],
  "hasWarnings": false,
  "status": []
}

kind vaut change, spec, decisions ou config — ce dernier seulement lorsque _codev/config.yaml contient des clés que ce codev ne connaît pas (voir Clés inconnues). Les constats sont rapportés dans items, et non dans status : status ne signale qu’un échec de la commande elle-même. Voir Codes de validation.

sync et archive

{
  "changeName": "add-dark-mode",
  "root": "/home/you/acme-app",
  "updated": [],
  "created": ["/home/you/acme-app/_codev/specs/ui/theme/spec.md"],
  "unchanged": [],
  "deleted": [],
  "movedTo": "/home/you/acme-app/_codev/changes/archive/2026-09-30-add-dark-mode",
  "status": []
}

codev sync --json renvoie le même document, sans movedTo. deleted liste les specs principales supprimées par un change qui retire une capacité.

review

{
  "changeName": "add-sessions",
  "path": "_codev/changes/add-sessions/review.md",
  "exists": true,
  "format": 1,
  "steps": [
    {
      "step": "plan.challenge",
      "recorded": true,
      "activeRoles": ["skeptic", "security"],
      "roles": [
        { "role": "skeptic", "state": "no-finding", "fallback": null, "credited": ["R-security-1"] },
        { "role": "security", "state": "findings", "fallback": null, "credited": [] }
      ],
      "mode": "isolated",
      "summarized": []
    },
    {
      "step": "code.review",
      "recorded": false,
      "activeRoles": ["newcomer", "security"],
      "roles": [],
      "mode": null,
      "summarized": []
    }
  ],
  "findings": [
    {
      "id": "R-security-1",
      "title": "Session tokens are stored in clear",
      "role": "security",
      "step": "plan.challenge",
      "line": 13,
      "severity": "high",
      "confidence": "high",
      "reported": true,
      "location": "design.md#Decision: Sessions live in the database",
      "evidence": "The session token is stored in the `sessions` table.\n",
      "recommendation": "Store a SHA-256 of the token and compare digests.",
      "status": "disputed",
      "awaiting": "human",
      "history": [
        { "status": "open", "by": "security", "note": null, "ref": null, "to": null },
        { "status": "disputed", "by": "architect", "note": "Tokens expire after 5 minutes.", "ref": null, "to": null },
        { "status": "disputed", "by": "security", "note": "Five minutes is enough to replay a stolen token.", "ref": null, "to": null }
      ],
      "raisedBy": ["security", "skeptic"]
    }
  ],
  "issues": [],
  "archive": {
    "ready": false,
    "blockers": [
      { "code": "review_step_missing", "message": "the review record has no `## code.review` section, while roles were active at it" },
      { "code": "review_unresolved", "message": "R-security-1 (Session tokens are stored in clear) is high and still disputed; fix it, or a human accepts the risk or defers it" }
    ]
  },
  "status": []
}

Le code de sortie vaut 1 seulement quand issues contient une erreur. Les champs que le fichier omet ou rend invalides valent null.

roles

codev roles --at plan.challenge --change add-dark-mode --json :

{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "at": "plan.challenge",
  "language": "en",
  "stacks": { "detected": ["TypeScript", "JavaScript"], "filter": "detected" },
  "diff": {
    "available": true,
    "reason": null,
    "base": "origin/main",
    "files": 14,
    "scanned": 11,
    "skipped": { "lockfile": 1, "prose": 2 },
    "truncated": false
  },
  "suggestions": [
    {
      "domain": "user-interface",
      "state": "ticked",
      "justification": null,
      "matchCount": 6,
      "matches": [
        { "source": "accessibility", "kind": "paths", "trigger": "**/*.{html,htm,css,scss,sass,less,jsx,tsx,vue,svelte,astro}", "path": "web/src/theme.css", "line": null },
        "…"
      ]
    },
    {
      "domain": "performance",
      "state": "justified",
      "justification": "the cache is the browser's, not ours",
      "matchCount": 1,
      "matches": [
        { "source": "performance", "kind": "patterns", "trigger": "(?i)\\b(cache|caching|memoi[sz]e|lru)\\b", "path": "web/src/theme.ts", "line": 12 }
      ]
    }
  ],
  "roles": [
    {
      "id": "skeptic",
      "name": "Skeptic",
      "kind": "step",
      "at": "plan.challenge",
      "steps": ["plan.challenge"],
      "artifact": null,
      "domains": [],
      "question": "Would the plan survive a reviewer who did not write it?",
      "when": "always",
      "whenOrigin": "project",
      "activatedBy": "project",
      "disableable": true,
      "knowledge": "## Signals\n\nPlanning smells — each one is a question to raise, not a verdict.\n…",
      "doneWhen": [
        { "origin": "built-in", "text": "**Need** — does the change solve the Why? Is there a simpler solution, or one without code?" },
        "…",
        { "origin": "project", "text": "The rollback plan is stated" }
      ]
    },
    {
      "id": "accessibility",
      "name": "Accessibility",
      "kind": "step",
      "at": "plan.challenge",
      "steps": ["plan.challenge", "code.review"],
      "artifact": null,
      "domains": ["user-interface"],
      "question": "Can everyone use what this change adds, with a keyboard or assistive technology?",
      "when": "on_domain",
      "whenOrigin": "default",
      "activatedBy": "domain:user-interface",
      "disableable": true,
      "knowledge": "## Scope\n\nLook at the user interface the change adds or modifies…",
      "doneWhen": [
        { "origin": "built-in", "text": "Every interactive element is reachable and operable with the keyboard alone, in a logical focus order, with a visible focus" },
        "…"
      ]
    }
  ],
  "disabled": [{ "id": "newcomer", "name": "Newcomer", "whenOrigin": "project" }],
  "review": {
    "mode": "isolated",
    "origin": "project",
    "material": {
      "limitBytes": 163840,
      "totalBytes": 18342,
      "summarized": false,
      "files": [
        { "path": "_codev/changes/add-dark-mode/design.md", "bytes": 6120, "treatment": "full" },
        "…"
      ]
    }
  },
  "status": []
}

Avec --at, roles ne contient que les rôles actifs, éventuellement aucun : l’étape est alors sautée. Sans --change, aucune proposal n’est lue : les experts sont donc inactifs. Un échec — unknown_step, unknown_role, invalid_role_activation, role_not_disableable — conserve cette forme, avec roles, disabled et suggestions vides, stacks, diff et review à null, et language renseigné comme pour instructions ; un mode de revue invalide échoue avec invalid_review_mode. Un déclencheur du projet inutilisable est écarté, avec un avertissement invalid_trigger dans status.

schemas

{
  "schemas": [
    { "name": "spec-driven", "origin": "built-in", "flow": ["proposal", "specs", "design", "tasks"] }
  ],
  "root": "/home/you/acme-app",
  "status": []
}

origin vaut project ou built-in. Un schéma du projet inutilisable est écarté de schemas, avec un avertissement schema_unusable dans status. Un schéma du projet dont le name: diffère de son dossier est listé sous le nom de son dossier, avec un avertissement schema_name_mismatch.

decision

codev decision list --json renvoie { "root", "decisions": [...], "status" }, et codev decision show --json renvoie { "root", "decision", "content", "status" }, où content est le Markdown complet du fichier. Une décision se présente ainsi :

{
  "id": "0001",
  "qualifiedId": "project/0001",
  "title": "Use PostgreSQL for persistence",
  "status": "superseded",
  "date": "2026-09-30",
  "tags": [],
  "supersedes": [],
  "deviatesFrom": [],
  "path": "…/_codev/decisions/0001-use-postgresql-for-persistence.md",
  "origin": "project",
  "inEffect": false,
  "supersededBy": "project/0003"
}

deviatedBy est ajouté pour une décision héritée écartée par un écart local. origin vaut project, path:<path> ou git:<url>. path est relatif au projet pour une décision qui s’y trouve, absolu sinon.

Les commandes qui créent ou scellent des décisions renvoient :

bodySha256 n’est présent que si la commande a scellé la décision : decision supersede, decision deviate et decision promote créent une décision proposed et ne scellent rien. Pour decision supersede, oldId, oldQualifiedId et oldPath désignent la décision que l’acceptation de la nouvelle remplacera ; elle n’est pas modifiée. superseded liste les prédécesseurs que decision accept a passés à superseded — chacun avec son id, son qualifiedId et son path — et reste vide quand la décision ne remplace rien.

Par exemple, codev decision accept 0002 --json pour une décision créée par codev decision supersede 0001 "Use SQLite" :

{
  "root": "/home/you/acme-app",
  "decision": {
    "id": "0002",
    "qualifiedId": "project/0002",
    "title": "Use SQLite",
    "status": "accepted",
    "date": "2026-09-30",
    "tags": [],
    "supersedes": [
      "0001"
    ],
    "deviatesFrom": [],
    "path": "_codev/decisions/0002-use-sqlite.md",
    "origin": "project",
    "inEffect": true,
    "supersededBy": null
  },
  "path": "/home/you/acme-app/_codev/decisions/0002-use-sqlite.md",
  "bodySha256": "sha256:c8873b83c178dbf8434045f43a722911b9d9913ee9f13915ccda893539b788c1",
  "superseded": [
    {
      "id": "0001",
      "qualifiedId": "project/0001",
      "path": "/home/you/acme-app/_codev/decisions/0001-use-postgresql.md"
    }
  ],
  "status": []
}

Une acceptation refusée garde la même forme, avec decision et path à null, superseded vide et le code dans status : unknown_decision_id, cannot_accept_inherited, decision_not_proposed, cannot_supersede_inherited ou predecessor_not_accepted.

sources

codev sources list --json renvoie { "root", "sources": [...], "status" }, où une source se présente ainsi :

{
  "type": "git",
  "address": "git@github.com:acme/codev-standards.git",
  "state": "locked",
  "gitRef": "main",
  "sha": "12958274cbed0eb66985f57d3272c6d3134b672d",
  "resolvedPath": "/home/you/.cache/codev/content/12958274cbed0eb66985f57d3272c6d3134b672d"
}

type vaut path ou git ; state prend l’une des valeurs resolved, unreadable, unlocked, locked, needs_update. gitRef, subpath, sha et resolvedPath sont omis lorsqu’ils ne s’appliquent pas.

codev sources show --json renvoie { "source", "filesExposed", "root", "status" }. codev sources update --json renvoie { "root", "changes", "lockWritten", "status" }, où chaque modification comporte un kind (added, moved ou unchanged), url, gitRef, from (pour moved) et to.

FAQ et dépannage

Questions générales

codev envoie-t-il mon code à un modèle ?

Non. Le binaire codev n’appelle jamais de modèle de langage. Il n’accède au réseau que pour récupérer les sources git héritées (codev sources update) et pour chercher une release plus récente de codev (codev status, codev self-update). C’est votre agent — Claude Code — qui rédige, avec les mêmes accès que dans n’importe quelle autre session.

codev vérifie-t-il les mises à jour ?

Oui, et seulement cela. Au plus une fois toutes les 24 heures, codev status envoie une requête HTTPS anonyme à l’API publique de GitHub (https://api.github.com/repos/mairistem/codev/releases/latest) pour lire le numéro de la dernière release, et le garde en cache dans ~/.cache/codev/update-check.json. La requête ne contient rien sur vous ni sur votre projet ; il n’y a aucune télémétrie. Une requête qui échoue reste silencieuse et n’est pas retentée avant le lendemain.

La vérification ne s’exécute jamais lorsque CI est défini, afin que les pipelines restent reproductibles. Pour la désactiver sur votre machine, définissez CODEV_NO_UPDATE_CHECK=1. Rien n’est jamais installé sans votre accord : la mise à jour passe par codev self-update, ou par votre réponse « Update now » dans une skill.

Puis-je utiliser codev sans Claude Code ?

La CLI fonctionne seule : vous pouvez créer des changes, rédiger vous-même les artefacts en suivant codev instructions, valider, synchroniser et archiver. Les skills, qui rédigent à votre place, ciblent uniquement Claude Code.

Faut-il commiter _codev/ et .claude/skills/ ?

Oui. _codev/ est la mémoire de vos specs, de vos décisions et de vos changes : commitez-le en entier, y compris _codev/decisions/seal.yaml et _codev/codev.lock. Commiter .claude/skills/ donne à toute l’équipe les mêmes skills, sans avoir à lancer codev init.

Une petite correction exige-t-elle un change complet ?

Chaque change suit le même cycle, mais le plan peut rester modeste : une proposal d’une ligne, un delta d’une seule exigence, une liste de deux tâches. Pour un change sans impact sur le comportement, définissez skip_specs: true dans son change.yaml.

Puis-je tenir codev à l’écart de CLAUDE.md, de la CI ou du modèle de pull request ?

Oui. Passez --no-claude-md, --no-ci ou --no-pr-template à codev init, ou --no-integration pour les trois. codev update ne les ajoute jamais par la suite. Pour garder le workflow tout en en reprenant la main, supprimez sa première ligne, # codev:managed : codev laisse alors le fichier tranquille. Pour retirer le texte de codev de CLAUDE.md ou du modèle, supprimez le bloc compris entre les marqueurs codev:begin et codev:end. Voir Intégration au dépôt et codev doctor.

Mes relecteurs doivent-ils travailler isolément ?

Par défaut (inline), la skill qui a écrit le plan ou le code le relit aussi, un rôle après l’autre, dans la même conversation. Avec review: { mode: isolated } dans _codev/config.yaml, chaque rôle relecteur travaille seul, comme sous-agent de Claude Code qui ne voit jamais la conversation, puis la skill fusionne ce qu’ils ont trouvé. Cela coûte plus cher — chaque relecteur lit la matière — et le bénéfice n’est pas encore mesuré : commencez par les changes où un regard neuf compte le plus, en définissant review: { mode: isolated } dans leur change.yaml, ou pour tout le projet une fois la différence constatée. Lancez codev update après avoir changé le mode du projet. Voir Revue en ligne ou isolée.

Comment partager cette documentation ?

codev docs --lang fr --write ~/Downloads/codev-manual-fr.html

Le fichier est autonome — CSS intégré, aucune ressource externe — et peut être envoyé par e-mail ou déposé dans un wiki.

Dépannage

no codev project found

error: no codev project found from /home/you — run `codev init` at the project root

codev cherche _codev/ dans le répertoire courant et dans ses parents. Lancez la commande depuis votre projet, ou initialisez-le avec codev init.

Les skills n’apparaissent pas dans Claude Code

Claude Code découvre les skills au démarrage d’une session. Après codev init ou codev update, redémarrez Claude Code ou ouvrez une nouvelle session. Vérifiez que les fichiers .claude/skills/codev-*/SKILL.md existent à la racine du projet que vous avez ouvert.

codev update laisse une skill en place

  Left in place because edited by hand — rerun with --force to overwrite:

Cette skill a été modifiée à la main — son contenu ne correspond plus à son empreinte —, et codev ne supprime pas votre travail. Conservez la modification et ignorez le message, ou lancez codev update --force pour la régénérer (vérifiez d’abord git diff). Une skill générée avant les empreintes est préservée de la même façon, jusqu’à ce qu’un codev update --force lui en donne une.

Le sous-agent d’un relecteur échoue

Lors d’une revue isolée, un sous-agent qui échoue ou qui est arrêté est relancé une fois ; s’il échoue encore, ce rôle relit en ligne et le compte rendu dit pourquoi, par une ligne Fallback: sous le rôle. Rien n’est perdu : la revue est faite, simplement pas isolément pour ce rôle. Si tous les rôles se rabattent sur la revue en ligne, vérifiez que Claude Code peut lancer des sous-agents (l’outil Agent) et que codev doctor indique des skills à jour pour le mode de revue : skills_review_mode signifie que codev update n’a pas été lancé depuis le changement de mode.

codev validate signale zero_delta_without_marker

Le change ne comporte aucun delta de spec sous specs/. Rédigez le delta — le comportement que le change ajoute ou modifie — ou, si le change n’a vraiment aucun impact sur le comportement, ajoutez skip_specs: true à son change.yaml.

codev validate signale decision_seal_mismatch

Le contenu d’une décision scellée a été modifié — à la main, ou par un outil de formatage. Les décisions acceptées sont immuables :

• Restaurez le contenu d’origine (git diff montre ce qui a changé) ; le sceau redevient valide.
• Ou, si la modification était volontaire, scellez-la à nouveau : codev decision seal <ID> --force.

Pour rédiger une décision avant de la sceller, laissez-la proposed — comme la créent codev decision new, supersede, deviate et promote — et lancez codev decision accept <ID> une fois son texte définitif. Une décision créée avec codev decision new --status accepted est scellée immédiatement, avec le texte d’exemple du template.

Pour changer ce que dit une décision, remplacez-la plutôt avec codev decision supersede <ID> "<new title>", rédigez la nouvelle décision, puis acceptez-la.

Pour tenir les outils de formatage à l’écart des décisions, excluez _codev/decisions/ dans leur configuration.

codev decision accept signale predecessor_not_accepted

La décision que vous acceptez liste, dans supersedes, une décision qui n’est plus accepted — le plus souvent parce qu’une autre décision l’a remplacée après la création de la vôtre. Rien n’a été écrit. Lancez codev decision list pour voir quelle décision est désormais en vigueur, puis faites pointer supersedes vers elle dans le frontmatter de la vôtre, ou abandonnez la vôtre si elle est devenue inutile. codev decision supersede refuse avec le même code une décision qui n’est pas accepted.

codev validate signale decision_missing_frontmatter

Chaque fichier .md de _codev/decisions/ est analysé comme une décision. Sortez de ce dossier les autres fichiers Markdown, un README par exemple.

Une spec archivée avec un codev antérieur contient une exigence coupée

Avec codev 0.6.1 et les versions antérieures — les compilations faites avant ce correctif —, archiver un change qui modifiait la dernière exigence d’une spec et ajoutait des exigences pouvait écrire les ajouts au milieu d’une ligne de l’exigence modifiée : la spec contient alors le début de cette exigence, les ajouts, puis sa fin collée derrière eux. codev validate ne le détecte pas, et synchroniser ou archiver à nouveau le change ne le répare pas. Pour vérifier, regardez le diff de chaque archivage d’un change dont le delta modifiait la dernière exigence d’une spec et ajoutait des exigences ; pour réparer, remettez l’exigence entière à la main, ou par un nouveau change dont le delta MODIFIED en donne le texte complet.

La synchronisation ou l’archivage refuse un change

error: change `add-dark-mode` has errors; run `codev validate add-dark-mode` for details

Avec --json, le code d’erreur est validation_failed. Lancez la commande codev validate suggérée, corrigez les constats, puis synchronisez ou archivez à nouveau. Si l’archivage est refusé parce qu’une exigence MODIFIED n’existe pas dans la spec principale, c’est que son nom diffère de celui de la spec principale : corrigez le nom, ou utilisez ADDED si l’exigence est nouvelle.

codev validate signale rename_source_missing

Le nom qui suit FROM: dans ## RENAMED Requirements ne correspond à aucun titre ### Requirement: de la spec principale. Il doit correspondre exactement, que vous écriviez le nom seul ou le titre complet entre accents graves :

- FROM: `### Requirement: Le thème choisi est mémorisé`
- TO: `### Requirement: Le thème choisi suit l'utilisateur`

codev validate signale delta_unexpected_heading

Un titre ### d’une section de delta n’est pas un titre d’exigence — par exemple ### Notes, ou un mot-clé dans une langue que codev ne connaît pas. codev lit ### Requirement: et son équivalent français ### Exigence : ; voir Langue des artefacts.

/codev-propose ignore mon ticket

1. mcp.jira_tool n’était pas défini dans _codev/config.yaml lors de la génération des skills : .claude/skills/codev-propose/SKILL.md affiche alors « (Jira MCP not configured) » à la place du nom de l’outil. Ajoutez la clé, puis lancez codev update --force.
2. L’outil est configuré mais indisponible dans la session Claude Code en cours — nom erroné, serveur non connecté, session expirée. La skill vous le signale et rédige la proposal à partir de votre seule demande.

Voir Jira et autres serveurs MCP.

codev init signale inherit_pin_failed

Une source git passée avec --inherit a été déclarée mais n’a pas pu être épinglée : git est absent, le réseau ou vos identifiants ont échoué, ou la ref n’existe pas (main par défaut ; un dépôt dont la branche par défaut est master demande …/repo.git@master). Corrigez la cause — ou la ref: dans _codev/config.yaml —, puis lancez codev sources update.

codev init signale managed_section_malformed

CLAUDE.md ou le modèle de pull request contient une ligne <!-- codev:begin sans <!-- codev:end --> correspondant, ou plusieurs. codev n’a pas touché au fichier. Gardez exactement une paire de marqueurs, ou supprimez-les tous pour que codev init ajoute une section neuve.

Une source git est unlocked ou needs_update

Lancez codev sources update. unlocked signifie que la source n’a jamais été résolue ; needs_update signifie qu’elle est épinglée dans codev.lock mais absente de votre cache local, typiquement sur une machine neuve.

Le codev d’un collègue échoue sur la configuration

Son codev est plus ancien que votre _codev/config.yaml : le fichier contient une clé que sa version ne connaît pas.

• codev 0.5 et les versions antérieures rejettent toute clé inconnue : chaque commande échoue avec invalid en nommant la clé. Il doit mettre à jour : codev self-update depuis une version récente, sinon l’installateur décrit dans Installation.
• Les versions plus récentes émettent à la place l’avertissement unknown_config_key et continuent de fonctionner ; l’avertissement cite votre codev_version et renvoie à codev self-update. Une clé inconnue dans une entrée de inherits ou dans changelog échoue toujours avec invalid, en citant codev_version.

Pour que le message soit explicite pour tous, relevez codev_version chaque fois que vous ajoutez une clé que seules les versions récentes connaissent. Voir Clés inconnues.

unknown_config_key

_codev/config.yaml contient une clé que ce codev ne connaît pas : elle est ignorée et le reste de la configuration s’applique. Soit la clé vient d’une version plus récente de codev (lancez codev self-update, ou la version que codev doctor indique dans sa vérification codev_version), soit c’est une faute de frappe, comme shema pour schema : corrigez-la. codev validate --strict échoue d’ici là. Lorsque codev doctor propose codev self-update --version <X.Y.Z>, votre codev est plus récent que ce qu’autorise le codev_version du projet, et cette commande installe une version qui le satisfait.

codev self-update signale update_checksum_mismatch

L’archive téléchargée ne correspond pas à sa ligne dans le SHA256SUMS de la release, ou cette ligne manque. Rien n’a été installé. Réessayez plus tard — un proxy a pu altérer le téléchargement — et, si le problème persiste, signalez-le : c’est la vérification qui vous protège d’une archive falsifiée.

codev self-update signale update_not_writable

codev ne peut pas écrire dans le dossier de son binaire, par exemple /usr/local/bin appartenant à root. Réinstallez codev dans un dossier qui vous appartient (install.sh utilise ~/.local/bin), ou lancez la commande avec les droits qu’exige ce dossier.

codev self-update indique que codev est géré ailleurs

Votre binaire a été installé par cargo install, compilé depuis un clone ou installé par un gestionnaire de paquets : codev laisse cet outil s’en charger et affiche la commande à lancer, par exemple cargo install --path crates/codev-cli depuis un clone à jour.

codev: command not found

Le dossier d’installation n’est pas dans votre PATH. Voir Vérifier l’installation.

Architecture

Ce chapitre s’adresse aux contributeurs : comment le code est organisé, et pourquoi. Les décisions qui le sous-tendent, avec leur contexte et les alternatives envisagées, sont consignées sous forme d’ADR dans _codev/decisions/ — codev est développé avec codev. Ce chapitre les résume et les relie entre elles.

Un cœur pur, une coquille impérative

codev suit un principe : décider n’est pas exécuter.

• Tout ce qui est pur vit dans codev-core : le modèle du domaine, les schémas, le graphe des artefacts, les analyseurs, les règles de validation, la fusion et le calcul des plans. Ni std::fs, ni std::env, ni horloge, ni réseau.
• Tout ce qui a besoin du monde extérieur vit au-dessus, derrière un port.

La règle de dépendance n’est pas une convention de dossiers : c’est le graphe des crates, et Cargo refuse de compiler un cycle. Le compilateur la fait respecter, sans interfaces de façade ni conteneur d’injection de dépendances.

Le graphe des crates

codev-cli ──▶ codev-agents ──▶ codev-engine ──▶ codev-core
    │                               ▲                ▲
    ├───────────────────────────────┘                │
    └────────────────────────────────────────────────┘

codev-agents dépend aussi de codev-core, et codev-cli de toutes les crates.

Un module ne devient une crate que lorsqu’il l’a mérité — une frontière de test nette, ou un consommateur externe. Découper plus tôt ne produit que des refactorisations inutiles.

Des plans, pas des effets de bord

Le cœur ne touche jamais au disque. Il renvoie un plan d’effets — fichiers à créer ou à écraser, fichiers à supprimer, dossiers à déplacer — que la coquille exécute. init, new change, sync, archive, l’installation des skills et les commandes de décision fonctionnent tous ainsi.

On y gagne plusieurs choses à la fois : le plan complet est validé avant la première écriture, les fusions se testent sans fichiers temporaires, et les exécutions à blanc ou les aperçus viennent sans effort supplémentaire.

Les ports

Il existe quatre ports, réservés aux effets :

Ce que codev s’interdit : pas de trait de dépôt masquant std::fs, pas de structures *UseCase à méthode unique, pas d’Arc<dyn Trait> par défaut. Les traits servent les frontières réellement ouvertes (AgentTarget, Rule), les génériques servent le reste, et les enums modélisent les ensembles fermés.

Les deux risques dont l’architecture protège

1. Une réécriture destructrice du Markdown. Un delta MODIFIED qui reformate le fichier ou perd du contenu qu’il ne mentionne pas. Les analyseurs conservent donc les plages d’octets d’origine de chaque bloc, afin que la fusion réécrive un bloc sans toucher au reste.
2. La dérive du contrat JSON. La sortie JSON est une API publique, consommée par des skills déjà installées sur les machines des utilisateurs. Les types du domaine ne dérivent donc pas Serialize : codev-cli dispose d’un module contract dédié, dont les types traduisent le domaine, avec des tests qui figent les noms des champs. C’est la seule frontière DTO du projet, et elle a une raison d’être.

Points d’extension

1. AgentTarget — une implémentation par outil d’agent. Claude Code aujourd’hui ; un autre outil peut être ajouté sans toucher au cœur.
2. Rule — une règle de validation par implémentation, enregistrée dans une liste.
3. Schémas, templates et workflows sous forme de données — schema.yaml, les templates et le corps des skills vivent dans assets/ et sont embarqués à la compilation. Améliorer une instruction ne demande jamais de toucher au code Rust.

Où se trouvent les choses

Décisions d’architecture

Conventions de code

• Erreurs. thiserror et des erreurs typées dans les crates de bibliothèque ; anyhow uniquement dans codev-cli, où les erreurs sont traduites dans le tableau status du contrat JSON.
• Commentaires. Ils sont rédigés en anglais et expliquent le pourquoi. Un commentaire qui paraphrase le code n’est que du bruit.
• Tests. Le cœur est testé par des tests unitaires purs ; le moteur, avec un FileSystem en mémoire et des Clock et Env figés ; le contrat JSON, par des tests sur les noms et la forme de ses champs.