Les briques

# AGENTS.md

Application web (Next.js, pnpm). Répondre en français.

## Vérifier avant de dire « fait »
- `npx tsc --noEmit` puis `pnpm test` : citer le résultat.
- `pnpm lint` signale à tort les fichiers générés : lancer `pnpm lint src`.

## Pièges
- Le serveur de développement écoute sur le port 4000, fixé dans `.env.example`.
- Après un changement de schéma : `pnpm db:migrate:create <nom>` puis `pnpm db:migrate`.

## Interdit
- Pas de commit sur main : une branche par sujet, une PR par branche.

@AGENTS.md

• @AGENTS.md un import : Claude Code lit AGENTS.md à la place, et Codex lit AGENTS.md directement. Un seul fichier à tenir.
• pourquoi le garder Claude Code récent lit AGENTS.md même sans ce pointeur, mais un simple CLAUDE.local.md suffit à le lui faire ignorer. Le pointeur évite ce piège.

---
paths:
  - "src/**/*.tsx"
---

# Composants React

- Tester avec Testing Library, jamais avec Enzyme.
- Un composant par fichier, nommé comme le fichier.
- Pas de style en ligne : les classes du design system.

• --- … --- l'en-tête, en YAML : des paires « clé: valeur » que l'outil lit, le modèle ne les voit pas comme du texte.
• paths les fichiers concernés. ** veut dire « dans tous les sous-dossiers », *.tsx « tout fichier qui finit par .tsx ». Sans paths, la règle est lue à chaque session, comme AGENTS.md : on la range à part seulement pour garder AGENTS.md court.

---
name: release-notes
description: Rédiger les notes de version à partir des PR fusionnées. À utiliser quand l'utilisateur demande « les notes de version », « le changelog » ou « qu'est-ce qui part en prod ».
---

# Notes de version

1. Lister les PR fusionnées depuis la dernière étiquette :
   `gh pr list --state merged --search "merged:>=<date>"`.
2. Les classer : nouveautés, corrections, technique.
3. Une ligne par PR, au présent, sans jargon interne.
4. Suivre le gabarit de `modele.md` (dans ce dossier).

• name le nom de la commande : /release-notes. Dans un plugin, il prend le préfixe du plugin (/kwa:tdd) ; sous Codex, on tape $ au lieu de /.
• description la seule partie toujours chargée. Le modèle la compare à votre demande pour décider d'appeler la skill : dites quand l'utiliser, avec les mots que l'on emploie vraiment.
• modele.md une annexe : lue seulement si la skill en a besoin, donc gratuite le reste du temps.

## Version <x.y.z> (<date>)

### Nouveautés
- …

### Corrections
- …

---
name: security-reviewer
description: Relit un diff sous l'angle de la sécurité (entrées non validées, secrets, droits). À utiliser avant une PR qui touche l'authentification, les paiements ou les données personnelles.
tools: Read, Grep, Glob
model: sonnet
---

Tu relis un changement sans le modifier. Pour chaque constat : le fichier et la
ligne, ce qui peut arriver, comment le reproduire, la gravité. Si rien ne pose
problème, dis-le en une phrase : n'invente pas de constat.

• tools les seuls outils qu'il aura : ici lire et chercher, pas écrire. C'est l'outil qui l'applique : la partie imposée d'un sous-agent. Le reste du fichier est du texte qu'il suit.
• model le modèle qui le fait tourner : sonnet, opus, haiku, ou inherit pour celui de la session. Absent, Claude Code choisit selon ses réglages, en général celui de la session.
• le texte sous l'en-tête ses consignes. Il ne voit rien de votre conversation : seulement la tâche que l'agent principal lui donne. Sans Bash, il ne lance pas git diff : le diff lui est fourni dans la demande (le relecteur de Kwa a Bash, en lecture seule, gardé par un hook).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/no-commit-on-main.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsx \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.ts"
          }
        ]
      }
    ]
  }
}

• PreToolUse, PostToolUse l'événement : avant ou après un outil. Il en existe une trentaine (démarrage, fin de réponse…).
• matcher le nom de l'outil visé : Bash (le terminal), Edit|Write (l'un ou l'autre).
• type: command le hook est un programme à lancer ; command est sa ligne de commande.
• $CLAUDE_PROJECT_DIR la racine du projet, remplie par Claude Code : le chemin marche quel que soit le dossier courant.

#!/usr/bin/env python3
"""PreToolUse : refuser git commit sur main. Un filet contre l'erreur, pas une barrière."""
import json
import re
import subprocess
import sys

COMMIT = re.compile(r"\bgit(\s+-[cC]\s+\S+)*\s+commit\b")  # git commit, git -C dir commit, git -c x=y commit


def refuse(reason):
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": reason,
    }}))
    sys.exit(0)


try:
    event = json.load(sys.stdin)  # ce que l'agent s'apprête à faire
    command = event.get("tool_input", {}).get("command", "")
    parts = re.split(r"&&|\|\||;|\|", command)  # cd app && git commit : chaque morceau compte
    if not any(COMMIT.search(p) for p in parts):
        sys.exit(0)  # sans sortie : la décision suit son cours normal
    branch = subprocess.run(["git", "branch", "--show-current"], cwd=event.get("cwd"),
                            capture_output=True, text=True, check=True).stdout.strip()
except Exception as error:  # un garde qui plante doit refuser, pas laisser passer
    refuse(f"Garde en erreur ({error}) : vérifier le hook avant de committer.")
if branch == "main":
    refuse("Pas de commit sur main : créer une branche de travail.")

• json.load(sys.stdin) Claude Code envoie sur l'entrée standard ce que l'agent s'apprête à faire : l'outil, sa commande, le dossier.
• re.split(…) cd app && git commit est une seule commande pour l'outil : on la découpe, sinon le commit passe.
• sys.exit(0) sans rien afficher « pas d'avis » : l'action suit son cours normal (permissions, demande éventuelle).
• permissionDecision: deny le refus. La raison est renvoyée à l'agent, qui la lit et change de cap : ici, il crée une branche.
• except Exception un script qui plante sort en code 1, ce qui ne bloque rien : un garde doit attraper ses propres erreurs et refuser.
• ou bien exit 2 l'autre façon de refuser : écrire la raison sur la sortie d'erreur et sortir avec le code 2. Le JSON permet en plus ask (demander) ou allow.

// PostToolUse : formater le fichier que l'agent vient d'écrire.
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";

const event = JSON.parse(readFileSync(0, "utf8"));
const file: string | undefined = event.tool_input?.file_path;
if (file && /\.(ts|tsx|css)$/.test(file)) {
  execFileSync("npx", ["--no-install", "prettier", "--write", file], { stdio: "ignore" });
}

• readFileSync(0) lit l'entrée standard, comme le script Python : n'importe quel langage fait l'affaire.
• npx --no-install utilise le prettier du projet sans rien télécharger ; un hook n'apporte pas ses dépendances (ici Node.js, tsx, prettier).
• le fichier change sous l'agent après formatage, la prochaine modification de l'agent peut échouer sur un texte qui n'existe plus : il relit le fichier et recommence.

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CONTEXT7_API_KEY}"
      }
    },
    "base": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub"
      ],
      "env": {
        "DSN": "${DB_URL}"
      }
    }
  }
}

• type: http un service distant, joint par une adresse ; headers porte l'authentification.
• type: stdio un programme lancé sur votre machine (npx -y le télécharge puis le lance), qui parle par l'entrée et la sortie standard.
• ${CONTEXT7_API_KEY} une variable d'environnement : la clé n'est jamais écrite dans le fichier, qui peut donc être versionné.
• DSN le nom de variable que ce serveur attend pour la base : chaque serveur documente les siens.

{
  "permissions": {
    "allow": [
      "Bash(pnpm test *)",
      "Bash(git status)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(secrets/**)",
      "Bash(rm -rf *)",
      "mcp__playwright__browser_run_code_unsafe"
    ]
  }
}

• Bash(pnpm test *) la commande pnpm test, seule ou suivie d'arguments (l'étoile).
• Read(.env) un nom de fichier seul vaut à toute profondeur (comme dans un .gitignore) ; ./.env ne viserait que le dossier courant. .env.local demande sa propre ligne.
• Bash(rm -rf *) un filet : rm -fr ou /bin/rm passent à côté. Une règle Bash lit le texte de la commande.
• deny, ask, allow évaluées dans cet ordre : un refus l'emporte toujours, même sur une autorisation plus précise, et vaut aussi pour chaque morceau d'une commande composée.

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": [
        "registry.npmjs.org"
      ]
    },
    "filesystem": {
      "allowWrite": [
        "/tmp/build"
      ]
    }
  }
}

• allowUnsandboxedCommands: false sans cela, Claude peut demander à relancer une commande hors du bac à sable quand elle échoue.
• network.allowedDomains les sites que le shell joint sans demander ; la liste part vide. Pour un autre site, le mode de permission de la session décide : une demande s'affiche en mode Manuel (default), acceptEdits ou plan ; le site est refusé en dontAsk, et en auto sauf si la commande l'a déclaré et que le classifieur l'a validé ; la connexion passe sans demande en bypassPermissions. Pour un refus net partout, network.strictAllowlist: true, à mettre dans vos réglages personnels (il est ignoré dans ceux du projet).
• filesystem.allowWrite les dossiers où écrire, en plus du projet.

mon-plugin/
├── .claude-plugin/
│   └── plugin.json          le manifeste : nom, version, où sont les hooks
├── skills/
│   └── release-notes/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json         les hooks, au format du bloc hooks de settings.json
└── .mcp.json                facultatif : les serveurs MCP

{
  "name": "mon-plugin",
  "version": "0.1.0",
  "description": "Les skills, agents et garde-fous de l'équipe."
}

• name le préfixe de ses skills et de ses agents : /mon-plugin:release-notes.
• pas de chemin de hooks hooks/hooks.json est l'emplacement par défaut ; un champ hooks en ajoute un autre (Kwa s'en sert).

{
  "kwa": 1,
  "modules": [
    "core",
    "craft",
    "issue-flow"
  ],
  "bash": {
    "deny": [
      {
        "id": "deploy-prod",
        "reason": "La production part par la PR, pas par ce script.",
        "all": [
          "npm run deploy:prod"
        ]
      }
    ]
  },
  "verify": {
    "commands": [
      "pnpm typecheck",
      "pnpm test"
    ]
  }
}

• bash.deny une commande que les gardes de Kwa refusent, avec la raison donnée à l'agent. Le même refus vaut sous Codex.
• verify.commands les vérifications que les skills de Kwa lancent avant de dire « fait ».