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 2026-02-20 15:04:29 +01:00
parent 146d15e958
commit 6d847d24de
14 changed files with 1528 additions and 14 deletions

View file

@ -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)