@silbaram/artifact-driven-agent 0.1.6 → 0.1.9

package/ai-dev-team/rules/api-change.md

@@ -0,0 +1,198 @@
+# API Change Rules (API 변경 규칙)
+
+> 이 문서는 api.md 변경 시 따라야 할 절차를 정의한다.
+> API는 Backend와 Frontend의 계약이므로 일방적 변경은 금지된다.
+
+---
+
+## 1. API 변경 원칙
+
+- api.md는 **Backend와 Frontend의 공식 계약**
+- 변경은 **양측 합의** 후에만 가능
+- **Breaking change는 Manager 승인** 필수
+- 모든 변경은 **문서에 기록**
+
+---
+
+## 2. 변경 유형 분류
+
+### 2.1 Non-Breaking Change (하위 호환)
+
+| 유형 | 예시 | 승인 |
+|------|------|------|
+| 새 엔드포인트 추가 | POST /api/v1/new | Frontend 통보 |
+| 응답에 optional 필드 추가 | 기존 + new_field | Frontend 통보 |
+| 새 에러 코드 추가 | ERROR_NEW | Frontend 통보 |
+| 요청에 optional 파라미터 | ?new_param=value | Frontend 통보 |
+
+### 2.2 Breaking Change (하위 비호환)
+
+| 유형 | 예시 | 승인 |
+|------|------|------|
+| 엔드포인트 삭제/변경 | /v1/old → /v2/new | Manager 필수 |
+| 필수 필드 추가 | required 필드 | Manager 필수 |
+| 필드 삭제 | 기존 필드 제거 | Manager 필수 |
+| 필드 타입 변경 | string → number | Manager 필수 |
+| 에러 코드 변경/삭제 | 기존 코드 변경 | Manager 필수 |
+
+---
+
+## 3. 변경 절차
+
+### 3.1 Non-Breaking Change
+
+```
+Backend 변경 필요 발견
+    ↓
+api.md에 [PROPOSED] 태그로 추가
+    ↓
+Frontend에 통보
+    ↓
+Frontend 확인 (48시간 내)
+    ├── 이의 없음 → [PROPOSED] 제거, 확정
+    └── 이의 있음 → 협의 후 조정
+    ↓
+api.md 갱신 → 구현 진행
+```
+
+### 3.2 Breaking Change
+
+```
+Breaking Change 필요 발견
+    ↓
+Manager에게 에스컬레이션
+    ↓
+api.md에 [BREAKING] 태그로 추가
+    ↓
+Manager 검토
+    ├── 승인 → Frontend 통보 → 마이그레이션 계획
+    └── 거부 → 대안 검토
+    ↓
+양측 합의 후 구현
+```
+
+---
+
+## 4. 변경 요청 형식
+
+### 4.1 Non-Breaking 변경 통보
+
+```markdown
+## API 변경 통보
+
+- 유형: Non-Breaking
+- Task: TASK-XXX
+- 대상: [엔드포인트]
+
+### 변경 내용
+[변경 설명]
+
+### 영향
+- 기존 동작: 영향 없음
+- 추가 사항: [내용]
+
+### 일정
+- 적용 예정: YYYY-MM-DD
+```
+
+### 4.2 Breaking 변경 요청
+
+```markdown
+## API Breaking Change 요청
+
+- 유형: Breaking
+- Task: TASK-XXX
+- 대상: [엔드포인트]
+
+### 변경 내용
+- Before: [현재]
+- After: [변경 후]
+
+### 변경 사유
+[필요 이유]
+
+### 영향 분석
+- 영향받는 화면: [목록]
+- Frontend 수정 필요: [내용]
+
+### 마이그레이션 계획
+1. [단계]
+2. [단계]
+
+### 일정
+- 승인 필요: YYYY-MM-DD
+- 적용 예정: YYYY-MM-DD
+```
+
+---
+
+## 5. 역할별 책임
+
+| 역할 | 책임 |
+|------|------|
+| Backend | 변경 제안, api.md 갱신, 구현 |
+| Frontend | 변경 검토, 영향 분석, 적용 |
+| Manager | Breaking change 승인, 일정 조정 |
+
+---
+
+## 6. 버전 관리
+
+### 6.1 URL 버전
+
+- 현재: /api/v1
+- Major Breaking 시: /api/v2
+
+### 6.2 하위 호환 기간
+
+- Breaking change 시 구버전 유지: 최소 2주
+- 양측 합의 시 단축 가능
+
+---
+
+## 7. 긴급 변경
+
+### 긴급 상황
+
+- 보안 취약점
+- 심각한 버그
+
+### 긴급 절차
+
+```
+긴급 상황 발생
+    ↓
+Manager에게 즉시 보고
+    ↓
+Manager 판단 (1시간 내)
+    ↓
+승인 시: 즉시 변경 + 사후 문서화
+```
+
+---
+
+## 8. 금지 사항
+
+- ❌ Frontend 통보 없이 API 변경
+- ❌ Manager 승인 없이 Breaking change
+- ❌ 문서 갱신 없이 구현 변경
+- ❌ 합의 없이 일정 변경
+
+---
+
+## 9. 체크리스트
+
+### API 변경 전 체크리스트
+
+- [ ] 변경 유형 분류 (Non-Breaking / Breaking)
+- [ ] api.md에 [PROPOSED]/[BREAKING] 태그 추가
+- [ ] Frontend 통보 완료
+- [ ] (Breaking인 경우) Manager 승인 완료
+- [ ] 마이그레이션 계획 수립 (필요 시)
+
+### API 변경 후 체크리스트
+
+- [ ] api.md 갱신 (태그 제거)
+- [ ] 변경 이력 기록
+- [ ] Frontend 구현 완료 확인
+- [ ] 테스트 완료

package/ai-dev-team/rules/document-priority.md

@@ -0,0 +1,199 @@
+# Document Priority Rules (문서 우선순위 규칙)
+
+> 이 문서는 문서 간 충돌 시 우선순위를 정의한다.
+> 모든 역할이 이 규칙을 따른다.
+
+---
+
+## 1. 문서 우선순위 (높은 순)
+
+```
+1. decision.md                          (사용자/팀 판단) ───── 최우선
+2. project.md                           (Frozen 상태) ───────── 기술 기준
+3. plan.md                              (기획 기준) ─────────── 요구사항 기준
+4. backlog/task-NNN.md                  (Task 정의) ─────────── 수용 조건
+5. 인터페이스 문서                       ─────────────────────── 구현 계약
+6. sprints/sprint-N/meta.md             ─────────────────────── 현재 범위
+7. sprints/sprint-N/review-reports/*.md ─────────────────────── 리뷰 결과
+```
+
+---
+
+## 2. 충돌 해결 규칙
+
+### 2.1 상위 문서 우선
+
+- 충돌 시 **상위 문서가 정답**
+- 하위 문서를 상위에 맞게 수정
+- 수정 불가 시 사용자에게 질문
+
+### 2.2 충돌 유형별 처리
+
+| 충돌 | 우선 | 조치 |
+|------|------|------|
+| decision.md ↔ 모든 문서 | decision.md | 다른 문서 수정 |
+| project.md ↔ plan.md | project.md | plan.md 조정 또는 사용자 질문 |
+| plan.md ↔ Task 파일 | plan.md | Task 파일 수정 |
+| Task 파일 ↔ 인터페이스 | Task 파일 | 인터페이스 수정 |
+
+### 2.3 예외 상황
+
+| 상황 | 처리 |
+|------|------|
+| 상위 문서가 오류 | 사용자에게 보고 |
+| 양쪽 모두 합리적 | 사용자 판단 요청 |
+| 해석 차이 | 사용자에게 명확화 요청 |
+
+---
+
+## 3. 문서별 수정 권한
+
+| 문서 | 작성 | 수정 | 승인 |
+|------|------|------|------|
+| decision.md | 사용자/팀 | 사용자/팀 | - |
+| project.md | 사용자/팀 | 금지 (RFC 필요) | 사용자 |
+| plan.md | Planner | Planner | 사용자 |
+| backlog/task-NNN.md | Planner | Planner/Developer | - |
+| 인터페이스 문서 | Developer | Developer | - |
+| sprints/sprint-N/meta.md | 자동 생성 | 사용자 (CLI) | - |
+| review-reports/task-NNN.md | Reviewer | Reviewer | - |
+
+---
+
+## 4. 문서 참조 규칙
+
+### 4.1 역할별 필수 참조
+
+| 역할 | 필수 참조 |
+|------|----------|
+| Planner | (이전 plan.md) |
+| Developer | plan.md, project.md (있으면), sprints/sprint-N/meta.md, tasks/task-NNN.md |
+| Reviewer | plan.md, project.md (있으면), tasks/task-NNN.md |
+| Documenter | plan.md, sprints/sprint-N/meta.md, tasks/*.md |
+
+### 4.2 참조 순서
+
+작업 시작 시:
+1. decision.md 확인 (사용자 판단 기록)
+2. sprints/sprint-N/meta.md 확인 (현재 스프린트)
+3. 관련 Task 파일 확인
+4. 작업 수행
+
+---
+
+## 5. 문서 상태 정의
+
+| 상태 | 설명 | 수정 가능 |
+|------|------|:--------:|
+| Draft | 작성 중 | ✅ |
+| Review | 검토 중 | ⚠️ 제한적 |
+| Confirmed | 확정됨 | ⚠️ 승인 필요 |
+| Frozen | 동결됨 | ❌ |
+
+### 상태 전환
+
+```
+Draft → Review → Confirmed → (Frozen)
+  ↑        ↓
+  └────────┘ (수정 필요 시)
+```
+
+---
+
+## 6. 버전 관리 규칙
+
+### 6.1 버전 형식
+
+```
+v[Major].[Minor]
+
+예: v1.0, v1.1, v2.0
+```
+
+### 6.2 버전 증가 기준
+
+| 변경 | 버전 |
+|------|------|
+| 오타/서식 수정 | 변경 없음 |
+| 내용 추가/수정 | Minor +1 |
+| 구조 변경 | Major +1 |
+
+---
+
+## 7. 충돌 감지 및 보고
+
+### 7.1 충돌 감지 시점
+
+- 작업 시작 전 문서 확인 시
+- 작업 중 참조 문서 확인 시
+- 리뷰 중 기준 확인 시
+
+### 7.2 충돌 보고 형식
+
+Task 파일에 이슈로 기록하거나 사용자에게 직접 질문:
+
+```markdown
+## 이슈: 문서 충돌 발견
+
+- 발견자: [역할]
+- 일시: YYYY-MM-DD
+
+### 충돌 내용
+- 문서 A: [문서명] - [내용]
+- 문서 B: [문서명] - [내용]
+
+### 충돌 유형
+- [ ] 해석 차이
+- [ ] 명시적 불일치
+- [ ] 누락
+
+### 제안
+[해결 제안]
+
+→ 사용자 승인 대기
+```
+
+---
+
+## 8. 빠른 참조 표
+
+### 문서 간 관계
+
+```
+decision.md
+    ↓ (최우선)
+project.md ←── Frozen (선택)
+    ↓
+plan.md
+    ↓
+backlog/task-NNN.md
+    ↓
+sprints/sprint-N/meta.md ←→ 인터페이스 문서
+    ↓
+sprints/sprint-N/tasks/task-NNN.md
+    ↓
+sprints/sprint-N/review-reports/task-NNN.md
+```
+
+### 충돌 시 판단 흐름
+
+```
+충돌 발생
+    ↓
+decision.md에 관련 판단 있음?
+├── Yes → decision.md 따름
+└── No ↓
+
+project.md와 충돌?
+├── Yes → project.md 따름 (있으면)
+└── No ↓
+
+plan.md와 충돌?
+├── Yes → plan.md 따름
+└── No ↓
+
+Task 파일과 충돌?
+├── Yes → Task 파일 따름
+└── No → 하위 문서 기준으로 판단
+```
+

package/ai-dev-team/rules/escalation.md

@@ -0,0 +1,172 @@
+# Escalation Rules (에스컬레이션 규칙)
+
+> 이 문서는 사용자에게 질문/보고해야 하는 상황과 절차를 정의한다.
+> 모든 역할이 이 규칙을 따른다.
+
+---
+
+## 1. 에스컬레이션 원칙
+
+- 판단 불가 시 → 즉시 에스컬레이션
+- 규칙 외 상황 → 즉시 에스컬레이션
+- 작업 완료 후 이상 발견 → 보고
+- 혼자 결정하지 않음
+
+---
+
+## 2. 즉시 에스컬레이션 (BLOCK)
+
+> 작업을 **중단**하고 사용자에게 질문해야 하는 상황
+
+### 2.1 BLOCK 상황
+
+| 상황 | 예시 |
+|------|------|
+| project.md에 없는 기술 필요 | 새 라이브러리 도입 필요 |
+| 요구사항 모호/충돌 | plan.md 해석 불가 |
+| 문서 간 충돌 | plan.md ↔ project.md 불일치 |
+| 역할 간 해석 불일치 | 같은 문서 다르게 해석 |
+| 구현 불가능 판단 | 기술적으로 불가 |
+| 보안/안전 이슈 | 심각한 취약점 발견 |
+
+### 2.2 BLOCK 시 조치
+
+```
+1. 즉시 작업 중단
+2. 현재 상태 저장 (Task 파일에 이슈 기록)
+3. 사용자에게 질문
+4. 사용자 응답 대기
+5. 응답에 따라 진행
+```
+
+---
+
+## 3. 작업 완료 후 보고
+
+> 작업은 완료하되, 사용자에게 **알려야** 하는 상황
+
+### 3.1 보고 상황
+
+| 상황 | 예시 |
+|------|------|
+| 예상보다 규모 큼 | Task가 예상보다 복잡 |
+| 경미한 이슈 발견 | 작은 개선점 발견 |
+| 문서 오류 발견 | 오타, 불일치 |
+| 일정 지연 예상 | 예상보다 시간 필요 |
+
+### 3.2 보고 시 조치
+
+```
+1. 작업 완료
+2. Task 파일에 이슈 기록
+3. 사용자에게 보고
+4. 필요시 추가 조치
+```
+
+---
+
+## 4. 에스컬레이션 형식
+
+### 4.1 BLOCK 보고 형식
+
+```markdown
+## Issue: [제목]
+
+- 유형: BLOCK
+- 보고자: [역할]
+- 일시: YYYY-MM-DD HH:MM
+- Task: TASK-XXX (해당 시)
+
+### 상황
+[구체적 상황 설명]
+
+### 문제점
+[무엇이 문제인지]
+
+### 시도한 것
+[이미 시도한 해결책]
+
+### 필요한 판단
+[사용자에게 필요한 결정]
+
+### 제안 (있으면)
+[해결책 제안]
+
+→ 사용자 응답 대기
+```
+
+### 4.2 보고 형식
+
+```markdown
+## Report: [제목]
+
+- 유형: INFO / WARN
+- 보고자: [역할]
+- 일시: YYYY-MM-DD HH:MM
+- Task: TASK-XXX (해당 시)
+
+### 내용
+[보고 내용]
+
+### 영향
+[예상되는 영향]
+
+### 제안 (있으면)
+[조치 제안]
+```
+
+---
+
+## 5. 역할별 에스컬레이션 권한
+
+| 역할 | BLOCK 가능 | 보고 대상 |
+|------|:----------:|----------|
+| Planner | ✅ | 요구사항 모호, 충돌 |
+| Developer | ✅ | 구현 불가, 기술 부족, project.md 추가 필요 |
+| Reviewer | ✅ | 구조적 문제, 설계 수준 이슈 |
+| Documenter | ✅ | 문서화 불가, 정보 부족 |
+
+---
+
+## 6. 에스컬레이션 금지 사항
+
+- ❌ 판단 가능한 것을 에스컬레이션
+- ❌ 문서에 답이 있는 것을 에스컬레이션
+- ❌ 개인 선호를 이유로 에스컬레이션
+- ❌ BLOCK 없이 작업 중단
+- ❌ 보고 없이 예외 처리
+
+---
+
+## 7. 에스컬레이션 응답 시간 기대치
+
+| 유형 | 기대 응답 |
+|------|----------|
+| BLOCK (긴급) | 즉시 ~ 1시간 |
+| BLOCK (일반) | 4시간 이내 |
+| 보고 (WARN) | 24시간 이내 |
+| 보고 (INFO) | 다음 체크인 |
+
+---
+
+## 8. 에스컬레이션 흐름도
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                 │
+│  이슈 발생                                                      │
+│      ↓                                                          │
+│  문서에 답이 있는가?                                            │
+│      ├── Yes → 문서대로 처리                                    │
+│      └── No ↓                                                   │
+│                                                                 │
+│  내 권한으로 판단 가능?                                          │
+│      ├── Yes → 판단 후 진행 (필요시 보고)                        │
+│      └── No ↓                                                   │
+│                                                                 │
+│  즉시 중단 필요?                                                │
+│      ├── Yes → BLOCK 에스컬레이션                               │
+│      └── No → 작업 완료 후 보고                                 │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```