all-for-claudecode 2.13.0 → 2.14.0

package/agents/afc-tech-advisor.md

@@ -13,7 +13,9 @@ disallowedTools:
   - MultiEdit
   - NotebookEdit
 model: sonnet
+maxTurns: 10
 memory: project
+effort: medium
 ---
 
 You are a Senior Tech Advisor consulting for a developer navigating unfamiliar technology ecosystems.
@@ -34,6 +36,13 @@ Follow the Session Start Protocol from expert-protocol.md:
 4. Check `.claude/.afc-state.json` for pipeline context
 5. Scale Check — apply Overengineering Guard
 
+## When to STOP and Ask
+
+- Conflicting requirements with no clear resolution
+- Missing critical project context needed for recommendation
+- Recommendation would require significant architecture change
+- User's question is outside this agent's domain → suggest correct expert
+
 ## Core Behavior
 
 ### What Makes You Different from Other Experts
@@ -53,11 +62,8 @@ When the user has no specific question (exploratory mode), probe these areas:
 ### Red Flags to Watch For
 
 - Reinventing solved problems (custom table component when AG Grid / Tanstack Table exist)
-- Choosing technology based on hype rather than project fit
-- Using a complex tool when a simpler alternative exists (Kubernetes for a solo dev's side project)
 - Mixing incompatible tools (e.g., two competing state management libraries)
 - Using deprecated or unmaintained packages (check last release date, open issues)
-- Choosing tools with licenses incompatible with the project
 - Over-investing in tool evaluation when any reasonable choice would work (analysis paralysis)
 - Ignoring existing project dependencies that already solve the problem
 
@@ -71,35 +77,11 @@ When the user has no specific question (exploratory mode), probe these areas:
 | "What's the current best practice for X?" | State of the Art: current consensus with WebSearch verification |
 | "I built X myself, should I switch to a library?" | Build vs Buy: honest assessment of their implementation |
 
-### Ecosystem Map Format
-
-When presenting options, always structure as a decision tree:
-
-```
-{Category} Options for Your Project:
-├─ {Approach A} (recommended for your situation)
-│  ├─ {Tool 1} — {one-line description} ★ recommended
-│  ├─ {Tool 2} — {one-line description}
-│  └─ {Tool 3} — {one-line description}
-├─ {Approach B} (alternative)
-│  ├─ {Tool 4} — {one-line description}
-│  └─ {Tool 5} — {one-line description}
-└─ Not Recommended for Your Case
-   └─ {Tool 6} — {why not}
-```
-
-### Comparison Matrix Format
+### Output Formats
 
-When comparing specific options:
+**Ecosystem Map** (when user doesn't know what exists): decision tree grouped by approach — recommended branch first, each tool with one-line description, "Not Recommended for Your Case" branch last.
 
-| Criterion | {Option A} | {Option B} | {Option C} |
-|-----------|-----------|-----------|-----------|
-| Learning curve | ... | ... | ... |
-| Bundle size / footprint | ... | ... | ... |
-| Your stack compatibility | ... | ... | ... |
-| Community / maintenance | ... | ... | ... |
-| License | ... | ... | ... |
-| Scale fit (your project) | ... | ... | ... |
+**Comparison Matrix** (when choosing between specific options): table with rows for learning curve, footprint, stack compatibility, community/maintenance, license, and scale fit — always project-specific values, never generic placeholders.
 
 ### Verification Protocol
 
@@ -121,6 +103,12 @@ Follow the base format from expert-protocol.md. Additionally:
 - Include a "Getting Started" snippet (minimal code to verify the tool works)
 - End with cross-referral: "Now that you've chosen {tool}, consult `/afc:consult {domain}` for best practices"
 
+Consultation is complete when: recommendation given with rationale, action items listed, memory updated.
+
+## Write Usage Policy
+
+Write is restricted to memory files only (.claude/agent-memory/afc-tech-advisor/). Do NOT write project code, documentation, or configuration.
+
 ## Anti-patterns
 
 - Do not recommend tools you cannot verify are actively maintained (check via WebSearch)

package/docs/agent-authoring-guide.md

@@ -0,0 +1,144 @@
+# Agent Authoring Guide
+
+> Based on [Claude Code subagents docs](https://code.claude.com/docs/en/sub-agents) and [community best practices](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/). All afc agents MUST follow these rules.
+
+## 1. Single Responsibility
+
+Each agent excels at **one** specific task. If an agent does two unrelated things, split it.
+
+## 2. Description (Delegation Trigger)
+
+Claude uses the description to decide when to delegate. Be specific:
+
+```yaml
+# Good — when을 명시
+description: "Architecture analysis agent — invoked during plan/review phases for ADR recording and design compliance checks."
+
+# Bad — 모호
+description: "Architecture analysis agent."
+```
+
+- Include "use proactively" if the agent should be invoked automatically
+- Include the pipeline phase context (when in the workflow this runs)
+
+## 3. Tool Restrictions (Minimal Access)
+
+**`tools` 생략 = 전체 접근 — 안티패턴.** 필요한 도구만 명시.
+
+```yaml
+# Read-only agent
+tools: [Read, Grep, Glob]
+
+# Code-changing agent
+tools: [Read, Write, Edit, Bash, Glob, Grep]
+```
+
+**Write 사용 시** 사용 범위를 프롬프트에 명시:
+
+```markdown
+## Write Usage Policy
+Write is restricted to memory files only:
+- .claude/agent-memory/{agent-name}/MEMORY.md
+Do NOT write project code, documentation, or configuration.
+```
+
+## 4. No Nested Agent Spawning
+
+Subagent는 다른 subagent를 생성할 수 없다. **tools에 Agent 포함 금지.**
+
+## 5. maxTurns (런어웨이 방지)
+
+| 에이전트 유형 | 권장 maxTurns |
+|-------------|--------------|
+| Expert 상담 | 10 |
+| 코드 스캔/리뷰 | 15-20 |
+| 구현 워커 | 50 |
+| PR 분석 | 15 |
+
+## 6. Model Selection
+
+| 모델 | 사용 시기 |
+|------|---------|
+| `haiku` | 빠른 조회, 분류 |
+| `sonnet` | 대부분의 작업 (기본값) |
+| `opus` | 복잡한 아키텍처 분석 |
+| `inherit` | 오케스트레이터 (부모 모델 상속) |
+
+## 7. Memory Configuration
+
+| 스코프 | 위치 | 사용 시기 |
+|--------|------|---------|
+| `project` | `.claude/agent-memory/` | 팀 공유 지식 (기본 권장) |
+| `user` | `~/.claude/agent-memory/` | 개인 전체 프로젝트 |
+| `local` | `.claude/agent-memory-local/` | 비공개 |
+| 미설정 | — | 임시 워커 (impl-worker, pr-analyst) |
+
+## 8. System Prompt Structure
+
+```markdown
+You are a {role} for {context}.
+
+## When to STOP and Ask
+- {condition 1}
+- {condition 2}
+
+## Workflow
+1. {step}
+2. {step}
+
+## Output Format
+{template}
+
+## Rules
+- {constraint}
+
+## Memory Usage
+{read/write protocol}
+```
+
+**필수 섹션:**
+- **역할 정의** (1문장)
+- **HITL 규칙** — 언제 멈추고 물어볼지
+- **워크플로우** — 단계별 절차
+- **출력 포맷** — 구조화된 결과
+- **완료 정의** — "끝"의 기준
+
+## 9. Prompt Conciseness
+
+Claude는 이미 OWASP, 디자인 패턴, 일반적인 red flags를 안다. **프로젝트 고유 지식만 제공.**
+
+```markdown
+# Bad (18줄) — Claude가 이미 아는 OWASP 테이블
+| # | Category | Common Mistake |
+| A01 | Broken Access Control | ... |
+...
+
+# Good (1줄)
+Apply OWASP Top 10 2025 checklist, focusing on project-specific attack surface.
+```
+
+**Red Flags 목록**: 모델이 범용적으로 아는 것(N+1, XSS, SQL injection 등)은 삭제. 프로젝트/도메인 특화 항목만 유지.
+
+## 10. Shared References
+
+인라인 복제 금지. 공유 문서 참조만:
+
+- `docs/expert-protocol.md` — Expert 에이전트 공통 프로토콜
+- `docs/critic-loop-rules.md` — Critic Loop 규칙
+- `docs/phase-gate-protocol.md` — Phase gate 프로토콜
+
+## Checklist
+
+에이전트 작성/수정 시 확인:
+
+- [ ] 단일 책임 — 하나의 구체적 작업
+- [ ] Description에 delegation trigger 명시
+- [ ] tools 명시적 나열 (생략 금지)
+- [ ] Agent 도구 미포함 (중첩 금지)
+- [ ] maxTurns 설정
+- [ ] HITL 규칙 포함 (언제 멈추고 물어볼지)
+- [ ] 출력 포맷 정의
+- [ ] 완료 기준 명시
+- [ ] Claude가 이미 아는 것 설명하지 않음
+- [ ] Write 사용 시 범위 문서화
+- [ ] Memory 100줄 제한 명시 (해당 시)

package/docs/context-management-harness.md

@@ -0,0 +1,293 @@
+# Context Management Harness
+
+> afc 파이프라인의 정확성, 신뢰성, 토큰 효율을 위한 공식 기능 활용 가이드.
+> 모든 내용은 [Claude Code 공식 문서](https://code.claude.com/docs/en/) 기반.
+
+## 설계 철학
+
+**1M 컨텍스트 ≠ "더 많이 담기". 1M = "auto-compact 전에 제어할 여유를 얻은 것".**
+
+200k 시절에는 auto-compact가 갑자기 발생하여 제어 불가. 1M에서는 5배의 여유가 생겨 **내가 원하는 시점에, 원하는 내용을 보존하면서** compact할 수 있다.
+
+```
+┌────────────────────── 1M Context Window ──────────────────────┐
+│ [고정] CLAUDE.md + rules + 스킬 메타데이터 (~5%)                │
+│ [고정] auto-memory MEMORY.md 첫 200줄 (~1%)                    │
+│ [누적] 대화 기록 + 도구 결과 (Phase 진행에 따라 증가)              │
+│ ....                                                          │
+│ ├── Phase 1 (Spec): ~50-100 prompts                           │
+│ ├── Phase 2 (Plan): ~50-100 prompts                           │
+│ ├── Phase 3 (Implement): ~100-300 prompts (서브에이전트 격리)    │
+│ └── Phase 4 (Review): ~50-100 prompts (서브에이전트 격리)        │
+│ ....                                                          │
+│ [여유] ← 이 공간이 "선제적 제어 여유"                             │
+│ [경계] auto-compact 95% (CLAUDE_AUTOCOMPACT_PCT_OVERRIDE로 조절) │
+└───────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. 선제적 Compact 제어 (Phase-Boundary Protocol)
+
+### 1.1 원리
+
+Auto-compact는 95% 도달 시 Claude가 임의로 요약 — 무엇을 보존할지 제어 불가.
+**Phase 경계에서 선제적으로 compact하면**: 보존 대상을 지정하고, 다음 phase를 깨끗한 컨텍스트로 시작.
+
+### 1.2 Phase-Boundary Compact Protocol
+
+```
+Phase 1 완료 → compact "spec.md ACs, edge cases, NFRs 보존"
+Phase 2 완료 → compact "File Change Map, Implementation Context, ADR 보존"
+Phase 3 완료 → compact "changed files list, CI results, 미해결 이슈 보존"
+Phase 4 완료 → compact "review findings, fix status 보존"
+```
+
+### 1.3 구현 방법
+
+`afc-user-prompt-submit.sh`의 Pipeline ACTIVE 분기에서, **phase 전환 직후** 첫 프롬프트에 compact 권고 주입:
+
+```
+[afc:context] Phase 전환 감지 ({prev} → {current}).
+이전 phase 컨텍스트를 정리하세요: /compact {phase별 보존 지시}
+```
+
+**트리거**: `afc-pipeline-manage.sh phase {new}` 실행 시 state에 `phaseTransition: true` 플래그 기록 → 다음 UserPromptSubmit에서 감지 후 주입 + 플래그 해제.
+
+### 1.4 Auto-Compact를 Safety Net으로 전환
+
+`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 환경변수로 auto-compact 트리거 시점을 조절:
+
+```
+기본값: 95% → auto-compact 발동
+권장값: 98% → 선제 compact(1.2)가 주도권, auto-compact는 최후 안전장치
+```
+
+**구현**: `/afc:init`에서 프로젝트 settings에 권장값 안내, `/afc:setup`에서 글로벌 설정 안내.
+
+**공식 출처**: [How Claude Code works - When context fills up](https://code.claude.com/docs/en/how-claude-code-works)
+
+### 1.5 Context Budget Monitor
+
+`promptCount`로 컨텍스트 사용량 추정:
+
+| promptCount 구간 | 추정 사용량 | 조치 |
+|-----------------|-----------|------|
+| 0-100 | ~30-50% | 정상 |
+| 100-150 | ~50-70% | `[afc:context] 50%+ 추정. 불필요한 탐색 결과는 서브에이전트에 위임 권장.` |
+| 150-200 | ~70-90% | `[afc:context] 70%+ 추정. /compact {현재 phase 보존 지시} 강력 권장.` |
+| 200+ | ~90%+ | auto-compact 임박 (safety net) |
+
+**구현**: UserPromptSubmit의 drift checkpoint 로직 확장. `totalPromptCount` 기준으로 budget 힌트 주입.
+
+---
+
+## 2. Compaction 품질 보장
+
+### 2.1 Compact Instructions (CLAUDE.md)
+
+`/afc:init`에서 프로젝트 CLAUDE.md에 자동 추가:
+
+```markdown
+# Compact instructions
+When compacting, always preserve:
+- Active pipeline feature name and current phase
+- File Change Map from plan.md (file paths + task assignments)
+- All unresolved ESCALATE items with their options
+- context.md contents (spec summary + plan decisions + advisor results)
+- Changed files list and CI/test pass/fail status
+- Current task progress (completed/total)
+```
+
+### 2.2 PreCompact Hook 강화
+
+현재 `pre-compact-checkpoint.sh`가 저장하는 것: git status, tasks 진행률.
+
+**추가**: context.md 내용도 checkpoint에 포함 → compaction 후 `/afc:resume`으로 풍부한 복구.
+
+```
+# checkpoint.md에 추가될 섹션
+## Feature Context (from context.md)
+{context.md 전문 또는 요약}
+
+## Advisor Insights
+{Skill Advisor가 수집한 expert 권고}
+```
+
+---
+
+## 3. Phase 간 컨텍스트 브릿지
+
+### 3.1 context.md 누적 패턴
+
+현재 갭: Skill Advisor가 expert를 호출하지만 결과가 context.md에 기록되지 않음.
+
+```
+Phase 1 → context.md 생성 (spec 요약, 핵심 AC)
+Advisor A → context.md 갱신 (security 권고 추가)
+Phase 2 → context.md 갱신 (plan 결정사항, ADR 요약)
+Advisor B → context.md 갱신 (architect 권고 추가)
+Advisor C → context.md 갱신 (consult 결과 추가)
+Phase 3 → impl-worker에 context.md 주입 (skills preload 또는 프롬프트)
+Phase 4 → reviewer에 context.md 주입
+```
+
+### 3.2 구현 방법
+
+auto.md의 각 Skill Advisor Checkpoint에 지시 추가:
+
+```markdown
+After advisor skill completes, append a 3-line summary to context.md:
+## Advisor: {skill_name} ({checkpoint})
+- Key insight: {1-line}
+- Action required: {1-line}
+```
+
+---
+
+## 4. Subagent 컨텍스트 최적화
+
+### 4.1 SendMessage Resume (의존 태스크)
+
+```
+현재: Task A → worker-1 생성 → 완료 → Task B(A 의존) → worker-2 생성 (A의 컨텍스트 없음)
+개선: Task A → worker-1 생성 → 완료 → Task B(A 의존) → worker-1 resume (A의 전체 컨텍스트 유지)
+```
+
+**구현**: implement.md의 Sequential/Batch 모드에서 의존 관계 태스크를 동일 worker에 SendMessage로 전달.
+
+### 4.2 Skills Preload
+
+```yaml
+# agents/afc-impl-worker.md
+---
+skills:
+  - docs/orchestration-modes.md  # 실행 모드 참조
+---
+```
+
+**주의**: skills preload는 서브에이전트 시작 시 전체 내용이 컨텍스트에 주입됨. 큰 스킬은 오히려 토큰 낭비 → **작고 핵심적인 참조만**.
+
+### 4.3 Effort Level
+
+```yaml
+# agents/afc-backend-expert.md (상담은 deep thinking 불필요)
+effort: medium
+
+# agents/afc-architect.md (아키텍처 분석은 기본)
+# effort 미설정 → inherit
+```
+
+---
+
+## 5. 토큰 효율 전략
+
+### 5.1 !`command` 프리페치
+
+스킬에서 `!`command``로 데이터 프리페치 → 모델의 별도 Bash 턴 절약 (1-2턴/스킬).
+
+**현재 적용**: 15개 스킬. **추가 대상**: 없음 (완료).
+
+### 5.2 Hook 기반 전처리
+
+테스트 출력, 로그 등 대량 데이터는 hook으로 필터링 후 전달.
+
+### 5.3 스킬 vs CLAUDE.md vs rules
+
+| 내용 | 위치 | 로드 시점 | 컨텍스트 비용 |
+|------|------|----------|-------------|
+| 항상 필요한 규칙 | CLAUDE.md (200줄 이하) | 매 세션 시작 | 항상 |
+| 특정 워크플로우 | Skills | 호출 시만 | on-demand |
+| 특정 파일 패턴 | .claude/rules/ (paths) | 해당 파일 작업 시 | conditional |
+| 서브에이전트 전용 | skills preload | 에이전트 시작 시 | 에이전트별 |
+
+### 5.4 MCP 도구 오버헤드
+
+각 MCP 서버가 매 요청마다 도구 정의를 컨텍스트에 추가. 미사용 서버 비활성화. CLI 도구 선호.
+
+---
+
+## 6. 신뢰성 패턴
+
+### 6.1 검증 루프
+
+Claude는 **자체 검증 가능 시 극적으로 성능 향상**. 테스트, 예상 출력을 제공.
+
+### 6.2 /clear 패턴
+
+2번 이상 같은 문제 수정 → `/clear` → 배운 것 반영한 더 나은 프롬프트로 새 시작.
+
+### 6.3 Checkpoint + Rewind
+
+모든 편집 전 스냅샷. `Esc+Esc`로 복원. PreCompact hook이 자동 체크포인트.
+
+### 6.4 Selective Summarize (구간 요약)
+
+`/rewind` → 특정 메시지 선택 → **Summarize from here** — 해당 지점부터만 요약하고 이전 컨텍스트는 원본 유지.
+
+**활용**: 긴 탐색/디버깅 후 탐색 구간만 요약, plan/spec 부분은 원본 보존.
+
+**공식 출처**: [Best practices - Manage context aggressively](https://code.claude.com/docs/en/best-practices)
+
+### 6.5 Non-blocking Expert 상담 (background)
+
+에이전트에 `background: true` 설정 → 메인 대화를 차단하지 않고 병렬 실행. 결과 완료 시 자동 알림.
+
+```yaml
+# Skill Advisor에서 expert 호출 시
+background: true  # 메인 작업 중단 없이 조언 수신
+```
+
+**적합**: Skill Advisor의 Enrich/Observe 모드 (결과가 blocking 아닌 참고용)
+**부적합**: Transform 모드 (결과가 다음 단계에 필수)
+
+---
+
+## 7. Agent Teams (실험적, 보류)
+
+비용 ~7x. 현재 subagent 패턴이 충분. cross-module 대규모 구현에서 향후 검토.
+
+---
+
+## 구현 계획
+
+### P1: 선제적 Context 제어 — "1M = 제어 여유"
+
+| # | 작업 | 대상 파일 | 설명 |
+|---|------|----------|------|
+| 1.1 | **Phase-Boundary Compact 권고** | `afc-pipeline-manage.sh` + `afc-user-prompt-submit.sh` | phase 전환 시 state에 `phaseTransition: true` 기록 → 다음 prompt에서 phase별 보존 지시 포함 `/compact` 권고 주입 → 플래그 해제 |
+| 1.2 | **Auto-Compact를 Safety Net으로** | `skills/init/SKILL.md` + `skills/setup/SKILL.md` | init/setup에서 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=98` 권장 안내 (선제 compact가 주도, auto-compact는 최후 보루) |
+| 1.3 | **Context Budget Monitor** | `afc-user-prompt-submit.sh` | `totalPromptCount` 100/150/200 구간별 힌트 주입: 서브에이전트 위임 권장 → compact 강력 권장 → 임박 경고 |
+| 1.4 | **Compact Instructions 자동 삽입** | `skills/init/SKILL.md` + `templates/afc.config.template.md` | `/afc:init` 시 CLAUDE.md에 `# Compact instructions` 섹션 추가 (feature/phase/File Change Map/context.md/ESCALATE 보존) |
+| 1.5 | **PreCompact checkpoint 강화** | `pre-compact-checkpoint.sh` | context.md + advisor insights를 checkpoint에 포함. compaction 후 resume 시 풍부한 복구 |
+
+### P2: Phase 간 컨텍스트 브릿지
+
+| # | 작업 | 대상 파일 | 설명 |
+|---|------|----------|------|
+| 2.1 | **Advisor → context.md 누적** | `skills/auto/SKILL.md` + `skills/auto/skill-advisor.md` | 각 Checkpoint(A-E)에서 advisor 완료 후 context.md에 3줄 요약 append 지시 추가 |
+| 2.2 | **SendMessage resume 패턴** | `skills/implement/SKILL.md` + `docs/orchestration-modes.md` | Sequential 모드에서 의존 태스크를 동일 worker에 SendMessage로 전달. Batch 모드에서 phase 내 의존 체인을 resume로 연결 |
+| 2.3 | **Selective Summarize 안내** | `skills/auto/SKILL.md` | Phase 3(Implement) 시작 전 "긴 탐색 구간이 있으면 `/rewind` → Summarize from here로 정리" 지시 |
+
+### P3: Subagent 효율
+
+| # | 작업 | 대상 파일 | 설명 |
+|---|------|----------|------|
+| 3.1 | **effort: medium** | 8개 expert agent `.md` | expert 상담 에이전트의 thinking 토큰 절약 |
+| 3.2 | **background 모드 검토** | `skills/auto/skill-advisor.md` | Enrich/Observe 모드의 advisor 호출에 `run_in_background: true` 적용 가능성 검토 (Transform은 blocking 필수) |
+| 3.3 | **skills preload 제한적 적용** | `agents/afc-impl-worker.md` | 프로젝트별 동적 config → preload 부적합. shell script conventions 같은 정적 참조만 후보 |
+
+---
+
+## Sources
+
+- [Best practices](https://code.claude.com/docs/en/best-practices)
+- [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)
+- [Create custom subagents](https://code.claude.com/docs/en/sub-agents)
+- [How Claude remembers your project](https://code.claude.com/docs/en/memory)
+- [Common workflows](https://code.claude.com/docs/en/common-workflows)
+- [Manage costs effectively](https://code.claude.com/docs/en/costs)
+- [Orchestrate teams](https://code.claude.com/docs/en/agent-teams)
+- [Subagents in the SDK](https://platform.claude.com/docs/en/agent-sdk/subagents)
+- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [Best practices for sub-agents](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/)