AI workflows — Claude Code, agents spécialisés, MCP local-only

Kohinos utilise Claude Code pour faire de l'audit qualité, sécurité et financier sur le codebase, et pour épauler le dev solo dans les boucles TDD / refacto / release. L'ensemble du dispositif respecte la priorité 2 du projet : souveraineté. Tous les MCP servers tournent en local (machine du dev ou Raspberry Pi), aucune donnée adhérent ne sort de la machine, aucun SaaS propriétaire n'est dans le path critique. Cf. .claude/rules/mcp-policy.md et .claude/rules/global.md.

Architecture d'ensemble

flowchart LR
  DEV([Dev solo]) -->|slash command| CC[Claude Code CLI]
  CC --> HK[hooks .claude/hooks/]
  CC --> AG[.claude/agents/]
  CC --> SK[.claude/skills/]
  HK -->|PreToolUse / PostToolUse| GR[code-review-graph]
  CC --> SCRIPT[bin/ai-workflows/*.sh]
  SCRIPT -->|déterministe| TOOLS[PHPUnit · SQL · xmllint · phpstan]
  SCRIPT -.diagnostic ambigu.-> AG
  CC --- MCP{MCP servers locaux}
  MCP --> M1[symfony-ai-mate]
  MCP --> M2[context7]
  MCP --> M3[mcp-server-mysql
SELECT only]
  MCP --> M4[code-review-graph]
    

Workflows scriptés (bin/ai-workflows/)

Quatre dossiers métier : financial/, security/, sepa/, et shared/ (prérequis). Chaque script est code-driven : il enchaîne les étapes déterministes (lint, SQL, PHPUnit, XSD) et n'appelle un sous-agent que pour produire du diagnostic humain-lisible en cas d'échec.

Agents Claude Code spécialisés

Chaque agent vit dans .claude/agents/<nom>.md avec un frontmatter YAML (name, description, tools, model). Le modèle est choisi au plus bas coût utile : haiku pour le mécanique, sonnet pour la revue scopée, opus pour les tradeoffs / planification financière.

Audit qualité (lecture seule)

Refactoring (proposition de diff)

Tests

Finance (cœur de Kohinos)

Sécurité

Documentation & release

Hors-scope direct (méthodologie)

MCP servers — autorisés (local-only)

MCP servers — interdits (cloud SaaS)

Justifications inscrites dans .claude/rules/global.md :

• AGPL-3.0 non négociable — pas de couche cloud propriétaire.
• Code auto-hébergeable : la totalité du dispositif doit pouvoir tourner sans Internet.
• Raspberry Pi friendly : RAM/CPU limités, pas de runtime cloud lourd.
• Intégrité financière > performance : aucune donnée adhérent (IBAN, montants, identité) ne sort de la machine.

Hooks Claude Code

Les hooks sont définis dans .claude/settings.json. Ils contraignent Claude Code pendant la session : certaines actions sont bloquées, d'autres déclenchent des effets de bord automatiques.

Permissions — phpunit borné

L'allowlist de settings.json n'autorise jamais vendor/bin/phpunit tout court — uniquement filtré :

"Bash(vendor/bin/phpunit --testsuite=*)",
"Bash(vendor/bin/phpunit tests/*)",
"Bash(vendor/bin/phpunit --filter=*)",

Conséquence : lancer toute la suite est impossible sans permission explicite. Aligné avec la règle CLAUDE.md « Ne jamais lancer toute la suite PHPUnit ».

Procédure pour ajouter un nouveau MCP

1. Vérifier qu'il tourne 100 % local (binaire, container, ou stdio process). Aucune connexion sortante non maîtrisée.
2. Vérifier l'absence de télémétrie : strace / tcpdump sur une session de test. Si du trafic sort vers un domaine tiers, refus.
3. PR + revue : justifier l'absence d'alternative déjà autorisée. Indiquer le binaire, sa version, son repo, sa licence.
4. Mettre à jour .claude/rules/mcp-policy.md : ajouter une ligne dans le tableau « Autorisé », avec rôle et permissions.
5. Tester sur Raspberry Pi cible : si le MCP ne tient pas en RAM/CPU sur la cible self-host, refus.

Boucle dev type (slash commands)

Pour une feature côté finance, la séquence canonique est :

sequenceDiagram
    autonumber
    participant Dev
    participant Office as kohinos-office-hours
    participant TDD as tdd-coach
    participant Code as (implémentation)
    participant Solid as solid-auditor
    participant SF as symfony-best-practices-reviewer
    participant Mut as mutation-tester
    participant CL as changelog-writer
    Dev->>Office: /kohinos-office-hours
    Office-->>Dev: 6 questions YC-style
    Dev->>TDD: spec → test RED
    TDD-->>Dev: PHPUnit RED confirmé
    Dev->>Code: implémentation
    Code-->>TDD: PHPUnit GREEN
    Dev->>Solid: audit SOLID
    Dev->>SF: audit best practices
    Solid-->>Dev: notes + diff proposé
    SF-->>Dev: corrections autowiring/types
    Dev->>Mut: infection sur le service
    Mut-->>Dev: MSI ≥ 80% sur code finance
    Dev->>CL: génère CHANGELOG.md + CHANGELOG_USER.md
    CL-->>Dev: diff prêt à commit
    

Étapes :

1. /kohinos-office-hours — validation YC-style avant écriture de code.
2. /tdd-coach — produit le test RED qui décrit la spec.
3. Implémentation manuelle (Claude propose, le dev valide).
4. /solid-auditor + /symfony-best-practices-reviewer.
5. /mutation-tester — Infection MSI ≥ 80 % sur le code finance (cf. Tests & qualité).
6. /changelog-writer — met à jour les deux changelogs.
7. git commit atomique avec hook Stop qui rappelle les changelogs.

Refus automatiques (rappel .claude/rules/global.md)

Skills (slash commands locales)

Les skills de Claude Code sont packagées sous .claude/skills/. Quatre skills locales Kohinos :

• debug-issue — debug systémique d'un bug avec capture des hypothèses.
• explore-codebase — exploration ciblée avec budget de tokens borné.
• refactor-safely — refacto avec garde-fou test RED → diff → tests verts.
• review-changes — revue de code avant commit, vérifie changelogs + invariants finance + style PHP.

Voir aussi