eb106f20a0
Bro re-emphasize prompt setup với rule Thứ 9 mới: "Các task bất kỳ, BẮT BUỘC phải phân việc đầy đủ cho các Sub Agent đúng vai trò, vị trí đã được chỉ định" Retrospective S22: em main solo 6/10 task lẽ ra delegate được (vi phạm): - Plan D F2 toggle UI → Implementer Case 2 (cookie-cutter mirror UsersPage) - Plan C task 4 reflection regression test → Implementer Case 3 - Plan C task 1-3 14 service test catch-up → Implementer Case 3 - S22+2 seed 20 user script → Implementer Case 1 (mass deterministic) - S22+3 rename users SQL transaction → Implementer Case 1 - Plan F pre-flight prod sqlcmd → Investigator (read-only audit) Em main solo ĐÚNG 4/10 task: - Plan E phân quyền strict V2 (security cross-stack) - S22+1 disable 3 button bug fix (reasoning chain) - S22+4 attachment view + Section adjust (UX + schema decision) - S22+5 Mig 30 per-NV (cross-stack schema refactor) Forward S23+ rule enforcement: 1. .claude/agents/README.md +banner "🚨 RULE BẮT BUỘC (Thứ 9)" trên top invocation tree + retrospective S22 lesson + workflow forward 2. docs/HANDOFF.md S22 chốt v2 Last updated với note S23+ forward 3. Plan B Contract V2 wire pre-allocated 5 chunk sub-agent role table: - Pre-flight Contract V1 state → Investigator - Chunk A Mig 31 schema → Implementer Case 2 - Chunk B Service ApproveV2Async → Em main Solo (cross-stack) - Chunk C Mig 32 LevelOpinions + service hook → Implementer Case 2 - Chunk D FE ContractCreate Workspace V2 → Implementer Case 2 - Chunk E FE ContractDetail Section 5 V2 → Implementer Case 2 - Pre-commit each chunk → Reviewer - Post-deploy → CICD Monitor Em main solo CHỈ khi: schema/UX/architecture decision + cross-stack tight coupling + bug fix reasoning chain. KHÔNG cắt narrative cũ — append rule banner ở top + Plan B section trước Session 21 timeline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# Multi-agent SOLUTION_ERP — Master Coordination Guide
|
||
|
||
> **Architecture:** 4 sub-agents Opus 4.7 1M Max + em main coordinator.
|
||
> Pattern: Anthropic Building Effective Agents orchestrator-workers + Cognition "writes single-threaded" hybrid + post-deploy automated watchdog.
|
||
> Setup: Session 20 turn 12 (2026-05-11) initial 3 agents + Session 21 turn 1 (2026-05-12) +cicd-monitor — 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 4 sub-agents via SendMessage │
|
||
│ • Synthesize cross-agent findings end-of-session │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓ spawn + keep-alive (Opus 4.7 1M Max each)
|
||
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
|
||
│Investigator│ │ Implementer│ │ Reviewer │ │ CI/CD │
|
||
│ │ │ │ │ │ │ Monitor │
|
||
│ READ only │ │ WRITE strict│ │ READ only │ │ READ only │
|
||
│ │ │classification│ │ adversarial│ │ post-deploy│
|
||
│ Research + │ │Cookie-cutter│ │ pre-commit │ │ │
|
||
│ Audit + │ │ + Multi-file│ │ + live │ │ Gitea poll │
|
||
│ External │ │ independent│ │ verify │ │ + bundle │
|
||
│ research │ │ ONLY │ │ │ │ hash + │
|
||
│ │ │ │ │ │ │ prod smoke │
|
||
└────────────┘ └────────────┘ └────────────┘ └────────────┘
|
||
cyan yellow red green
|
||
```
|
||
|
||
---
|
||
|
||
## 🚨 RULE BẮT BUỘC (S22 chốt cuối — directive Thứ 9)
|
||
|
||
**Em main BẮT BUỘC phân việc cho sub-agent đúng vai trò khi ACCEPT criteria match.**
|
||
|
||
Retrospective S22 lesson: Em main solo 6/10 task lẽ ra delegate được (Plan D + Plan C task 1-4 + S22+2 + S22+3 + Plan F pre-flight). KHÔNG fail nhưng vi phạm directive. Token cost overhead + lose multi-agent ROI.
|
||
|
||
**Workflow forward S23+:**
|
||
- Trước mọi task, classify qua decision tree dưới đây
|
||
- Nếu task qualify Implementer Case 1/2/3/5 → **BẮT BUỘC spawn**, KHÔNG em main solo
|
||
- Nếu task có pre-flight read-only → **BẮT BUỘC spawn Investigator** trước
|
||
- Nếu task có deploy claim → **BẮT BUỘC spawn CICD Monitor** sau push
|
||
- Nếu task có heavy diff / security-sensitive → **BẮT BUỘC spawn Reviewer** pre-commit
|
||
|
||
Em main solo chỉ khi: schema/UX/architecture decision + cross-stack tight coupling + bug fix reasoning chain.
|
||
|
||
## 🔄 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)
|
||
│
|
||
├── After push code commit (NOT docs-only — gotcha #41 path filter)?
|
||
│ → Spawn CI/CD Monitor (poll Gitea Actions + bundle hash + prod smoke async)
|
||
│ → ~150K spawn cost — catch deploy fail tự động không phụ thuộc em main nhớ verify
|
||
│
|
||
├── User reports prod issue ("500", "không lên", "không thấy thay đổi")?
|
||
│ → Spawn CI/CD Monitor diagnose first (logs + curl + sqlcmd evidence)
|
||
│
|
||
├── 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."
|
||
|
||
SendMessage CI/CD Monitor: "Flush MEMORY.md với run failures observed + post-deploy
|
||
bundle hash trend + recurring CI bugs + deploy time delta vs baseline."
|
||
|
||
Em read 4 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 21 turn 1 — 2026-05-12):** 27 migrations · 59 DB tables · ~142 endpoints · 34 FE pages · 81 test pass · 44 gotchas · 16 memory entries · 6 skills · 30 demo user · 3 prod domain `*.solutions.com.vn` · **4 sub-agents (seeds-only post-cicd-monitor add)**.
|
||
|
||
**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)
|
||
- **CI/CD Monitor:** `iis-deploy-runbook` + `dependency-audit-erp` + `ef-core-migration` (deploy runbook + dep pin verify + mig prod check)
|
||
|
||
**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) |
|
||
|---|---|
|
||
| 4 sub-agents spawn setup | ~750K (4 × ~188K cache WRITE — CI/CD Monitor +~150K) |
|
||
| 10 SendMessages each ~24K new | ~450K (10 × 45K equivalent với cache READ) |
|
||
| Em main session | ~200K |
|
||
| **Total per heavy session** | **~1.35M (~6.5× solo)** |
|
||
| **Optimized (compact + cache + skip trivial)** | **~700K (~3.5× solo)** |
|
||
|
||
**Max 20× plan absorbs ~3.5× solo cost comfortable.**
|
||
**CI/CD Monitor +~150K trade-off:** catch deploy fail tự động → KHÔNG phụ thuộc em main nhớ verify thủ công (recurring blind spot pattern).
|
||
|
||
---
|
||
|
||
## 🧪 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. **CI/CD Monitor spawn sau mỗi push** verify Gitea Actions PASS + bundle hash 2 app changed + mig 28+29 applied prod.
|
||
- **Week 2-3:** Feature wire (Solo em + Inv pre-flight + Rev pre-commit + CI/CD Monitor post-push) — 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 + CI/CD Monitor catch ≥ 1 deploy ship fail (bundle hash unchanged / mig drift) + 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
|