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.