[CLAUDE] Skill: Setup multi-agent infrastructure (Investigator + Implementer + Reviewer)

Session 20 turn 12: User paste self-contained template setup multi-agent từ NAMGROUP s41-s43 trial (empirical-grounded Anthropic Building Effective Agents + Cognition "writes single-threaded"). Pre-flight decision gate 6/6 pass → proceed setup. ### Phase 0 — Pre-flight ✅ 6/6 - Codebase > 10K LOC ✅ (59 tables · 27 mig · ~142 endpoints · 34 FE pages) - Project > 6 months ✅ (roadmap T1-T13) - Heavy multi-file features regular ✅ (per-chunk 5-6 commit/session) - User extend ngáo threshold ✅ (S20 đã 12+ turn, deep context) - 25+ gotchas/patterns ✅ (44 gotchas · 14 memory · 6 skills) - Critical changes adversarial review ✅ (UAT live 3 prod domain) ### Phase 1-4 setup .claude/ ├── agents/ │ ├── README.md (master coordination guide ~9.7KB) │ ├── investigator.md (READ — research + audit + WebFetch ~7.3KB) │ ├── implementer.md (WRITE conditional Case 1+2+3+5 ~8.4KB) │ └── reviewer.md (READ adversarial pre-commit + live curl ~9.6KB) └── agent-memory/ ├── investigator/MEMORY.md (seed ~5.9KB) ├── implementer/MEMORY.md (seed ~6.9KB) └── reviewer/MEMORY.md (seed ~6.5KB) ### Customizations per SOLUTION_ERP - Stack: .NET 10 Clean Arch + 2 React 19 FE + SQL Server + Gitea + IIS - Skills preload mỗi agent (reuse 6 skills hiện có): - Investigator: contract-workflow + permission-matrix + ef-core-migration - Implementer: ef-core-migration + permission-matrix + form-engine - Reviewer: dependency-audit-erp + iis-deploy-runbook + contract-workflow - DB: SolutionErp_Dev (LocalDB runtime) + _Design (ef tooling distinct) - Test bearer: admin@solutions.com.vn / Admin@123456 (full) + nv.test@solutions.com.vn / TestUser@123456 (Drafter UAT scope) - Prod UAT: api/admin/eoffice.solutions.com.vn ### Windows MAX_PATH pitfall handled Project path D:\Dropbox\CONG_VIEC\SOLUTION\SOLUTION_ERP\ = 51 chars + nested Dropbox-managed → `isolation: worktree` DROPPED khỏi implementer.md frontmatter per template Pitfall 1. Em main reviews diff before commit (compensate). ### Memory baseline seeded 3 MEMORY.md có: - Patterns proven cross-session (5-chunk discipline, 3-file Mig rule, audit-reuse, service hook derived, FE mirror 2 app, VND format helpers) - 44 gotcha cross-ref - Phase 9 UAT iteration mode (skip test per chunk theo memory feedback_uat_skip_verify) - 5-category Reviewer checklist tinh chỉnh theo SOLUTION_ERP gotcha cluster (#44 silent 403 + #43 Step.Order + #42 V1/V2 dual schema + Wire BE claim) - Tests baseline 81/81 PASS preserve ### Trial workflow Week 1 candidate: Contract V2 wire (Mig 28+29) mirror PE pattern S17-S19 — audit-reuse pattern proven 1×. ~600+ LOC, 2 mig + Service + Controller + FE × 2 app. Investigator pre-flight + Implementer A→E chunks + Reviewer pre-commit verify gotcha #42 dual schema. Em main spawn first time qua /agents command. Pattern tracking ROI 4 tuần trial (week 4 evaluate keep / tune / archive). ### Acceptance criteria 7/7 ✅ - 4 agent .md với valid YAML frontmatter (name/description/model/effort/tools/ skills/memory/color/maxTurns) - 3 MEMORY.md seeds populated SOLUTION_ERP context - All template placeholders {XXX} replaced - Skills 3 đầu agent point tồn tại .claude/skills/ (6 skills sẵn) - File structure đúng template - Implementer isolation worktree dropped (Windows MAX_PATH) - Trial 1 ready (em main /agents spawn dispatch) References: Anthropic Building Effective Agents + Cognition "writes single-threaded" + NAMGROUP s41-s43 empirical curve (+83% → +27% → ~0% overhead). Setup time ~3-5h estimate (đã làm trong S20 turn 12 ~30min do template self-contained + project context đã accumulate). Path filter CI sẽ skip (.claude/skills/** trong paths-ignore, mirror cho .claude/agents/** + .claude/agent-memory/** thực tế cũng docs-class). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 21:09:46 +07:00
parent 6e338f745e
commit ae1814cdba
7 changed files with 1279 additions and 0 deletions
--- a/.claude/agents/README.md
+++ b/.claude/agents/README.md
@ -0,0 +1,207 @@
+# Multi-agent SOLUTION_ERP — Master Coordination Guide
+
+> **Architecture:** 3 sub-agents Opus 4.7 1M Max + em main coordinator.
+> Pattern: Anthropic Building Effective Agents orchestrator-workers + Cognition "writes single-threaded" hybrid.
+> Setup: Session 20 turn 12 (2026-05-11) — empirical-grounded từ NAMGROUP s41-s43 trial curve.
+
+---
+
+## 🎯 Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ EM (Main) — Opus 4.7 1M Max                             │
+│ • Reasoning + write code (single-threaded principle)    │
+│ • User dialog + architectural decisions                 │
+│ • Coordinate 3 sub-agents via SendMessage               │
+│ • Synthesize cross-agent findings end-of-session        │
+└─────────────────────────────────────────────────────────┘
+                ↓ spawn + keep-alive (Opus 4.7 1M Max each)
+  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+  │ Investigator │  │  Implementer │  │   Reviewer   │
+  │   READ only  │  │  WRITE strict│  │   READ only  │
+  │              │  │ classification│  │              │
+  │  Research +  │  │ Cookie-cutter│  │ Adversarial  │
+  │   Audit +    │  │  + Multi-file│  │ pre-commit + │
+  │   External   │  │  independent │  │ live verify  │
+  │   research   │  │     ONLY     │  │              │
+  └──────────────┘  └──────────────┘  └──────────────┘
+        cyan             yellow              red
+```
+
+---
+
+## 🔄 Invocation decision tree (em main apply)
+
+Task input → classify task type:
+
+```
+├── Read-only research / audit / scan > 5 files / external fetch?
+│     → Spawn Investigator (always safe)
+│
+├── Adversarial pre-commit verify / heavy diff / deploy claim?
+│     → Spawn Reviewer (always before push critical)
+│
+├── Cookie-cutter mechanical (N independent files same pattern, deterministic spec)?
+│     ✓ N >= 5 files
+│     ✓ Spec deterministic (no implicit decisions)
+│     ✓ Pattern proven > 1× prior
+│     → Spawn Implementer (Case 1 Anthropic verified)
+│
+├── Multi-file independent changes (different modifications per file)?
+│     ✓ Each file verifiable independently
+│     ✓ Files NOT cross-stack tight coupling
+│     → Spawn Implementer (Case 2 orchestrator-workers)
+│
+├── Test generation for isolated methods?
+│     → Spawn Implementer (Case 3 verified)
+│
+├── Mass code migration (framework upgrade, per-file deterministic)?
+│     → Spawn Implementer (Case 5 verified)
+│
+├── Quick task < 30 min (overhead spawn không xứng)?
+│     → Em solo direct
+│
+├── Schema design / UX flow / architectural decision / cross-stack tight coupling?
+│     → Em solo (Cognition "writes single-threaded")
+│     → Investigator pre-flight optional
+│     → Reviewer pre-commit always
+│
+└── Bug fix tightly coupled (cross BE/FE/DB, reasoning chain)?
+      → Em solo (Anthropic warning: "tightly interdependent coding")
+      → Investigator pre-flight optional
+      → Reviewer pre-commit always
+```
+
+---
+
+## 📋 Implementer task classification — CRITICAL rules
+
+**Em main MUST self-check before spawning Implementer:**
+
+### ✅ ACCEPT criteria (ALL must be true)
+1. ✅ Spec deterministic (no implicit decisions left for agent)
+2. ✅ Files independent (modifications don't depend on each other)
+3. ✅ Pattern repeatable (proven > 1× prior session — reference memory entries)
+4. ✅ Estimated effort > 30 min (overhead worth)
+5. ✅ Max 2 layers cross-stack (NOT BE entity + DTO + FE wire 3-layer)
+6. ✅ Each file output verifiable independently
+
+### ❌ REFUSE criteria (ANY triggers refusal)
+1. ❌ Schema design decisions needed
+2. ❌ UX flow decisions needed
+3. ❌ Cross-stack > 2 layers tight coupling
+4. ❌ Bug fix involving reasoning chain
+5. ❌ Integration testing involving multiple components
+6. ❌ < 30 min trivial task
+7. ❌ First time pattern (no prior precedent)
+8. ❌ Spec ambiguity > 20%
+
+**Implementer agent ALSO has self-check trong system prompt → auto-refuse out-of-scope.**
+
+---
+
+## 💾 Memory consult discipline
+
+Each agent has `.claude/agent-memory/<name>/MEMORY.md` persistent diary:
+
+- **Spawn:** Auto-inject first 200 lines / 25KB của MEMORY.md
+- **During work:** Agent may Read full MEMORY.md if task complex
+- **Before return:** Agent MUST update MEMORY.md với findings (BẮT BUỘC)
+- **Cross-session:** MEMORY.md persists on disk
+
+**Em main routine end-of-session:**
+
+```
+SendMessage Investigator: "Flush MEMORY.md với findings session này. Format:
+  1-2 sentences per finding. Categories: patterns / anti-patterns / gotchas
+  discovered / external research summary."
+
+SendMessage Implementer: "Flush MEMORY.md với patterns applied + ambiguities
+  encountered + scope refusals."
+
+SendMessage Reviewer: "Flush MEMORY.md với anti-patterns observed + gotcha
+  regressions caught + claim verification results."
+
+Em read 3 MEMORY.md updates → synthesize cross-agent learnings → integrate
+  vào project memory / session log.
+
+Em proceed normal close-out: STATUS update + commit + push.
+```
+
+---
+
+## 🛠️ SendMessage discipline
+
+**Cost optimization:**
+- Within 5min cache TTL window khi possible (90% discount cached prefix)
+- Compact prompts (~5K new content each) thay vì dump (~24K)
+- Skip spawn cho task < 30min
+
+**Context discovery preservation:**
+- Include explicit "Include surprising findings + edge cases discovered" trong spec
+- Periodic checkpoint mỗi 1-2h heavy work: prompt agents flush MEMORY.md
+- Session crash → MEMORY.md preserved on disk, in-session context lost
+
+---
+
+## 🎯 Project-specific tunings (SOLUTION_ERP)
+
+**Stack:** .NET 10 Clean Architecture + CQRS MediatR + EF Core 10 + SQL Server + 2 React 19 Vite 8 FE (admin + user) + Gitea Actions CI + Windows IIS.
+
+**Current state (Session 20 turn 12):** 27 migrations · 59 DB tables · ~142 endpoints · 34 FE pages · 81 test pass · 44 gotchas · 14 memory entries · 6 skills · 30 demo user · 3 prod domain `*.solutions.com.vn`.
+
+**Skills preload mỗi sub-agent:**
+- **Investigator:** `contract-workflow` + `permission-matrix` + `ef-core-migration` (research patterns + schema audit)
+- **Implementer:** `ef-core-migration` + `permission-matrix` + `form-engine` (scaffold + 3-file rule + permission seed)
+- **Reviewer:** `dependency-audit-erp` + `iis-deploy-runbook` + `contract-workflow` (security/deploy/workflow audit)
+
+**Context paste session start (em main responsibility):**
+- `docs/STATUS.md` current state
+- `docs/CLAUDE.md` root tech context
+- Latest 2 session logs `docs/changelog/sessions/`
+- Active gotchas `docs/gotchas.md`
+- Memory entries `C:\Users\pqhuy\.claude\projects\D--Dropbox-CONG-VIEC-SOLUTION\memory\MEMORY.md`
+
+→ Auto-inject baseline ~80-150K per agent. Plus task-specific Read on-demand.
+
+**Windows MAX_PATH pitfall:** Project path `D:\Dropbox\CONG_VIEC\SOLUTION\SOLUTION_ERP\` đã nested 51 chars + Dropbox-managed. **Implementer frontmatter KHÔNG dùng `isolation: worktree`** (per Pitfall 1 template). Default branch isolation OK.
+
+**UAT live mode (Phase 9 active):** Memory `feedback_uat_skip_verify` — skip `dotnet test` mỗi chunk, vẫn `npm run build` × 2 app. Reviewer khi spawn pre-commit cần áp rule này (không yêu cầu test increment cho UAT iteration), VẪN verify wire BE + security + anti-fiddle.
+
+---
+
+## 📊 Cost reality
+
+| Component | Effective tokens billed (after caching) |
+|---|---|
+| 3 sub-agents spawn setup | ~564K (3 × 188K cache WRITE) |
+| 10 SendMessages each ~24K new | ~450K (10 × 45K equivalent với cache READ) |
+| Em main session | ~200K |
+| **Total per heavy session** | **~1.2M (~6× solo)** |
+| **Optimized (compact + cache + skip trivial)** | **~600K (~3× solo)** |
+
+**Max 20× plan absorbs ~3× solo cost comfortable.**
+
+---
+
+## 🧪 Trial workflow (2-4 tuần evaluate)
+
+- **Week 1:** Setup + Plan trial cookie-cutter (Case 1 verified). SOLUTION_ERP candidate: Contract V2 wire Mig 28+29 mirror PE pattern — pattern proven 1× S17-S19 (PE V2). ~600+ LOC, 2 mig + Service + Controller + FE × 2 app.
+- **Week 2-3:** Feature wire (Solo em + Inv pre-flight + Rev pre-commit) — phân quyền strict V2 + drop legacy V1.
+- **Week 4:** Evaluate quality vs cost real numbers.
+  - Pass criteria: Rev catch ≥ 2 wire bugs trước commit + time saving ≥ 25% Case 1+2 + Max 20× quota comfortable
+  - Fail criteria: any of above unmet → rollback solo, agents archived
+
+---
+
+## 🔗 References
+
+- [Anthropic Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
+- [Cognition "Multi-Agents Working"](https://cognition.ai/blog/dont-build-multi-agents)
+- [Anthropic Sub-agents docs](https://docs.claude.com/en/docs/claude-code/sub-agents)
+- Memory entries (`C:\Users\pqhuy\.claude\projects\D--Dropbox-CONG-VIEC-SOLUTION\memory\`):
+  - `feedback_per_chunk_commit.md` — per-chunk discipline reference cho Implementer pattern
+  - `feedback_uat_skip_verify.md` — Reviewer rule trong Phase 9
+  - `feedback_drastic_refactor_scope.md` — Implementer refuse criteria reference
+  - `feedback_audit_reuse_before_clone.md` — Investigator audit-first pattern