Playbook et règles
Une règle, c'est un standard que votre équipe énonce déjà en revue de code, écrit une bonne fois et appliqué partout.
Anatomie d'une règle
| Champ | Sémantique |
|---|---|
| Titre | Court et précis — c'est lui qui apparaît dans les violations et les dashboards. |
| Énoncé | La règle en langage naturel (markdown GitHub). Rédigez-la à l'impératif et expliquez le pourquoi : le modèle juge mieux quand il connaît l'intention. |
| Sévérité | error bloque le merge · warning et info remontent sans bloquer. Réservez error aux vrais dangers. |
| Scopes (globs) | Où la règle s'applique : src/**, apps/api/**… Vide = tout le repo. Une règle n'est contrôlée que sur les fichiers que ses globs matchent. |
| Tags | Des libellés libres (security, api…) pour catégoriser et filtrer. Purement organisationnels : ils n'influencent pas l'analyse. |
| Exemples | Des extraits conformes / non conformes, optionnels, servis aux agents à la demande quand l'énoncé seul reste ambigu. |
Ce qui rend une règle applicable
Le test : un reviewer senior pourrait-il trancher pass/fail en lisant un diff ? Si oui, le modèle le peut aussi.
- ✅ « Les appels HTTP passent par
lib/http.ts— il gère le retry, le timeout et le tracing. N'appelez jamaisfetchdirectement. » - ✅ « Toute migration de base embarque un rollback dans la même PR. »
- ❌ « Écrivez du code propre et maintenable. » — impossible à trancher sur un diff ; ne produira que du bruit.
Vous ne savez pas par où commencer ? La bibliothèque de playbooks contient sept playbooks prêts à l'emploi — sécurité d'API, Next.js App Router, Terraform, migrations, isolation multi-tenant et d'autres — chaque règle écrite selon ce même test, et copiable en markdown pour l'avoir sous les yeux pendant que vous saisissez celles que vous gardez (les règles s'ajoutent une par une ; il n'y a pas d'import en masse).
Normik ne signale que les lignes réellement ajoutées dans le diff, et ne cite que des règles qui existent : un numéro de ligne ou un identifiant de règle halluciné est écarté avant même que vous le voyiez.
Workspaces et héritage
Les règles placées à la racine s'appliquent à toute l'organisation. Celles placées dans un workspace s'appliquent en plus, et uniquement pour les tokens de ce workspace. Glissez-déposez les règles entre les dossiers depuis la page Playbook ; à la suppression d'un workspace, on vous demande si ses règles remontent à la racine ou partent avec lui.
Versionnage et restauration
Chaque modification de contenu prend un instantané de l'état précédent — les 10 dernières versions sont conservées. Restaurer réapplique une ancienne version après avoir figé l'actuelle : une restauration est elle-même annulable.
Générer un playbook depuis un repo existant
Un agent connecté peut appeler la capacité bootstrap_playbook, ou vous pouvez cliquer sur Bootstrap from repo directement depuis la page Playbook et sélectionner des fichiers ou un dossier — la génération est la même. Normik en dérive 3 à 10 règles spécifiques et vérifiables, sur votre clé, toujours rédigées en anglais quelle que soit la langue des fichiers soumis. Elles arrivent proposées par l'IA, en attente de revue : rien ne s'active sans un humain(voir Gouvernance).
Exports pour les agents sans MCP
Le bouton Export de la page Playbook génère un AGENTS.md ou un CLAUDE.md à partir de vos règles actives — déterministe, trié par sévérité, limité au dossier courant. Committez-le dans les repos dont l'outillage ne parle pas MCP.
Skills
Les skills sont des modes d'emploi réutilisables (des instructions en markdown), avec la même hiérarchie, le même versionnage et la même gouvernance que les règles. Les agents les listent, les chargent à la demande, et leur usage est mesuré. Vous pouvez aussi générer un brouillon de skill depuis un prompt — relu dans le formulaire avant enregistrement.