k kh2114/claude-skills-public

Coding Harness Designer v1

« Ce qu’un agent n’a pas accompli n’est pas dû à un manque de compétence, mais à un environnement insuffisant. » — OpenAI
« Ne laissez pas le créateur évaluer son propre travail. » — Anthropic
« Quand un agent fait une erreur, ingénierisez l’environnement pour qu’il ne la reproduise plus jamais. » — Mitchell Hashimoto

Relation entre cette compétence et harness-designer

┌─────────────────────────────────────────────────────────────┐
│  Base commune : 5 piliers de conception d’un harnais          │
│  Progressive Disclosure / Mechanical Enforcement /             │
│  Feedback Loop / Session Continuity / Entropy Management       │
├──────────────────────────┬──────────────────────────────────┤
│  harness-designer (existant) │  coding-harness-designer (ceci) │
│  Espace de travail analyse/décision │  Espace de travail codage/développement │
│  Agent = rôle de point de vue      │  Agent = travailleur du code             │
│  Livrable = rapports/décisions      │  Livrable = code source/tests            │
│  Validation = checklist/discussion  │  Validation = CI/linter/tests navigateur  │
│  « conception d’une salle de réunion » │  « conception d’une chaîne de production » │
└──────────────────────────┴──────────────────────────────────┘

---

Les 7 piliers du coding harness

Aux 5 piliers existants s’ajoutent 2 piliers spécifiques au codage :

Pilier	Question clé	Principe
Progressive Disclosure	L’agent voit‑il uniquement ce dont il a besoin ?	AGENTS.md ~100 lignes → docs/
Mechanical Enforcement	L’architecture est‑elle imposée mécaniquement ?	Linter, tests structurels, CI
Feedback Loop	L’agent se corrige‑t‑il automatiquement en cas d’échec ?	Les messages d’erreur enseignent la correction
Session Continuity	Le hand‑off entre sessions est‑il net ?	progress + feature‑status + git
Entropy Management	La qualité du code se maintient‑elle dans le temps ?	Scan automatique, refactoring, note de qualité
Architectural Rigidity ← nouveau	Les frontières des modules sont‑elles imposées ?	Règles de couche, validation du sens des dépendances
Observable Runtime ← nouveau	L’agent peut‑il voir les résultats d’exécution ?	Accès aux logs, métriques, DOM, captures d’écran

---

Relation entre les deux couches

┌─────────────────────────────────────────────────────────────┐
│  COUCHE 1 : MÉTA (rôle de cette compétence)                  │
│                                                             │
│  Planner → Generator → Evaluator                            │
│     ↑        (séquentiel unidirectionnel, pas de référence inverse)     │
│     └──── Feed‑back si insuffisant ─────────────┘          │
│                                                             │
│  Objectif : concevoir, générer et valider la structure du    │
│  harnais de codage                                           │
└────────────────────────┬──────────────────────────────────┘
                         │ Validation → harnais terminé
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  COUCHE 2 : EXPLOITATION (rôle du harnais terminé)          │
│                                                             │
│  ┌ Initializer (première exécution) → échafaudage + config   │
│  │                                                          │
│  └ Agent de codage (exécution itérative) :                   │
│    1. Lire progress → choisir la tâche suivante              │
│    2. Implémenter (génération de code)                       │
│    3. Auto‑validation (tests, linter, navigateur)            │
│    4. Demander une revue (code review entre agents)          │
│    5. Appliquer le feed‑back → itérer                        │
│    6. Committer en état propre                               │
│                                                             │
│  Objectif : écrire, tester, refactorer et déployer du code   │
│  réel                                                        │
└─────────────────────────────────────────────────────────────┘

---

COUCHE 1 : MÉTA — Processus de conception du coding harness

Trois agents L1 (séquentiel unidirectionnel, pas de référence inverse)

Planner (planification)

Analyse les besoins de l’utilisateur et conçoit la structure du coding harness.

• Entrée : exigences du projet (collectées par questions)
• Sortie : conception de l’architecture + structure des dossiers + règles imposées + critères d’évaluation

Generator (construction)

Transforme le plan du Planner en fichiers et configurations réels.

• Entrée : plan approuvé par le Planner
• Sortie : AGENTS.md, docs/, règles de linter, configuration CI, structure de test

Evaluator (validation)

Valide les livrables du Generator de manière indépendante sur la base des 7 piliers.

• Entrée : fichiers générés par le Generator + critères d’évaluation du Planner
• Sortie : score par pilier + validation fonctionnelle + feed‑back d’amélioration

---

L1 Phase 0 : Pattern Match — Référence harness‑100 (nouveau v1.1)

« 99 % des bonnes conceptions ont déjà été faites par quelqu’un. Trouve‑les et adapte‑les. »

Avant le Discovery, recherche de l’exemplaire le plus proche parmi les exemplaires validés de harness‑100 (https://github.com/revfactory/harness-100, Apache‑2.0) pour l’utiliser comme référence. Pour les non‑développeurs, orientation vers la compétence harness-starter-coding.

Exemplaires cibles (27 domaines de codage)

• Dev & DevOps #16–30 : fullstack‑webapp, mobile‑app‑builder, api‑designer, database‑architect, devops‑pipeline, security‑audit, performance‑tuning, refactoring‑squad, test‑automation, monitoring‑setup, etc.
• Data & AI/ML #31–42 : ml‑experiment, data‑pipeline, rag‑llm‑app, nlp‑processor, recommendation‑engine, design‑system, etc.

Procédure de la Phase 0

1. Extraire les mots‑clés du type d’application à partir de la demande de l’utilisateur (1‑2 phrases)
2. Proposer les 3 meilleurs candidats parmi les 27 ci‑dessus + confirmation de l’utilisateur
3. Enregistrer le numéro de l’exemplaire choisi dans le champ reference_exemplar de _workspace/00_input.md
4. Similarité < 0,5 → passage en mode conception libre (poursuite avec l’ancienne Phase 1)

Application du résultat de la Phase 0 aux étapes suivantes

• Planner : utiliser la composition à 5 agents de l’exemplaire par défaut, ajuster selon le mode d’échelle (Full/Reduced/Single)
• Generator : utiliser d’abord l’échafaudage de l’exemplaire, imposer la convention de numérotation _workspace/NN_*.md
• Evaluator : utiliser les 8 critères de qualité de l’exemplaire (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) comme rubrique

Pattern Fidelity (évaluation qualitative, limitée à la Phase 0)

Ne fait pas partie de la notation automatique des 7 piliers. Évaluation qualitative lors de la correspondance avec l’exemplaire en Phase 0.

Vérifier séparément les 8 Quality Standards de l’exemplaire harness‑100 choisi en Phase 0 (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) par rapport à la notation de l’Evaluator.

• Points d’application : 1 fois lors de la Phase 0 (sélection de l’exemplaire), 1 fois lors du rapport après le PASS de l’Evaluator
• Pas de score : n’est pas inclus dans la notation des 23 items des 7 piliers
• pillar‑weight : seul l’ajustement des poids des 7 piliers est possible. La Pattern Fidelity n’est pas un élément de pondération

Trigger Boundaries (should + NOT)

Le Planner/Generator doit inclure une section should‑NOT trigger dans le fichier orchestrator skill.md généré. Exemple : « Ne pas utiliser pour les applications mobiles, les microservices d’entreprise, les sites web statiques. »

Principes de comportement de l’agent de codage (inspirés de Karpathy, injection obligatoire)

Le Generator doit inclure la section suivante à la fin du fichier .claude/CLAUDE.md généré. Ces 4 principes sont synchronisés avec la compétence karpathy‑guidelines (installée indépendamment) et constituent les instructions de base de tous les agents de codage du harnais.

## Coding Agent Behavior Principles (inspirés de Karpathy)

Tout agent de codage respecte les 4 principes suivants pendant son travail.
Voir la compétence karpathy‑guidelines pour plus de détails (déclenchement automatique).

1. Think Before Coding — Formuler des hypothèses, poser des questions en cas d’ambiguïté, proposer des alternatives
2. Simplicity First — Faire exactement ce qui est demandé. Pas d’abstraction ou de fonctionnalité spéculative
3. Surgical Changes — Modifier uniquement les lignes demandées. Ne pas améliorer le code environnant
4. Goal‑Driven Execution — Critères de succès vérifiables → boucle → confirmation

Ajouter l’élément « Présence de la section des 4 principes Karpathy dans CLAUDE.md » à la checklist de l’Evaluator.

Scale Modes (valeur par défaut de la couche d’exploitation)

Mode	Composition des agents
Full	architect + frontend + backend + qa + devops
Backend	architect + backend + qa
Frontend	architect + frontend + qa
Refactoring	architect + développeur(s) concerné(s) + qa
DevOps	devops seul

---

L1 Phase 1 : Discovery — Fonctionnement du Planner

Le Discovery se compose de 4 étapes de questions. Chaque étape se déroule dans l’ordre, les questions suivantes peuvent varier en fonction de la réponse de l’utilisateur. Passer à l’étape suivante après avoir reçu la réponse de l’étape en cours. Ne pas poser toutes les questions à la fois.

1-1. Étape 1 — Objectif et contexte (POURQUOI / QUI)

Comprendre la raison d’être du projet, pas la technologie.

P1. Quel problème ce projet cherche‑t‑il à résoudre ?
    (Quelle gêne/inefficacité cherche‑t‑on à éliminer ?)

P2. Qui l’utilise ?
    (Employés internes / Clients / Développeurs / Grand public)
    → Suivi : Combien d’utilisateurs ? Quel est leur niveau de compétence informatique ?

P3. Quel est le critère de succès de ce projet ?
    (Qu’est‑ce qui doit être vrai pour dire « bien fait » ?)

P4. Existe‑t‑il un système existant similaire ?
    (S’agit‑il d’un remplacement ou d’une création ex nihilo ?)
    → Suivi [remplacement] : Quel est le plus gros problème du système existant ?
    → Suivi [nouveau] : Y a‑t‑il un service de référence ?

Branchement des questions suivantes :

• P2 « Employés internes » → « Combien ? Y a‑t‑il une structure de service ? Un système de droits est‑il nécessaire ? »
• P2 « Clients » → « Quel est le mode d’inscription ? Y a‑t‑il un paiement ? Un traitement des données personnelles ? »
• P3 mention de chiffres concrets → « Comment ces chiffres sont‑ils mesurés ? »
• P3 réponse vague → « Concrètement, quel écran/fonctionnement serait un succès ? »

1-2. Étape 2 — Fonctionnalités et contenu (QUOI)

Ce qu’il contient, quelles sont les fonctionnalités principales.

F1. Quelles sont les 3 fonctionnalités principales, par ordre de priorité ?
    (De la plus indispensable à la moins urgente)

F2. Quelle est la nature des données ?
    (Relationnel / Document / Série temporelle / Fichier / Mixte)
    → Suivi : Les relations entre les données sont‑elles complexes ? Les agrégations/statistiques sont‑elles importantes ?

F3. Y a‑t‑il des exigences d’authentification/droits ?
    (Aucune / Simple connexion / Basé sur les rôles / Droits hiérarchiques organisationnels)
    → Suivi [basé sur les rôles ou plus] : Combien de niveaux de droits ? L’isolation des données est‑elle nécessaire ?

F4. Y a‑t‑il des intégrations avec des systèmes externes ?
    (Aucune / API / Import/export de fichiers / Paiement / Notifications)

F5. Un support hors ligne ou mobile est‑il nécessaire ?

Branchement des questions suivantes :

• F1 plus de 3 fonctionnalités → « Quelle est la complexité de chaque fonctionnalité (haute/moyenne/faible) ? »
• F2 « Mixte » → « Quels types sont mélangés ? Faut‑il séparer les stockages ? »
• F3 « Droits hiérarchiques » → « Les départements sont‑ils fréquemment ajoutés/modifiés ? L’extension doit‑elle se faire sans modification du code ? »

1-3. Étape 3 — Technologie et structure (COMMENT)

Comment le réaliser. En tenant compte des réponses des étapes 1 et 2, proposer une technologie adaptée.

T1. Avez‑vous une préférence de pile technologique ?
    (Si oui, précisez / Sinon, « recommande‑moi »)
    → Recommandation « boring technology » : les agents fonctionnent mieux avec des technologies stables et disposant de nombreuses données d’apprentissage (principe OpenAI)
    → Proposer une pile adaptée en fonction des réponses des étapes 1 et 2

T2. Quel est l’environnement de déploiement ?
    (Vercel / AWS / Serveur interne / Je ne sais pas)

T3. Quel outil d’agent de codage ?
    (Claude Code / Codex / Cursor / Autre)
    → La configuration du harnais diffère selon l’outil

T4. Quel est le niveau d’autonomie de l’agent ?
    (Merge après revue humaine / Merge automatique après revue entre agents / Totalement autonome)

T5. Quelle est la taille et la durée du projet ?
    (Prototype 1‑2 semaines / Moyen 1‑3 mois / Grand projet à long terme)

T6. Existe‑t‑il une base de code existante ?
    (Nouveau / Application du harnais à un code existant)
    → Si code existant, concevoir une stratégie d’application progressive

Branchement des questions suivantes :

• T1 « recommande‑moi » → présenter un tableau comparatif de 2‑3 options en fonction des réponses des étapes 1 et 2, puis choisir
• T2 « Je ne sais pas » → recommander en fonction de la taille des utilisateurs et des fonctionnalités
• T5 « Grand projet à long terme » → « Quelle est la taille de l’équipe ? Combien d’agents travaillent simultanément ? »

1-3.5. Étape 3.5 — Suivi de l’historique des modifications du workflow (FLOW HISTORY) [Optionnel]

Recommandé pour les projets à long terme ou susceptibles d’évoluer sur plusieurs sessions. Peut être ignoré pour les prototypes de 1‑2 semaines.

F1. « Souhaitez‑vous conserver un historique lorsque les prompts, protocoles, modèles, scripts d’API, commandes, CLAUDE.md seront modifiés à l’avenir ? »

    Utilité :
    - Rétrospective de l’historique d’amélioration du projet (pourquoi ces changements ?)
    - Base pour un éventuel rollback vers une version antérieure
    - Référence pour la conception de futurs coding harness similaires

    ※ N’est pas destiné à être lu à chaque session.
      Référencé uniquement lors de la modification, du rollback ou de l’import du workflow.

    → « Non » → ne pas inclure 05‑flow‑history/. Passer à l’étape 4.
    → « Oui » → passer à F2.

F2. « Souhaitez‑vous enregistrer automatiquement la version initiale (v1) sous forme d’enregistrement change 0001 ? »
    - Valeur par défaut : oui (les réponses du Discovery du Planner sont conservées comme justificatif de la conception)
    - Non → créer uniquement un CHANGELOG et enregistrer manuellement lors de la première modification

Principes de gestion de l’historique du workflow (après génération et en exploitation) : Cet historique enregistre uniquement les modifications du système de workflow (prompts, protocoles, modèles, scripts d’API, commandes, CLAUDE.md). Les livrables produits par le système (code, rapports, résultats d’analyse) ne sont pas enregistrés. Critère de distinction : « Sans cette modification, le résultat de la prochaine exécution serait‑il différent ? » → Oui = modification système = enregistrement / Non = livrable = pas d’enregistrement nécessaire Détails : 00‑system/protocols/flow‑change‑protocol.md

Ajout à la sortie du Planner (relatif à l’historique du workflow) :

• flow_history_enabled: true/false
• flow_history_initial_record: true/false (réponse F2)

1-4. Étape 4 — Qualité et critères d’évaluation (QUALITÉ / ÉVALUER)

Comprendre les valeurs importantes pour l’utilisateur et convenir des critères d’évaluation.

E1. Quels sont les attributs de qualité les plus importants de ce projet ? (Top 3)
    □ Sécurité (droits, isolation des données, authentification)
    □ Performance (temps de réponse, connexions simultanées)
    □ Extensibilité (passage à l’échelle sans modification du code)
    □ Maintenabilité (facilité de modification par d’autres personnes/agents)
    □ Expérience utilisateur (UI intuitive, réactivité)
    □ Testabilité (assurance qualité par des tests automatisés)
    □ Mise sur le marché rapide (MVP d’abord, la qualité viendra plus tard)
    □ Cohérence des données (enregistrement précis, pas de perte)

E2. Y a‑t‑il des plans d’extension futurs ?
    (Aucun / Ajout de fonctionnalités / Intégration avec d’autres systèmes / Augmentation du nombre d’utilisateurs)
    → Suivi : Quelle extension concrètement ? Quand ?

E3. Qu’est‑ce qui ne doit en aucun cas être compromis dans ce projet ?
    (Exemple : « L’isolation des droits ne doit pas être compromise », « Les données ne doivent pas être perdues »)

E4. Au contraire, qu’est‑ce qui peut être absent dans un premier temps ?
    (Exemple : « L’adaptation mobile peut attendre », « Le tableau de bord statistique est pour la phase 2 »)

Branchement des questions suivantes :

• E1 « Sécurité » → « Quel type de sécurité ? Authentification/droits/chiffrement des données/journaux d’audit ? »
• E2 « Intégration avec d’autres systèmes » → « Quel système ? Le format de données est‑il compatible ? »
• Réponse à E3 → utilisée comme entrée clé pour la pondération de l’Evaluator

1-5. Accord sur la pondération (après la fin de l’étape 4)

Analyser les réponses des étapes 1 à 4 pour proposer les poids des 7 piliers. Conviennent avec l’utilisateur pour finalisation.

[PROCESSUS DE PROPOSITION DE PONDÉRATION]

ÉTAPE 1. Extraire les mots‑clés des réponses des étapes 1 à 4
  - « Isolation des droits » → Mechanical Enforcement, Architectural Rigidity ↑
  - « Extension sans modification du code » → Architectural Rigidity ↑
  - « Mise sur le marché rapide » → Entropy Management ↓, Observable Runtime ↑
  - « Cohérence des données » → Feedback Loop ↑, Mechanical Enforcement ↑

ÉTAPE 2. Proposer un ajustement par rapport aux poids de base

  Poids de base (avant prise en compte des caractéristiques du projet) :
  | Pilier | Base | Justification de l’ajustement | Proposition |
  |--------|------|-------------------------------|-------------|
  | Progressive Disclosure | 15% | (motif de variation) | ?% |
  | Mechanical Enforcement | 20% | (motif de variation) | ?% |
  | Feedback Loop | 15% | (motif de variation) | ?% |
  | Session Continuity | 10% | (motif de variation) | ?% |
  | Entropy Management | 10% | (motif de variation) | ?% |
  | Architectural Rigidity | 20% | (motif de variation) | ?% |
  | Observable Runtime | 10% | (motif de variation) | ?% |

  « Pour ce projet, compte tenu de [justification],
   nous avons ajusté le poids de [pilier] de [base]% → [proposition]%.
   N’hésitez pas à donner votre avis ou à suggérer des modifications. »

ÉTAPE 3. Prendre en compte les retours de l’utilisateur
  - Accord → validation
  - « Augmente encore la sécurité » → augmenter le poids du pilier concerné, diminuer les autres, puis reproposer
  - « Ce pilier n’est pas nécessaire » → le mettre à 0 %, redistribuer le reste, puis reproposer

ÉTAPE 4. Validation finale
  « Poids final validé. L’Evaluator notera avec ces poids. »
  → Utiliser ces poids convenus au lieu des poids par défaut du fichier evaluator‑protocol.md

1-6. Mapping automatique des patterns d’architecture

→ Voir references/architecture‑patterns.md → Proposer le pattern le plus adapté en fonction des réponses des étapes 2 et 3

Type d’application	Structure de couche recommandée
Application web full‑stack	Types→Config→Repo→Service→Runtime→UI
Service API	Types→Config→Repo→Service→Runtime
Outil CLI	Types→Config→Core→CLI
Bibliothèque	Types→Core→Public API

1-7. Livrables du Planner

① Résumé du contexte du projet — Objectif, utilisateurs, critères de succès, contraintes clés (basé sur les étapes 1 et 2) ② Plan d’architecture — Structure des couches, frontières des modules, sens des dépendances ③ Ébauche de la structure des dossiers — Basé sur references/coding‑folder‑patterns.md ④ Conception des règles imposées — Quelles règles sont imposées par le linter/CI/tests structurels ⑤ Stratégie de test — Portée des tests unitaires/intégration/E2E et critères de couverture ⑥ Conception de l’autonomie de l’agent — Boucle de revue, passerelles d’approbation, critères d’escalade ⑦ Stratégie d’extension — Décisions de conception en prévision d’extensions futures (basé sur l’étape 4 E2) ⑧ Critères d’évaluation + poids convenus — Checklist des 7 piliers + tableau des poids

[Planner terminé — Demande d’approbation de l’utilisateur]
Veuillez examiner les points ① à ⑧ et me faire part de vos modifications.
Une fois approuvé, le Generator commencera la construction.

---

L1 Phase 2 : Build — Fonctionnement du Generator

2-1. Génération des livrables clés (dans l’ordre)

Ordre	Livrable	Description
2‑1a	Diagramme d’architecture	Mermaid — Couches, modules, sens des dépendances
2‑1b	AGENTS.md (~100 lignes)	Table des matières, inclut le routage des références
2‑1c	Répertoire docs/	Détail ci‑dessous
2‑1d	Règles d’imposition de l’architecture	Règles de linter + tests structurels
2‑1e	Conception du pipeline CI/CD	Définition des passerelles de validation
2‑1f	Structure de test	Répertoire de test + configuration de base
2‑1g	Livrables de hand‑off de session	progress.json + feature‑status.json
2‑1h	Configuration de la boucle de code review	Protocole de revue entre agents
2‑1i	Configuration de l’observabilité	Accès aux logs, métriques, DOM
2‑1j	README.md	Guide du développeur
2‑1k	Initialisation du projet bkit	Exécuté uniquement après une question opt‑in de l’utilisateur si T3 détecte Claude Code + bkit installé (détail ci‑dessous)
2‑1l	Configuration de l’environnement	Environnement virtuel, variables d’environnement, hooks — pas de création forcée. Proposition par LLM après la Phase 3‑7, choix de l’utilisateur
2‑1m	Wiki de l’historique des modifications du workflow (optionnel)	Uniquement si F1 de l’étape 3.5 = oui. Voir ~/.claude/skills/harness‑designer‑workspace/references/flow‑history‑template.md pour créer 05‑flow‑history/ + 00‑system/protocols/flow‑change‑protocol.md. Ajouter 2 lignes de routage + section « Suivi des modifications du workflow (enregistrement sélectif) » à AGENTS.md. Principe de gestion : enregistrer uniquement les changements système (règles, procédures, outils). Les livrables (code, rapports) ne sont pas enregistrés. Critère de distinction : « Sans cette modification, le résultat de la prochaine exécution serait‑il différent ? »

2-1b. Règles d’écriture d’AGENTS.md (le plus important)

→ Voir references/agents‑md‑template.md

Appliquer directement les leçons clés du principe OpenAI :

~100 lignes, table des matières. Pas une encyclopédie.

# [Nom du projet]

> [Description en une ligne]

## Aperçu de l’architecture
[Résumé de la structure des couches en 3 lignes]
→ Détail : docs/architecture.md

## Routage des références
| Situation | Fichier à lire |
|-----------|----------------|
| Règles d’architecture | → docs/architecture.md |
| Conventions de codage | → docs/conventions.md |
| Conception du domaine | → docs/design/[domain].md |
| Plans d’exécution | → docs/exec‑plans/[plan].md |
| Note de qualité | → docs/quality‑grades.md |
| Dette technique | → docs/exec‑plans/tech‑debt‑tracker.md |
| État de session | → progress.json |
| État des fonctionnalités | → feature‑status.json |

## Règles clés (5 au maximum)
1. [Règle immuable 1 — Exemple : « Valider la forme des données à toutes les frontières »]
2. [Règle immuable 2 — Exemple : « Interdire les dépendances en sens inverse des couches »]
3. [Règle immuable 3]

## Règles de test
→ docs/testing‑strategy.md

## Commandes
| Commande | Fonction |
|----------|----------|
| /implement [fonctionnalité] | Implémenter une fonctionnalité |
| /review | Exécuter une revue de code |
| /test | Exécuter les tests |
| /refactor [cible] | Refactorer |

## Dernière mise à jour : AAAA‑MM‑JJ

2-1c. Répertoire docs/ (System of Record)

→ Voir references/docs‑structure.md

docs/
├── architecture.md         ← Structure des couches, frontières des modules, sens des dépendances
├── conventions.md          ← Conventions de codage, nommage, format
├── design/                 ← Documentation de conception détaillée
│   └── [domain].md
├── exec‑plans/             ← Plans d’exécution détails
│   ├── [plan].md
│   └── tech‑debt‑tracker.md
├── testing‑strategy.md     ← Stratégie de test
├── quality‑grades.md       ← Grille de qualité
├── ci‑pipeline.md          ← Pipeline CI/CD
└── decisions.md            ← Journal des décisions de conception (ADR)

2-1d. Règles d’imposition de l’architecture

→ Voir references/enforcement‑rules.md

Cibler les 3 à 5 règles les plus critiques pour le projet.

Exemples :

• Règle de couche (ex. : Interdire l’import direct Service → UI)
• Règle d’isolation des données (ex. : Interdire les requêtes SQL directes dans le code métier)
• Règle de gestion des erreurs (ex. : Tous les appels externes doivent avoir un try/catch)
• Règle d’immuabilité (ex. : Les types partagés sont dans types/, pas de duplication)
• Règle de test (ex. : Toute fonction publique doit avoir un test unitaire)

Chaque règle doit être :

1. Applicable automatiquement (linter, CI, test structurel)
2. Auditable (message d’erreur clair, suggestion de correction)
3. Contournable uniquement par décision explicite (commentaire // override approuvé)

2-1e. Conception du pipeline CI/CD

→ Voir references/ci‑pipeline‑template.md

Structure de base :

┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│  Lint    │ → │  Test    │ → │  Build   │ → │  Review  │ → │  Deploy  │
└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
     │              │              │              │
     ▼              ▼              ▼              ▼
  Échec →        Échec →       Échec →        Échec →
  rapport        rapport       rapport         rapport

Définir les éléments suivants :

• Gatings d’approbation (ex. : nombre minimum de revues, temps d’attente)
• Pas de merge tant que les tests ne passent pas
• Notifications en cas d’échec
• Règles de déploiement automatique/environnement de staging

2-1f. Structure de test

→ Voir references/test‑structure.md

Structure de base :

tests/
├── unit/              ← Tests unitaires (par module)
│   └── [module]/
├── integration/       ← Tests d’intégration (inter‑modules)
├── e2e/               ← Tests de bout en bout (système complet)
├── fixtures/          ← Données de test
└── helpers/           ← Utilitaires de test

Configurations de test de base :

• Fichier de configuration (jest.config.ts, vitest.config.ts, etc.)
• Scripts de test (package.json)
• Couverture minimale (ex. : 80 %)

2-1g. Livrables de hand‑off de session

Fichiers JSON pour la continuité entre les sessions.

progress.json :

{
  "current_phase": "Phase 2",
  "tasks_completed": ["architecture", "AGENTS.md"],
  "next_task": "docs/architecture.md",
  "blockers": [],
  "last_updated": "AAAA-MM-DDTHH:MM:SSZ"
}

feature‑status.json :

{
  "features": [
    {
      "name": "authentification",
      "status": "in_progress",
      "tests": "passing",
      "last_reviewed": "AAAA-MM-DD"
    }
  ]
}

Règle : Le premier agent d’une nouvelle session doit lire progress.json et feature‑status.json avant de commencer.

2-1h. Configuration de la boucle de code review

→ Voir references/code‑review‑protocol.md

Procédure de base de la revue entre agents :

1. L’agent A termine la tâche A
2. L’agent A crée une PR (ou commit sur sa branche)
3. L’agent B (reviewer) examine le code
   • Vérifie les règles de couche
   • Vérifie les tests
   • Vérifie les conventions
   • Évalue la qualité du code
4. L’agent B envoie ses commentaires (suggestion de modification / approbation)
5. L’agent A modifie (ou justifie) et repasse en revue
6. Après validation, merge (ou passe à l’étape suivante)

Critères d’escalade : Si la revue de l’agent A et de l’agent B n’aboutit pas à un accord pendant plus de 2 cycles, escaladez vers le Planner (ou l’humain).

2-1i. Configuration de l’observabilité

→ Voir references/observability‑config.md

Définir :

• Logs : Niveau de log, format, destination (stdout, fichier, service externe)
• Métriques : Métriques clés (temps de réponse, taux d’erreur, etc.) + exposition
• Accès DOM : Pour le développement frontend, capture d’écran ou inspection DOM
• Scripts d’observation : Scripts pour collecter les résultats

Principe : L’agent doit pouvoir vérifier immédiatement le résultat de son action.

2-1j. README.md

→ Voir references/readme‑template.md

Contenu standard :

• Nom du projet et description
• Prérequis
• Installation
• Méthode d’exécution
• Structure du projet
• Commandes (y compris les commandes agents)
• Comment contribuer
• Licence

---

L1 Phase 3 : Validate — Fonctionnement de l’Evaluator

3-1. Évaluation sur la base des 7 piliers (notation automatique)

Vérifier chaque pilier selon les critères suivants et attribuer une note sur 5 (0 = non satisfait, 5 = parfait). Utiliser les poids convenus (accord de l’étape 1‑5) pour calculer le score total.

[Pilier 1] Progressive Disclosure (poids : ?%)

N°	Critère	Note /5	Commentaire
1	AGENTS.md fait‑il environ 100 lignes et sert‑il de table des matières ? (pas un manuel)
2	AGENTS.md contient‑il le routage vers les fichiers détaillés ?
3	Le contenu des fichiers détaillés est‑il bien structuré et lisible ?
4	La documentation permet‑elle une compréhension rapide du projet ?
5	Le niveau de détail est‑il adapté (pas trop verbeux, sans manquer l’essentiel) ?

[Pilier 2] Mechanical Enforcement (poids : ?%)

N°	Critère	Note /5	Commentaire
6	Des règles de linter pour l’architecture sont‑elles définies ?
7	Existe‑t‑il des tests structurels qui vérifient les dépendances entre les couches ?
8	Le pipeline CI inclut‑il une étape de validation de l’architecture ?
9	La non‑conformité se traduit‑elle par un message d’erreur clair avec suggestion de correction ?
10	Les règles sont‑elles évaluables automatiquement sans intervention humaine ?

[Pilier 3] Feedback Loop (poids : ?%)

N°	Critère	Note /5	Commentaire
11	Les tests échoués guident‑ils l’agent vers une correction (message utile) ?
12	Existe‑t‑il un processus de revue de code entre agents ?
13	Le retour de l’Evaluator est‑il structuré et exploitable par les agents ?
14	Le cycle « essai → erreur → correction » est‑il automatisé ?
15	Existe‑t‑il un processus d’escalade en cas d’absence de correction après un nombre défini d’itérations ?

[Pilier 4] Session Continuity (poids : ?%)

N°	Critère	Note /5	Commentaire
16	progress.json est‑il mis à jour automatiquement à chaque fin de tâche ?
17	feature‑status.json reflète‑t‑il l’état réel de chaque fonctionnalité ?
18	Le premier agent d’une nouvelle session lit‑il ces deux fichiers avant de commencer ?
19	L’historique des commits est‑il structuré et clair ?
20	Les décisions de conception sont‑elles documentées et accessibles (ADR) ?

[Pilier 5] Entropy Management (poids : ?%)

N°	Critère	Note /5	Commentaire
21	Existe‑t‑il une grille d’évaluation de la qualité du code (quality‑grades.md) ?
22	La note de qualité est‑elle évaluée périodiquement ou à chaque étape clé ?
23	Existe‑t‑il un mécanisme de refactoring automatique (ou semi‑automatique) ?
24	Le suivi de la dette technique est‑il documenté (tech‑debt‑tracker.md) ?
25	La qualité se dégrade‑t‑elle visiblement sans que personne ne la remarque ? (évaluer si le suivi manque)

[Pilier 6] Architectural Rigidity (poids : ?%)

N°	Critère	Note /5	Commentaire
26	Les règles de couche (sens des dépendances) sont‑elles clairement définies ?
27	Les frontières des modules sont‑elles clairement documentées ?
28	La violation des frontières des modules est‑elle détectée automatiquement (linter, test) ?
29	L’introduction d’une nouvelle dépendance entre modules nécessite‑t‑elle une approbation ?
30	La structure des dossiers reflète‑t‑elle l’architecture (pas de dossiers vs architecture incohérents) ?

[Pilier 7] Observable Runtime (poids : ?%)

N°	Critère	Note /5	Commentaire
31	L’agent peut‑il vérifier immédiatement le résultat de son action (log, sortie standard, etc.) ?
32	Les logs sont‑ils structurés et contiennent‑ils des informations exploitables par un agent ?
33	L’état du runtime (métriques, état des processus) est‑il accessible aux agents ?
34	Existe‑t‑il un mécanisme pour capturer et analyser les échecs d’exécution (capture d’écran, stack trace) ?
35	Les informations d’observabilité sont‑elles utilisées dans la boucle de feedback (amélioration par les agents) ?

3-2. Notation et rapport

Calcul du score total :

Score total = Σ (note_pilier_i × poids_i / 100)
Note_pilier_i = (somme des notes de chaque question du pilier) / (nombre de questions × 5) × 100

Seuils d’évaluation :

• 90‑100 : Parfait. HARNAIS VALIDÉ ✅
• 70‑89 : Acceptable. VALIDÉ, mais avec des suggestions d’amélioration ⚠️
• 50‑69 : Insuffisant. NON VALIDÉ, nécessite une refonte partielle 🔄
• 0‑49 : Échec. NON VALIDÉ, nécessite une refonte complète ❌

Structure du rapport :

1. Score total + conclusion (VALIDÉ / NON VALIDÉ)
2. Scores par pilier (tableau)
3. Forces et faiblesses (par pilier)
4. Propositions d’amélioration (10 maximum, par ordre de priorité)
5. Commentaires de la Pattern Fidelity (le cas échéant)

3-3. Validation fonctionnelle

En plus de la notation basée sur les piliers, effectuer une validation fonctionnelle de base du livrable :

• Les fichiers essentiels (AGENTS.md, docs/, CI, etc.) sont‑ils tous générés ?
• Les chemins sont‑ils cohérents entre eux ?
• Les règles de linter sont‑elles syntaxiquement valides ?
• Le plan de test est‑il réalisable ?

3-4. Résultat et boucle de feedback

• Si VALIDÉ : Le harnais est terminé, passe en Couche 2 (exploitation) 🔄
• Si NON VALIDÉ : Envoyer le feedback au Planner pour refonte, répéter depuis la Phase 1 ou 2

---

COUCHE 2 : EXPLOITATION — Utilisation du coding harness terminé

Rôles et fonctionnement

Initializer (première exécution)

Configuration initiale du projet

1. Exécuter la commande de génération de l’architecture → générer l’échafaudage du projet
2. Installer les dépendances (npm, pip, etc.)
3. Exécuter la configuration initiale du linter/CI
4. Créer les données/dossiers initiaux
5. Effectuer une construction de vérification (build ou test de base)
6. Enregistrer l’état initial dans progress.json

Coding Agent (exécution itérative)

Cycle de développement réel

Étape 1 : Lire progress / feature‑status

• Vérifier l’état d’avancement et la tâche suivante

Étape 2 : Implémenter

• Écrire le code (génération, modification)
• Suivre les règles de l’architecture (couches, dépendances)
• Respecter les principes Karpathy (Think, Simplicity, Surgical, Goal‑Driven)

Étape 3 : Auto‑validation

• Exécuter les tests unitaires
• Exécuter le linter
• Vérification de base de l’interface (si frontend)
• Valider le respect des règles d’architecture

Étape 4 : Demander une revue

• Assigner un autre agent (ou reviewer humain) pour la revue de code
• Attendre l’approbation ou les commentaires

Étape 5 : Appliquer le feedback

• Modifier selon les commentaires
• Re‑exécuter les tests
• Répéter les étapes 3 à 5 jusqu’à approbation

Étape 6 : Committer

• Committer avec un message structuré
• Mettre à jour progress.json et feature‑status.json
• (Si l’étape est terminée) Mettre à jour l’état

---

Références et ressources connexes

Fichiers de mappage de patterns

Fichier	Emplacement	Contenu
Architecture Patterns	references/architecture‑patterns.md	Mapping type d’application → structure de couches
Coding Folder Patterns	references/coding‑folder‑patterns.md	Structure des dossiers par type
AGENTS.md Template	references/agents‑md‑template.md	Modèle de rédaction d’AGENTS.md
Docs Structure	references/docs‑structure.md	Structure recommandée de docs/
Enforcement Rules	references/enforcement‑rules.md	Exemples et principes des règles imposées
CI Pipeline Template	references/ci‑pipeline‑template.md	Conception du pipeline CI de base
Test Structure	references/test‑structure.md	Structure des dossiers de test
Code Review Protocol	references/code‑review‑protocol.md	Procédure de revue entre agents
Observability Config	references/observability‑config.md	Configuration de l’observabilité
README Template	references/readme‑template.md	Modèle de README

Compétences connexes

Compétence	Rôle
harness‑designer	Conception d’harnais de workspace d’analyse/décision (basé sur les 5 piliers)
karpathy‑guidelines	Installation et synchronisation des 4 principes de comportement des agents de codage
harness‑starter‑coding	Version simplifiée du coding harness pour non‑développeurs

---

Annexe : Structure des dossiers du coding harness (exemple)

mon‑projet/
├── .claude/
│   └── CLAUDE.md                 ← Fichier de configuration principal de l’agent Claude
├── AGENTS.md                     ← Table des matières, routage des références
├── docs/
│   ├── architecture.md           ← Architecture (couches, modules, dépendances)
│   ├── conventions.md            ← Conventions de codage
│   ├── design/
│   │   └── [domaine].md          ← Documentation de conception détaillée
│   ├── exec‑plans/
│   │   ├── [plan].md             ← Plans d’exécution
│   │   └── tech‑debt‑tracker.md  ← Suivi de la dette technique
│   ├── testing‑strategy.md       ← Stratégie de test
│   ├── quality‑grades.md         ← Grille d’évaluation de la qualité
│   ├── ci‑pipeline.md            ← Configuration CI/CD
│   └── decisions.md              ← Journal des décisions de conception (ADR)
├── references/                   ← Fichiers de mapping de patterns (copiés séparément)
├── tests/
│   ├── unit/
│   ├── integration/
│   ├── e2e/
│   ├── fixtures/
│   └── helpers/
├── src/                          ← Code source (structure variable selon le projet)
├── progress.json                 ← État d’avancement (lecture en début de session)
├── feature‑status.json           ← État des fonctionnalités (lecture en début de session)
├── 05‑flow‑history/             ← Historique des modifications du workflow (optionnel)
│   ├── 0001‑init.md
│   ├── 0002‑update‑prompts.md
│   └── …
├── 00‑system/
│   └── protocols/
│       └── flow‑change‑protocol.md ← Protocole de suivi des modifications du workflow
├── package.json (ou pyproject.toml etc.)
├── tsconfig.json (ou équivalent)
├── .eslintrc.js (ou équivalent)
├── .github/
│   └── workflows/
│       └── ci.yml               ← Configuration CI (GitHub Actions)
└── README.md

---

Log des modifications

Version	Date	Modifications
v1.0	–	Version initiale
v1.1	–	Ajout de la Phase 0 Pattern Match, des 2 nouveaux piliers, de la règle Trigger Boundaries, des principes Karpathy, de la structure docs/ et AGENTS.md améliorée, de l’étape 3.5 Flow History, du protocole de notation de l’Evaluator (35 items)