From 6d847d24dea5cb3d39fe0240b650ef490bf41a86 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Fri, 20 Feb 2026 15:04:29 +0100 Subject: [PATCH] docs: add Profile-Based Module Assembly pattern (Section 3.5) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CHANGELOG.md | 58 +++ README.md | 14 +- ...allanhillgeek-decomposition-agentic-dev.md | 147 ++++++++ .../agents-md-empirical-study-2602-11988.md | 130 +++++++ .../sylvain-chabaud-spec-to-code-factory.md | 144 ++++++++ examples/team-config/claude-skeleton.md | 75 ++++ examples/team-config/profile-template.yaml | 41 +++ examples/team-config/sync-script.ts | 213 +++++++++++ guide/methodologies.md | 20 ++ guide/ultimate-guide.md | 298 ++++++++++++++++ guide/workflows/README.md | 9 +- guide/workflows/spec-first.md | 49 ++- guide/workflows/team-ai-instructions.md | 331 ++++++++++++++++++ machine-readable/reference.yaml | 13 + 14 files changed, 1528 insertions(+), 14 deletions(-) create mode 100644 docs/resource-evaluations/2026-02-19-allanhillgeek-decomposition-agentic-dev.md create mode 100644 docs/resource-evaluations/agents-md-empirical-study-2602-11988.md create mode 100644 docs/resource-evaluations/sylvain-chabaud-spec-to-code-factory.md create mode 100644 examples/team-config/claude-skeleton.md create mode 100644 examples/team-config/profile-template.yaml create mode 100644 examples/team-config/sync-script.ts create mode 100644 guide/workflows/team-ai-instructions.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a4dffaf..fb36e94 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index c883611..7321b26 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Stars Last Update Quiz - Templates + Templates Threat Database

@@ -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
Root] root --> guide[📖 guide/
19K lines] - root --> examples[📋 examples/
161 templates] + root --> examples[📋 examples/
164 templates] root --> quiz[🧠 quiz/
274 questions] root --> tools[🔧 tools/
utils] root --> machine[🤖 machine-readable/
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 |
-Examples Library (161 templates) +Examples Library (164 templates) **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* + + + + +--- + +## 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}} diff --git a/examples/team-config/profile-template.yaml b/examples/team-config/profile-template.yaml new file mode 100644 index 0000000..912cce7 --- /dev/null +++ b/examples/team-config/profile-template.yaml @@ -0,0 +1,41 @@ +# examples/team-config/profile-template.yaml +# Profile template for Profile-Based Module Assembly +# Copy to profiles/.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 diff --git a/examples/team-config/sync-script.ts b/examples/team-config/sync-script.ts new file mode 100644 index 0000000..44663e7 --- /dev/null +++ b/examples/team-config/sync-script.ts @@ -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// 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 = { + '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 = { + 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 `` + } + 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) diff --git a/guide/methodologies.md b/guide/methodologies.md index 04a3bee..952725c 100644 --- a/guide/methodologies.md +++ b/guide/methodologies.md @@ -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) diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 8acdf8b..85a7320 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -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 diff --git a/guide/workflows/README.md b/guide/workflows/README.md index 9599cbc..e76751c 100644 --- a/guide/workflows/README.md +++ b/guide/workflows/README.md @@ -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 diff --git a/guide/workflows/spec-first.md b/guide/workflows/spec-first.md index 5d3c137..4e0ee54 100644 --- a/guide/workflows/spec-first.md +++ b/guide/workflows/spec-first.md @@ -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) diff --git a/guide/workflows/team-ai-instructions.md b/guide/workflows/team-ai-instructions.md new file mode 100644 index 0000000..2d0a9dd --- /dev/null +++ b/guide/workflows/team-ai-instructions.md @@ -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 + +## 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 + +# 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 diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 92f84aa..c3c2b25 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -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