@silbaram/artifact-driven-agent 0.1.5 → 0.1.7

package/README.md

@@ -1,883 +1,530 @@
-# Artifact-Driven AI Agent Framework
-
-CLI 기반 멀티 AI 에이전트를 사용해 기획 → 설계 → 개발 → 리뷰 → QA → 관리까지
-**사람 팀처럼 역할을 분리하여 개발하는 구조**를 가진다.
-
-## 🎯 목표
-
-- AI가 감으로 개발하지 못하게 한다
-- 모든 판단을 문서 기준으로 고정한다
-- **Task 단위로 반복 가능한 애자일 개발 파이프라인**을 만든다
-
-## 💡 핵심 개념
-
-이 구조는 AI가 똑똑해서 돌아가는 시스템이 아니다.
-**AI가 규칙을 어기지 못해서** 안정적으로 돌아간다.
-
-### 문서 기반 제약 구현
-
-AI 에이전트 실행 시, 시스템 프롬프트에 다음을 포함합니다:
-
-1. **모든 규칙 파일 내용** (rules/*.md) - 규칙을 반드시 알아야 함
-2. **핵심 산출물 내용** (decision.md, project.md, current-sprint.md, plan.md, backlog.md)
-3. **인터페이스 문서 내용** (api.md, ui.md, public-api.md 등)
-4. **멀티 세션 상태 관리 안내** (.ada-status.json 사용법)
-
-이를 통해 AI는:
-- 문서에 명시된 규칙을 따라야만 함
-- 현재 작업 범위(current-sprint.md)를 벗어날 수 없음
-- 기술 기준(project.md)에 없는 기술을 추가할 수 없음
-- 다른 세션과 상태를 공유하며 협업
-
-**파일명만 나열하지 않고, 내용을 포함**하는 것이 핵심입니다.
-
----
-
-## 📁 디렉토리 구조
-
-```
-artifact-driven-agent/
-│
-├── package.json               # npm 패키지 설정
-├── bin/
-│   └── cli.js                 # CLI 진입점 (ada 명령어)
-│
-├── 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           # 파일/경로 유틸리티
-│       └── sessionState.js    # 멀티 세션 상태 관리
-│
-├── core/                      # 범용 핵심 (6역할, 8산출물, 5규칙)
-│   ├── roles/
-│   ├── artifacts/
-│   └── rules/
-│
-├── templates/                 # 프로젝트 유형별 템플릿
-│   ├── web-dev/
-│   ├── library/
-│   ├── game/
-│   └── cli/
-│
-├── ai-dev-team/               # 작업 디렉토리 (setup 후 사용)
-├── examples/                  # 예제 프로젝트
-└── scripts/                   # 쉘 스크립트 (레거시)
-```
-
----
-
-## 🚀 설치
-
-### 방법 1: npm 설치 (권장)
-
-```bash
-# 전역 설치
-npm install -g @silbaram/artifact-driven-agent
-
-# 또는 npx로 바로 실행
-npx @silbaram/artifact-driven-agent setup web
-```
-
-### 방법 2: 저장소 클론
-
-```bash
-git clone https://github.com/silbaram/artifact-driven-agent.git
-cd artifact-driven-agent
-npm install
-npm link  # 전역 명령어 등록
-```
-
-### 설치 확인
-
-```bash
-ada --version
-ada --help
-```
-
----
-
-## 🖥️ CLI 명령어 상세
-
-### 전체 명령어 요약
-
-| 명령어 | 설명 |
-|--------|------|
-| `ada` | 대화형 모드 |
-| `ada setup [template]` | 템플릿 세팅 |
-| `ada status` | 상태 확인 |
-| `ada reset [-f]` | 초기화 |
-| `ada validate [doc]` | 문서 검증 |
-| `ada sessions` | 세션 목록 |
-| `ada sessions -w` | Watch 모드 (실시간 모니터링) |
-| `ada logs [id]` | 로그 확인 |
-| `ada run <role> <tool>` | AI 실행 |
-| `ada <role> <tool>` | AI 실행 (단축) |
-
----
-
-### `ada setup` - 프로젝트 세팅
-
-**소스:** `src/commands/setup.js`
-
-템플릿을 선택하여 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` 파일에 현재 템플릿 저장
-
----
-
-### `ada status` - 상태 확인
-
-**소스:** `src/commands/status.js`
-
-현재 세팅 상태를 확인합니다.
-
-```bash
-ada status
-```
-
-**출력 내용:**
-- 현재 템플릿
-- 역할 목록
-- 산출물 목록 (상태 표시: Draft/Confirmed/Frozen)
-- 규칙 목록
-
----
-
-### `ada validate` - 문서 검증
-
-**소스:** `src/commands/validate.js`
-
-산출물 문서의 완성도를 자동 검사합니다.
-
-```bash
-# 전체 검증
-ada validate
-
-# 특정 문서만
-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. `.ada-status.json`에 세션 등록 (멀티 세션 지원)
-3. 역할 파일 로드 → 시스템 프롬프트 생성
-   - 모든 규칙(rules/) 파일 내용 포함
-   - 핵심 산출물(decision.md, project.md 등) 내용 포함
-   - 인터페이스 문서(api.md, ui.md 등) 내용 포함
-4. 활성 세션 및 대기 질문 표시
-5. AI CLI 도구 실행 또는 프롬프트 출력
-6. 세션 종료 시 상태 파일에서 제거
-7. 세션/로그 기록
-
----
-
-### `ada sessions` - 실시간 세션 상태
-
-**소스:** `src/commands/sessions.js`
-
-**실시간 멀티 세션 상태**와 세션 기록을 확인합니다.
-
-```bash
-# 기본 모드
-ada sessions
-
-# Watch 모드 (실시간 모니터링 대시보드)
-ada sessions --watch
-ada sessions -w
-```
-
-#### 기본 모드 출력 내용:
-
-1. **🟢 활성 세션 (실시간)**: 현재 실행 중인 역할 목록
-2. **⚠️ 대기 질문**: Manager에게 응답 대기 중인 질문
-3. **📊 진행 중인 Task**: Task별 진행률 및 담당자
-4. **📜 최근 세션 기록**: 완료된 세션 히스토리
-
-이 명령어는 멀티 터미널 환경에서 다른 세션들의 작업 상태를 실시간으로 확인할 때 유용합니다.
-
-#### Watch 모드 (Manager 전용):
-
-**실시간 모니터링 대시보드**로, Manager 역할 수행 시 유용합니다.
-
-**주요 기능:**
-- 📊 **통계 패널**: 활성 세션, 대기 질문, 진행 Task, 알림 요약
-- 🟢 **활성 세션**: 각 세션의 역할, 도구, 실행 시간 표시
-- ⚠️ **대기 질문**: 응답이 필요한 질문 강조 표시 (대기 시간 포함)
-- 📊 **진행 Task**: 진행률 바와 색상으로 상태 시각화
-- 🔔 **최근 알림**: 읽음/안읽음 표시
-
-**자동 갱신:**
-- `.ada-status.json` 파일 변경 시 즉시 갱신
-- 2초마다 시간 정보 자동 갱신
-
-**키보드 단축키:**
-- `q` - 종료
-- `r` - 수동 새로고침
-- `c` - 화면 지우기
-- `h` - 도움말
-- `Ctrl+C` - 강제 종료
-
-**사용 시나리오:**
-```bash
-# 터미널 1: Manager Watch 모드 (모니터링)
-ada sessions --watch
-
-# 터미널 2-4: 여러 개발 세션
-ada developer codex
-ada reviewer gemini
-ada qa claude
-```
-
----
-
-### `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 역할 (7개)
-
-| 역할 | 파일 | 책임 |
-|------|------|------|
-| **Analyzer** | analyzer.md | 기존 프로젝트 분석, project.md/plan.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-dev | backend | API 설계, 서버 구현 |
-| web-dev | frontend | UI 구현, API 연동 |
-| library | library-developer | 공개 API 설계, 버전 관리 |
-| game | game-logic | 게임 시스템 설계 |
-| game | rendering | 화면/이펙트 구현 |
-| cli | cli-developer | 명령어 설계, 출력 형식 |
-
----
-
-## 📄 산출물 (Artifacts)
-
-### Core 산출물 (8개)
-
-| 문서 | 용도 | 관리자 | 상태 |
-|------|------|--------|------|
-| 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-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) 전체 상세
-
-### Core 규칙 (5개)
-
----
-
-#### 1. `iteration.md` - 스프린트/Task 단위 작업
-
-**위치:** `core/rules/iteration.md`
-
-Task 단위 반복 개발 규칙을 정의합니다.
-
-**핵심 원칙:**
-
-```
-❌ 잘못된 방식 (Waterfall)
-전체 기획 → 전체 설계 → 전체 개발 → 전체 테스트
-
-✅ 올바른 방식 (Iterative)
-Task 1 완성 → Task 2 완성 → Task 3 완성 → ...
-```
-
-**작업 범위 제한:**
-- `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`
-
-문서 간 충돌 시 우선순위를 정의합니다.
-
-**우선순위 (높은 순):**
-
-```
-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 에스컬레이션
-
----
-
-#### 5. `rfc.md` - Frozen 문서 변경 절차
-
-**위치:** `core/rules/rfc.md`
-
-Frozen 상태 문서 변경을 위한 공식 절차입니다.
-
-**RFC 필요 상황:**
-- project.md 변경
-- plan.md의 확정된 기능 범위 변경
-- decision.md 항목 번복
-
-**RFC 절차:**
-
-```
-1. RFC 문서 작성 (ai-dev-team/artifacts/rfc/RFC-NNNN-title.md)
-2. Manager 리뷰
-3. 승인/거부 결정
-4. 승인 시: 문서 업데이트 + decision.md 기록
-```
-
-**RFC 상태:**
-
-| 상태 | 설명 |
-|------|------|
-| Draft | 작성 중 |
-| Under Review | 리뷰 중 |
-| Approved | 승인됨 |
-| Rejected | 거부됨 |
-
-**긴급 변경:**
-- 보안 취약점, 심각한 버그 등
-- 구두 승인 후 적용
-- 24시간 내 RFC 사후 작성
-
----
-
-### 템플릿별 규칙
-
----
-
-#### `api-change.md` (web-dev)
-
-**위치:** `templates/web-dev/rules/api-change.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`
-
-Semantic Versioning 규칙을 정의합니다.
-
-**버전 형식:** `MAJOR.MINOR.PATCH`
-
-| 변경 유형 | 버전 증가 | 예시 |
-|----------|----------|------|
-| 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)
-
-**위치:** `templates/game/rules/system-change.md`
-
-게임 시스템 변경 절차를 정의합니다.
-
-**변경 영향 분석 필수:**
-- 밸런스 영향
-- 다른 시스템 의존성
-- 저장 데이터 호환성
-
-**변경 유형:**
-
-| 유형 | 승인 필요 |
-|------|:--------:|
-| 수치 조정 (10% 이내) | 불필요 |
-| 수치 조정 (10% 초과) | QA 확인 |
-| 시스템 로직 변경 | **Manager 승인** |
-| 새 시스템 추가 | **Architect 설계** |
-
----
-
-#### `command-change.md` (cli)
-
-**위치:** `templates/cli/rules/command-change.md`
-
-CLI 명령어 변경 절차를 정의합니다.
-
-**하위 호환성 원칙:**
-- 기존 명령어 삭제 금지 (Deprecated 후 다음 메이저 버전)
-- 기존 옵션 동작 변경 금지
-- 출력 형식 변경 시 --format 옵션 제공
-
-**변경 유형:**
-
-| 유형 | 승인 필요 |
-|------|:--------:|
-| 새 명령어 추가 | 불필요 |
-| 새 옵션 추가 | 불필요 |
-| 명령어 Deprecated | **Manager 승인** |
-| 출력 형식 변경 | QA 확인 |
-
----
-
-## 🔄 워크플로우
-
-### 전체 흐름
-
-```
-[신규 프로젝트]          [기존 프로젝트]
-      │                        │
-      │                   Analyzer (분석)
-      │                        │
-      ↓                        ↓
-Planner (plan.md + backlog.md)
-      ↓
-Architect (project.md → Frozen)
-      ↓
-Manager (스프린트 시작)
-      ↓
-[Sprint Loop]
-Developer → Reviewer → QA → Manager (Task 완료)
-      ↓
-Manager (스프린트 종료)
-      ↓
-(다음 스프린트 또는 완료)
-```
-
-### Task 상태 흐름
-
-```
-BACKLOG → READY → IN_SPRINT → IN_DEV → IN_REVIEW → IN_QA → DONE
-```
-
----
-
-## 🖥️ 멀티 세션 모드
-
-여러 터미널에서 동시에 다른 역할을 실행할 수 있습니다. 각 세션은 자동으로 등록되고, 상태를 실시간으로 공유합니다.
-
-### 사용 예시
-
-```bash
-# 터미널 1: Manager (오케스트레이터)
-ada manager claude
-
-# 터미널 2: Developer
-ada developer codex
-
-# 터미널 3: Reviewer
-ada reviewer gemini
-```
-
-### 자동 세션 관리
-
-**세션 시작 시:**
-- `.ada-status.json`에 자동 등록
-- 다른 활성 세션 목록 표시
-- 대기 중인 질문 알림
-
-**세션 종료 시:**
-- 상태 파일에서 자동 제거
-- 보유한 파일 잠금 해제
-
-### 상태 파일
-
-```
-ai-dev-team/.ada-status.json
-```
-
-모든 세션이 이 파일을 통해 상태를 공유합니다.
-
-**스키마 구성:**
-- `activeSessions[]`: 현재 실행 중인 세션
-- `pendingQuestions[]`: 응답 대기 중인 질문
-- `taskProgress{}`: Task별 진행률
-- `notifications[]`: 세션 간 알림
-- `locks{}`: 파일 잠금 상태
-
-### 실시간 모니터링
-
-어느 터미널에서든 실시간 상태를 확인할 수 있습니다:
-
-```bash
-ada sessions
-```
-
-**출력 예시:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📋 세션 상태
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-🟢 활성 세션 (실시간)
-
-  역할        도구      시작 시간           상태
-  developer  codex     2024-12-29 14:20   🟢 active
-  reviewer   gemini    2024-12-29 14:25   🟢 active
-
-⚠️  대기 질문
-
-  [QD001] developer → manager
-  질문: Redis 캐시를 적용할까요?
-  옵션: y: 적용, n: 미적용
-
-📊 진행 중인 Task
-
-  T001: ████████░░ 80% (IN_REVIEW)
-    담당: developer
-    메모: API 구현 완료, 리뷰 대기 중
-```
-
-### 질문/응답 프로토콜
-
-AI 에이전트가 Manager에게 질문해야 할 때, `.ada-status.json`의 `pendingQuestions`에 질문을 추가합니다.
-
-**질문 등록 (AI가 수행):**
-
-```javascript
-// AI가 .ada-status.json 파일을 직접 수정
-{
-  "pendingQuestions": [
-    {
-      "id": "QD001",
-      "from": "developer",
-      "to": "manager",
-      "question": "Redis 캐시를 적용할까요?",
-      "options": ["y: 적용", "n: 미적용"],
-      "status": "waiting",
-      "createdAt": "2024-12-29T14:30:00Z"
-    }
-  ]
-}
-```
-
-**응답 확인:**
-
-Manager 역할(또는 사용자)이 상태 파일을 업데이트하면, Developer 역할이 응답을 읽어서 작업을 계속합니다.
-
-**모니터링:**
-
-```bash
-# 어느 터미널에서든 확인 가능
-ada sessions
-```
-
-### AI 에이전트의 상태 관리
-
-AI 에이전트는 시스템 프롬프트를 통해 다음 작업을 수행하도록 안내받습니다:
-
-1. **Task 진행 상황 업데이트**: `taskProgress` 섹션 수정
-2. **질문 등록**: `pendingQuestions` 배열에 추가
-3. **알림 전송**: `notifications` 배열에 추가
-4. **파일 잠금**: `locks` 객체로 동시 수정 방지
-
-### 관련 문서
-
-- `core/rules/session-state.md` - 상태 파일 스키마
-- `core/rules/role-state-protocol.md` - 역할별 프로토콜
-- `src/utils/sessionState.js` - 상태 관리 유틸리티 구현
-
----
-
-## 📦 Feature 단위 구조 (대규모)
-
-대규모 프로젝트에서 병렬 개발을 위한 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/`
-
-각 Feature는 독립적으로 개발/리뷰/QA 가능합니다.
-
----
-
-## 📊 템플릿 비교
-
-| 항목 | web-dev | library | game | cli |
-|------|:-------:|:-------:|:----:|:---:|
-| 개발자 역할 | 2개 | 1개 | 2개 | 1개 |
-| API 계약 | ✅ | ✅ | - | ✅ |
-| 버전 관리 | - | ✅ | - | ✅ |
-| 에셋 관리 | - | - | ✅ | - |
-| UI/UX 문서 | ✅ | - | ✅ | ✅ |
-
----
-
-## ⚠️ 핵심 원칙
-
-### 금지 사항
-
-- ❌ 문서 없는 진행
-- ❌ 기준 없는 판단
-- ❌ 감으로 추가된 기술
-- ❌ 스프린트 외 작업
-- ❌ Frozen 문서 무단 변경
-
-### 필수 사항
-
-- ✅ 문서 기준 판단
-- ✅ 역할별 책임 분리
-- ✅ Task 단위 반복 개발
-- ✅ 변경 시 RFC 절차
-
----
-
-## 📄 라이선스
-
-MIT License
+# Artifact-Driven AI Agent Framework
+
+**문서 기반 멀티 AI 에이전트 개발 프레임워크**
+
+4개 핵심 역할(Planner, Developer, Reviewer, Documenter)이 스프린트 단위로 협업하여 안정적인 개발 워크플로우를 만듭니다.
+
+## 🎯 목표
+
+- AI가 감으로 개발하지 못하게 한다
+- 모든 판단을 문서 기준으로 고정한다
+- **스프린트/Task 단위 반복 개발 파이프라인**을 만든다
+
+## 💡 핵심 개념
+
+이 구조는 AI가 똑똑해서 돌아가는 시스템이 아니다.
+**AI가 규칙을 어기지 못해서** 안정적으로 돌아간다.
+
+### 문서 기반 제약 구현
+
+AI 에이전트 실행 시, 시스템 프롬프트에 다음을 포함합니다:
+
+1. **모든 규칙 파일 내용** (rules/*.md)
+2. **핵심 산출물 내용** (plan.md, project.md, 현재 스프린트 Task 파일)
+3. **인터페이스 문서 내용** (api.md, ui.md 등)
+
+이를 통해 AI는:
+- 문서에 명시된 규칙을 따라야만 함
+- 현재 스프린트 범위를 벗어날 수 없음
+- project.md에 없는 기술을 추가할 수 없음
+
+**파일명만 나열하지 않고, 내용을 포함**하는 것이 핵심입니다.
+
+---
+
+## 🚀 설치
+
+### npm 설치 (권장)
+
+```bash
+# 전역 설치
+npm install -g @silbaram/artifact-driven-agent
+
+# 또는 npx로 바로 실행
+npx @silbaram/artifact-driven-agent setup web
+```
+
+### 저장소 클론
+
+```bash
+git clone https://github.com/silbaram/artifact-driven-agent.git
+cd artifact-driven-agent
+npm install
+npm link  # 전역 명령어 등록
+```
+
+### 설치 확인
+
+```bash
+ada --version
+ada --help
+```
+
+---
+
+## 🖥️ 빠른 시작
+
+### 1. 프로젝트 세팅
+
+```bash
+ada setup web       # 웹 서비스
+ada setup lib       # 라이브러리
+ada setup game      # 게임
+ada setup cli       # CLI 도구
+```
+
+### 2. 기획 시작
+
+```bash
+ada planner claude  # 요구사항 수집 → plan.md + backlog/*.md 생성
+```
+
+### 3. 스프린트 생성
+
+```bash
+ada sprint create                # 새 스프린트 생성
+ada sprint add task-001 task-002 # Task 추가
+```
+
+### 4. 개발
+
+```bash
+ada developer claude  # Task 구현 → DONE 상태로 변경
+```
+
+### 5. 리뷰
+
+```bash
+ada reviewer claude   # 코드 리뷰 → review-reports/ 생성
+```
+
+### 6. 스프린트 종료
+
+```bash
+ada sprint close               # 스프린트 종료
+ada documenter claude          # 문서 작성
+```
+
+---
+
+## 👥 역할 시스템
+
+### 핵심 역할 (4개) - 모든 프로젝트 필수
+
+| 역할 | 책임 | 산출물 |
+|------|------|--------|
+| **Planner** | 요구사항 수집, Task 분해 | plan.md, backlog/*.md |
+| **Developer** | 코드 구현, Task 완료 | 소스 코드, Task 파일 업데이트 |
+| **Reviewer** | 코드 리뷰, 품질 판정 | review-reports/*.md |
+| **Documenter** | 스프린트 완료 시 문서 작성 | API Changelog, Release Notes, User Guide |
+
+### 선택 역할 (1개) - 기존 프로젝트 도입 시
+
+| 역할 | 책임 | 사용 시점 |
+|------|------|----------|
+| **Analyzer** | 기존 코드베이스 분석, project.md 역생성 | 레거시 프로젝트에 ada 도입 시 |
+
+---
+
+## 📂 디렉토리 구조
+
+### 프로젝트 루트
+
+```
+artifact-driven-agent/
+├── bin/cli.js              # CLI 진입점
+├── src/
+│   ├── commands/           # 명령어 구현
+│   │   ├── setup.js
+│   │   ├── run.js
+│   │   ├── sprint.js      # 스프린트 관리
+│   │   └── sessions.js    # 세션 모니터링
+│   └── utils/
+│       ├── files.js
+│       └── sessionState.js
+├── core/                   # 범용 핵심
+│   ├── roles/              # 5개 역할
+│   ├── artifacts/          # 산출물 템플릿
+│   │   └── sprints/
+│   │       └── _template/  # 스프린트 템플릿
+│   └── rules/              # 5개 규칙
+└── templates/              # 프로젝트 유형별
+    ├── web-dev/
+    ├── library/
+    ├── game/
+    └── cli/
+```
+
+### 작업 디렉토리 (setup 후)
+
+```
+ai-dev-team/
+├── artifacts/
+│   ├── plan.md             # 전체 요구사항
+│   ├── project.md          # 기술 기준 (선택)
+│   ├── backlog/            # 스프린트 미할당 Task
+│   │   ├── task-001.md
+│   │   └── task-002.md
+│   └── sprints/            # 스프린트별 디렉토리
+│       ├── sprint-1/       # 완료된 스프린트
+│       │   ├── meta.md
+│       │   ├── tasks/
+│       │   │   ├── task-003.md
+│       │   │   └── task-004.md
+│       │   ├── review-reports/
+│       │   │   ├── task-003.md
+│       │   │   └── task-004.md
+│       │   ├── docs/
+│       │   │   ├── api-changelog.md
+│       │   │   └── release-notes.md
+│       │   └── retrospective.md
+│       └── sprint-2/       # 진행 중인 스프린트
+│           ├── meta.md
+│           └── tasks/
+│               └── task-005.md
+├── roles/                  # core + template 병합
+├── rules/
+└── .sessions/              # 세션 이력
+    ├── logs/
+    └── .ada-status.json    # 멀티 세션 상태 파일
+```
+
+---
+
+## 🖥️ CLI 명령어
+
+### 기본 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `ada` | 대화형 모드 |
+| `ada setup [template]` | 템플릿 세팅 (web, lib, game, cli) |
+| `ada status` | 상태 확인 |
+| `ada validate [doc]` | 문서 검증 |
+| `ada reset [-f]` | 초기화 |
+
+### 스프린트 관리
+
+| 명령어 | 설명 |
+|--------|------|
+| `ada sprint create` | 새 스프린트 생성 |
+| `ada sprint add task-001 ...` | Task 추가 |
+| `ada sprint close` | 현재 스프린트 종료 |
+| `ada sprint list` | 스프린트 목록 |
+
+### AI 에이전트 실행
+
+```bash
+# 정식 형식
+ada run <role> <tool>
+
+# 단축 형식 (run 생략)
+ada <role> <tool>
+
+# 예시
+ada planner claude
+ada developer codex
+ada reviewer gemini
+ada documenter claude
+```
+
+**지원 도구:** claude, codex, gemini, copilot
+
+### 세션 모니터링
+
+```bash
+# 세션 목록 및 상태
+ada sessions
+
+# 실시간 모니터링 대시보드
+ada sessions --watch
+ada sessions -w
+
+# 대기 질문이 있으면 자동으로 응답 프롬프트가 표시됩니다.
+# 세션 로그 확인
+ada logs
+ada logs [session-id]
+```
+
+---
+
+## 🔄 워크플로우
+
+### 신규 프로젝트
+
+```
+1. Planner: 요구사항 수집
+   → plan.md + backlog/*.md 생성
+
+2. Manager: 스프린트 생성/Task 할당
+   → (plan.md Confirmed 후 watch에서 승인하면 자동 실행)
+   → 자동 실행: ada sprint create
+   → 자동 실행: ada sprint add task-001 task-002
+
+3. Developer: Task 구현
+   → 코드 작성
+   → Task 상태를 DONE으로 변경
+
+4. Reviewer: 코드 리뷰
+   → review-reports/*.md 생성
+   → PASS/REJECT 판정
+
+5. 사용자: 스프린트 종료
+   → ada sprint close
+
+6. Documenter: 문서 작성
+   → docs/*.md 생성 (API Changelog, Release Notes 등)
+
+7. 다음 스프린트 시작
+   → ada sprint create
+```
+
+### 기존 프로젝트
+
+```
+0. Analyzer: 코드베이스 분석
+   → project.md 역생성
+
+1. Planner: 추가 기능 기획
+   → plan.md 업데이트
+   → backlog/*.md 생성
+
+2. 이후 신규 프로젝트와 동일
+```
+
+### Task 상태 흐름
+
+```
+BACKLOG → IN_DEV → DONE → (리뷰 후) → 스프린트 완료
+```
+
+---
+
+## 📋 규칙 시스템
+
+### Core 규칙 (5개)
+
+| 규칙 | 용도 |
+|------|------|
+| `iteration.md` | 스프린트/Task 단위 작업 규칙 |
+| `escalation.md` | 에스컬레이션 기준 |
+| `rollback.md` | REJECT 시 처리 절차 |
+| `document-priority.md` | 문서 충돌 시 우선순위 |
+| `rfc.md` | Frozen 문서 변경 절차 |
+
+### 템플릿별 규칙
+
+| 템플릿 | 규칙 | 용도 |
+|--------|------|------|
+| web-dev | `api-change.md` | API 변경 절차 |
+| library | `versioning.md` | Semantic Versioning |
+| game | `system-change.md` | 게임 시스템 변경 |
+| cli | `command-change.md` | CLI 명령어 변경 |
+
+---
+
+## 📄 산출물
+
+### Core 산출물
+
+| 문서 | 관리자 | 용도 |
+|------|--------|------|
+| plan.md | Planner | 전체 요구사항 |
+| project.md | 사용자/팀 (선택) | 기술 기준 (Frozen) |
+| backlog/*.md | Planner | 스프린트 미할당 Task |
+| sprints/sprint-N/meta.md | 자동 생성 | 스프린트 메타정보 |
+| sprints/sprint-N/tasks/*.md | Developer | Task별 상세 정보 |
+| sprints/sprint-N/review-reports/*.md | Reviewer | 리뷰 결과 |
+| sprints/sprint-N/docs/*.md | Documenter | 릴리스 문서 |
+| sprints/sprint-N/retrospective.md | 사용자 | 회고 |
+
+### 템플릿별 산출물
+
+| 템플릿 | 문서 | 용도 |
+|--------|------|------|
+| web-dev | api.md, ui.md | API 계약, 화면 설계 |
+| library | public-api.md, changelog.md | 공개 API, 변경 이력 |
+| game | game-systems.md, assets.md | 시스템, 에셋 |
+| cli | commands.md, output-format.md | 명령어, 출력 형식 |
+
+---
+
+## 🖥️ 멀티 세션 모드
+
+여러 터미널에서 동시에 다른 역할을 실행할 수 있습니다.
+
+### 사용 예시
+
+```bash
+# 터미널 1: Planner
+ada planner claude
+
+# 터미널 2: Developer
+ada developer codex
+
+# 터미널 3: Reviewer
+ada reviewer gemini
+
+# 터미널 4: 실시간 모니터링
+ada sessions --watch
+```
+
+**세션 모니터링 포인트**
+- 대기 질문이 생성되면 watch 화면이 자동 프롬프트로 전환됩니다.
+- 프롬프트는 사용자가 직접 입력하며, 응답은 `.ada-status.json`에 저장됩니다.
+- 승인형 질문에 '예'로 응답하면 필요한 CLI 작업을 자동 실행합니다.
+
+### 자동 세션 관리
+
+**세션 시작 시:**
+- `.ada-status.json`에 자동 등록
+- 터미널 타이틀 설정 (예: "ADA: developer (codex)")
+- 역할 이모지 배너 표시
+
+**세션 종료 시:**
+- 상태 파일에서 자동 제거
+- 세션 로그 저장
+
+### 상태 파일
+
+```
+ai-dev-team/.sessions/.ada-status.json
+```
+
+모든 세션이 이 파일을 통해 상태를 공유합니다.
+
+**구성:**
+- `activeSessions[]`: 실행 중인 세션
+- `pendingQuestions[]`: 대기 질문 및 응답 상태
+- `taskProgress[]`: Task 진행 상황
+- `notifications[]`: 세션 간 알림
+- (기존 Manager 관련 필드는 제거됨)
+
+---
+
+## ⚠️ 핵심 원칙
+
+### 금지 사항
+
+- ❌ 문서 없는 진행
+- ❌ 기준 없는 판단
+- ❌ 감으로 추가된 기술
+- ❌ 스프린트 외 작업
+- ❌ "김에" 리팩토링
+- ❌ 역할 간 경계 침범
+
+### 필수 사항
+
+- ✅ 문서 기준 판단
+- ✅ 역할별 책임 분리
+- ✅ Task 단위 반복 개발
+- ✅ 스프린트 단위 관리
+- ✅ REJECT 시 원인 분석
+
+---
+
+## 📊 템플릿 비교
+
+| 템플릿 | 설명 | 특화 문서 |
+|--------|------|----------|
+| **web-dev** | 웹 서비스/API 서버 | api.md, ui.md |
+| **library** | npm/pip 라이브러리 | public-api.md, changelog.md |
+| **game** | 게임 개발 | game-systems.md, assets.md |
+| **cli** | CLI 도구 | commands.md, output-format.md |
+
+---
+
+## 🎯 주요 개선 사항 (v0.2.0)
+
+### 역할 시스템 간소화
+
+**이전 (v0.1.x):**
+- 7개 Core 역할 + 템플릿별 특화 역할 (총 13개)
+- Manager 중심의 복잡한 승인 프로세스
+- 역할 간 blocking 문제 (backend ↔ frontend)
+
+**현재 (v0.2.x):**
+- 4개 핵심 역할 (planner, developer, reviewer, documenter)
+- 사용자 직접 스프린트 관리 (CLI 명령어)
+- 단순화된 워크플로우
+
+### 스프린트 기반 구조
+
+**이전:**
+- 단일 파일 (backlog.md, current-sprint.md)
+- Git 충돌 위험
+- Task별 독립성 부족
+
+**현재:**
+- 디렉토리 기반 (sprints/sprint-N/)
+- Task별 개별 파일 (task-NNN.md)
+- 리뷰/문서도 Task별 분리
+- 완료된 스프린트는 불변 (이력 보존)
+
+### 자동화 개선
+
+**추가된 CLI 명령어:**
+- `ada sprint create` - 스프린트 자동 생성
+- `ada sprint add` - Task 자동 추가
+- `ada sprint close` - 스프린트 종료 및 회고 템플릿 생성
+- `ada sprint list` - 스프린트 목록 확인
+
+---
+
+## 🔧 개발 환경
+
+### 필수 요구사항
+
+- Node.js 18+
+- npm 7+
+
+### 로컬 개발
+
+```bash
+git clone https://github.com/silbaram/artifact-driven-agent.git
+cd artifact-driven-agent
+npm install
+npm link  # 전역 ada 명령어 등록
+```
+
+### 테스트
+
+```bash
+npm test   # Node.js 내장 test runner 사용
+```
+
+---
+
+## 📄 문서
+
+- **CLAUDE.md**: Claude Code AI를 위한 상세 가이드
+- **core/roles/*.md**: 각 역할의 상세 규칙
+- **core/rules/*.md**: 핵심 규칙 문서
+- **templates/*/**: 템플릿별 특화 문서
+
+---
+
+## 🤝 기여
+
+이슈 및 PR 환영합니다!
+
+**보고 위치:**
+- GitHub Issues: https://github.com/silbaram/artifact-driven-agent/issues
+
+---
+
+## 📄 라이선스
+
+MIT License
+
+---
+
+## 📮 연락처
+
+- GitHub: [@silbaram](https://github.com/silbaram)
+- npm: [@silbaram/artifact-driven-agent](https://www.npmjs.com/package/@silbaram/artifact-driven-agent)
+
+
+
+
+