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.