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

Clé	Obligatoire	Signification
`name`	oui	Nom du schéma, en kebab-case — le nom du dossier du schéma, celui qu’utilise codev
`version`	non	Version du format de schéma, `1` par défaut
`description`	non	Description en une ligne
`artifacts`	oui	Les artefacts d’un change, au moins un
`artifacts[].id`	oui	Identifiant de l’artefact, en kebab-case, unique
`artifacts[].generates`	oui	Chemin de sortie relatif au dossier du change ; peut être un motif glob comme `specs/*/.md`
`artifacts[].description`	non	Courte description, présentée à l’agent
`artifacts[].template`	non	Nom du fichier de template, recherché dans le dossier `templates/` du schéma
`artifacts[].instruction`	non	Consignes pour l’agent qui rédige cet artefact
`artifacts[].requires`	non	Identifiants des artefacts qui doivent exister au préalable
`artifacts[].role`	non	Le rôle qui a la charge de l’artefact — voir Déclarer les rôles des artefacts
`apply.requires`	oui	Artefacts qui doivent exister avant le début de l’implémentation
`apply.tracks`	oui	Fichier dont les cases à cocher suivent l’avancement de l’implémentation
`apply.instruction`	non	Consignes pour la phase d’implémentation

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

Clé	Obligatoire	Signification
`role.id`	oui	Identifiant du rôle, en kebab-case, unique dans le schéma, et distinct des rôles d’étape intégrés comme `skeptic`
`role.name`	oui	Noms affichés par code de langue ; `en` est obligatoire et sert pour les langues sans nom
`role.question`	oui	La question dont le rôle a la charge
`role.done_when`	non	Les critères que l’agent vérifie, avec l’origine `schema:<name>`

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.

Raccourcis clavier