@silbaram/artifact-driven-agent 0.1.0 → 0.1.2

package/README.md

@@ -21,77 +21,46 @@ CLI 기반 멀티 AI 에이전트를 사용해 기획 → 설계 → 개발 →
 ```
 artifact-driven-agent/
 │
-├── README.md
-├── .gitignore
+├── package.json               # npm 패키지 설정
+├── bin/
+│   └── cli.js                 # CLI 진입점 (ada 명령어)
 │
-├── scripts/                       # 🔧 실행 스크립트
-│   ├── ai-role.sh                 # Linux/Mac
-│   ├── ai-role.ps1                # Windows PowerShell
-│   ├── ai-role.bat                # Windows CMD
-│   └── lint/
-│       └── validate-docs.sh       # 문서 검증 스크립트
+├── src/                       # CLI 소스 코드
+│   ├── index.js               # 모듈 익스포트
+│   ├── commands/              # 명령어 구현
+│   │   ├── setup.js           # 템플릿 세팅
+│   │   ├── status.js          # 상태 확인
+│   │   ├── reset.js           # 초기화
+│   │   ├── validate.js        # 문서 검증
+│   │   ├── sessions.js        # 세션 목록
+│   │   ├── logs.js            # 로그 확인
+│   │   ├── run.js             # AI 에이전트 실행
+│   │   └── interactive.js     # 대화형 모드
+│   └── utils/
+│       └── files.js           # 파일/경로 유틸리티
 │
-├── ai-dev-team/                   # 🎯 작업 디렉토리 (setup 후 사용)
-│   ├── roles/                     # 세팅된 역할들
-│   ├── artifacts/                 # 세팅된 산출물 템플릿
-│   │   ├── features/              # Feature 단위 산출물
-│   │   │   └── _template/         # Feature 템플릿
-│   │   └── rfc/                   # RFC 변경 요청서
-│   │       └── RFC-0000-template.md
-│   └── rules/                     # 세팅된 규칙들
+├── core/                      # 범용 핵심 (6역할, 8산출물, 5규칙)
+│   ├── roles/
+│   ├── artifacts/
+│   └── rules/
 │
-├── core/                          # 🔵 범용 핵심 (소스)
-│   ├── roles/                     # 6개: planner, architect, developer,
-│   │   │                          #       reviewer, qa, manager
-│   │   ├── planner.md
-│   │   ├── architect.md
-│   │   ├── developer.md
-│   │   ├── reviewer.md
-│   │   ├── qa.md
-│   │   └── manager.md
-│   │
-│   ├── artifacts/                 # 8개: 공통 산출물 템플릿
-│   │   ├── plan.md
-│   │   ├── project.md
-│   │   ├── backlog.md
-│   │   ├── current-sprint.md
-│   │   ├── decision.md
-│   │   ├── architecture-options.md
-│   │   ├── review-report.md
-│   │   └── qa-report.md
-│   │
-│   └── rules/                     # 5개: 공통 규칙
-│       ├── iteration.md
-│       ├── escalation.md
-│       ├── rollback.md
-│       ├── document-priority.md
-│       └── rfc.md                 # RFC 변경 관리 규칙
+├── templates/                 # 프로젝트 유형별 템플릿
+│   ├── web-dev/
+│   ├── library/
+│   ├── game/
+│   └── cli/
 │
-├── templates/                     # 🟢 프로젝트 유형별 템플릿 (소스)
-│   ├── web-dev/                   # 웹 서비스 개발
-│   ├── library/                   # 라이브러리/SDK 개발
-│   ├── game/                      # 게임 개발
-│   └── cli/                       # CLI 도구 개발
-│
-├── docs/                          # 📖 가이드 문서
-│   └── feature-structure.md       # Feature 단위 구조 가이드
-│
-└── examples/                      # 📚 예제 프로젝트
-    └── todo-app/                  # Todo App 예제
-        ├── README.md
-        └── artifacts/
-            ├── plan.md
-            ├── project.md
-            └── backlog.md
+├── ai-dev-team/               # 작업 디렉토리 (setup 후 사용)
+├── docs/                      # 가이드 문서
+├── examples/                  # 예제 프로젝트
+└── scripts/                   # 쉘 스크립트 (레거시)
 ```
 
 ---
 
-## 🚀 빠른 시작
-
-### 설치 방법
+## 🚀 설치
 
-#### 방법 1: npm (권장)
+### 방법 1: npm 설치 (권장)
 
 ```bash
 # 전역 설치
@@ -101,311 +70,563 @@ npm install -g @silbaram/artifact-driven-agent
 npx @silbaram/artifact-driven-agent setup web
 ```
 
-#### 방법 2: 직접 다운로드
+### 방법 2: 저장소 클론
 
 ```bash
-# 저장소 클론
 git clone https://github.com/silbaram/artifact-driven-agent.git
 cd artifact-driven-agent
 npm install
 npm link  # 전역 명령어 등록
 ```
 
-### 1단계: 개발 스타일 세팅
+### 설치 확인
 
 ```bash
-# npm 설치 후
-ada setup web
-
-# 또는 직접 지정
-ada setup web      # 웹 서비스 개발 (web-dev 별칭)
-ada setup library  # 라이브러리 개발 (lib 별칭)
-ada setup game     # 게임 개발
-ada setup cli      # CLI 도구 개발
+ada --version
+ada --help
 ```
 
-> ⚠️ **Windows PowerShell 오류 시**
-> ```powershell
-> # 현재 세션에서만 실행 허용
-> Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
-> ```
+---
 
-### 2단계: AI 에이전트 실행
+## 🖥️ CLI 명령어 상세
 
-```bash
-# 대화형으로 역할/도구 선택
-ada
+### 전체 명령어 요약
 
-# 또는 직접 지정
-ada backend claude
-ada planner codex
-ada run frontend gemini
-```
+| 명령어 | 설명 |
+|--------|------|
+| `ada` | 대화형 모드 |
+| `ada setup [template]` | 템플릿 세팅 |
+| `ada status` | 상태 확인 |
+| `ada reset [-f]` | 초기화 |
+| `ada validate [doc]` | 문서 검증 |
+| `ada sessions` | 세션 목록 |
+| `ada logs [id]` | 로그 확인 |
+| `ada run <role> <tool>` | AI 실행 |
+| `ada <role> <tool>` | AI 실행 (단축) |
 
 ---
 
-## 🖥 스크립트 명령어
+### `ada setup` - 프로젝트 세팅
 
-### 세팅 명령어
+**소스:** `src/commands/setup.js`
 
-| 명령어             | 설명                           |
-| ------------------ | ------------------------------ |
-| `setup`            | 대화형으로 템플릿 선택 후 세팅 |
-| `setup <template>` | 특정 템플릿으로 세팅           |
-| `status`           | 현재 세팅 상태 확인            |
-| `reset`            | ai-dev-team 초기화             |
+템플릿을 선택하여 ai-dev-team 디렉토리를 구성합니다.
+
+```bash
+# 대화형 선택
+ada setup
+
+# 직접 지정
+ada setup web       # 웹 서비스 (web-dev 별칭)
+ada setup lib       # 라이브러리 (library 별칭)
+ada setup game      # 게임
+ada setup cli       # CLI 도구
+```
 
-### 실행 명령어
+**동작:**
+1. `core/` 디렉토리의 공통 roles, artifacts, rules 복사
+2. 선택한 템플릿의 전용 파일 병합
+3. Feature/RFC 템플릿 복사
+4. `.current-template` 파일에 현재 템플릿 저장
 
-| 명령어          | 설명                              |
-| --------------- | --------------------------------- |
-| (인자 없음)     | 대화형으로 역할/도구 선택 후 실행 |
-| `<role> <tool>` | 직접 역할과 도구 지정해서 실행    |
+---
 
-### 검증/관리 명령어
+### `ada status` - 상태 확인
 
-| 명령어              | 설명                                      |
-| ------------------- | ----------------------------------------- |
-| `validate`          | 산출물 문서 검증 (plan.md, project.md 등) |
-| `sessions`          | AI 실행 세션 목록                         |
-| `logs`              | 가장 최근 세션 로그 확인                  |
-| `logs <session-id>` | 특정 세션 로그 확인                       |
+**소스:** `src/commands/status.js`
 
-### 예시
+현재 세팅 상태를 확인합니다.
 
 ```bash
-# 웹 개발로 세팅
-ada setup web
-
-# 현재 상태 확인
 ada status
+```
+
+**출력 내용:**
+- 현재 템플릿
+- 역할 목록
+- 산출물 목록 (상태 표시: Draft/Confirmed/Frozen)
+- 규칙 목록
+
+---
 
-# 문서 검증 (스프린트 시작 전 권장)
+### `ada validate` - 문서 검증
+
+**소스:** `src/commands/validate.js`
+
+산출물 문서의 완성도를 자동 검사합니다.
+
+```bash
+# 전체 검증
 ada validate
 
-# 백엔드 개발자로 Claude 실행
+# 특정 문서만
+ada validate plan
+ada validate project
+ada validate backlog
+ada validate sprint
+```
+
+**검사 항목:**
+
+| 문서 | 검사 내용 |
+|------|----------|
+| plan.md | 필수 섹션(서비스 개요, 기능 목록, 비기능 요구사항), TBD 3개 이하 |
+| project.md | 필수 섹션(프로젝트 규모, 기술 스택), Frozen 상태, 버전 형식 |
+| backlog.md | Task 개수, 수용 조건 존재 |
+| current-sprint.md | 스프린트 번호, 목표 섹션 |
+
+---
+
+### `ada run` / `ada <role> <tool>` - AI 에이전트 실행
+
+**소스:** `src/commands/run.js`
+
+특정 역할로 AI 도구를 실행합니다.
+
+```bash
+# 정식 명령어
+ada run backend claude
+ada run planner codex
+
+# 단축 명령어 (run 생략)
 ada backend claude
+ada planner codex
+ada frontend gemini
+```
+
+**지원 역할:**
+- Core: planner, architect, developer, reviewer, qa, manager
+- 템플릿별: backend, frontend, library-developer, game-logic, rendering, cli-developer
 
-# 세션 목록 확인
+**지원 도구:** claude, codex, gemini, copilot
+
+**동작:**
+1. 세션 ID 생성 (YYYYMMDD-HHMMSS-random)
+2. 역할 파일 로드 → 시스템 프롬프트 생성
+3. AI CLI 도구 실행 또는 프롬프트 출력
+4. 세션/로그 기록
+
+---
+
+### `ada sessions` - 세션 목록
+
+**소스:** `src/commands/sessions.js`
+
+AI 에이전트 실행 이력을 확인합니다.
+
+```bash
 ada sessions
+```
+
+---
 
-# 최근 로그 확인
+### `ada logs` - 로그 확인
+
+**소스:** `src/commands/logs.js`
+
+세션별 상세 로그를 확인합니다.
+
+```bash
+# 최근 세션 로그
 ada logs
+
+# 특정 세션 로그
+ada logs 20241228-143022-a1b2c3d4
+```
+
+---
+
+### `ada reset` - 초기화
+
+**소스:** `src/commands/reset.js`
+
+ai-dev-team 디렉토리를 초기 상태로 되돌립니다.
+
+```bash
+# 확인 후 초기화
+ada reset
+
+# 강제 초기화
+ada reset --force
+ada reset -f
+```
+
+---
+
+### `ada` (인자 없음) - 대화형 모드
+
+**소스:** `src/commands/interactive.js`
+
+대화형으로 역할과 도구를 선택합니다.
+
+```bash
+ada
 ```
 
+**동작:**
+1. 세팅 안 됐으면 setup 제안
+2. 역할 선택 (목록 표시)
+3. 도구 선택 (목록 표시)
+4. AI 에이전트 실행
+
 ---
 
 ## 👥 역할 (Roles)
 
-### Core 역할 (모든 템플릿에서 사용)
+### Core 역할 (6개)
 
-| 역할      | 파일         | 책임                      |
-| --------- | ------------ | ------------------------- |
-| Planner   | planner.md   | 요구사항 수집, Task 분해  |
-| Architect | architect.md | 규모 예측, 기술 스택 결정 |
-| Developer | developer.md | 코드 구현 (범용)          |
-| Reviewer  | reviewer.md  | 코드 리뷰                 |
-| QA        | qa.md        | 수용 조건 검증            |
-| Manager   | manager.md   | 스프린트 관리, 승인       |
+| 역할 | 파일 | 책임 |
+|------|------|------|
+| **Planner** | planner.md | 요구사항 수집, Task 분해, plan.md/backlog.md 작성 |
+| **Architect** | architect.md | 규모 예측, 기술 스택 결정, project.md 작성 |
+| **Developer** | developer.md | 코드 구현 (범용) |
+| **Reviewer** | reviewer.md | 코드 리뷰, PASS/REJECT 판정 |
+| **QA** | qa.md | 수용 조건 검증, PASS/FAIL 판정 |
+| **Manager** | manager.md | 스프린트 관리, 승인, 에스컬레이션 처리 |
 
 ### 템플릿별 특화 역할
 
-| 템플릿  | 역할              | 책임                     |
-| ------- | ----------------- | ------------------------ |
-| web     | backend           | API 설계, 서버 구현      |
-| web     | frontend          | UI 구현, API 연동        |
+| 템플릿 | 역할 | 책임 |
+|--------|------|------|
+| web-dev | backend | API 설계, 서버 구현 |
+| web-dev | frontend | UI 구현, API 연동 |
 | library | library-developer | 공개 API 설계, 버전 관리 |
-| game    | game-logic        | 게임 시스템 설계         |
-| game    | rendering         | 화면/이펙트 구현         |
-| cli     | cli-developer     | 명령어 설계, 출력 형식   |
+| game | game-logic | 게임 시스템 설계 |
+| game | rendering | 화면/이펙트 구현 |
+| cli | cli-developer | 명령어 설계, 출력 형식 |
 
 ---
 
 ## 📄 산출물 (Artifacts)
 
-### Core 산출물
+### Core 산출물 (8개)
 
-| 문서                    | 용도               | 관리자           |
-| ----------------------- | ------------------ | ---------------- |
-| plan.md                 | 기획서             | Planner          |
-| project.md              | 기술 기준 (Frozen) | Architect        |
-| backlog.md              | Task 목록          | Planner, Manager |
-| current-sprint.md       | 현재 스프린트      | Manager          |
-| decision.md             | 판단 기록          | Manager          |
-| architecture-options.md | 아키텍처 협상      | Architect        |
-| review-report.md        | 리뷰 결과          | Reviewer         |
-| qa-report.md            | QA 결과            | QA               |
+| 문서 | 용도 | 관리자 | 상태 |
+|------|------|--------|------|
+| plan.md | 기획서 | Planner | Draft → Confirmed |
+| project.md | 기술 기준 | Architect | Draft → **Frozen** |
+| backlog.md | Task 목록 | Planner, Manager | - |
+| current-sprint.md | 현재 스프린트 | Manager | - |
+| decision.md | 판단 기록 (최우선) | Manager | - |
+| architecture-options.md | 아키텍처 옵션 | Architect | - |
+| review-report.md | 리뷰 결과 | Reviewer | - |
+| qa-report.md | QA 결과 | QA | - |
 
 ### 템플릿별 산출물
 
-| 템플릿  | 문서             | 용도            |
-| ------- | ---------------- | --------------- |
-| web     | api.md           | REST API 계약   |
-| web     | ui.md            | 화면 설계       |
-| library | public-api.md    | 공개 인터페이스 |
-| library | examples.md      | 사용 예제       |
-| library | changelog.md     | 버전 변경 이력  |
-| game    | game-systems.md  | 게임 시스템     |
-| game    | assets.md        | 에셋 목록       |
-| game    | hud.md           | HUD/UI 설계     |
-| cli     | commands.md      | 명령어 정의     |
-| cli     | output-format.md | 출력 형식       |
+| 템플릿 | 문서 | 용도 |
+|--------|------|------|
+| web-dev | api.md, ui.md | API 계약, 화면 설계 |
+| library | public-api.md, examples.md, changelog.md | 공개 API, 예제, 변경 이력 |
+| game | game-systems.md, assets.md, hud.md | 시스템, 에셋, HUD |
+| cli | commands.md, output-format.md | 명령어, 출력 형식 |
 
 ---
 
-## 📋 규칙 (Rules)
+## 📋 규칙 (Rules) 전체 상세
 
-### Core 규칙
+### Core 규칙 (5개)
 
-| 규칙                 | 용도                    |
-| -------------------- | ----------------------- |
-| iteration.md         | 스프린트/Task 단위 작업 |
-| escalation.md        | Manager 보고 기준       |
-| rollback.md          | REJECT/FAIL 시 되돌림   |
-| document-priority.md | 문서 충돌 해결          |
-| rfc.md               | Frozen 문서 변경 절차   |
-
-### 템플릿별 규칙
+---
 
-| 템플릿  | 규칙              | 용도                |
-| ------- | ----------------- | ------------------- |
-| web     | api-change.md     | API 변경 절차       |
-| library | versioning.md     | Semantic Versioning |
-| game    | system-change.md  | 게임 시스템 변경    |
-| cli     | command-change.md | 명령어 변경 절차    |
+#### 1. `iteration.md` - 스프린트/Task 단위 작업
 
----
+**위치:** `core/rules/iteration.md`
 
-## 🔄 워크플로우
+Task 단위 반복 개발 규칙을 정의합니다.
 
-### 전체 흐름
+**핵심 원칙:**
 
 ```
-Planner (plan.md + backlog.md)
-    ↓
-Architect (project.md)
-    ↓
-Manager (스프린트 시작)
-    ↓
-[Sprint Loop]
-Developer → Reviewer → QA → Manager (Task 완료)
-    ↓
-Manager (스프린트 종료)
-    ↓
-(다음 스프린트 또는 완료)
+❌ 잘못된 방식 (Waterfall)
+전체 기획 → 전체 설계 → 전체 개발 → 전체 테스트
+
+✅ 올바른 방식 (Iterative)
+Task 1 완성 → Task 2 완성 → Task 3 완성 → ...
 ```
 
-### Task 상태 흐름
+**작업 범위 제한:**
+- `current-sprint.md`에 정의된 Task만 작업
+- 스프린트 외 작업 금지 (Manager 승인 없이)
+- "김에" 작업 금지
+
+**Task 완료 조건:**
+- [ ] 수용 조건 100% 충족
+- [ ] Reviewer PASS
+- [ ] QA PASS
+- [ ] Manager 확인
+
+---
+
+#### 2. `escalation.md` - Manager 보고 기준
+
+**위치:** `core/rules/escalation.md`
+
+Manager에게 보고해야 하는 상황을 정의합니다.
+
+**에스컬레이션 원칙:**
+- 판단 불가 시 → 즉시 에스컬레이션
+- 규칙 외 상황 → 즉시 에스컬레이션
+- 혼자 결정하지 않음
+
+**즉시 에스컬레이션 (BLOCK):**
+
+| 상황 | 예시 |
+|------|------|
+| project.md에 없는 기술 필요 | 새 라이브러리 도입 필요 |
+| 요구사항 모호/충돌 | plan.md 해석 불가 |
+| 문서 간 충돌 | plan.md ↔ project.md 불일치 |
+| 역할 간 해석 불일치 | 같은 문서 다르게 해석 |
+| 구현 불가능 판단 | 기술적으로 불가 |
+| 보안/안전 이슈 | 심각한 취약점 발견 |
+
+**보고 사항 (REPORT):**
+- 예상보다 규모가 큼
+- 의존성 문제 발견
+- 일정 지연 예상
+
+---
+
+#### 3. `rollback.md` - REJECT/FAIL 시 되돌림
+
+**위치:** `core/rules/rollback.md`
+
+REJECT/FAIL 발생 시 처리 절차를 정의합니다.
+
+**되돌림 원칙:**
+- REJECT/FAIL은 정상적인 피드백
+- 되돌림 시 원인 분석 필수
+- 반복 되돌림 시 프로세스 점검
+
+**Reviewer REJECT 처리:**
+
+| REJECT 유형 | 되돌림 대상 | Manager 개입 |
+|-------------|------------|:------------:|
+| 수용 조건 미충족 | Developer | 불필요 |
+| project.md 규칙 위반 | Developer | 불필요 |
+| 구조적 문제 | Architect | 필요 |
+| 설계 수준 문제 | Architect | 필요 |
+
+**QA FAIL 처리:**
+
+| FAIL 유형 | 되돌림 대상 |
+|-----------|------------|
+| 버그 | Developer |
+| 수용 조건 오해 | Planner |
+| 설계 문제 | Architect |
+
+**3회 반복 시:** Manager가 원인 분석 후 프로세스 점검
+
+---
+
+#### 4. `document-priority.md` - 문서 충돌 해결
+
+**위치:** `core/rules/document-priority.md`
+
+문서 간 충돌 시 우선순위를 정의합니다.
+
+**우선순위 (높은 순):**
 
 ```
-BACKLOG → READY → IN_SPRINT → IN_DEV → IN_REVIEW → IN_QA → DONE
+1. decision.md        ← Manager 판단 (최우선)
+2. project.md         ← 기술 기준 (Frozen)
+3. plan.md            ← 요구사항 기준
+4. backlog.md         ← Task/수용 조건
+5. 인터페이스 문서    ← api.md, ui.md 등
+6. current-sprint.md  ← 현재 범위
+7. architecture-options.md
+8. review/qa-report.md
 ```
 
+**충돌 해결:**
+- 상위 문서가 정답
+- 하위 문서를 상위에 맞게 수정
+- 수정 불가 시 Manager 에스컬레이션
+
 ---
 
-## 🔒 RFC (변경 관리)
+#### 5. `rfc.md` - Frozen 문서 변경 절차
 
-Frozen 상태인 `project.md`나 확정된 `plan.md`를 변경해야 할 때 사용합니다.
+**위치:** `core/rules/rfc.md`
 
-### RFC가 필요한 경우
+Frozen 상태 문서 변경을 위한 공식 절차입니다.
 
+**RFC 필요 상황:**
 - project.md 변경
 - plan.md의 확정된 기능 범위 변경
 - decision.md 항목 번복
 
-### RFC 절차
+**RFC 절차:**
 
-1. `ai-dev-team/artifacts/rfc/RFC-NNNN-title.md` 작성
+```
+1. RFC 문서 작성 (ai-dev-team/artifacts/rfc/RFC-NNNN-title.md)
 2. Manager 리뷰
 3. 승인/거부 결정
 4. 승인 시: 문서 업데이트 + decision.md 기록
+```
 
-상세 규칙: `core/rules/rfc.md`
+**RFC 상태:**
+
+| 상태 | 설명 |
+|------|------|
+| Draft | 작성 중 |
+| Under Review | 리뷰 중 |
+| Approved | 승인됨 |
+| Rejected | 거부됨 |
+
+**긴급 변경:**
+- 보안 취약점, 심각한 버그 등
+- 구두 승인 후 적용
+- 24시간 내 RFC 사후 작성
 
 ---
 
-## 📦 Feature 단위 구조 (대규모 프로젝트)
+### 템플릿별 규칙
+
+---
 
-규모 M 이상, 기능 3개 이상일 때 Feature 단위로 산출물을 분리합니다.
+#### `api-change.md` (web-dev)
 
-```
-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/       # 템플릿
-```
+**위치:** `templates/web-dev/rules/api-change.md`
 
-상세 가이드: `docs/feature-structure.md`
+REST API 변경 절차를 정의합니다.
+
+**변경 유형:**
+
+| 유형 | 예시 | 승인 필요 |
+|------|------|:--------:|
+| 추가 | 새 엔드포인트 | 불필요 |
+| 수정 (호환) | 선택 필드 추가 | 불필요 |
+| 수정 (Breaking) | 필수 필드 추가, 삭제 | **Manager 승인** |
+| 삭제 | 엔드포인트 제거 | **Manager 승인** |
+
+**Breaking Change 절차:**
+1. api.md에 Deprecated 표시
+2. RFC 작성
+3. Manager 승인
+4. 마이그레이션 가이드 작성
+5. 변경 적용
 
 ---
 
-## ✅ 문서 검증
+#### `versioning.md` (library)
 
-스프린트 시작 전 문서 완성도를 자동 검사합니다.
+**위치:** `templates/library/rules/versioning.md`
 
-```bash
-ada validate
-```
+Semantic Versioning 규칙을 정의합니다.
 
-### 검사 항목
+**버전 형식:** `MAJOR.MINOR.PATCH`
 
-- plan.md: 필수 섹션, TBD 3개 이하
-- project.md: Frozen 상태, 버전 형식
-- backlog.md: Task 개수, 수용 조건
-- current-sprint.md: 스프린트 번호, 목표
+| 변경 유형 | 버전 증가 | 예시 |
+|----------|----------|------|
+| Breaking Change | MAJOR | 1.0.0 → 2.0.0 |
+| 새 기능 (호환) | MINOR | 1.0.0 → 1.1.0 |
+| 버그 수정 | PATCH | 1.0.0 → 1.0.1 |
+
+**changelog.md 필수 기록:**
+- 변경 내용
+- Breaking Change 여부
+- 마이그레이션 가이드 (필요 시)
 
 ---
 
-## 🔍 세션/로그 관리
+#### `system-change.md` (game)
 
-AI 에이전트 실행마다 세션 ID가 부여되어 추적이 가능합니다.
+**위치:** `templates/game/rules/system-change.md`
 
-```bash
-# 세션 목록
-ada sessions
+게임 시스템 변경 절차를 정의합니다.
 
-# 로그 확인
-ada logs
-ada logs 20241227-143022-a1b2c3d4
+**변경 영향 분석 필수:**
+- 밸런스 영향
+- 다른 시스템 의존성
+- 저장 데이터 호환성
+
+**변경 유형:**
+
+| 유형 | 승인 필요 |
+|------|:--------:|
+| 수치 조정 (10% 이내) | 불필요 |
+| 수치 조정 (10% 초과) | QA 확인 |
+| 시스템 로직 변경 | **Manager 승인** |
+| 새 시스템 추가 | **Architect 설계** |
+
+---
+
+#### `command-change.md` (cli)
+
+**위치:** `templates/cli/rules/command-change.md`
+
+CLI 명령어 변경 절차를 정의합니다.
+
+**하위 호환성 원칙:**
+- 기존 명령어 삭제 금지 (Deprecated 후 다음 메이저 버전)
+- 기존 옵션 동작 변경 금지
+- 출력 형식 변경 시 --format 옵션 제공
+
+**변경 유형:**
+
+| 유형 | 승인 필요 |
+|------|:--------:|
+| 새 명령어 추가 | 불필요 |
+| 새 옵션 추가 | 불필요 |
+| 명령어 Deprecated | **Manager 승인** |
+| 출력 형식 변경 | QA 확인 |
+
+---
+
+## 🔄 워크플로우
+
+### 전체 흐름
+
+```
+Planner (plan.md + backlog.md)
+    ↓
+Architect (project.md → Frozen)
+    ↓
+Manager (스프린트 시작)
+    ↓
+[Sprint Loop]
+Developer → Reviewer → QA → Manager (Task 완료)
+    ↓
+Manager (스프린트 종료)
+    ↓
+(다음 스프린트 또는 완료)
 ```
 
-### 세션 ID 형식
+### Task 상태 흐름
 
 ```
-YYYYMMDD-HHMMSS-<random>
-예: 20241227-143022-a1b2c3d4
+BACKLOG → READY → IN_SPRINT → IN_DEV → IN_REVIEW → IN_QA → DONE
 ```
 
 ---
 
-## 📚 예제 프로젝트
-
-`examples/todo-app/`에 완성된 예제가 있습니다.
+## 📦 Feature 단위 구조 (대규모)
 
-- 규모: S (Small)
-- 기간: 1주일
-- 완료된 산출물: plan.md, project.md, backlog.md
+규모 M 이상, 기능 3개 이상일 때 사용합니다.
 
-학습 포인트:
-1. 문서 순서: plan → project → 개발
-2. 체크리스트로 완성도 보장
-3. Task 단위 작업
+```
+ai-dev-team/artifacts/features/
+├── F001-user-auth/
+│   ├── spec.md
+│   ├── api.md
+│   ├── ui.md
+│   ├── review.md
+│   └── qa.md
+└── _template/
+```
 
 ---
 
 ## 📊 템플릿 비교
 
-| 항목        |  web  | library | game  |  cli  |
-| ----------- | :---: | :-----: | :---: | :---: |
-| 개발자 역할 |  2개  |   1개   |  2개  |  1개  |
-| API 계약    |   ✅   |    ✅    |   -   |   ✅   |
-| 버전 관리   |   -   |    ✅    |   -   |   ✅   |
-| 에셋 관리   |   -   |    -    |   ✅   |   -   |
-| UI/UX 문서  |   ✅   |    -    |   ✅   |   ✅   |
+| 항목 | web-dev | library | game | cli |
+|------|:-------:|:-------:|:----:|:---:|
+| 개발자 역할 | 2개 | 1개 | 2개 | 1개 |
+| API 계약 | ✅ | ✅ | - | ✅ |
+| 버전 관리 | - | ✅ | - | ✅ |
+| 에셋 관리 | - | - | ✅ | - |
+| UI/UX 문서 | ✅ | - | ✅ | ✅ |
 
 ---
 
@@ -417,40 +638,17 @@ YYYYMMDD-HHMMSS-<random>
 - ❌ 기준 없는 판단
 - ❌ 감으로 추가된 기술
 - ❌ 스프린트 외 작업
-- ❌ 수용 조건 외 기능 추가
+- ❌ Frozen 문서 무단 변경
 
 ### 필수 사항
 
 - ✅ 문서 기준 판단
 - ✅ 역할별 책임 분리
 - ✅ Task 단위 반복 개발
-- ✅ 스프린트 범위 준수
-
----
-
-## 📚 추가 정보
-
-### 문서 우선순위
-
-```
-decision.md > project.md > plan.md > backlog.md > 인터페이스 문서
-```
-
-### 에스컬레이션 기준
-
-- project.md에 없는 기술 필요 → BLOCK
-- 요구사항 모호 → BLOCK
-- 예상보다 규모 큼 → 보고
-
-### 되돌림 규칙
-
-- Reviewer REJECT → Developer 수정
-- QA FAIL → 원인에 따라 대상 결정
-- 3회 반복 → Manager 개입
+- ✅ 변경 시 RFC 절차
 
 ---
 
-## 🤝 기여
+## 📄 라이선스
 
-이 프레임워크는 AI 에이전트 기반 개발의 표준화를 목표로 합니다.
-새로운 템플릿이나 규칙 개선 제안은 언제나 환영합니다.
+MIT License

package/core/roles/architect.md

@@ -167,7 +167,12 @@ Architect: plan.md를 분석했습니다.
 - ❌ 기능 추가/삭제 제안
 - ❌ 사용자 동의 없이 기술 결정
 - ❌ project.md 확정 후 임의 변경
-- ❌ 구현 코드 작성
+- ❌ **코드 작성/구현 (절대 금지)**
+- ❌ **소스 파일 생성/수정 (절대 금지)**
+- ❌ **개발 작업 수행 (절대 금지)**
+
+> ⚠️ **중요**: Architect는 오직 project.md와 architecture-options.md 문서만 작성합니다.
+> 코드, 설정 파일, 소스 파일 등 어떠한 구현 작업도 수행하지 않습니다.
 
 ---
 

package/core/roles/developer.md

@@ -118,6 +118,13 @@ IN_DEV → IN_REVIEW    : 구현 완료 시
 - ❌ 수용 조건 외 "개선" 작업
 - ❌ 문서 없이 구조 변경
 - ❌ 다른 개발자 영역 임의 수정
+- ❌ **기획 문서 작성 (Planner 역할)**
+- ❌ **아키텍처/기술 스택 결정 (Architect 역할)**
+- ❌ **코드 리뷰 수행 (Reviewer 역할)**
+- ❌ **QA 테스트 수행 (QA 역할)**
+
+> ⚠️ **중요**: Developer는 current-sprint.md에 할당된 Task의 코드만 구현합니다.
+> 다른 역할의 작업은 절대 수행하지 않습니다.
 
 ---
 

package/core/roles/manager.md

@@ -196,13 +196,21 @@ Manager: 현재 상태를 검토했습니다.
 
 ---
 
-## 6. 금지 사항
+## 6. 금지 사항 (CRITICAL)
 
 - ❌ 문서 없이 진행 승인
 - ❌ REJECT/FAIL 무시
 - ❌ 기록 없는 예외 승인
-- ❌ 역할 범위 침해 (직접 코드 수정 등)
 - ❌ 스프린트 범위 임의 변경
+- ❌ **코드 직접 수정/구현 (절대 금지)**
+- ❌ **기획 작업 (Planner 역할)**
+- ❌ **아키텍처 작업 (Architect 역할)**
+- ❌ **개발 작업 (Developer 역할)**
+- ❌ **코드 리뷰 (Reviewer 역할)**
+- ❌ **QA 테스트 (QA 역할)**
+
+> ⚠️ **중요**: Manager는 오직 스프린트 관리, 승인, 에스컬레이션 처리만 수행합니다.
+> 다른 역할의 작업은 절대 수행하지 않습니다.
 
 ---
 

package/core/roles/planner.md

@@ -160,6 +160,12 @@ Planner: 할일 관리 앱이군요. 몇 가지 여쭤볼게요.
 - ❌ 구현 방법 언급
 - ❌ "~로 만들면 될 것 같아요" 류 발언
 - ❌ 개발 일정 추정
+- ❌ **코드 작성/구현 (절대 금지)**
+- ❌ **소스 파일 생성/수정 (절대 금지)**
+- ❌ **개발 작업 수행 (절대 금지)**
+
+> ⚠️ **중요**: Planner는 오직 plan.md와 backlog.md 문서만 작성합니다.
+> 코드, 설정 파일, 소스 파일 등 어떠한 구현 작업도 수행하지 않습니다.
 
 ---
 

package/core/roles/qa.md

@@ -116,7 +116,12 @@
 - ❌ 기술적 구현 방식 지적 (Reviewer 영역)
 - ❌ 새로운 요구사항 추가
 - ❌ "더 좋을 것 같다"로 FAIL 판정
-- ❌ 코드 직접 수정
+- ❌ **코드 직접 수정/구현 (절대 금지)**
+- ❌ **기획/아키텍처 작업 (다른 역할)**
+- ❌ **코드 리뷰 수행 (Reviewer 역할)**
+
+> ⚠️ **중요**: QA는 오직 수용 조건 검증과 qa-report.md 작성만 수행합니다.
+> 코드 수정이나 다른 역할의 작업은 절대 수행하지 않습니다.
 
 ---
 

package/core/roles/reviewer.md

@@ -149,7 +149,12 @@ project.md 규칙 준수?
 - ❌ 수용 조건 외 기능 요구
 - ❌ 개인 스타일 강요 (project.md에 없는)
 - ❌ 아키텍처 변경 요구 (Manager 승인 없이)
-- ❌ 코드 직접 수정
+- ❌ **코드 직접 수정/구현 (절대 금지)**
+- ❌ **기획/아키텍처 작업 (다른 역할)**
+- ❌ **QA 테스트 수행 (QA 역할)**
+
+> ⚠️ **중요**: Reviewer는 오직 코드 리뷰와 review-report.md 작성만 수행합니다.
+> 코드 수정이나 다른 역할의 작업은 절대 수행하지 않습니다.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silbaram/artifact-driven-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI 기반 멀티 AI 에이전트 개발 프레임워크 - AI가 규칙을 어기지 못하게 하는 문서 기반 개발",
   "type": "module",
   "bin": {

package/templates/cli/roles/cli-developer.md

@@ -209,6 +209,10 @@ Task 구현 시:
 - ❌ stderr/stdout 혼용
 - ❌ project.md에 없는 기술 도입
 - ❌ 스프린트 외 작업
+- ❌ **기획 문서 작성 (Planner 역할)**
+- ❌ **아키텍처/기술 스택 결정 (Architect 역할)**
+
+> ⚠️ **중요**: CLI Developer는 오직 할당된 Task의 CLI 코드만 구현합니다.
 
 ---
 

package/templates/game/roles/game-logic.md

@@ -148,6 +148,11 @@ Task 구현 시:
 - ❌ project.md에 없는 기술 도입
 - ❌ 스프린트 외 작업
 - ❌ 다른 시스템 임의 수정
+- ❌ **기획 문서 작성 (Planner 역할)**
+- ❌ **아키텍처/기술 스택 결정 (Architect 역할)**
+- ❌ **Rendering 영역 코드 수정**
+
+> ⚠️ **중요**: Game Logic은 오직 할당된 Task의 게임 시스템 코드만 구현합니다.
 
 ---
 

package/templates/game/roles/rendering.md

@@ -112,6 +112,11 @@ plan.md와 project.md를 기준으로 게임의 시각적 요소를 구현한다
 - ❌ 하드코딩된 에셋 경로
 - ❌ project.md에 없는 기술 도입
 - ❌ 스프린트 외 작업
+- ❌ **기획 문서 작성 (Planner 역할)**
+- ❌ **아키텍처/기술 스택 결정 (Architect 역할)**
+- ❌ **Game Logic 영역 코드 수정**
+
+> ⚠️ **중요**: Rendering은 오직 할당된 Task의 렌더링/에셋 코드만 구현합니다.
 
 ---
 

package/templates/library/roles/library-developer.md

@@ -151,6 +151,10 @@ Task 구현 시:
 - ❌ PATCH 버전에서 기능 추가
 - ❌ MINOR 버전에서 Breaking change
 - ❌ 스프린트 외 작업
+- ❌ **기획 문서 작성 (Planner 역할)**
+- ❌ **아키텍처/기술 스택 결정 (Architect 역할)**
+
+> ⚠️ **중요**: Library Developer는 오직 할당된 Task의 라이브러리 코드만 구현합니다.
 
 ---
 

package/templates/web-dev/roles/backend.md

@@ -86,6 +86,11 @@ Task 구현 시 api.md 갱신:
 - ❌ Breaking change를 Manager 승인 없이
 - ❌ project.md에 없는 기술 도입
 - ❌ 스프린트 외 작업
+- ❌ **기획 문서 작성 (Planner 역할)**
+- ❌ **아키텍처/기술 스택 결정 (Architect 역할)**
+- ❌ **Frontend 영역 코드 수정**
+
+> ⚠️ **중요**: Backend는 오직 할당된 Task의 서버/API 코드만 구현합니다.
 
 ---
 

package/templates/web-dev/roles/frontend.md

@@ -111,6 +111,11 @@ Task 구현 시 ui.md 갱신:
 - ❌ project.md에 없는 라이브러리 도입
 - ❌ 스프린트 외 작업
 - ❌ 수용 조건 외 기능 추가
+- ❌ **기획 문서 작성 (Planner 역할)**
+- ❌ **아키텍처/기술 스택 결정 (Architect 역할)**
+- ❌ **Backend 영역 코드 수정**
+
+> ⚠️ **중요**: Frontend는 오직 할당된 Task의 UI/클라이언트 코드만 구현합니다.
 
 ---