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.