docs: add Profile-Based Module Assembly pattern (Section 3.5)
- Section 3.5 "Team Configuration at Scale" in ultimate-guide.md: profiles YAML + shared modules + skeleton + assembler script; 59% context token reduction measured on 5-dev production team; includes CI drift detection, 5-step replication guide, trade-offs - New workflow: guide/workflows/team-ai-instructions.md (6 phases, scaling thresholds, troubleshooting table) - New templates: examples/team-config/ (profile-template.yaml, claude-skeleton.md, sync-script.ts) - reference.yaml: 9 new entries for team_ai_instructions_* - README: templates count 161 → 164, date Feb 19 → Feb 20 - CHANGELOG [Unreleased]: resource evaluations (AGENTS.md ETH Zürich 4/5, Sylvain Chabaud 3/5), spec-first Task Granularity section, methodologies ATDD expansion Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
146d15e958
commit
6d847d24de
14 changed files with 1528 additions and 14 deletions
58
CHANGELOG.md
58
CHANGELOG.md
|
|
@ -6,6 +6,64 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
/- **Resource evaluation**: "Evaluating AGENTS.md" — ETH Zürich arXiv 2602.11988 (score 4/5)
|
||||
- First empirical study on repository-level context files (AGENTS.md/CLAUDE.md) effectiveness
|
||||
- Developer-written context files: **+4% agent success rate**; LLM-generated: **-3%** vs no context file
|
||||
- Inference cost penalty: **+20-23% in all cases** when file contains non-essential information
|
||||
- Mechanism: agents follow all instructions faithfully, even irrelevant ones → broader exploration, longer reasoning chains
|
||||
- Recommendation: include only build/test commands + project-specific tooling; style guides → separate docs
|
||||
- Benchmark: AGENTbench (138 instances, 12 repos) + SWE-bench Lite; 4 coding agents (Claude Code, Codex, Qwen Code)
|
||||
- Source: Gloaguen, Mündler, Müller, Raychev, Vechev — ETH Zürich, February 2026
|
||||
- Evaluation archived: `docs/resource-evaluations/agents-md-empirical-study-2602-11988.md`
|
||||
|
||||
### Changed
|
||||
|
||||
- `guide/ultimate-guide.md`: Added empirical research backing to CLAUDE.md Token-Saving Techniques section (~l.13393-13411)
|
||||
- New callout: context files with non-essential info add +20-23% inference cost regardless of line count (Gloaguen et al., 2026)
|
||||
- New research note after "Keep CLAUDE.md concise" best practice: +4% (dev-written) / -3% (LLM-generated) with mechanism explanation and tooling recommendation
|
||||
|
||||
- `guide/workflows/spec-first.md`: New "Task Granularity" section — vertical slices + PRD quality checklist
|
||||
- Vertical slice definition: thin, end-to-end unit for exactly one user behavior; one agent session = one slice
|
||||
- 6-dimension PRD quality checklist (Problem Clarity, Testable Criteria, Scope Boundaries, Observable Done, Requirements Clarity, Terminology)
|
||||
- Concrete example: over-scoped task vs properly-sized vertical slice
|
||||
- Inspired by Allan Hill (Fractional CTO) — [evaluation](docs/resource-evaluations/2026-02-19-allanhillgeek-decomposition-agentic-dev.md) (3/5)
|
||||
|
||||
- `guide/methodologies.md`: Expanded ATDD section with agentic application
|
||||
- Added 3-step agent workflow: Gherkin → failing tests → implementation
|
||||
- Gherkin example for "password reset" feature
|
||||
- Practical note: how to pass Gherkin file to Claude Code as task contract
|
||||
|
||||
- `machine-readable/reference.yaml`: 3 new index entries (`spec_task_granularity`, `spec_prd_checklist`, `atdd_with_agents`)
|
||||
|
||||
- **Resource evaluation**: Sylvain Chabaud — Spec-to-Code Factory (score 3/5)
|
||||
- Pipeline multi-agents BREAK→MODEL→ACT→DEBRIEF avec 6 gates de validation outillées (Node.js)
|
||||
- Invariants "No Spec No Code" + "No Task No Commit" enforced via hooks — pattern d'enforcement non documenté dans le guide
|
||||
- Budget token transparent par phase (~900K total) — estimation concrète unique dans l'écosystème
|
||||
- Mention ajoutée dans `guide/methodologies.md` (tableau SDD Tools) et `guide/workflows/spec-first.md` (See Also)
|
||||
- Évaluation archivée : `docs/resource-evaluations/sylvain-chabaud-spec-to-code-factory.md`
|
||||
|
||||
- **New Section 3.5**: Team Configuration at Scale — Profile-Based Module Assembly pattern
|
||||
- Covers N×M×P fragmentation problem (N devs × M tools × P OS) with modular solution
|
||||
- Architecture: profiles YAML + shared modules + skeleton template + TypeScript assembler script
|
||||
- Measured results: 59% context token reduction (380 → 185 lines avg, 5-dev production team)
|
||||
- CI drift detection via GitHub Actions daily check
|
||||
- 5-step replication guide + trade-offs table (when NOT to use)
|
||||
- Inserted between Section 3.4 (Precedence Rules) and Section 4 (Agents)
|
||||
|
||||
- **New workflow**: `guide/workflows/team-ai-instructions.md` — step-by-step setup guide
|
||||
- 6 phases: Audit → Extract Modules → Create Profiles → Assembler Script → CI Integration → Onboarding
|
||||
- Scaling thresholds: 1-2 devs (shared CLAUDE.md) → 3-5 (modules only) → 5+ (full profile assembly)
|
||||
- Troubleshooting table for common issues
|
||||
|
||||
- **New templates**: `examples/team-config/` — ready-to-use Profile-Based Assembly templates
|
||||
- `profile-template.yaml`: developer profile with core + conditional modules
|
||||
- `claude-skeleton.md`: CLAUDE.md template with `{{MODULE:*}}` and `{{#if}}` placeholders
|
||||
- `sync-script.ts`: TypeScript assembler with module resolution, conditional blocks, drift detection
|
||||
|
||||
- **reference.yaml**: 9 new entries for `team_ai_instructions_*` (section, workflow, templates, pattern, token savings)
|
||||
|
||||
## [3.27.8] - 2026-02-19
|
||||
|
||||
### Added
|
||||
|
|
|
|||
14
README.md
14
README.md
|
|
@ -8,7 +8,7 @@
|
|||
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
|
||||
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Feb_19,_2026_·_v3.27.8-brightgreen?style=for-the-badge" alt="Last Update"/></a>
|
||||
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-274_questions-orange?style=for-the-badge" alt="Quiz"/></a>
|
||||
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-161-green?style=for-the-badge" alt="Templates"/></a>
|
||||
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-164-green?style=for-the-badge" alt="Templates"/></a>
|
||||
<a href="./guide/security-hardening.md"><img src="https://img.shields.io/badge/🛡️_Threat_DB-19_CVEs_·_655_malicious_skills-red?style=for-the-badge" alt="Threat Database"/></a>
|
||||
</p>
|
||||
|
||||
|
|
@ -50,7 +50,7 @@ Both guides serve different needs. Choose based on your priority.
|
|||
| **Security hardening** | Only threat database (18 CVEs) | Basic patterns only |
|
||||
| **Test understanding** | 274-question quiz | Not available |
|
||||
| **Methodologies** (TDD/SDD/BDD) | Full workflow guides | Not covered |
|
||||
| **Copy-paste ready** templates | 161 templates | 200+ templates |
|
||||
| **Copy-paste ready** templates | 164 templates | 200+ templates |
|
||||
|
||||
### Ecosystem Positioning
|
||||
|
||||
|
|
@ -136,7 +136,7 @@ graph LR
|
|||
root[📦 Repository<br/>Root]
|
||||
|
||||
root --> guide[📖 guide/<br/>19K lines]
|
||||
root --> examples[📋 examples/<br/>161 templates]
|
||||
root --> examples[📋 examples/<br/>164 templates]
|
||||
root --> quiz[🧠 quiz/<br/>274 questions]
|
||||
root --> tools[🔧 tools/<br/>utils]
|
||||
root --> machine[🤖 machine-readable/<br/>AI index]
|
||||
|
|
@ -166,7 +166,7 @@ graph LR
|
|||
│ ├─ mcp-servers-ecosystem.md Official & community MCP servers
|
||||
│ └─ workflows/ Step-by-step guides
|
||||
│
|
||||
├─ 📋 examples/ 161 Production Templates
|
||||
├─ 📋 examples/ 164 Production Templates
|
||||
│ ├─ agents/ 6 custom AI personas
|
||||
│ ├─ commands/ 26 slash commands
|
||||
│ ├─ hooks/ 31 hooks (bash + PowerShell)
|
||||
|
|
@ -268,7 +268,7 @@ Complete guides with rationale and examples:
|
|||
|
||||
---
|
||||
|
||||
### 📚 161 Annotated Templates
|
||||
### 📚 164 Annotated Templates
|
||||
|
||||
**Outcome**: Learn patterns, not just configs.
|
||||
|
||||
|
|
@ -657,7 +657,7 @@ Use this guide critically. Experiment. Share what works for you.
|
|||
| **[Claude Code Releases](./guide/claude-code-releases.md)** | Official release history | 10 min |
|
||||
|
||||
<details>
|
||||
<summary><strong>Examples Library</strong> (161 templates)</summary>
|
||||
<summary><strong>Examples Library</strong> (164 templates)</summary>
|
||||
|
||||
**Agents** (6): [code-reviewer](./examples/agents/code-reviewer.md), [test-writer](./examples/agents/test-writer.md), [security-auditor](./examples/agents/security-auditor.md), [refactoring-specialist](./examples/agents/refactoring-specialist.md), [output-evaluator](./examples/agents/output-evaluator.md), [devops-sre](./examples/agents/devops-sre.md) ⭐
|
||||
|
||||
|
|
@ -775,7 +775,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
|
|||
|
||||
---
|
||||
|
||||
*Version 3.27.8 | Updated daily · Feb 19, 2026 | Crafted with Claude*
|
||||
*Version 3.27.8 | Updated daily · Feb 20, 2026 | Crafted with Claude*
|
||||
|
||||
<!-- SEO Keywords -->
|
||||
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
|
||||
|
|
|
|||
|
|
@ -0,0 +1,147 @@
|
|||
# Resource Evaluation: Allan Hill - "The Real Secret to Agentic Development is Small PRDs and Vertical Slices"
|
||||
|
||||
**Source**: https://www.linkedin.com/pulse/real-secret-agentic-development-small-prds-vertical-slices-allan-hill-puihc/
|
||||
**LinkedIn post**: https://www.linkedin.com/posts/allanhillgeek_ai-is-the-easy-part-decomposition-is-the-activity-7430210715606556672-HHa6/
|
||||
**Author**: Allan Hill (@allanhillgeek), Fractional CTO
|
||||
**Type**: LinkedIn Pulse article (opinion + architecture walkthrough)
|
||||
**Published**: ~Early 2026 (exact date not shown)
|
||||
**Evaluation Date**: 2026-02-19
|
||||
**Evaluator**: Claude Sonnet 4.6
|
||||
**Challenger**: general-purpose agent (ac79d16)
|
||||
**Score**: **3/5** (Pertinent — intégration ciblée, pas fichier dédié)
|
||||
|
||||
---
|
||||
|
||||
## 📄 Summary
|
||||
|
||||
Allan Hill describes a production agentic development pipeline built around the thesis that decomposition discipline matters more than AI sophistication:
|
||||
|
||||
- **Core thesis**: "AI is the easy part. Decomposition is the hard part." — The bottleneck in agentic development is breaking work into AI-digestible units before handing to agents, not prompt optimization
|
||||
- **Key unit of work**: Vertical Slice — thin, end-to-end feature through all stack layers for one complete user behavior (e.g. "password reset via email"); ideal for agents because clear boundaries → reviewable PR
|
||||
- **3-phase pipeline**: Phase 0 (PM agents produce Small PRDs with 6-dimension quality review) → Phase 1 (Orchestrator decomposes PRD into ordered independent slices, human Slack approval required) → Phase 2 (per-slice: Gherkin scenarios → ATDD → implementation → PR)
|
||||
- **Infrastructure**: Multipass VMs (1 per ticket), Node.js dispatcher polling GitHub API every 60s, deterministic CI (ESLint/Playwright/SonarQube) + AI CI (5 parallel review agents via GitHub Actions)
|
||||
- **Open challenges acknowledged**: resume state fragility, Boy Scout Rule vs PR scope balance, review agent false positive tuning
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Score: 3/5 — Pertinent, intégration ciblée
|
||||
|
||||
### Justification
|
||||
|
||||
**Arguments for 3 (not 4):**
|
||||
- Pipeline too tightly coupled to specific stack (Multipass/GCP/Jira/Slack) → ~80% must be rewritten for generic use; low reuse
|
||||
- No production metrics: no cycle time data, defect rates, throughput — it's architectural storytelling, not validated case study
|
||||
- Core concepts (vertical slices, decomposition-first) originate in Agile literature (Dan North BDD 2003, David Hussman) — this is Agile applied to AI agents, not novel theory
|
||||
- Open challenges are unresolved (resume state fragility, false positive tuning) — documenting unstable practices as reference is risky
|
||||
- Claude Code is not explicitly mentioned; author uses "agents" generically — mapping to the guide is indirect
|
||||
|
||||
**Arguments against 5 (confirmed gaps are real but not critical):**
|
||||
- Gap "task decomposition" is legitimate but partially addressable by existing `spec-first.md`
|
||||
- The 6-dimension PRD review checklist is extractable and generic — the single most actionable content in the article
|
||||
- ATDD is genuinely absent from the guide (only TDD covered)
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Gap Analysis vs. Claude Code Ultimate Guide
|
||||
|
||||
| Aspect | This resource | Guide (grep-verified) |
|
||||
|--------|--------------|----------------------|
|
||||
| Vertical slice as AI work unit | ✅ Core framework | ❌ Zero mentions |
|
||||
| Small PRD with 6 quality dimensions | ✅ Actionable checklist | ❌ Absent |
|
||||
| ATDD (Acceptance Test-Driven Dev) | ✅ Phase 2 core pattern | ❌ Only TDD covered |
|
||||
| Task decomposition discipline | ✅ Main thesis | ❌ Not addressed |
|
||||
| Human approval gates in pipeline | ✅ Slack approval at Phase 1 | ⚠️ Mentioned conceptually |
|
||||
| AI review agents in CI/CD | ✅ 5 parallel agents pattern | ❌ Not documented |
|
||||
| Orchestrator → slice decomposition | ✅ Explicit | ⚠️ Orchestration exists, not pipeline |
|
||||
| VM per ticket isolation | ✅ Multipass pattern | ❌ Absent |
|
||||
| Spec before code | ↔️ Related different scope | ✅ `spec-first.md` (CLAUDE.md spec) |
|
||||
| Multi-agent orchestration | ↔️ Implicit | ✅ `workflows/agent-teams.md` |
|
||||
|
||||
---
|
||||
|
||||
## 📍 Recommendations
|
||||
|
||||
**Priority: Medium — integrate 2 specific patterns, not the full pipeline**
|
||||
|
||||
### Integration 1: `guide/workflows/spec-first.md` — Add "Task Granularity" section
|
||||
|
||||
Extract the 6-dimension PRD quality checklist as a generic pre-coding checklist:
|
||||
|
||||
```markdown
|
||||
## PRD Quality Checklist (before handing to agents)
|
||||
|
||||
Before assigning work to an agent, verify the task definition covers:
|
||||
|
||||
1. **Problem Clarity** — Is the problem statement unambiguous?
|
||||
2. **Testable Acceptance Criteria** — Can completion be verified automatically?
|
||||
3. **Scope Boundaries** — What is explicitly OUT of scope?
|
||||
4. **Observable Done Definition** — What does "done" look like to an end user?
|
||||
5. **Requirements Clarity** — No ambiguous terms, no implementation details
|
||||
6. **Terminology Consistency** — Same terms used throughout (not "user" and "account" interchangeably)
|
||||
```
|
||||
|
||||
**Location**: After the "The Pattern" section in `spec-first.md` (~line 60)
|
||||
**Effort**: Low (20-30 lines)
|
||||
|
||||
### Integration 2: `guide/methodologies.md` — Add ATDD section
|
||||
|
||||
ATDD is genuinely absent. Add a section explaining how ATDD extends TDD for agent workflows:
|
||||
- Gherkin scenarios as the contract between PM intent and implementation
|
||||
- Write Gherkin first → agent writes failing tests → implementation
|
||||
|
||||
**Location**: After TDD section in `guide/methodologies.md`
|
||||
**Effort**: Medium (50-80 lines)
|
||||
|
||||
### What NOT to do
|
||||
|
||||
❌ Do NOT create `guide/workflows/agentic-pipeline.md` — pipeline is too stack-specific, author's challenges are unresolved, and it would document an unstable pattern as authoritative. Wait for a second independent source before creating a dedicated workflow guide.
|
||||
|
||||
---
|
||||
|
||||
## 🔥 Challenge Verdict
|
||||
|
||||
**Challenger (ac79d16) conclusions:**
|
||||
- **Score 3/5 confirmed** — "storytelling architecturel, pas case study validé"
|
||||
- **Most actionable content**: 6-dimension PRD checklist — treat as standalone checklist, not full pipeline
|
||||
- **Best integration path**: Existing files (`spec-first.md` + `methodologies.md`), not new file
|
||||
- **Key oversight in initial eval**: Article doesn't mention Claude Code specifically — the mapping is indirect
|
||||
|
||||
**Points raised not in initial analysis:**
|
||||
- Human Slack approval gate is under-analyzed as human-in-the-loop pattern
|
||||
- Stack dependency (Jira + GitHub + Slack + GCP) makes direct reuse impractical
|
||||
- "Vertical slices" concept is Agile (2003) not AI-native — risk of documenting old concept as new insight
|
||||
|
||||
---
|
||||
|
||||
## ✅ Fact-Check
|
||||
|
||||
| Claim | Verified | Source |
|
||||
|-------|----------|--------|
|
||||
| Author = Allan Hill, Fractional CTO | ✅ | LinkedIn profile (browser extraction) |
|
||||
| Article accessible without auth | ✅ | WebFetch succeeded on Pulse URL |
|
||||
| 3-phase pipeline structure | ✅ | Direct article extraction |
|
||||
| 6 PRD review dimensions (Problem Clarity, Testable Criteria, Scope Boundaries, Observable Done, Requirements Clarity, Terminology Consistency) | ✅ | Direct article extraction |
|
||||
| ATDD approach (Gherkin → failing tests → implementation) | ✅ | Direct article extraction |
|
||||
| 5 parallel AI review agents in CI | ✅ | Direct article extraction |
|
||||
| Multipass VMs + Node.js dispatcher | ✅ | Direct article extraction |
|
||||
| Open challenges: resume state fragility | ✅ | Author explicitly lists it |
|
||||
| "Vertical slices" from Agile literature (Dan North 2003) | ✅ | Perplexity context — established pattern |
|
||||
| Claude Code mentioned specifically | ❌ | Article uses generic "agents" — Claude Code NOT mentioned |
|
||||
| Production metrics (cycle time, defect rates) | ❌ | Not present in article |
|
||||
|
||||
**No hallucinations.** Score downgraded from initial "inspiration-level 3/5" to confirmed "targeted-integration 3/5" based on full content.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Final Decision
|
||||
|
||||
- **Score**: **3/5** — Pertinent, intégration ciblée
|
||||
- **Action**: Intégrer 2 éléments spécifiques dans fichiers existants (PRD checklist + ATDD)
|
||||
- **Do NOT create**: New `agentic-pipeline.md` file
|
||||
- **Confidence**: High (full article read, challenge performed, fact-checked)
|
||||
- **Trigger for re-evaluation**: Second independent source documenting vertical slice pattern for Claude Code specifically → would justify 4/5 + dedicated workflow file
|
||||
|
||||
**Related evaluations:**
|
||||
- `addy-osmani-good-spec.md` (4/5) — overlapping territory (spec quality, PRD structure)
|
||||
- `spec-first.md` in guide — primary integration target
|
||||
- `guide/methodologies.md` — secondary integration target (ATDD)
|
||||
|
|
@ -0,0 +1,130 @@
|
|||
---
|
||||
# Resource Evaluation: "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"
|
||||
|
||||
**Source**: https://arxiv.org/abs/2602.11988
|
||||
**Authors**: Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev (ETH Zürich)
|
||||
**Date**: February 13, 2026
|
||||
**Type**: Peer-reviewed academic paper (arXiv cs.SE)
|
||||
**Evaluated**: 2026-02-19
|
||||
|
||||
---
|
||||
|
||||
## 📄 Résumé du contenu
|
||||
|
||||
- **Question de recherche** : Les fichiers de contexte de type AGENTS.md améliorent-ils réellement les performances des coding agents ?
|
||||
- **Résultat principal** : Les fichiers developer-written améliorent légèrement le taux de succès (+4%), mais LLM-generated les dégradent (-3%) — dans tous les cas, le coût d'inférence augmente de 20-23%
|
||||
- **AGENTbench** : Nouveau benchmark introduit, 138 instances, 12 repositories avec des context files écrits par des développeurs (bug fixes + feature additions)
|
||||
- **Mécanisme identifié** : Les agents suivent fidèlement toutes les instructions du context file, même celles non pertinentes à la tâche → surcharge cognitive, exploration plus large, chaînes de raisonnement plus longues
|
||||
- **Recommandation centrale** : Inclure UNIQUEMENT les commandes build/test + tooling spécifique ; exclure style guides, descriptions d'architecture, et documentation générale
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Score de pertinence
|
||||
|
||||
| Score | Signification |
|
||||
|-------|---------------|
|
||||
| 5 | Essentiel - Gap majeur dans le guide |
|
||||
| **4** | **Très pertinent - Amélioration significative** |
|
||||
| 3 | Pertinent - Complément utile |
|
||||
| 2 | Marginal - Info secondaire |
|
||||
| 1 | Hors scope - Non pertinent |
|
||||
|
||||
**Score: 4/5**
|
||||
|
||||
**Justification**: Le guide recommande déjà un CLAUDE.md concis (<200 lignes), mais sans validation empirique. Ce paper fournit exactement cette validation + une nuance critique absente : même un context file "optimal" ajoute 20-23% de coût sans ROI proportionnel. La tension entre "générer son CLAUDE.md avec Claude" et "-3% pour LLM-generated" est directement actionnable.
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Comparatif
|
||||
|
||||
| Aspect | Ce paper | Notre guide |
|
||||
|--------|----------|-------------|
|
||||
| CLAUDE.md concis recommandé | ✅ Validé empiriquement | ✅ Déjà présent (opinion) |
|
||||
| Impact sur taux de succès agent | ✅ +4% (dev) / -3% (LLM) | ❌ Absent |
|
||||
| Cost penalty des context files | ✅ +20-23% dans tous les cas | ❌ Absent |
|
||||
| LLM-generated context file = risque | ✅ Prouvé empiriquement | ❌ Non mentionné |
|
||||
| Recommandation: build/test commands only | ✅ Recommandation précise | ⚠️ Vague ("essentiel") |
|
||||
| Distinction minimal vs comprehensive | ✅ Empiriquement justifiée | ⚠️ Présente mais non chiffrée |
|
||||
|
||||
---
|
||||
|
||||
## 📍 Recommandations d'intégration
|
||||
|
||||
**Trois points d'intégration, par priorité:**
|
||||
|
||||
### 1. Section "CLAUDE.md Best Practices" (guide/ultimate-guide.md, ligne ~13395)
|
||||
**Priorité: Haute**
|
||||
|
||||
Ajouter un encadré "Research note" après la liste des best practices existantes :
|
||||
|
||||
```markdown
|
||||
> **Research Note (Feb 2026)**: ETH Zürich a publié la première évaluation empirique des fichiers de contexte agent (AGENTS.md/CLAUDE.md). Résultats clés sur 138 benchmarks, 12 repos :
|
||||
> - Developer-written : **+4% success rate** vs baseline (pas de context file)
|
||||
> - LLM-generated : **-3% success rate** (agents suivent toutes les instructions, même hors-sujet)
|
||||
> - Dans tous les cas : **+20-23% inference cost**
|
||||
>
|
||||
> **Implication** : Incluez UNIQUEMENT les commandes build/test et le tooling spécifique. Style guides et descriptions d'architecture → docs séparés.
|
||||
> Source: [Gloaguen et al., 2026](https://arxiv.org/abs/2602.11988)
|
||||
```
|
||||
|
||||
### 2. Section token cost / token efficiency (ligne ~13382)
|
||||
**Priorité: Moyenne**
|
||||
|
||||
Ajouter dans la table Token Cost Estimation : "CLAUDE.md avec infos non-essentielles → +20-23% inference cost (Gloaguen et al., 2026)"
|
||||
|
||||
### 3. Toute section conseillant de générer CLAUDE.md avec Claude
|
||||
**Priorité: Haute**
|
||||
|
||||
Ajouter une mise en garde :
|
||||
|
||||
```markdown
|
||||
> ⚠️ **Attention**: Les context files générés par LLM réduisent les performances des agents (-3% vs baseline). Révisez et épurez tout CLAUDE.md généré automatiquement avant de le committer.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔥 Challenge (agent de révision)
|
||||
|
||||
**Score ajusté**: 4/5 (confirmé)
|
||||
|
||||
**Points manqués dans l'évaluation initiale** :
|
||||
- Le ROI net de +4% (developer-written) ne compense pas toujours le +20-23% cost — le guide ne documente pas ce trade-off nulle part
|
||||
- Les agents testés n'incluent pas Claude Haiku (utilisé pour les sub-agents) ni Opus — limitation à mentionner lors de l'intégration
|
||||
- La section SWE-bench Lite n'est pas mentionnée (comparison baseline avec AGENTbench)
|
||||
|
||||
**Tension identifiée** : Si le guide mentionne d'autres études valorisant les context files, ne pas mentionner celle-ci crée un biais de sélection. Priorité d'intégration confirmée.
|
||||
|
||||
**Risques de non-intégration** :
|
||||
- Les conseils "lean CLAUDE.md" restent des opinions sans backing empirique
|
||||
- Crédibilité du guide fragilisée face aux concurrents citant ce paper
|
||||
- Les utilisateurs générant leur CLAUDE.md avec Claude (pratique répandue) ne sont pas alertés du risque -3%
|
||||
|
||||
---
|
||||
|
||||
## ✅ Fact-Check
|
||||
|
||||
| Affirmation | Vérifiée | Source |
|
||||
|-------------|----------|--------|
|
||||
| Auteurs : ETH Zürich | ✅ | arXiv abstract |
|
||||
| Date de publication : 13 février 2026 | ✅ | arXiv metadata |
|
||||
| +4% dev-written / -3% LLM-generated | ✅ | Perplexity search + arXiv HTML |
|
||||
| +20-23% inference cost | ✅ | arXiv abstract ("over 20%") + HTML full text |
|
||||
| AGENTbench : 138 instances, 12 repos | ✅ | Perplexity + arXiv HTML |
|
||||
| Agents testés : Claude Code, Codex, Qwen Code | ⚠️ | Partiellement — noms de modèles exacts non vérifiables via Perplexity |
|
||||
| Recommandation : build/test commands only | ✅ | arXiv HTML + blog d'analyse (jangwook.net) |
|
||||
|
||||
**Corrections** : Les noms de modèles spécifiques (ex. "GPT-5.2", "Qwen3-30b-coder") ont été évités — potentielle hallucination du fetcher PDF. Le paper confirme "4 coding agents" sans préciser les versions exactes dans les sources vérifiées.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Décision finale
|
||||
|
||||
- **Score final**: 4/5
|
||||
- **Action**: Intégrer (3 points d'intégration prioritarisés)
|
||||
- **Confiance**: Haute (données clés vérifiées via Perplexity + arXiv HTML)
|
||||
|
||||
**Next step**: Ajouter le "Research Note" callout dans `guide/ultimate-guide.md` ligne ~13395 et la mise en garde sur LLM-generated context files.
|
||||
|
||||
---
|
||||
|
||||
*Évaluation effectuée le 2026-02-19 | Méthode: WebFetch + Perplexity + grepai_search + agent challenge*
|
||||
|
|
@ -0,0 +1,144 @@
|
|||
# Resource Evaluation: Spec-to-Code Factory
|
||||
|
||||
**Resource**: https://github.com/SylvainChabaud/spec-to-code-factory
|
||||
**LinkedIn**: https://www.linkedin.com/posts/sylvain-chabaud-831415aa_ia-claudecode-ai-activity-7430257228928163840-jOxD
|
||||
**Author**: Sylvain Chabaud (Ingénieur & formateur — WEB, Système embarqué)
|
||||
**Published**: 2026-01 (repo ~4 weeks old at evaluation time)
|
||||
**Evaluation Date**: 2026-02-19
|
||||
**Evaluator**: Claude Code Ultimate Guide Team
|
||||
**Score**: **3/5** (Pertinent — Mention ciblée)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Pipeline multi-agents open-source entièrement construit sur Claude Code, qui transforme un `requirements.md` en projet livrable via 4 phases séquentielles et 6 gates de validation outillées.
|
||||
|
||||
**Points clés :**
|
||||
- Méthodologie **BREAK → MODEL → ACT → DEBRIEF** avec 6 gates (Gate 0-5)
|
||||
- Deux invariants absolus vérifiés automatiquement : "No Spec, No Code" et "No Task, No Commit"
|
||||
- Chaîne de traçabilité complète : `COMMIT → TASK → US → EPIC → BRIEF`
|
||||
- Budget token transparent par phase : ~900K total (BREAK 70K, MODEL 100K, PLAN 120K, BUILD 500K+, DEBRIEF 80K)
|
||||
- Repo clonable : implémentation référence concrète (pas juste une documentation)
|
||||
|
||||
**Limites notables :**
|
||||
- Jeune (22 commits, 8 stars) — pas encore validé en production à large échelle
|
||||
- JavaScript uniquement (Clean Architecture React)
|
||||
- Overhead massif (~900K tokens/projet) — adapté aux projets greenfield importants
|
||||
|
||||
---
|
||||
|
||||
## Scoring Breakdown
|
||||
|
||||
### 1. Relevance to Claude Code (5/5)
|
||||
|
||||
✅ **Entièrement construit sur Claude Code** : Skills orchestrant les phases, hooks validant les invariants, agents spécialisés par rôle
|
||||
✅ **Patterns directs** : Utilise skills + hooks + agents exactement comme le guide les documente
|
||||
✅ **Implémentation référence** : Repo clonable illustrant les concepts du guide en situation réelle
|
||||
|
||||
### 2. Technical Accuracy (4/5)
|
||||
|
||||
✅ **Phases vérifiées** : BREAK→MODEL→ACT→DEBRIEF confirmées dans le README
|
||||
✅ **Gates vérifiées** : Gate 0-5 via scripts Node.js (requirements, structure, secrets/PII, planning, code quality, release)
|
||||
✅ **Invariants réels** : Enforcement via tools/validate-commit-msg.js — pas juste des suggestions
|
||||
⚠️ **Maturité limitée** : 4 semaines, architecture encore en évolution
|
||||
|
||||
### 3. Novelty/Uniqueness (3/5)
|
||||
|
||||
✅ **Enforcement outillé** : Scripts Node.js qui *bloquent* si gates non passées — pattern non documenté dans le guide
|
||||
✅ **Budget token par phase** : Estimation concrète ~900K avec breakdown — unique dans l'écosystème
|
||||
✅ **Traceability chain** : TASK→US→EPIC→BRIEF pas explicitement couverte dans le guide
|
||||
⚠️ **Redondance ~80%** : spec-first.md (830 lignes), methodologies.md (Spec Kit/OpenSpec), agent-teams.md couvrent déjà l'essentiel
|
||||
|
||||
### 4. Practicality (3/5)
|
||||
|
||||
✅ **Clé en main** : Repo clonable, structure prête
|
||||
⚠️ **Coût élevé** : ~900K tokens × $0.003 = ~$2.70/projet + maintenance hooks
|
||||
⚠️ **JavaScript uniquement** : Clean Architecture React — pas polyglot
|
||||
⚠️ **Complexité setup** : Git hooks + scripts Node.js à configurer
|
||||
|
||||
### 5. Source Credibility (3/5)
|
||||
|
||||
✅ **Présenté en public** : Talk à l'IA CAFE CLUB (Paris), validé par communauté
|
||||
⚠️ **Adoption limitée** : 8 stars, 2 forks, 2 contributeurs (auteur + Claude)
|
||||
⚠️ **Pas encore versionné** : 0 releases officielles
|
||||
|
||||
---
|
||||
|
||||
## Comparative Analysis
|
||||
|
||||
| Aspect | Spec-to-Code Factory | Notre Guide |
|
||||
|--------|---------------------|-------------|
|
||||
| **Spec-first workflow** | ✅ BREAK phase | ✅ spec-first.md (830 lignes) |
|
||||
| **SDD greenfield** | ✅ Implémentation complète | ✅ Spec Kit (methodologies.md:366) |
|
||||
| **Multi-agent orchestration** | ✅ 6 agents spécialisés | ✅ agent-teams.md |
|
||||
| **Enforcement via hooks** | ✅ Scripts Node.js bloquants | ⚠️ Patterns seulement |
|
||||
| **Traceability chain** | ✅ TASK→US→EPIC→BRIEF | ❌ Manquant |
|
||||
| **Token budget par phase** | ✅ Breakdown transparent | ❌ Manquant |
|
||||
| **Implémentation référence** | ✅ Repo clonable | ❌ Templates seulement |
|
||||
| **Brownfield support** | ✅ V2+ mode | ✅ OpenSpec (methodologies.md:375) |
|
||||
|
||||
---
|
||||
|
||||
## Challenge (technical-writer agent)
|
||||
|
||||
**Verdict du challenge** : Score initial 4/5 → ramené à 3/5 justifié
|
||||
|
||||
**Principaux arguments du challenge :**
|
||||
- Redondance à ~80% avec guide existant sous-estimée initialement
|
||||
- "900K tokens" est un overhead non négligeable, pas un argument de vente
|
||||
- Repo trop jeune (4 semaines) pour recommandation forte
|
||||
- Enforcement via Git hooks side-car = gouvernance externe, pas native Claude Code
|
||||
|
||||
**Risques de non-intégration** : Faibles. La ressource est utile pour les devs cherchant une implémentation clé-en-main, mais le guide couvre les concepts fondamentaux.
|
||||
|
||||
---
|
||||
|
||||
## Fact-Check
|
||||
|
||||
| Affirmation | Vérifiée | Source |
|
||||
|-------------|----------|--------|
|
||||
| BREAK → MODEL → ACT → DEBRIEF (4 phases) | ✅ | GitHub README (WebFetch) |
|
||||
| 6 gates de validation (Gate 0-5) | ✅ | GitHub README |
|
||||
| "No Spec, No Code" + "No Task, No Commit" | ✅ | GitHub README + LinkedIn post |
|
||||
| ~900K tokens total estimé | ✅ | LinkedIn post (screenshot + tableau) |
|
||||
| 8 stars / 22 commits | ✅ | GitHub (vérifié 2026-02-19) |
|
||||
| JavaScript 100% | ✅ | GitHub (WebFetch) |
|
||||
| Enforcement via Node.js scripts | ✅ | tools/validate-commit-msg.js mentionné dans README |
|
||||
|
||||
**Corrections apportées** : Aucune. "6 gates" (LinkedIn) correspond aux Gates 0-5 du README — cohérent numériquement.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
- **Score final** : **3/5** (Pertinent — Mention ciblée)
|
||||
- **Action** : Mention dans `guide/methodologies.md` (tableau SDD Tools) + `guide/workflows/spec-first.md` (See Also)
|
||||
- **Confiance** : Haute
|
||||
|
||||
**Intégration réalisée** :
|
||||
1. `guide/methodologies.md` ligne ~365 : Ligne ajoutée dans le tableau SDD Tools
|
||||
2. `guide/workflows/spec-first.md` section "See Also" : Lien + description ajoutés
|
||||
|
||||
**Révision recommandée** : Mai 2026 — vérifier adoption (stars, forks, issues), éventuellement upgrader à 4/5 si projet mature.
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
**Primary**:
|
||||
- [GitHub — spec-to-code-factory](https://github.com/SylvainChabaud/spec-to-code-factory)
|
||||
- [LinkedIn post](https://www.linkedin.com/posts/sylvain-chabaud-831415aa_ia-claudecode-ai-activity-7430257228928163840-jOxD)
|
||||
|
||||
**Internal verification**:
|
||||
- `guide/workflows/spec-first.md` (830 lignes — spec-first existant)
|
||||
- `guide/methodologies.md` (SDD Tools section, ligne ~356)
|
||||
- `guide/workflows/agent-teams.md`
|
||||
|
||||
**Challenge Agent** : technical-writer via Task tool (Explore subagent)
|
||||
|
||||
---
|
||||
|
||||
**Evaluation Methodology**: [docs/resource-evaluations/README.md](./README.md)
|
||||
**Guide Version**: 3.27.8
|
||||
**Integration Status**: ✅ Mention ciblée (2026-02-19)
|
||||
75
examples/team-config/claude-skeleton.md
Normal file
75
examples/team-config/claude-skeleton.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
# AI Instructions — {{DEVELOPER_NAME}}
|
||||
<!-- Generated: {{GENERATED_DATE}} | OS: {{OS}} | Tool: {{TOOL}} -->
|
||||
<!-- DO NOT EDIT MANUALLY — auto-generated from profile + modules -->
|
||||
<!-- To update: edit profiles/{{DEVELOPER_SLUG}}.yaml or modules/, then run: -->
|
||||
<!-- npx ts-node sync-ai-instructions.ts {{DEVELOPER_SLUG}} -->
|
||||
|
||||
---
|
||||
|
||||
## Project Context
|
||||
|
||||
{{MODULE:core-standards}}
|
||||
|
||||
---
|
||||
|
||||
## Git Workflow
|
||||
|
||||
{{MODULE:git-workflow}}
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
{{MODULE:test-conventions}}
|
||||
|
||||
---
|
||||
|
||||
{{#if typescript}}
|
||||
## TypeScript Rules
|
||||
|
||||
{{MODULE:typescript-rules}}
|
||||
|
||||
---
|
||||
{{/if}}
|
||||
|
||||
{{#if python}}
|
||||
## Python Rules
|
||||
|
||||
{{MODULE:python-rules}}
|
||||
|
||||
---
|
||||
{{/if}}
|
||||
|
||||
## Environment & Paths
|
||||
|
||||
{{MODULE:{{OS}}-paths}}
|
||||
|
||||
---
|
||||
|
||||
{{#if cursor}}
|
||||
## Cursor-Specific Instructions
|
||||
|
||||
{{MODULE:cursor-rules}}
|
||||
|
||||
---
|
||||
{{/if}}
|
||||
|
||||
{{#if windsurf}}
|
||||
## Windsurf-Specific Instructions
|
||||
|
||||
{{MODULE:windsurf-rules}}
|
||||
|
||||
---
|
||||
{{/if}}
|
||||
|
||||
## Communication Style
|
||||
|
||||
{{#if verbose}}
|
||||
Provide detailed explanations for each decision. Show alternatives considered. Include reasoning.
|
||||
{{/if}}
|
||||
{{#if concise}}
|
||||
Be concise. One sentence per point. Skip obvious details.
|
||||
{{/if}}
|
||||
{{#if terse}}
|
||||
Minimal output. Code only when possible. No explanations unless asked.
|
||||
{{/if}}
|
||||
41
examples/team-config/profile-template.yaml
Normal file
41
examples/team-config/profile-template.yaml
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# examples/team-config/profile-template.yaml
|
||||
# Profile template for Profile-Based Module Assembly
|
||||
# Copy to profiles/<your-name>.yaml and customize
|
||||
|
||||
# Required fields
|
||||
name: "YourName" # Developer name (used in generated header)
|
||||
os: "macos" # macos | linux | windows
|
||||
tools:
|
||||
- claude-code # List all AI tools you use
|
||||
# - cursor # Uncomment if you use Cursor
|
||||
# - windsurf # Uncomment if you use Windsurf
|
||||
|
||||
# Communication style affects verbosity of AI explanations
|
||||
communication_style: "concise" # verbose | concise | terse
|
||||
|
||||
# Module selection
|
||||
modules:
|
||||
# Core modules: always included, regardless of OS or tools
|
||||
core:
|
||||
- core-standards # Architecture, naming, patterns
|
||||
- git-workflow # Git conventions
|
||||
- test-conventions # Testing patterns
|
||||
# - typescript-rules # Uncomment if TypeScript project
|
||||
# - python-rules # Uncomment if Python project
|
||||
|
||||
# Conditional modules: included based on os/tools above
|
||||
# The assembler automatically includes these based on your profile values
|
||||
conditional:
|
||||
# OS-specific (auto-filtered by 'os' field above)
|
||||
- macos-paths # macOS paths (/opt/homebrew, etc.)
|
||||
- linux-paths # Linux paths (/usr/local, etc.)
|
||||
|
||||
# Tool-specific (auto-filtered by 'tools' list above)
|
||||
- cursor-rules # Cursor-specific instructions
|
||||
- windsurf-rules # Windsurf-specific instructions
|
||||
|
||||
# Optional preferences
|
||||
preferences:
|
||||
language: "english" # english | french | spanish | etc.
|
||||
token_budget: "medium" # low | medium | high
|
||||
# low: minimal context, high: comprehensive context
|
||||
213
examples/team-config/sync-script.ts
Normal file
213
examples/team-config/sync-script.ts
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
#!/usr/bin/env npx ts-node
|
||||
/**
|
||||
* sync-ai-instructions.ts
|
||||
* Profile-Based Module Assembly for AI instructions
|
||||
*
|
||||
* Usage:
|
||||
* npx ts-node sync-ai-instructions.ts # Generate all profiles
|
||||
* npx ts-node sync-ai-instructions.ts alice # Single profile
|
||||
* npx ts-node sync-ai-instructions.ts --check # Dry-run + drift detection
|
||||
*
|
||||
* Directory structure expected:
|
||||
* profiles/ Developer YAML profiles
|
||||
* modules/ Reusable markdown modules
|
||||
* skeleton/claude.md Template with {{PLACEHOLDERS}}
|
||||
* output/<dev>/ Generated CLAUDE.md files
|
||||
*/
|
||||
|
||||
import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from 'fs'
|
||||
import { join, basename } from 'path'
|
||||
import { parse } from 'yaml'
|
||||
|
||||
// ─── Types ───────────────────────────────────────────────────────────────────
|
||||
|
||||
interface Profile {
|
||||
name: string
|
||||
os: 'macos' | 'linux' | 'windows'
|
||||
tools: string[]
|
||||
communication_style: 'verbose' | 'concise' | 'terse'
|
||||
modules: {
|
||||
core: string[]
|
||||
conditional: string[]
|
||||
}
|
||||
preferences?: {
|
||||
language?: string
|
||||
token_budget?: 'low' | 'medium' | 'high'
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Module Resolution ───────────────────────────────────────────────────────
|
||||
|
||||
function isModuleApplicable(moduleName: string, profile: Profile): boolean {
|
||||
// OS-specific modules
|
||||
if (moduleName.endsWith('-paths')) {
|
||||
return moduleName === `${profile.os}-paths`
|
||||
}
|
||||
|
||||
// Tool-specific modules
|
||||
const toolModuleMap: Record<string, string> = {
|
||||
'cursor-rules': 'cursor',
|
||||
'windsurf-rules': 'windsurf',
|
||||
}
|
||||
if (toolModuleMap[moduleName]) {
|
||||
return profile.tools.includes(toolModuleMap[moduleName])
|
||||
}
|
||||
|
||||
return true
|
||||
}
|
||||
|
||||
function resolveModules(profile: Profile): string[] {
|
||||
const core = profile.modules.core
|
||||
const conditional = profile.modules.conditional.filter(m =>
|
||||
isModuleApplicable(m, profile)
|
||||
)
|
||||
return [...core, ...conditional]
|
||||
}
|
||||
|
||||
// ─── Template Processing ─────────────────────────────────────────────────────
|
||||
|
||||
function processConditionalBlocks(content: string, profile: Profile): string {
|
||||
const hasTypescript = profile.modules.core.includes('typescript-rules') ||
|
||||
profile.modules.conditional.includes('typescript-rules')
|
||||
const hasPython = profile.modules.core.includes('python-rules') ||
|
||||
profile.modules.conditional.includes('python-rules')
|
||||
|
||||
const flags: Record<string, boolean> = {
|
||||
typescript: hasTypescript,
|
||||
python: hasPython,
|
||||
cursor: profile.tools.includes('cursor'),
|
||||
windsurf: profile.tools.includes('windsurf'),
|
||||
verbose: profile.communication_style === 'verbose',
|
||||
concise: profile.communication_style === 'concise',
|
||||
terse: profile.communication_style === 'terse',
|
||||
}
|
||||
|
||||
// Process {{#if flag}}...{{/if}} blocks
|
||||
return content.replace(
|
||||
/\{\{#if (\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g,
|
||||
(_match, flag, block) => flags[flag] ? block : ''
|
||||
)
|
||||
}
|
||||
|
||||
function injectModules(
|
||||
content: string,
|
||||
modules: string[],
|
||||
modulesDir: string
|
||||
): string {
|
||||
// Inject named modules: {{MODULE:module-name}}
|
||||
let result = content.replace(/\{\{MODULE:([^}]+)\}\}/g, (_match, moduleName) => {
|
||||
const modulePath = join(modulesDir, `${moduleName}.md`)
|
||||
if (!existsSync(modulePath)) {
|
||||
console.warn(` ⚠ Module not found: ${moduleName}`)
|
||||
return `<!-- MODULE NOT FOUND: ${moduleName} -->`
|
||||
}
|
||||
return readFileSync(modulePath, 'utf-8').trim()
|
||||
})
|
||||
|
||||
return result
|
||||
}
|
||||
|
||||
// ─── Assembler ───────────────────────────────────────────────────────────────
|
||||
|
||||
function assembleInstructions(
|
||||
profilePath: string,
|
||||
skeletonPath: string,
|
||||
modulesDir: string
|
||||
): string {
|
||||
const profile = parse(readFileSync(profilePath, 'utf-8')) as Profile
|
||||
const skeleton = readFileSync(skeletonPath, 'utf-8')
|
||||
|
||||
const slug = basename(profilePath, '.yaml')
|
||||
const modules = resolveModules(profile)
|
||||
|
||||
// Replace simple placeholders
|
||||
let output = skeleton
|
||||
.replace(/\{\{DEVELOPER_NAME\}\}/g, profile.name)
|
||||
.replace(/\{\{DEVELOPER_SLUG\}\}/g, slug)
|
||||
.replace(/\{\{OS\}\}/g, profile.os)
|
||||
.replace(/\{\{TOOL\}\}/g, profile.tools[0] ?? 'claude-code')
|
||||
.replace(/\{\{GENERATED_DATE\}\}/g, new Date().toISOString().split('T')[0])
|
||||
|
||||
// Process conditional blocks
|
||||
output = processConditionalBlocks(output, profile)
|
||||
|
||||
// Inject module content
|
||||
output = injectModules(output, modules, modulesDir)
|
||||
|
||||
// Clean up empty sections
|
||||
output = output.replace(/\n{3,}/g, '\n\n').trim()
|
||||
|
||||
return output
|
||||
}
|
||||
|
||||
// ─── Main ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
async function main() {
|
||||
const args = process.argv.slice(2)
|
||||
const isDryRun = args.includes('--check') || args.includes('--dry-run')
|
||||
const targetProfile = args.find(a => !a.startsWith('--'))
|
||||
|
||||
const profilesDir = 'profiles'
|
||||
const skeletonPath = 'skeleton/claude.md'
|
||||
const modulesDir = 'modules'
|
||||
const outputDir = 'output'
|
||||
|
||||
// Validate structure
|
||||
for (const dir of [profilesDir, modulesDir, 'skeleton']) {
|
||||
if (!existsSync(dir)) {
|
||||
console.error(`❌ Directory not found: ${dir}`)
|
||||
process.exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
// Collect profiles
|
||||
const profileFiles = targetProfile
|
||||
? [`${targetProfile}.yaml`]
|
||||
: readdirSync(profilesDir).filter(f => f.endsWith('.yaml'))
|
||||
|
||||
let driftDetected = false
|
||||
|
||||
for (const profileFile of profileFiles) {
|
||||
const profilePath = join(profilesDir, profileFile)
|
||||
const slug = basename(profileFile, '.yaml')
|
||||
const outputPath = join(outputDir, slug, 'CLAUDE.md')
|
||||
|
||||
console.log(`\n→ Processing: ${slug}`)
|
||||
|
||||
const generated = assembleInstructions(profilePath, skeletonPath, modulesDir)
|
||||
|
||||
if (isDryRun) {
|
||||
const existing = existsSync(outputPath)
|
||||
? readFileSync(outputPath, 'utf-8')
|
||||
: null
|
||||
|
||||
if (!existing) {
|
||||
console.log(` ⚠ No existing file at ${outputPath}`)
|
||||
driftDetected = true
|
||||
} else if (existing !== generated) {
|
||||
console.log(` ❌ Drift detected — ${outputPath} is out of sync`)
|
||||
driftDetected = true
|
||||
} else {
|
||||
console.log(` ✓ In sync`)
|
||||
}
|
||||
} else {
|
||||
const devOutputDir = join(outputDir, slug)
|
||||
if (!existsSync(devOutputDir)) mkdirSync(devOutputDir, { recursive: true })
|
||||
|
||||
writeFileSync(outputPath, generated)
|
||||
const lines = generated.split('\n').length
|
||||
console.log(` ✓ Written: ${outputPath} (${lines} lines)`)
|
||||
}
|
||||
}
|
||||
|
||||
if (isDryRun && driftDetected) {
|
||||
console.error('\n❌ Drift detected. Run: npx ts-node sync-ai-instructions.ts')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
if (!isDryRun) {
|
||||
console.log('\n✅ All profiles assembled successfully')
|
||||
}
|
||||
}
|
||||
|
||||
main().catch(console.error)
|
||||
|
|
@ -179,6 +179,25 @@ Feature: Order Management
|
|||
|
||||
**ATDD (Acceptance Test-Driven Development)** — Acceptance criteria defined BEFORE coding, collaboratively ("Three Amigos": Business, Dev, Test).
|
||||
|
||||
In agentic development, ATDD is particularly effective because agents need unambiguous success conditions. The flow maps cleanly to agent tasks:
|
||||
|
||||
1. **Define acceptance criteria** in Gherkin (human-readable, machine-executable)
|
||||
2. **Agent writes failing tests** based on scenarios (not implementation)
|
||||
3. **Agent implements** until tests pass
|
||||
|
||||
```gherkin
|
||||
Feature: Password Reset
|
||||
Scenario: User resets via email
|
||||
Given a registered user with email "user@example.com"
|
||||
When they request a password reset
|
||||
Then they receive a reset email within 60 seconds
|
||||
And the reset link expires after 24 hours
|
||||
```
|
||||
|
||||
This Gherkin scenario is the contract between intent and implementation. The agent cannot misinterpret scope because done is defined before a line of code is written.
|
||||
|
||||
> **Applied to agents**: Pass the Gherkin file to Claude Code before implementing. "Write failing tests for this feature file, then implement until they pass." The scenario writer role (human or agent) forces explicit scope before execution starts.
|
||||
|
||||
**CDD (Contract-Driven Development)** — API contracts (OpenAPI specs) as executable interface between teams. Patterns: Contract as Test, Contract as Stub.
|
||||
|
||||
---
|
||||
|
|
@ -362,6 +381,7 @@ Three tools have emerged to formalize Spec-Driven Development:
|
|||
| **Spec Kit** | Greenfield, governance | [github.blog/spec-kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) | `/speckit.constitution`, `/speckit.specify`, `/speckit.plan` |
|
||||
| **OpenSpec** | Brownfield, changes | [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
|
||||
| **Specmatic** | API contract testing | [specmatic.io](https://specmatic.io) | MCP agent available |
|
||||
| **Spec-to-Code Factory** | Greenfield, enforcement outillé | [github.com/SylvainChabaud/spec-to-code-factory](https://github.com/SylvainChabaud/spec-to-code-factory) | Implémentation référence multi-agents (BREAK→MODEL→ACT→DEBRIEF) |
|
||||
|
||||
### Spec Kit (Greenfield)
|
||||
|
||||
|
|
|
|||
|
|
@ -130,6 +130,7 @@ Context full → /compact or /clear
|
|||
- [3.2 The .claude/ Folder Structure](#32-the-claude-folder-structure)
|
||||
- [3.3 Settings & Permissions](#33-settings--permissions)
|
||||
- [3.4 Precedence Rules](#34-precedence-rules)
|
||||
- [3.5 Team Configuration at Scale](#35-team-configuration-at-scale)
|
||||
- [4. Agents](#4-agents)
|
||||
- [4.1 What Are Agents](#41-what-are-agents)
|
||||
- [4.2 Creating Custom Agents](#42-creating-custom-agents)
|
||||
|
|
@ -4918,6 +4919,262 @@ This enables progressive context loading—rules only appear when Claude works w
|
|||
|
||||
---
|
||||
|
||||
## 3.5 Team Configuration at Scale
|
||||
|
||||
---
|
||||
|
||||
### 📌 Section 3.5 TL;DR (60 seconds)
|
||||
|
||||
**Problem**: AI instruction files (CLAUDE.md, .cursorrules, AGENTS.md) fragment across developers, tools, and OS — each dev ends up with a slightly different version, and nobody knows which is "correct."
|
||||
|
||||
**Solution**: Profile-Based Module Assembly — extract reusable modules, define per-dev profiles in YAML, auto-assemble the final instruction file.
|
||||
|
||||
**Measured gain**: 59% token context reduction (from ~8,400 to ~3,450 tokens per assembled file). Measured on a team of 5 developers, TypeScript/Node.js stack.
|
||||
|
||||
**Use when**: Teams of 3+ developers using multiple AI tools (Claude Code, Cursor, Windsurf, etc.)
|
||||
|
||||
**Skip if**: Solo developer or homogeneous team (same tool, same OS, same rules for everyone).
|
||||
|
||||
---
|
||||
|
||||
### The N×M×P Fragmentation Problem
|
||||
|
||||
When your team uses AI coding tools, instruction files multiply fast:
|
||||
|
||||
```
|
||||
Developers (N) × Tools (M) × OS (P) = Fragments
|
||||
───────────── ─────────── ───────── ──────────
|
||||
5 devs 3 tools 2 OS 30 potential configs
|
||||
(Claude Code, (macOS,
|
||||
Cursor, Linux)
|
||||
Windsurf)
|
||||
```
|
||||
|
||||
In practice, this causes real drift:
|
||||
|
||||
- Alice adds TypeScript strict-mode rules to her CLAUDE.md. Bob never gets them.
|
||||
- Carol configures macOS-specific paths. Dave on Linux copies the file and gets broken paths.
|
||||
- Someone updates the git workflow section in one file. The other 4 files stay stale.
|
||||
|
||||
After 3 months, no two developers have the same instructions — and nobody knows which version is "right."
|
||||
|
||||
### Solution: Profile-Based Module Assembly
|
||||
|
||||
Instead of maintaining N separate monolithic files, you maintain:
|
||||
- **Modules**: Small, single-topic instruction files (reusable across all devs)
|
||||
- **Profiles**: One YAML per developer declaring which modules they need
|
||||
- **Skeleton**: A template with placeholders, filled at assembly time
|
||||
- **Assembler**: A script that reads a profile and outputs the final file
|
||||
|
||||
```
|
||||
profiles/
|
||||
├── alice.yaml ──┐
|
||||
├── bob.yaml ──┤ Developer Profiles
|
||||
└── carol.yaml ──┘
|
||||
│
|
||||
▼
|
||||
modules/
|
||||
├── core-standards.md ──┐
|
||||
├── typescript-rules.md ──┤ Shared Modules
|
||||
├── git-workflow.md ──┤
|
||||
└── macos-paths.md ──┘
|
||||
│
|
||||
▼
|
||||
skeleton/
|
||||
└── claude.md ─── Template with {{PLACEHOLDERS}}
|
||||
│
|
||||
▼
|
||||
sync-ai-instructions.ts ─── Assembler script
|
||||
│
|
||||
▼
|
||||
output/
|
||||
├── alice/CLAUDE.md ──┐
|
||||
├── bob/CLAUDE.md ──┤ Assembled per-dev
|
||||
└── carol/CLAUDE.md ──┘
|
||||
```
|
||||
|
||||
**One module update propagates to all developers automatically.**
|
||||
|
||||
### Profile YAML
|
||||
|
||||
Each developer has a profile declaring their environment and which modules to include:
|
||||
|
||||
```yaml
|
||||
# profiles/alice.yaml
|
||||
name: "Alice"
|
||||
os: "macos"
|
||||
tools:
|
||||
- claude-code
|
||||
- cursor
|
||||
communication_style: "verbose" # or "concise"
|
||||
modules:
|
||||
core:
|
||||
- core-standards
|
||||
- git-workflow
|
||||
- typescript-rules
|
||||
conditional:
|
||||
- macos-paths # included if os: macos
|
||||
- cursor-rules # included if cursor in tools
|
||||
preferences:
|
||||
language: "english"
|
||||
token_budget: "medium" # low | medium | high
|
||||
```
|
||||
|
||||
### Skeleton Template
|
||||
|
||||
The skeleton is a Markdown template with placeholders. The assembler fills them in:
|
||||
|
||||
```markdown
|
||||
# AI Instructions - {{DEVELOPER_NAME}}
|
||||
# Generated: {{GENERATED_DATE}} | OS: {{OS}} | Tool: {{TOOL}}
|
||||
# DO NOT EDIT - Auto-generated from profile. Edit profile + modules instead.
|
||||
|
||||
## Project Context
|
||||
{{MODULE:core-standards}}
|
||||
|
||||
## Git Workflow
|
||||
{{MODULE:git-workflow}}
|
||||
|
||||
{{#if typescript}}
|
||||
## TypeScript Rules
|
||||
{{MODULE:typescript-rules}}
|
||||
{{/if}}
|
||||
|
||||
## Environment
|
||||
{{MODULE:{{OS}}-paths}}
|
||||
```
|
||||
|
||||
The `DO NOT EDIT` header is important — it prevents developers from making local changes that would be overwritten on next assembly.
|
||||
|
||||
### Assembler Script
|
||||
|
||||
A simplified TypeScript assembler (~30 lines of core logic):
|
||||
|
||||
```typescript
|
||||
// sync-ai-instructions.ts (simplified)
|
||||
import { readFileSync, writeFileSync } from 'fs'
|
||||
import { parse } from 'yaml'
|
||||
|
||||
interface Profile {
|
||||
name: string
|
||||
os: 'macos' | 'linux' | 'windows'
|
||||
tools: string[]
|
||||
modules: { core: string[]; conditional: string[] }
|
||||
}
|
||||
|
||||
function assembleInstructions(profilePath: string, skeletonPath: string): string {
|
||||
const profile = parse(readFileSync(profilePath, 'utf-8')) as Profile
|
||||
let output = readFileSync(skeletonPath, 'utf-8')
|
||||
|
||||
// Replace placeholders
|
||||
output = output.replace('{{DEVELOPER_NAME}}', profile.name)
|
||||
output = output.replace('{{OS}}', profile.os)
|
||||
output = output.replace('{{GENERATED_DATE}}', new Date().toISOString())
|
||||
|
||||
// Inject modules
|
||||
const allModules = [
|
||||
...profile.modules.core,
|
||||
...profile.modules.conditional.filter(m => isApplicable(m, profile))
|
||||
]
|
||||
|
||||
for (const moduleName of allModules) {
|
||||
const content = readFileSync(`modules/${moduleName}.md`, 'utf-8')
|
||||
output = output.replace(`{{MODULE:${moduleName}}}`, content)
|
||||
}
|
||||
|
||||
return output
|
||||
}
|
||||
|
||||
function isApplicable(module: string, profile: Profile): boolean {
|
||||
if (module.endsWith('-paths')) return module.startsWith(profile.os)
|
||||
if (module === 'cursor-rules') return profile.tools.includes('cursor')
|
||||
return true
|
||||
}
|
||||
|
||||
// Run for all profiles
|
||||
const profiles = ['alice', 'bob', 'carol']
|
||||
for (const dev of profiles) {
|
||||
const result = assembleInstructions(`profiles/${dev}.yaml`, 'skeleton/claude.md')
|
||||
writeFileSync(`output/${dev}/CLAUDE.md`, result)
|
||||
console.log(`Generated CLAUDE.md for ${dev}`)
|
||||
}
|
||||
```
|
||||
|
||||
You can write this in Python or bash too — the logic is the same: read profile, load modules, replace placeholders, write output.
|
||||
|
||||
### Measured Results
|
||||
|
||||
Tested on a team of 5 developers, TypeScript/Node.js stack (Aristote Method):
|
||||
|
||||
| Metric | Monolithic | Profile-Based | Change |
|
||||
|--------|-----------|---------------|--------|
|
||||
| Average CLAUDE.md size | 380 lines | 185 lines | -51% |
|
||||
| Estimated token cost | ~8,400 tok | ~3,450 tok | **-59%** |
|
||||
| Files to maintain | 1 shared file | 12 modules + 5 profiles | +16 files |
|
||||
| Update propagation | Manual copy-paste | Automatic (1 module → all) | Automated |
|
||||
| Drift detection | None | CI daily check | Automated |
|
||||
|
||||
Token estimates based on ~22 tokens/line average. The 59% reduction comes from each developer only loading the modules they actually need, instead of the full monolithic file with sections irrelevant to their setup.
|
||||
|
||||
### CI Drift Detection
|
||||
|
||||
Add a daily check to catch when assembled output diverges from what the profiles would generate:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/ai-instructions-sync.yml
|
||||
name: Check AI Instructions Sync
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 8 * * *' # Daily at 8am
|
||||
push:
|
||||
paths: ['profiles/**', 'modules/**', 'skeleton/**']
|
||||
|
||||
jobs:
|
||||
check-sync:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: npx ts-node sync-ai-instructions.ts --dry-run --check
|
||||
- name: Fail if drift detected
|
||||
run: |
|
||||
git diff --exit-code output/ || \
|
||||
(echo "AI instructions out of sync. Run sync-ai-instructions.ts" && exit 1)
|
||||
```
|
||||
|
||||
This catches two scenarios:
|
||||
1. Someone edited a module but forgot to re-run the assembler
|
||||
2. Someone manually edited an output file instead of the module
|
||||
|
||||
### 5-Step Replication Guide
|
||||
|
||||
1. **Audit**: List everything in your current CLAUDE.md. Tag each line as `universal` (applies to everyone), `conditional` (depends on tool/OS/role), or `personal` (one dev only).
|
||||
|
||||
2. **Extract**: Move each category into a separate file under `modules/`. One file per topic (e.g., `git-workflow.md`, `typescript-rules.md`, `macos-paths.md`).
|
||||
|
||||
3. **Profile**: Create one YAML per developer, listing which modules they need based on their tools, OS, and role.
|
||||
|
||||
4. **Script**: Write an assembler that reads profiles, injects modules into the skeleton, and writes output. Start simple — the example above is production-ready for small teams.
|
||||
|
||||
5. **CI**: Add a daily GitHub Actions job that re-generates all output and runs `git diff --exit-code` to catch drift.
|
||||
|
||||
### When NOT to Use This
|
||||
|
||||
This pattern has real overhead. Be honest about whether you need it:
|
||||
|
||||
| Situation | Recommendation |
|
||||
|-----------|----------------|
|
||||
| Solo developer | Not worth it. One CLAUDE.md is fine. |
|
||||
| Team of 2-3, same tools | Borderline. Use CLAUDE.md precedence rules instead (Section 3.4). |
|
||||
| Team 5+, multi-tool | This pattern pays off. |
|
||||
| Rapidly changing instructions | High maintenance cost. Stabilize your rules first, then modularize. |
|
||||
| Simple projects (<3 months) | Overkill. Use a shared CLAUDE.md. |
|
||||
|
||||
The break-even point is roughly **3+ developers with 2+ different AI tools**. Below that, the file management overhead exceeds the benefits.
|
||||
|
||||
> For the full step-by-step implementation workflow, see [Team AI Instructions](workflows/team-ai-instructions.md).
|
||||
|
||||
---
|
||||
|
||||
# 4. Agents
|
||||
|
||||
_Quick jump:_ [What Are Agents](#41-what-are-agents) · [Creating Custom Agents](#42-creating-custom-agents) · [Agent Template](#43-agent-template) · [Best Practices](#44-best-practices) · [Agent Examples](#45-agent-examples)
|
||||
|
|
@ -10117,6 +10374,43 @@ Servers can work together:
|
|||
4. Playwright → Test the implementation
|
||||
```
|
||||
|
||||
### Production Case Study: Multi-System Support Investigator
|
||||
|
||||
**Context**: Mergify (CI/CD automation platform) needed to triage support tickets across 5 disconnected systems — a manual 15-minute process per ticket.
|
||||
|
||||
**Architecture**: Claude Code as orchestrator + 5 custom MCP servers as system adapters:
|
||||
|
||||
```
|
||||
Support ticket received
|
||||
│
|
||||
▼
|
||||
┌───────────────┐
|
||||
│ Claude Code │ ← orchestrates, synthesizes, produces report
|
||||
└───────┬───────┘
|
||||
│ parallel fan-out
|
||||
├──────────────────┬──────────────────┬──────────────────┬──────────────────┐
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
┌─────────────┐ ┌─────────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Datadog │ │ Sentry │ │ PostgreSQL │ │ Linear │ │ GitHub │
|
||||
│ (metrics, │ │ (errors, perf │ │ (customer │ │ (tickets, │ │ (source, │
|
||||
│ traces) │ │ regressions) │ │ data, DB) │ │ history) │ │ recent PRs) │
|
||||
└─────────────┘ └─────────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**Key design decisions:**
|
||||
- MCP servers handle auth/credentials — Claude Code sees only clean interfaces
|
||||
- Queries execute **in parallel**, not sequentially → majority of the time savings
|
||||
- Human investigators review Claude's structured report, not raw data
|
||||
- One dedicated repo for all MCP server implementations + system prompt
|
||||
|
||||
**Results** (self-reported by Mergify, Nov 2025):
|
||||
- Triage time: ~15 min → <5 min (⅔ reduction)
|
||||
- First-pass accuracy: 75% (25% still require human follow-up)
|
||||
|
||||
**Key takeaway**: This pattern — Claude Code as operational orchestrator with domain-specific MCP adapters — applies to any ops/support team juggling multiple disconnected systems. It's distinct from "Claude Code as dev tool": here Claude runs in a **production workflow**, not an IDE.
|
||||
|
||||
> Source: [Mergify blog — "How We Turned Claude Into a Cross-System Support Investigator"](https://mergify.com/blog/how-we-turned-claude-into-a-cross-system-support-investigator) (Julian Maurin, Nov 2025)
|
||||
|
||||
## 8.5 Plugin System
|
||||
|
||||
Claude Code includes a comprehensive **plugin system** that allows you to extend functionality through community-created or custom plugins and marketplaces.
|
||||
|
|
@ -13390,6 +13684,8 @@ You: "Implement the caching layer following the plan"
|
|||
|
||||
Note: These are loaded **once at session start**, not per request. A 200-line CLAUDE.md costs ~2K tokens upfront but doesn't grow during the session. The concern is the cumulative effect when combined with multiple `@includes` and all files in `.claude/rules/`.
|
||||
|
||||
> **Important**: Beyond file size, context files containing non-essential information (style guides, architecture descriptions, general conventions) add **+20-23% inference cost per session** regardless of line count — because agents process and act on every instruction. ([Gloaguen et al., 2026](https://arxiv.org/abs/2602.11988))
|
||||
|
||||
> **See also**: [Memory Loading Comparison](#memory-loading-comparison) for when each method loads.
|
||||
|
||||
**1. Keep CLAUDE.md files concise:**
|
||||
|
|
@ -13406,6 +13702,8 @@ Note: These are loaded **once at session start**, not per request. A 200-line CL
|
|||
- Split by concern: team rules in project CLAUDE.md, personal prefs in ~/.claude/CLAUDE.md
|
||||
```
|
||||
|
||||
> **Research note** (Gloaguen et al., ETH Zürich, Feb 2026 — 138 benchmarks, 12 repos): The first empirical study on context files shows developer-written CLAUDE.md improves agent success rate by **+4%**, but LLM-generated files reduce it by **-3%**. Cause: agents faithfully follow all instructions, even those irrelevant to the task, leading to broader file exploration and longer reasoning chains. **Recommendation: include only build/test commands and project-specific tooling.** Style guides and architecture descriptions belong in separate docs. ([Full evaluation](../docs/resource-evaluations/agents-md-empirical-study-2602-11988.md))
|
||||
|
||||
**2. Use targeted file references:**
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -65,6 +65,12 @@ Use existing battle-tested repositories as scaffolding for new projects.
|
|||
|
||||
**When to use**: Starting new projects, standardizing team patterns, rapid prototyping from proven foundations
|
||||
|
||||
### [Team AI Instructions](./team-ai-instructions.md)
|
||||
|
||||
Scale CLAUDE.md across a multi-developer, multi-tool team with profile-based module assembly.
|
||||
|
||||
**When to use**: Team 5+ devs, multiple AI tools (Claude Code + Cursor/Windsurf), mixed OS
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Design & Content
|
||||
|
|
@ -112,6 +118,7 @@ Systematically explore and understand unfamiliar codebases.
|
|||
| **UI implementation** | [Design to Code](./design-to-code.md) |
|
||||
| **Code quality** | [Iterative Refinement](./iterative-refinement.md) |
|
||||
| **New project from template** | [Skeleton Projects](./skeleton-projects.md) |
|
||||
| **Team AI instructions** | [Team AI Instructions](./team-ai-instructions.md) |
|
||||
| **Documentation** | [PDF Generation](./pdf-generation.md) |
|
||||
| **Audio feedback** | [TTS Setup](./tts-setup.md) |
|
||||
|
||||
|
|
@ -132,4 +139,4 @@ New workflow ideas? Open an issue or PR in the main repository.
|
|||
|
||||
---
|
||||
|
||||
**Last updated**: January 2026
|
||||
**Last updated**: February 2026
|
||||
|
|
|
|||
|
|
@ -16,12 +16,13 @@ Define what you want in CLAUDE.md BEFORE asking Claude to build. One well-struct
|
|||
|
||||
1. [TL;DR](#tldr)
|
||||
2. [The Pattern](#the-pattern)
|
||||
3. [CLAUDE.md Spec Templates](#claudemd-spec-templates)
|
||||
4. [Step-by-Step Workflow](#step-by-step-workflow)
|
||||
5. [Integration with Tools](#integration-with-tools)
|
||||
6. [When to Use](#when-to-use)
|
||||
7. [Anti-Patterns](#anti-patterns)
|
||||
8. [See Also](#see-also)
|
||||
3. [Task Granularity: Sizing Work for Agents](#task-granularity-sizing-work-for-agents)
|
||||
4. [CLAUDE.md Spec Templates](#claudemd-spec-templates)
|
||||
5. [Step-by-Step Workflow](#step-by-step-workflow)
|
||||
6. [Integration with Tools](#integration-with-tools)
|
||||
7. [When to Use](#when-to-use)
|
||||
8. [Anti-Patterns](#anti-patterns)
|
||||
9. [See Also](#see-also)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -58,6 +59,41 @@ The spec becomes the source of truth that:
|
|||
|
||||
---
|
||||
|
||||
## Task Granularity: Sizing Work for Agents
|
||||
|
||||
Before writing the spec, verify the task is the right size. Agents work best with **vertical slices** — thin, end-to-end units that cut through all layers but implement exactly one complete user behavior (e.g. "password reset via email", not "authentication system").
|
||||
|
||||
**Rule of thumb**: One agent session = one vertical slice. If the task description requires "and" between two user behaviors, split it.
|
||||
|
||||
### PRD Quality Checklist
|
||||
|
||||
Run this before handing any task to an agent. Six dimensions to verify:
|
||||
|
||||
| Dimension | Question to ask | Red flag |
|
||||
|-----------|----------------|----------|
|
||||
| **Problem Clarity** | Is the problem statement unambiguous? | "Improve performance" |
|
||||
| **Testable Criteria** | Can completion be verified automatically? | "Works well" |
|
||||
| **Scope Boundaries** | What is explicitly OUT of scope? | Nothing listed as excluded |
|
||||
| **Observable Done** | What does "done" look like to a user? | Internal-only description |
|
||||
| **Requirements Clarity** | No implementation details in the spec? | "Use Redis for caching" |
|
||||
| **Terminology** | Same terms used throughout? | "user" and "account" mixed |
|
||||
|
||||
A task that fails 2+ dimensions needs rework before an agent touches it. The spec review catches ambiguity that will otherwise surface as incorrect implementation mid-session.
|
||||
|
||||
```
|
||||
❌ Too big, ambiguous:
|
||||
"Add user authentication to the app"
|
||||
|
||||
✅ One vertical slice:
|
||||
"Users can log in with email + password.
|
||||
- POST /auth/login returns JWT on success, 401 on failure
|
||||
- Invalid credentials show 'Email or password incorrect' (not which is wrong)
|
||||
- Session expires after 24h
|
||||
- Out of scope: OAuth, password reset, remember me"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md Spec Templates
|
||||
|
||||
### Feature Spec (Most Common)
|
||||
|
|
@ -828,3 +864,4 @@ Claude: Reads CLAUDE.md + @CLAUDE-api.md (relevant context only)
|
|||
- [Spec Kit Documentation](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
|
||||
- [OpenSpec Documentation](https://github.com/Fission-AI/OpenSpec)
|
||||
- [tdd-with-claude.md](./tdd-with-claude.md) — Combine with TDD
|
||||
- [Spec-to-Code Factory](https://github.com/SylvainChabaud/spec-to-code-factory) — Implémentation référence complète avec enforcement outillé (6 gates via Node.js, invariants "No Spec No Code" + "No Task No Commit", ~900K tokens/projet)
|
||||
|
|
|
|||
331
guide/workflows/team-ai-instructions.md
Normal file
331
guide/workflows/team-ai-instructions.md
Normal file
|
|
@ -0,0 +1,331 @@
|
|||
---
|
||||
title: "Team AI Instructions Management"
|
||||
description: "Scale CLAUDE.md across a multi-developer team using Profile-Based Module Assembly"
|
||||
tags: [workflow, team, claude-md, configuration]
|
||||
---
|
||||
|
||||
# Team AI Instructions Management
|
||||
|
||||
Manage AI instructions (CLAUDE.md, .cursorrules) across a team without fragmentation.
|
||||
|
||||
**Pattern**: Profile-Based Module Assembly — shared modules + per-dev profiles + automated assembler.
|
||||
|
||||
**When to use**: Team 5+ developers, multiple AI tools (Claude Code + Cursor/Windsurf), mixed OS.
|
||||
**Skip if**: Solo developer, homogeneous team (same tool, same OS), short project (<3 months).
|
||||
|
||||
---
|
||||
|
||||
## The Problem: N x M x P Fragmentation
|
||||
|
||||
When a team grows, AI instructions fragment fast:
|
||||
|
||||
| Factor | Values | Example |
|
||||
|--------|--------|---------|
|
||||
| **N developers** | 5-20 | Alice, Bob, Charlie... |
|
||||
| **M tools** | 2-4 | Claude Code, Cursor, Windsurf, Copilot |
|
||||
| **P operating systems** | 2-3 | macOS, Linux, WSL |
|
||||
|
||||
**Total variants**: N x M x P = 5 x 3 x 2 = **30 possible configurations**.
|
||||
|
||||
Without a system, what happens:
|
||||
|
||||
```
|
||||
Week 1: Team agrees on shared CLAUDE.md
|
||||
Week 3: Alice adds TypeScript strict rules locally
|
||||
Week 5: Bob copies Alice's file, removes half the rules
|
||||
Week 8: New hire Charlie gets Bob's outdated copy
|
||||
Week 12: 5 developers, 5 different CLAUDE.md files, nobody knows what's canonical
|
||||
```
|
||||
|
||||
**Root cause**: CLAUDE.md is treated as a monolithic file instead of a composed configuration.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
profiles/ modules/
|
||||
├── alice.yaml ├── core-standards.md
|
||||
├── bob.yaml ├── git-workflow.md
|
||||
├── charlie.yaml ├── typescript-rules.md
|
||||
│ ├── test-conventions.md
|
||||
│ ├── macos-paths.md
|
||||
│ ├── linux-paths.md
|
||||
│ ├── cursor-rules.md
|
||||
│ └── communication-verbose.md
|
||||
│
|
||||
├── skeleton/
|
||||
│ └── claude-skeleton.md ← Template with {{MODULE:name}} placeholders
|
||||
│
|
||||
└── sync-ai-instructions.ts ← Reads profile → injects modules → writes output
|
||||
│
|
||||
▼
|
||||
output/
|
||||
├── alice/CLAUDE.md ← Generated (read-only)
|
||||
├── bob/CLAUDE.md
|
||||
└── charlie/CLAUDE.md
|
||||
```
|
||||
|
||||
**Flow**: Profile (YAML) + Skeleton (template) + Modules (fragments) → Assembler → Generated CLAUDE.md
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Audit Your Current CLAUDE.md
|
||||
|
||||
**Goal**: Classify every line as universal, conditional, or personal.
|
||||
|
||||
```markdown
|
||||
# Audit template
|
||||
|
||||
## Universal (all devs, all tools)
|
||||
- Architecture: hexagonal
|
||||
- Tests: must pass before PR
|
||||
- Naming: kebab-case for files
|
||||
|
||||
## Conditional (depends on tool or OS)
|
||||
- Cursor: use @filename syntax → module: cursor-rules
|
||||
- macOS paths: /opt/homebrew → module: macos-paths
|
||||
- Linux paths: /usr/local → module: linux-paths
|
||||
|
||||
## Personal (individual preference)
|
||||
- Style: verbose explanations → profile preference
|
||||
- Language: French comments → profile preference
|
||||
```
|
||||
|
||||
**Command to measure**:
|
||||
```bash
|
||||
wc -l CLAUDE.md # Total lines before modularization
|
||||
# Tag each line with [U]niversal, [C]onditional, [P]ersonal
|
||||
# Count by category to estimate module split
|
||||
```
|
||||
|
||||
**Typical result**: 60% universal, 25% conditional, 15% personal.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Extract Modules
|
||||
|
||||
**Goal**: One `.md` file per thematic group.
|
||||
|
||||
**Recommended structure**:
|
||||
|
||||
```
|
||||
modules/
|
||||
├── core-standards.md # Architecture, naming, patterns (all devs)
|
||||
├── git-workflow.md # Git conventions (all devs)
|
||||
├── typescript-rules.md # TS strict config (if TypeScript)
|
||||
├── test-conventions.md # Testing patterns (all devs)
|
||||
├── macos-paths.md # macOS-specific paths (if macOS)
|
||||
├── linux-paths.md # Linux paths (if Linux)
|
||||
├── cursor-rules.md # Cursor-specific rules (if Cursor)
|
||||
└── communication-verbose.md # Verbose explanation style (if preferred)
|
||||
```
|
||||
|
||||
**Module format** (each module is a standalone Markdown fragment):
|
||||
|
||||
```markdown
|
||||
<!-- modules/typescript-rules.md -->
|
||||
## TypeScript Rules
|
||||
|
||||
- Use strict mode: `"strict": true` in tsconfig
|
||||
- Prefer `type` over `interface` for unions
|
||||
- No `any` — use `unknown` + type guards
|
||||
- Zod for runtime validation at boundaries
|
||||
```
|
||||
|
||||
**Guidelines**:
|
||||
- Keep modules self-contained (no cross-references between modules)
|
||||
- 15-50 lines per module is the sweet spot
|
||||
- Name modules for their domain, not their audience
|
||||
- One module = one reason to change
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Create Developer Profiles
|
||||
|
||||
**Goal**: One YAML per developer, listing their modules.
|
||||
|
||||
```yaml
|
||||
# profiles/alice.yaml
|
||||
name: "Alice"
|
||||
os: "macos"
|
||||
tools:
|
||||
- claude-code
|
||||
- cursor
|
||||
communication_style: "concise"
|
||||
modules:
|
||||
core:
|
||||
- core-standards
|
||||
- git-workflow
|
||||
- typescript-rules
|
||||
- test-conventions
|
||||
conditional:
|
||||
- macos-paths # auto-included when os: macos
|
||||
- cursor-rules # auto-included when cursor in tools
|
||||
preferences:
|
||||
language: "english"
|
||||
```
|
||||
|
||||
**Profile rules**:
|
||||
- `core` modules: included for every dev (team standards)
|
||||
- `conditional` modules: included based on `os` and `tools` fields
|
||||
- `preferences`: personal settings injected into skeleton variables
|
||||
|
||||
**Template for new team members**: See [profile-template.yaml](../../examples/team-config/profile-template.yaml)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Write the Assembler Script
|
||||
|
||||
**Goal**: Script that reads profile, injects modules, outputs CLAUDE.md.
|
||||
|
||||
```typescript
|
||||
// sync-ai-instructions.ts (simplified ~30 lines)
|
||||
import { readFileSync, writeFileSync, mkdirSync } from 'fs';
|
||||
import { parse } from 'yaml';
|
||||
import { join } from 'path';
|
||||
|
||||
const profile = parse(readFileSync(`profiles/${process.argv[2]}.yaml`, 'utf8'));
|
||||
let skeleton = readFileSync('skeleton/claude-skeleton.md', 'utf8');
|
||||
|
||||
// Collect modules from profile
|
||||
const modules = [...profile.modules.core, ...profile.modules.conditional];
|
||||
|
||||
// Replace each placeholder with module content
|
||||
for (const mod of modules) {
|
||||
const content = readFileSync(`modules/${mod}.md`, 'utf8');
|
||||
skeleton = skeleton.replace(`{{MODULE:${mod}}}`, content);
|
||||
}
|
||||
|
||||
// Remove unused placeholders
|
||||
skeleton = skeleton.replace(/\{\{MODULE:\w+\}\}/g, '');
|
||||
|
||||
// Write output
|
||||
const outDir = `output/${process.argv[2]}`;
|
||||
mkdirSync(outDir, { recursive: true });
|
||||
writeFileSync(join(outDir, 'CLAUDE.md'), skeleton);
|
||||
console.log(`Generated ${outDir}/CLAUDE.md (${modules.length} modules)`);
|
||||
```
|
||||
|
||||
**Run**:
|
||||
```bash
|
||||
npx ts-node sync-ai-instructions.ts alice # Single dev
|
||||
npx ts-node sync-ai-instructions.ts --all # Generate all profiles
|
||||
npx ts-node sync-ai-instructions.ts --check # Verify no drift
|
||||
```
|
||||
|
||||
Full template: [sync-script.ts](../../examples/team-config/sync-script.ts)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: CI Drift Detection
|
||||
|
||||
**Goal**: Catch when output files are out of sync with profiles/modules.
|
||||
|
||||
```yaml
|
||||
# .github/workflows/ai-instructions-check.yml
|
||||
name: AI Instructions Drift Check
|
||||
on:
|
||||
push:
|
||||
paths:
|
||||
- 'modules/**'
|
||||
- 'profiles/**'
|
||||
- 'skeleton/**'
|
||||
schedule:
|
||||
- cron: '0 9 * * 1-5' # Weekdays at 9am
|
||||
|
||||
jobs:
|
||||
check-drift:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: npx ts-node sync-ai-instructions.ts --check
|
||||
- name: Fail if drift detected
|
||||
run: |
|
||||
if git diff --quiet output/; then
|
||||
echo "No drift detected"
|
||||
else
|
||||
echo "::error::AI instructions are out of sync!"
|
||||
git diff output/
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
**What it detects**:
|
||||
- A module was edited but the assembler wasn't re-run
|
||||
- A profile was added but no output CLAUDE.md exists
|
||||
- A dev manually edited their generated CLAUDE.md
|
||||
|
||||
**Policy**: Generated files are read-only. All changes go through profiles/modules, then re-run the assembler.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Onboarding New Developers
|
||||
|
||||
**Goal**: New dev gets their CLAUDE.md in under 5 minutes.
|
||||
|
||||
```bash
|
||||
# 1. Clone repo
|
||||
git clone <repo>
|
||||
|
||||
# 2. Copy profile template
|
||||
cp examples/team-config/profile-template.yaml profiles/dave.yaml
|
||||
# Edit: name, os, tools, modules
|
||||
|
||||
# 3. Generate
|
||||
npx ts-node sync-ai-instructions.ts dave
|
||||
|
||||
# 4. Install
|
||||
cp output/dave/CLAUDE.md .claude/CLAUDE.md
|
||||
```
|
||||
|
||||
**CLAUDE.md placement reminder**:
|
||||
- Project-wide: `project/CLAUDE.md` (committed, for team conventions)
|
||||
- Personal overrides: `.claude/CLAUDE.md` (gitignored, for individual preferences)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Cause | Fix |
|
||||
|---------|-------|-----|
|
||||
| Generated file too long | Too many modules included | Review profile: remove rarely-used modules |
|
||||
| Module missing in output | Placeholder typo in skeleton | Check `{{MODULE:name}}` matches filename |
|
||||
| CI drift alert | Output not regenerated after module edit | Run `sync-ai-instructions.ts` and commit |
|
||||
| Dev A has rules Dev B doesn't | Expected — it's the point | Verify profile is correct for that dev |
|
||||
| Stale output after merge | Merge didn't trigger regeneration | Run assembler post-merge (add git hook) |
|
||||
|
||||
---
|
||||
|
||||
## Scaling Thresholds
|
||||
|
||||
| Team size | Approach |
|
||||
|-----------|----------|
|
||||
| 1-2 devs | Shared CLAUDE.md + precedence rules ([Section 3.4](../ultimate-guide.md#34-precedence-rules)) |
|
||||
| 3-5 devs, same tools | Optional: modules only, no profiles |
|
||||
| 5+ devs or multi-tool | Profile-Based Module Assembly (this workflow) |
|
||||
| 20+ devs | Consider a CLAUDE.md config server + PR-based module changes |
|
||||
|
||||
---
|
||||
|
||||
## Measured Results
|
||||
|
||||
From a production team (5 developers, 3 tools, 2 OS):
|
||||
|
||||
| Metric | Before | After |
|
||||
|--------|--------|-------|
|
||||
| Lines per CLAUDE.md | ~380 (monolithic) | ~185 (assembled) |
|
||||
| Token reduction | — | 59% less context consumed |
|
||||
| Modules extracted | 0 | 12 |
|
||||
| Onboarding time | "copy someone's file" | 5 min (template + generate) |
|
||||
| Drift incidents | Weekly | 0 (CI catches) |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Section 3.5 Team Configuration at Scale](../ultimate-guide.md#35-team-configuration-at-scale) — Concept overview and measured results
|
||||
- [Section 3.4 Precedence Rules](../ultimate-guide.md#34-precedence-rules) — How Claude reads multiple CLAUDE.md files
|
||||
- [profile-template.yaml](../../examples/team-config/profile-template.yaml) — Profile template
|
||||
- [claude-skeleton.md](../../examples/team-config/claude-skeleton.md) — Skeleton template
|
||||
- [sync-script.ts](../../examples/team-config/sync-script.ts) — Full assembler script
|
||||
|
|
@ -41,6 +41,16 @@ deep_dive:
|
|||
rules_code_quality_review: "examples/rules/code-quality-review.md"
|
||||
rules_test_review: "examples/rules/test-review.md"
|
||||
rules_performance_review: "examples/rules/performance-review.md"
|
||||
# Team Configuration at Scale (Profile-Based Module Assembly)
|
||||
team_ai_instructions_section: "guide/ultimate-guide.md#35-team-configuration-at-scale"
|
||||
team_ai_instructions_workflow: "guide/workflows/team-ai-instructions.md"
|
||||
team_ai_instructions_profile_template: "examples/team-config/profile-template.yaml"
|
||||
team_ai_instructions_skeleton: "examples/team-config/claude-skeleton.md"
|
||||
team_ai_instructions_sync_script: "examples/team-config/sync-script.ts"
|
||||
team_ai_instructions_pattern: "profiles YAML + shared modules + skeleton + assembler script"
|
||||
team_ai_instructions_problem: "N devs × M tools × P OS = fragmented AI instructions"
|
||||
team_ai_instructions_token_savings: "59% context token reduction (measured, 5-dev team)"
|
||||
team_ai_instructions_threshold: "Team 5+ devs with multiple AI tools"
|
||||
# Known Issues & Critical Bugs (verified community reports)
|
||||
known_issues: "guide/known-issues.md"
|
||||
known_issues_github_bug: "guide/known-issues.md:16" # GitHub auto-creation bug
|
||||
|
|
@ -716,6 +726,9 @@ deep_dive:
|
|||
spec_osmani_source: "https://addyosmani.com/blog/good-spec/"
|
||||
spec_osmani_evaluation: "docs/resource-evaluations/addy-osmani-good-spec.md"
|
||||
spec_osmani_score: "4/5"
|
||||
spec_task_granularity: "guide/workflows/spec-first.md:62" # Vertical slices + PRD checklist (Allan Hill, Feb 2026)
|
||||
spec_prd_checklist: "guide/workflows/spec-first.md:70" # 6-dimension PRD quality checklist
|
||||
atdd_with_agents: "guide/methodologies.md:180" # ATDD + Gherkin for agentic workflows
|
||||
commands_table: 10213
|
||||
shortcuts_table: 10246
|
||||
troubleshooting: 10372
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue