@silbaram/artifact-driven-agent 0.1.6 → 0.1.9

package/ai-dev-team/roles/manager.md

@@ -0,0 +1,544 @@
+# Role: Manager (프로젝트 관리자)
+
+> 이 문서는 **사용자(당신)**를 위한 가이드입니다.
+> 프로젝트 전체를 슈퍼권한으로 관리하는 방법을 설명합니다.
+
+---
+
+## 🎯 Manager 역할 개요
+
+**Manager = 사용자 본인**
+
+AI 역할들(Planner, Developer, Reviewer, Documenter)을 관리하고,
+최종 결정권을 가진 프로젝트 책임자입니다.
+
+### 핵심 책임
+
+- ✅ 스프린트 생성 및 종료 (CLI)
+- ✅ 최종 결정 및 승인 (decision.md)
+- ✅ AI 역할들의 질문에 응답
+- ✅ 프로젝트 전체 모니터링
+- ✅ 문서 간 충돌 해결
+
+---
+
+## 1. 스프린트 관리 (CLI)
+
+### 1.1 스프린트 생성
+
+```bash
+# 새 스프린트 생성
+ada sprint create
+
+# 생성 결과
+✅ Sprint 1 생성됨
+📁 sprints/sprint-1/
+   ├── meta.md
+   ├── tasks/
+   ├── review-reports/
+   └── docs/
+```
+
+### 1.2 Task 추가
+
+```bash
+# backlog에서 Task 선택하여 스프린트에 추가
+ada sprint add task-001 task-002 task-003
+
+# 확인
+✅ task-001 추가됨 (P0, M)
+✅ task-002 추가됨 (P1, S)
+✅ task-003 추가됨 (P1, L)
+
+📊 Sprint 1 현황
+- 총 Task: 3개
+- 예상 규모: M×1 + S×1 + L×1
+```
+
+### 1.3 스프린트 진행 상황 확인
+
+```bash
+# 기본 확인
+ada sessions
+
+# 실시간 모니터링 대시보드
+ada sessions --watch
+ada sessions -w
+```
+
+**대시보드 내용:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 ADA 세션 모니터링 대시보드
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📈 통계
+  활성 세션: 2    대기 질문: 1    진행 Task: 3
+
+🟢 활성 세션
+┌──────────┬────────┬──────────┬─────────────┐
+│ 역할     │ 도구   │ Task     │ 실행 시간   │
+├──────────┼────────┼──────────┼─────────────┤
+│ Developer│ claude │ task-001 │ 15분 23초   │
+│ Reviewer │ gemini │ task-003 │ 5분 10초    │
+└──────────┴────────┴──────────┴─────────────┘
+
+⚠️ 대기 질문 (1개)
+  [Q001] Developer: Redis 캐시 추가 승인 필요
+         옵션: (y) 승인 / (n) 거부
+         대기 시간: 2분 30초
+
+📊 Task 진행률
+  task-001 [████████░░] 80% (Developer)
+  task-002 [██████████] 100% (DONE)
+  task-003 [████░░░░░░] 40% (Reviewer)
+
+키: q(종료) r(새로고침) c(화면지우기) h(도움말)
+```
+
+### 1.4 스프린트 종료
+
+```bash
+ada sprint close
+
+# 회고 작성 프롬프트
+✅ Sprint 1 종료 처리 중...
+
+📝 회고 작성
+1. 완료된 Task: 3개
+2. 미완료 Task: 0개
+
+잘된 점을 입력하세요:
+> _
+
+개선할 점을 입력하세요:
+> _
+
+✅ Sprint 1 종료됨
+📁 retrospective.md 생성됨
+```
+
+---
+
+## 2. AI 역할 질문 응답
+
+### 2.1 직접 응답 (터미널)
+
+AI가 작업 중 질문하면 터미널에서 직접 응답:
+
+```
+Developer 세션:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💻 Developer 작업 중...
+
+⚠️ 결정 필요
+project.md에 없는 기술이 필요합니다.
+
+  기술: Redis (캐시 서버)
+  목적: API 응답 속도 개선
+  영향: project.md 업데이트 필요
+
+추가하시겠습니까? (y/n): _
+```
+
+사용자 입력: `y`
+
+```
+✅ 승인됨
+📝 decision.md에 기록됨
+
+계속 진행합니다...
+```
+
+### 2.2 모니터링 대시보드에서 응답
+
+백그라운드 실행 중이거나 다른 터미널에서 실행 중일 때:
+
+```bash
+ada sessions --watch
+```
+
+대시보드에서 질문 확인 후:
+- 질문 번호와 응답 입력: `1 y` 또는 `1 n`
+- AI 세션이 자동으로 응답 수신
+
+### 2.3 Task 파일에서 확인
+
+급하지 않은 질문은 Task 파일에 이슈로 기록됨:
+
+```bash
+# Task 파일 확인
+cat ai-dev-team/artifacts/backlog/task-001.md
+
+# 또는 스프린트 Task
+cat ai-dev-team/artifacts/sprints/sprint-1/tasks/task-001.md
+```
+
+```markdown
+## 이슈
+
+### Redis 캐시 추가 필요
+- 상황: API 응답 속도가 느림
+- 제안: Redis 캐시 도입
+- 영향: project.md에 Redis 추가 필요
+
+→ 사용자 승인 대기
+```
+
+직접 파일 수정하여 응답:
+```markdown
+→ ✅ 승인됨 (2024-01-04)
+```
+
+---
+
+## 3. 결정 사항 기록 (decision.md)
+
+### 3.1 자동 기록
+
+중요한 결정은 자동으로 decision.md에 기록됨:
+- AI 질문에 대한 승인/거부
+- RFC 승인
+- 스프린트 생성/종료
+- 예외 처리
+
+### 3.2 수동 기록
+
+필요시 직접 기록:
+
+```markdown
+# Decision Log
+
+## Decision #003
+- 일시: 2024-01-04 14:30
+- 유형: 기술 추가 승인
+- 내용: Redis 캐시 서버 도입 승인
+- 근거: API 응답 속도 개선 필요 (300ms → 50ms 목표)
+- 결과: 승인
+- 영향: project.md 업데이트 필요
+```
+
+---
+
+## 4. 프로젝트 전체 관리
+
+### 4.1 문서 상태 확인
+
+```bash
+ada status
+
+# 출력
+📋 역할 (5개)
+  ✅ planner
+  ✅ developer
+  ✅ reviewer
+  ✅ documenter
+  ✅ analyzer
+
+📄 산출물 (3개)
+  ✅ plan.md
+  ⚠️ project.md (선택, 미생성)
+  ✅ decision.md
+
+📊 스프린트
+  현재: sprint-1 (active)
+  Task: 3개 (2 DONE, 1 IN_DEV)
+
+📦 Backlog
+  총 Task: 5개
+  READY: 2개
+```
+
+### 4.2 문서 검증
+
+```bash
+# 전체 검증
+ada validate
+
+# 특정 문서 검증
+ada validate plan
+ada validate project
+```
+
+### 4.3 로그 확인
+
+```bash
+# 최근 세션 로그
+ada logs
+
+# 특정 세션 로그
+ada logs 20240104-143022-a1b2
+```
+
+---
+
+## 5. 슈퍼권한 작업
+
+### 5.1 문서 직접 수정
+
+모든 문서를 직접 수정 가능:
+```bash
+# plan.md 직접 수정
+vim ai-dev-team/artifacts/plan.md
+
+# project.md 수정 (Frozen이지만 권한 있음)
+vim ai-dev-team/artifacts/project.md
+```
+
+**주의:** project.md는 Frozen 문서이므로 변경 시 decision.md에 기록 권장
+
+### 5.2 Task 상태 강제 변경
+
+```bash
+# sprints/sprint-1/meta.md에서 직접 수정
+vim ai-dev-team/artifacts/sprints/sprint-1/meta.md
+
+# Task 상태 변경
+| task-001 | BACKLOG | - | P0 | M |
+↓
+| task-001 | DONE | developer | P0 | M |
+```
+
+### 5.3 스프린트 강제 종료
+
+```bash
+ada sprint close -f     # 미완료 Task 있어도 강제 종료
+```
+
+### 5.4 세션 정리
+
+```bash
+# 좀비 세션 정리 (프로세스 종료 감지 포함)
+ada sessions
+
+# 오래된 완료 세션 정리
+ada sessions --clean
+
+# 특정 세션 강제 종료
+kill [session-pid]
+```
+
+---
+
+## 6. 워크플로우 예시
+
+### 6.1 신규 프로젝트 시작
+
+```bash
+# 1. 템플릿 설정
+ada setup web
+
+# 2. 기획 시작
+ada planner claude
+# → plan.md, backlog/*.md 생성
+
+# 3. project.md 작성 (선택)
+vim ai-dev-team/artifacts/project.md
+# → 기술 스택, 구조, 품질 기준 정의
+
+# 4. 스프린트 생성
+ada sprint create
+ada sprint add task-001 task-002
+
+# 5. 개발 시작
+ada developer claude
+
+# 6. 모니터링 (별도 터미널)
+ada sessions --watch
+
+# 7. 리뷰
+ada reviewer claude
+
+# 8. 문서 작성
+ada documenter claude
+
+# 9. 스프린트 종료
+ada sprint close
+```
+
+### 6.2 진행 중 개입
+
+**시나리오 1: AI가 막혔을 때**
+```
+Developer: ⚠️ 구현 불가 - Websocket 필요하지만 project.md에 없음
+사용자: y (승인)
+       → decision.md에 자동 기록
+       → project.md 업데이트
+Developer: ✅ 계속 진행
+```
+
+**시나리오 2: 품질 문제 발견**
+```
+Reviewer: ❌ REJECT - 수용 조건 미충족
+사용자: (ada sessions로 확인)
+       → review-reports/task-001.md 확인
+       → Developer에게 재작업 지시
+```
+
+**시나리오 3: 긴급 Task 추가**
+```
+사용자: vim ai-dev-team/artifacts/backlog/task-010.md
+       (긴급 Task 생성)
+
+       ada sprint add task-010
+       ✅ 현재 스프린트에 추가됨
+
+       decision.md에 기록:
+       "긴급 보안 패치 - CVE-2024-XXXX 대응"
+```
+
+---
+
+## 7. 모니터링 팁
+
+### 7.1 Watch 모드 활용
+
+**터미널 1:** 개발 진행
+```bash
+ada developer claude
+```
+
+**터미널 2:** 실시간 모니터링
+```bash
+ada sessions --watch
+```
+
+**터미널 3:** 리뷰 진행
+```bash
+ada reviewer gemini
+```
+
+### 7.2 알림 확인
+
+`.ada-status.json`의 notifications 필드:
+```json
+{
+  "notifications": [
+    {
+      "from": "developer",
+      "message": "task-001 구현 완료",
+      "taskId": "task-001",
+      "timestamp": "2024-01-04T14:30:00Z",
+      "read": false
+    }
+  ]
+}
+```
+
+`ada sessions`로 확인 가능
+
+---
+
+## 8. 충돌 해결
+
+### 8.1 문서 간 충돌
+
+AI가 충돌을 발견하면 보고:
+```
+Developer: ⚠️ 문서 충돌 발견
+  plan.md: "사용자 인증 필요"
+  project.md: "인증 시스템 제외"
+
+  어떻게 처리할까요?
+```
+
+사용자 결정:
+```
+옵션:
+1. plan.md 우선 (project.md 수정)
+2. project.md 우선 (plan.md 수정)
+3. 둘 다 수정
+
+선택: _
+```
+
+decision.md에 기록하여 향후 참조
+
+### 8.2 역할 간 해석 차이
+
+```
+Developer: "로그인 = 이메일/비밀번호"
+Reviewer: "로그인 = OAuth 포함해야 함"
+
+→ plan.md 명확화 필요
+→ 사용자가 최종 판단
+```
+
+---
+
+## 9. 금지 사항
+
+Manager(사용자)는 슈퍼권한을 가지지만, 다음을 지키는 것을 권장:
+
+- ⚠️ Frozen 문서 무단 변경 (RFC 절차 권장)
+- ⚠️ 진행 중인 스프린트 범위 임의 변경
+- ⚠️ AI 역할의 산출물 직접 수정 (역할 재실행 권장)
+
+**권장 방식:**
+- ✅ AI가 잘못했으면 → 역할 재실행
+- ✅ 문서 수정 필요하면 → decision.md에 기록
+- ✅ 긴급 상황만 → 직접 수정
+
+---
+
+## 10. 체크리스트
+
+### 스프린트 시작 전
+- [ ] plan.md 확정
+- [ ] backlog에 READY Task 충분
+- [ ] project.md 작성 (선택)
+- [ ] 스프린트 생성 및 Task 추가
+
+### 스프린트 진행 중
+- [ ] ada sessions로 주기적 확인
+- [ ] AI 질문에 신속 응답
+- [ ] REJECT된 Task 확인 및 조치
+- [ ] 충돌/이슈 즉시 해결
+
+### 스프린트 종료 전
+- [ ] 모든 Task DONE 확인
+- [ ] 문서 작성 완료 (Documenter)
+- [ ] 회고 작성
+- [ ] decision.md 정리
+
+---
+
+## 11. 참고 명령어 요약
+
+```bash
+# 스프린트
+ada sprint create              # 생성
+ada sprint add task-001        # Task 추가
+ada sprint close               # 종료
+ada sprint list                # 목록
+
+# 모니터링
+ada sessions                   # 세션 확인
+ada sessions --watch           # 실시간 대시보드
+ada sessions --clean           # 좀비 정리
+ada logs [id]                  # 로그
+
+# 상태 확인
+ada status                     # 전체 상태
+ada validate                   # 문서 검증
+
+# AI 역할 실행
+ada planner claude
+ada developer codex
+ada reviewer gemini
+ada documenter claude
+```
+
+---
+
+## 12. 마무리
+
+**Manager = 당신**
+
+- 🎯 최종 결정권자
+- 📊 프로젝트 전체 조망
+- ⚖️ AI 역할들의 중재자
+- 📝 품질 최종 책임자
+
+CLI 도구와 모니터링 대시보드를 활용하여
+효율적으로 프로젝트를 관리하세요! 🚀