@silbaram/artifact-driven-agent 0.1.0

package/core/rules/escalation.md

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

package/core/rules/iteration.md

@@ -0,0 +1,236 @@
+# Iteration Rules (스프린트/Task 단위 작업 규칙)
+
+> 이 문서는 Task 단위 반복 개발의 규칙을 정의한다.
+> 모든 역할이 이 규칙을 따른다.
+> Manager가 스프린트를 관리한다.
+
+---
+
+## 1. 핵심 원칙
+
+### 1.1 Task 단위 개발
+
+```
+❌ 잘못된 방식 (Waterfall)
+전체 기획 → 전체 설계 → 전체 개발 → 전체 테스트
+
+✅ 올바른 방식 (Iterative)
+Task 1 완성 → Task 2 완성 → Task 3 완성 → ...
+```
+
+### 1.2 작업 범위 제한
+
+- 각 역할은 **current-sprint.md에 정의된 Task만** 작업한다
+- 스프린트 외 작업은 금지 (Manager 승인 없이)
+- "김에" 작업 금지
+
+### 1.3 완료의 정의
+
+Task는 다음을 모두 충족해야 DONE:
+- [ ] 수용 조건 100% 충족
+- [ ] 구현 완료
+- [ ] 문서 반영 완료
+- [ ] Reviewer PASS
+- [ ] QA PASS
+- [ ] Manager 승인
+
+---
+
+## 2. 스프린트 라이프사이클
+
+### 2.1 스프린트 시작
+
+**트리거:** Manager가 스프린트 시작 선언
+
+**절차:**
+1. Manager가 backlog.md에서 READY 상태 Task 선택
+2. 선택된 Task를 IN_SPRINT로 변경
+3. current-sprint.md 생성/갱신
+4. 스프린트 목표 정의
+5. 역할별 작업 배정
+
+**산출물:**
+- current-sprint.md 갱신
+- backlog.md 상태 갱신
+
+### 2.2 스프린트 진행
+
+**Task 상태 흐름:**
+```
+IN_SPRINT → IN_DEV → IN_REVIEW → IN_QA → DONE
+               ↑          ↓          ↓
+               └──────────┴──────────┘
+                  (REJECT/FAIL 시)
+```
+
+**일일 확인 사항:**
+- 각 Task 상태
+- 차단 사항 (Blockers)
+- 예상 완료 여부
+
+### 2.3 스프린트 종료
+
+**트리거:** 
+- 모든 Task DONE, 또는
+- 스프린트 종료일 도달
+
+**절차:**
+1. 완료/미완료 Task 정리
+2. 미완료 Task 처리 결정 (이월/취소)
+3. current-sprint.md 회고 작성
+4. backlog.md 상태 갱신
+5. 다음 스프린트 준비
+
+---
+
+## 3. 역할별 이터레이션 규칙
+
+### 3.1 Planner
+
+- 스프린트 중 새 요구사항 → backlog에 BACKLOG 상태로 추가
+- 현재 스프린트의 Task 변경 금지 (Manager 승인 없이)
+- 진행 중(IN_DEV+) Task의 수용 조건 변경 금지
+
+### 3.2 Developer
+
+- current-sprint.md의 내 Task만 작업
+- Task 완료 후 다음 Task로 이동
+- 스프린트 외 작업 금지
+- 수용 조건 외 기능 추가 금지
+
+### 3.3 Reviewer
+
+- IN_REVIEW 상태 Task만 리뷰
+- 해당 Task 범위 내 코드만 리뷰
+- 스프린트 외 코드 리뷰 금지
+- 수용 조건 외 요구 금지
+
+### 3.4 QA
+
+- IN_QA 상태 Task만 검증
+- 해당 Task 수용 조건만 검증
+- 스프린트 외 기능 검증 금지
+- 수용 조건 외 기준으로 FAIL 금지
+
+### 3.5 Manager
+
+- 스프린트 시작/종료 결정
+- Task 상태 전환 승인 (→ DONE)
+- 긴급 Task 추가 승인
+- 스프린트 범위 변경 승인
+
+---
+
+## 4. Task 단위 문서 갱신
+
+### 4.1 갱신 시점
+
+| 문서 | 갱신 시점 | 담당 |
+|------|----------|------|
+| backlog.md | Task 상태 변경 시 | 해당 역할 |
+| current-sprint.md | 매일 / 상태 변경 시 | Manager |
+| 인터페이스 문서 | Task 완료 시 | Developer |
+| review-report.md | 리뷰 완료 시 | Reviewer |
+| qa-report.md | QA 완료 시 | QA |
+| decision.md | 판단 발생 시 | Manager |
+
+### 4.2 Task 태그
+
+문서 변경 시 관련 Task ID를 태그:
+
+```markdown
+## 변경 이력
+| Task | 날짜 | 변경 내용 |
+|------|------|----------|
+| [TASK-001] | 2024-01-15 | 초기 구현 |
+```
+
+---
+
+## 5. 예외 상황 처리
+
+### 5.1 긴급 Task 추가
+
+```
+긴급 요청 발생
+    ↓
+Planner: backlog에 P0로 추가
+    ↓
+Manager: 긴급성 판단
+    ├── 긴급 아님 → 다음 스프린트
+    └── 긴급 맞음 ↓
+        ↓
+Manager: 현재 스프린트에 추가
+    ↓
+필요시 다른 Task 조정
+    ↓
+decision.md에 예외 기록
+```
+
+### 5.2 요구사항 변경
+
+- 진행 중 Task: 현재 수용 조건으로 완료 후 새 Task 생성
+- 미시작 Task: 수용 조건 수정 가능 (Manager 승인)
+
+### 5.3 차단 (Blocker) 발생
+
+```
+차단 발생
+    ↓
+Task 상태 → BLOCKED
+    ↓
+Manager에게 즉시 보고
+    ↓
+해결 방안 결정
+    ↓
+해결 후 원래 상태로 복귀
+```
+
+---
+
+## 6. 스프린트 체크리스트
+
+### 스프린트 시작 체크리스트
+
+- [ ] backlog.md에 READY Task 있음
+- [ ] 스프린트 목표 정의됨
+- [ ] current-sprint.md 생성됨
+- [ ] Task 담당자 배정됨
+- [ ] 의존성 확인됨
+
+### 스프린트 종료 체크리스트
+
+- [ ] 모든 Task 상태 확인
+- [ ] 미완료 Task 처리 결정됨
+- [ ] 회고 작성됨
+- [ ] backlog.md 갱신됨
+- [ ] 스프린트 히스토리 기록됨
+
+---
+
+## 7. 문서 참조 관계
+
+```
+backlog.md (전체 Task)
+    │
+    ├── current-sprint.md (현재 범위)
+    │       │
+    │       ├── 인터페이스 문서 (Task별 변경)
+    │       └── 소스 코드
+    │
+    ├── plan.md (요구사항 출처)
+    └── project.md (기술 기준)
+```
+
+---
+
+## 8. 금지 사항 요약
+
+| 역할 | 금지 사항 |
+|------|----------|
+| 전체 | 스프린트 외 작업 |
+| 전체 | 수용 조건 외 기능 추가 |
+| Developer | "김에" 리팩토링 |
+| Reviewer | 스프린트 외 코드 리뷰 |
+| QA | 스프린트 외 기능 검증 |
+| Planner | 진행 중 Task 변경 |

package/core/rules/rfc.md

@@ -0,0 +1,31 @@
+# RFC (Request for Change) 규칙
+
+> Frozen 문서 변경을 위한 공식 절차
+
+## RFC가 필요한 경우
+
+- project.md 변경
+- plan.md의 확정된 기능 범위 변경
+- 승인된 decision.md 항목 번복
+
+## RFC 절차
+
+1. RFC 문서 작성 (`rfc/RFC-NNNN-title.md`)
+2. Manager 리뷰
+3. 승인/거부 결정
+4. 승인 시: 문서 업데이트 + decision.md 기록
+
+## RFC 상태
+
+| 상태 | 설명 |
+|------|------|
+| Draft | 작성 중 |
+| Under Review | 리뷰 중 |
+| Approved | 승인됨 |
+| Rejected | 거부됨 |
+
+## 긴급 변경
+
+- 보안 취약점, 심각한 버그 등
+- 구두 승인 후 적용
+- 24시간 내 RFC 사후 작성

package/core/rules/rollback.md

@@ -0,0 +1,218 @@
+# Rollback Rules (되돌림 규칙)
+
+> 이 문서는 REJECT/FAIL 발생 시 되돌림 절차를 정의한다.
+> Manager가 되돌림을 관리한다.
+
+---
+
+## 1. 되돌림 원칙
+
+- REJECT/FAIL은 정상적인 피드백
+- 되돌림은 품질 보장 과정
+- 되돌림 시 원인 분석 필수
+- 반복 되돌림 시 프로세스 점검
+
+---
+
+## 2. Reviewer REJECT 시 되돌림
+
+### 2.1 REJECT 유형별 처리
+
+| REJECT 유형 | 되돌림 대상 | Manager 개입 |
+|-------------|------------|:------------:|
+| 수용 조건 미충족 | Developer | 불필요 |
+| project.md 규칙 위반 | Developer | 불필요 |
+| 구조적 문제 | Architect | 필요 |
+| 설계 수준 문제 | Architect | 필요 |
+
+### 2.2 REJECT 처리 절차
+
+```
+Reviewer REJECT
+    ↓
+Task 상태: IN_REVIEW → IN_DEV
+    ↓
+review-report.md에 REJECT 사유 기록
+    ↓
+Developer가 수정
+    ↓
+Task 상태: IN_DEV → IN_REVIEW
+    ↓
+Reviewer 재리뷰
+```
+
+### 2.3 구조적 REJECT 시
+
+```
+Reviewer: 구조적 문제로 REJECT
+    ↓
+Manager에게 에스컬레이션
+    ↓
+Manager: Architect 재검토 결정
+    ↓
+Architect: project.md 또는 설계 수정
+    ↓
+Developer: 수정된 설계로 재구현
+```
+
+---
+
+## 3. QA FAIL 시 되돌림
+
+### 3.1 FAIL 유형별 처리
+
+| FAIL 유형 | 되돌림 대상 | 조치 |
+|-----------|------------|------|
+| 구현 누락 | Developer | 누락 기능 구현 |
+| 버그 | Developer | 버그 수정 |
+| 조건 모호 | Planner | 조건 명확화 |
+| 기술적 불가 | Architect | 설계 재검토 |
+
+### 3.2 FAIL 처리 절차
+
+```
+QA FAIL
+    ↓
+Task 상태: IN_QA → IN_DEV
+    ↓
+qa-report.md에 FAIL 사유 기록
+    ↓
+원인에 따라 담당자 결정
+    ↓
+수정 후 재리뷰 → 재QA
+```
+
+---
+
+## 4. BLOCK 시 되돌림
+
+### 4.1 BLOCK 상황
+
+| 상황 | 처리 |
+|------|------|
+| 기술적 불가 | Architect 재검토 |
+| 요구사항 불명확 | Planner 명확화 |
+| 외부 의존성 | 대기 또는 우회 |
+
+### 4.2 BLOCK 처리 절차
+
+```
+BLOCK 발생
+    ↓
+Task 상태 → BLOCKED
+    ↓
+Manager에게 에스컬레이션
+    ↓
+Manager: 원인 분석 및 대상 결정
+    ↓
+해당 역할이 문제 해결
+    ↓
+Task 상태 복원 → 재진행
+```
+
+---
+
+## 5. 문서 수정 시 연쇄 영향
+
+### 5.1 plan.md 수정 시
+
+| 영향 | 조치 |
+|------|------|
+| 기존 Task 영향 | backlog.md 수용 조건 검토 |
+| 새 기능 추가 | 새 Task 생성 |
+| 기능 삭제 | 관련 Task 취소 검토 |
+
+### 5.2 project.md 수정 시
+
+| 영향 | 조치 |
+|------|------|
+| 기술 스택 변경 | 전체 코드 검토 필요 |
+| 규칙 변경 | 영향받는 Task 재리뷰 |
+| 구조 변경 | 영향받는 코드 수정 |
+
+> ⚠️ project.md는 Frozen이므로 수정 시 Manager 승인 필수
+
+### 5.3 연쇄 영향 흐름
+
+```
+상위 문서 수정
+    ↓
+영향받는 하위 문서 식별
+    ↓
+영향받는 Task 식별
+    ↓
+Task 상태에 따른 처리:
+├── DONE → 재검증 필요 여부 판단
+├── IN_QA/IN_REVIEW → 재검증
+├── IN_DEV → 수정 반영
+└── IN_SPRINT/READY → 문서만 갱신
+```
+
+---
+
+## 6. 되돌림 제한 규칙
+
+### 6.1 반복 되돌림
+
+| 횟수 | 조치 |
+|:----:|------|
+| 1-2회 | 정상 피드백 |
+| 3회 | Manager 개입, 원인 분석 |
+| 4회+ | 프로세스/역량 점검 |
+
+### 6.2 되돌림 제한
+
+- 같은 사유로 3회 이상 되돌림 금지
+- 3회 도달 시 근본 원인 해결 필수
+- Manager가 되돌림 패턴 모니터링
+
+---
+
+## 7. 되돌림 기록 형식
+
+### decision.md 기록
+
+```markdown
+## Rollback #[번호]
+
+| 항목 | 값 |
+|------|-----|
+| 일시 | YYYY-MM-DD |
+| Task | TASK-XXX |
+| 유형 | REJECT / FAIL / BLOCK |
+| 원인 | [원인] |
+
+### 상세
+- 문제: [문제 설명]
+- 원인 분석: [원인]
+- 되돌림 대상: [역할]
+- 조치: [조치 내용]
+
+### 재발 방지
+- [방지 조치]
+```
+
+---
+
+## 8. 되돌림 흐름 요약
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                 │
+│  REJECT / FAIL / BLOCK 발생                                     │
+│         ↓                                                       │
+│  원인 분석                                                      │
+│         ↓                                                       │
+│  되돌림 대상 결정                                               │
+│  (Developer / Planner / Architect)                              │
+│         ↓                                                       │
+│  decision.md 기록                                               │
+│         ↓                                                       │
+│  수정 수행                                                      │
+│         ↓                                                       │
+│  재검증 (영향받는 단계부터)                                     │
+│         ↓                                                       │
+│  완료 또는 재되돌림                                             │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```

package/docs/feature-structure.md

@@ -0,0 +1,36 @@
+# Feature 단위 Artifacts 구조
+
+> 대규모 프로젝트에서 병렬 개발을 위한 Feature 분리 구조
+
+## 📁 구조
+
+```
+ai-dev-team/artifacts/features/
+├── F001-user-auth/
+│   ├── spec.md      # Feature 스펙
+│   ├── api.md       # Feature API
+│   ├── ui.md        # Feature UI
+│   ├── review.md    # 리뷰 기록
+│   └── qa.md        # QA 기록
+└── _template/       # 템플릿
+```
+
+## 🎯 언제 사용하는가?
+
+### 사용 권장
+- 프로젝트 규모 M 이상
+- 기능 3개 이상
+- 병렬 개발 필요
+
+### 사용 불필요
+- 프로젝트 규모 S
+- 기능 2개 이하
+- 순차 개발
+
+## 📋 명명 규칙
+
+```
+<Feature-ID>-<feature-name>/
+```
+
+예시: `F001-user-auth/`, `F002-dashboard/`

package/examples/todo-app/README.md

@@ -0,0 +1,23 @@
+# 예제: Todo App 프로젝트
+
+> Artifact-Driven AI Agent Framework 예제
+
+## 프로젝트 개요
+
+- **규모**: S (Small)
+- **기간**: 1주일
+- **상태**: ✅ 완료
+
+## 워크플로우
+
+1. Planner: plan.md 작성 → Confirmed
+2. Architect: project.md 작성 → Frozen
+3. Manager: 스프린트 시작
+4. Developer/Reviewer/QA: Task 완료
+5. Manager: 스프린트 종료
+
+## 산출물
+
+- `artifacts/plan.md` - 기획서
+- `artifacts/project.md` - 기술 기준
+- `artifacts/backlog.md` - Task 목록