@silbaram/artifact-driven-agent 0.1.7 → 0.1.9

package/README.md

@@ -2,7 +2,7 @@
 
 **문서 기반 멀티 AI 에이전트 개발 프레임워크**
 
-4개 핵심 역할(Planner, Developer, Reviewer, Documenter)이 스프린트 단위로 협업하여 안정적인 개발 워크플로우를 만듭니다.
+5개 핵심 역할(Planner, Improver, Developer, Reviewer, Documenter)이 스프린트 단위로 협업하여 안정적인 개발 워크플로우를 만듭니다.
 
 ## 🎯 목표
 
@@ -60,6 +60,36 @@ ada --version
 ada --help
 ```
 
+### 업그레이드
+
+npm 패키지를 업데이트한 후, 기존 작업공간도 최신 버전으로 업그레이드해야 합니다.
+
+```bash
+# npm 패키지 업데이트
+npm install -g @silbaram/artifact-driven-agent@latest
+
+# 작업공간 상태 확인 (버전 불일치 경고 표시)
+ada status
+
+# 변경 사항 미리보기
+ada upgrade --dry-run
+
+# 안전 업그레이드 (백업 + 확인)
+ada upgrade
+
+# 강제 업그레이드 (확인 없이)
+ada upgrade --force
+
+# 문제 발생 시 롤백
+ada upgrade --rollback
+```
+
+**업그레이드 동작:**
+- ✅ `roles/`, `rules/` 디렉토리 업데이트 (프레임워크 파일)
+- ✅ 자동 백업 생성 (`.backups/upgrade-YYYYMMDD-HHMMSS/`)
+- ✅ 사용자 데이터 보존 (`backlog/`, `sprints/`, `decision.md`, `project.md`, `plan.md`)
+- ✅ 버전 추적 (`.ada-version` 파일)
+
 ---
 
 ## 🖥️ 빠른 시작
@@ -98,22 +128,54 @@ ada developer claude  # Task 구현 → DONE 상태로 변경
 ada reviewer claude   # 코드 리뷰 → review-reports/ 생성
 ```
 
-### 6. 스프린트 종료
+### 6. 스프린트 종료 및 문서화
 
 ```bash
-ada sprint close               # 스프린트 종료
-ada documenter claude          # 문서 작성
+# 스프린트 종료 및 정리
+ada sprint close              # 작업 파일을 archive/ 폴더로 이동 (권장)
+ada sprint close --clean      # 작업 파일 완전 삭제 (최종 문서만 유지)
+ada sprint close --keep-all   # 모든 파일 유지
+
+# 문서 작성
+ada documenter claude         # Release Notes, API Changelog 등 생성
+```
+
+### 7. (선택) 프로젝트 문서 관리
+
+```bash
+# 문서 사이트 초기화 (최초 1회)
+ada docs init
+
+# 문서 생성/업데이트
+ada documenter claude         # Documenter가 docs/ 업데이트
+
+# 로컬 미리보기
+ada docs serve
+
+# GitHub Pages 배포
+ada docs publish
+```
+
+**종료 후 구조 (기본):**
+```
+sprints/sprint-N/
+├── meta.md                    # 스프린트 정보
+├── docs/                      # 최종 문서 ✅
+└── archive/                   # 작업 과정 보관
+    ├── tasks/
+    └── review-reports/
 ```
 
 ---
 
 ## 👥 역할 시스템
 
-### 핵심 역할 (4개) - 모든 프로젝트 필수
+### 핵심 역할 (5개) - 모든 프로젝트 필수
 
 | 역할 | 책임 | 산출물 |
 |------|------|--------|
-| **Planner** | 요구사항 수집, Task 분해 | plan.md, backlog/*.md |
+| **Planner** | 신규 기능 요구사항 수집, Task 분해 | plan.md, backlog/*.md |
+| **Improver** | 기존 기능 개선 분석 및 기획 | improvement-reports/*.md, backlog/*.md |
 | **Developer** | 코드 구현, Task 완료 | 소스 코드, Task 파일 업데이트 |
 | **Reviewer** | 코드 리뷰, 품질 판정 | review-reports/*.md |
 | **Documenter** | 스프린트 완료 시 문서 작성 | API Changelog, Release Notes, User Guide |
@@ -138,12 +200,14 @@ artifact-driven-agent/
 │   │   ├── setup.js
 │   │   ├── run.js
 │   │   ├── sprint.js      # 스프린트 관리
-│   │   └── sessions.js    # 세션 모니터링
+│   │   ├── sessions.js    # 세션 모니터링
+│   │   └── config.js      # 설정 관리
 │   └── utils/
 │       ├── files.js
+│       ├── config.js      # 설정 유틸리티
 │       └── sessionState.js
 ├── core/                   # 범용 핵심
-│   ├── roles/              # 5개 역할
+│   ├── roles/              # 6개 역할
 │   ├── artifacts/          # 산출물 템플릿
 │   │   └── sprints/
 │   │       └── _template/  # 스프린트 템플릿
@@ -184,9 +248,10 @@ ai-dev-team/
 │               └── task-005.md
 ├── roles/                  # core + template 병합
 ├── rules/
+├── ada.config.json         # 역할별 AI 도구 설정
+├── .ada-status.json        # 멀티 세션 상태 파일
 └── .sessions/              # 세션 이력
-    ├── logs/
-    └── .ada-status.json    # 멀티 세션 상태 파일
+    └── logs/
 ```
 
 ---
@@ -199,7 +264,15 @@ ai-dev-team/
 |--------|------|
 | `ada` | 대화형 모드 |
 | `ada setup [template]` | 템플릿 세팅 (web, lib, game, cli) |
-| `ada status` | 상태 확인 |
+| `ada status` | 상태 확인 (버전 체크 포함) |
+| `ada config` | 설정 변경 (대화형) |
+| `ada config show` | 현재 설정 보기 |
+| `ada config list` | 현재 설정 보기 (show와 동일) |
+| `ada config get <key>` | 설정 값 조회 |
+| `ada config set <key> <value>` | 설정 값 변경 |
+| `ada upgrade` | 작업공간을 최신 버전으로 업그레이드 |
+| `ada upgrade --dry-run` | 변경 사항 미리보기 |
+| `ada upgrade --rollback` | 이전 백업으로 롤백 |
 | `ada validate [doc]` | 문서 검증 |
 | `ada reset [-f]` | 초기화 |
 
@@ -209,7 +282,11 @@ ai-dev-team/
 |--------|------|
 | `ada sprint create` | 새 스프린트 생성 |
 | `ada sprint add task-001 ...` | Task 추가 |
-| `ada sprint close` | 현재 스프린트 종료 |
+| `ada sprint sync` | meta.md 상태 동기화 (Task 파일 반영) |
+| `ada sprint close` | 스프린트 종료 (작업 파일 archive/) |
+| `ada sprint close --auto` | 스프린트 자동 종료 (회고 기본값) |
+| `ada sprint close --clean` | 스프린트 종료 (작업 파일 삭제) |
+| `ada sprint close --keep-all` | 스프린트 종료 (파일 유지) |
 | `ada sprint list` | 스프린트 목록 |
 
 ### AI 에이전트 실행
@@ -222,12 +299,15 @@ ada run <role> <tool>
 ada <role> <tool>
 
 # 예시
-ada planner claude
+ada planner claude      # 신규 기능 기획
+ada improver claude     # 기존 기능 개선 기획
 ada developer codex
 ada reviewer gemini
 ada documenter claude
 ```
 
+tool을 생략하면 `ada.config.json` 기본값을 사용합니다.
+
 **지원 도구:** claude, codex, gemini, copilot
 
 ### 세션 모니터링
@@ -240,13 +320,33 @@ ada sessions
 ada sessions --watch
 ada sessions -w
 
-# 대기 질문이 있으면 자동으로 응답 프롬프트가 표시됩니다.
 # 세션 로그 확인
 ada logs
 ada logs [session-id]
 ```
 
----
+### 문서 관리
+
+```bash
+# 문서 구조 초기화 (MkDocs/Jekyll)
+ada docs init
+ada docs init -g mkdocs    # MkDocs 템플릿
+ada docs init -g jekyll    # Jekyll 템플릿
+
+# 문서 생성 (Documenter 역할 실행 안내)
+ada docs generate
+
+# 로컬 문서 서버 실행
+ada docs serve
+
+# GitHub Pages 배포
+ada docs publish
+```
+
+**참고:** 실제 문서 내용 생성은 Documenter 역할로 수행합니다:
+```bash
+ada documenter claude
+```
 
 ## 🔄 워크플로우
 
@@ -256,10 +356,9 @@ 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
+2. 사용자: 스프린트 생성
+   → ada sprint create
+   → ada sprint add task-001 task-002
 
 3. Developer: Task 구현
    → 코드 작성
@@ -273,9 +372,15 @@ ada logs [session-id]
    → ada sprint close
 
 6. Documenter: 문서 작성
-   → docs/*.md 생성 (API Changelog, Release Notes 등)
+   → ada documenter claude
+   → sprints/sprint-N/docs/*.md 생성 (Release Notes, API Changelog 등)
+   → (선택) 프로젝트 docs/ 업데이트 (문서 사이트용)
+
+7. (선택) 문서 사이트 배포
+   → ada docs serve (로컬 미리보기)
+   → ada docs publish (GitHub Pages 배포)
 
-7. 다음 스프린트 시작
+8. 다음 스프린트 시작
    → ada sprint create
 ```
 
@@ -285,11 +390,23 @@ ada logs [session-id]
 0. Analyzer: 코드베이스 분석
    → project.md 역생성
 
-1. Planner: 추가 기능 기획
-   → plan.md 업데이트
-   → backlog/*.md 생성
+1. [분기점]
 
-2. 이후 신규 프로젝트와 동일
+   A) 신규 기능 추가 시:
+      Planner: 추가 기능 기획
+      → plan.md 업데이트
+      → backlog/*.md 생성
+
+   B) 기존 기능 개선 시:
+      Improver: 개선 분석 및 기획
+      → improvement-reports/IMP-NNN.md 생성
+      → backlog/*.md 생성
+
+2. 사용자: 스프린트 생성
+   → ada sprint create
+   → ada sprint add task-001 task-002
+
+3. 이후 신규 프로젝트와 동일 (Developer → Reviewer → Documenter)
 ```
 
 ### Task 상태 흐름
@@ -369,11 +486,6 @@ ada reviewer gemini
 ada sessions --watch
 ```
 
-**세션 모니터링 포인트**
-- 대기 질문이 생성되면 watch 화면이 자동 프롬프트로 전환됩니다.
-- 프롬프트는 사용자가 직접 입력하며, 응답은 `.ada-status.json`에 저장됩니다.
-- 승인형 질문에 '예'로 응답하면 필요한 CLI 작업을 자동 실행합니다.
-
 ### 자동 세션 관리
 
 **세션 시작 시:**
@@ -388,17 +500,85 @@ ada sessions --watch
 ### 상태 파일
 
 ```
-ai-dev-team/.sessions/.ada-status.json
+ai-dev-team/.ada-status.json
 ```
 
 모든 세션이 이 파일을 통해 상태를 공유합니다.
 
 **구성:**
 - `activeSessions[]`: 실행 중인 세션
-- `pendingQuestions[]`: 대기 질문 및 응답 상태
-- `taskProgress[]`: Task 진행 상황
+- `pendingQuestions[]`: 대기 질문
+- `taskProgress{}`: Task 진행 상태
 - `notifications[]`: 세션 간 알림
-- (기존 Manager 관련 필드는 제거됨)
+- `locks{}`: 파일 잠금 상태
+
+---
+
+## ⚙️ 설정 관리
+
+역할별로 사용할 AI 도구를 설정할 수 있습니다.
+
+### 설정 파일
+
+```
+ai-dev-team/ada.config.json
+```
+
+```json
+{
+  "version": "1.0",
+  "defaults": {
+    "tool": "claude"
+  },
+  "roles": {
+    "manager": "claude",
+    "planner": "claude",
+    "developer": "gemini",
+    "reviewer": "claude",
+    "documenter": "claude"
+  }
+}
+```
+
+### 대화형 설정
+
+```bash
+ada config
+```
+
+**메뉴:**
+- 📋 현재 설정 보기
+- 🔧 역할별 도구 설정
+- ⚡ 기본 도구 변경
+- 🎯 빠른 설정 (프리셋)
+
+### 프리셋
+
+| 프리셋 | 설명 |
+|--------|------|
+| All Claude | 모든 역할에 Claude 사용 |
+| All Gemini | 모든 역할에 Gemini 사용 |
+| Mixed Optimal | 역할별 최적 조합 |
+| Dev Gemini + Review Claude | 개발은 Gemini, 리뷰는 Claude |
+
+### 명령어 모드
+
+```bash
+# 개별 역할 설정
+ada config set roles.developer gemini
+ada config set roles.reviewer claude
+
+# 기본 도구 변경
+ada config set defaults.tool gemini
+
+# 설정 확인
+ada config show       # 또는 ada config list
+
+# 특정 값 조회
+ada config get roles.manager
+```
+
+설정을 초기화하려면 `ai-dev-team/ada.config.json` 삭제 후 `ada config`를 실행하세요.
 
 ---
 
@@ -444,9 +624,10 @@ ai-dev-team/.sessions/.ada-status.json
 - 역할 간 blocking 문제 (backend ↔ frontend)
 
 **현재 (v0.2.x):**
-- 4개 핵심 역할 (planner, developer, reviewer, documenter)
+- 5개 핵심 역할 (planner, improver, developer, reviewer, documenter)
 - 사용자 직접 스프린트 관리 (CLI 명령어)
 - 단순화된 워크플로우
+- 신규 기능(Planner)과 개선(Improver) 분리
 
 ### 스프린트 기반 구조
 
@@ -460,16 +641,18 @@ ai-dev-team/.sessions/.ada-status.json
 - Task별 개별 파일 (task-NNN.md)
 - 리뷰/문서도 Task별 분리
 - 완료된 스프린트는 불변 (이력 보존)
+- 종료 시 작업 파일 자동 정리 (archive/ 또는 삭제)
 
 ### 자동화 개선
 
 **추가된 CLI 명령어:**
 - `ada sprint create` - 스프린트 자동 생성
 - `ada sprint add` - Task 자동 추가
-- `ada sprint close` - 스프린트 종료 및 회고 템플릿 생성
+- `ada sprint close` - 스프린트 종료 및 작업 파일 정리 (archive/clean/keep-all 옵션)
 - `ada sprint list` - 스프린트 목록 확인
+- `ada config` - 설정 조회/변경
+
 
----
 
 ## 🔧 개발 환경
 
@@ -524,7 +707,3 @@ MIT License
 - GitHub: [@silbaram](https://github.com/silbaram)
 - npm: [@silbaram/artifact-driven-agent](https://www.npmjs.com/package/@silbaram/artifact-driven-agent)
 
-
-
-
-

package/ai-dev-team/.ada-status.json

@@ -0,0 +1,10 @@
+{
+  "version": "1.0",
+  "updatedAt": "2026-01-24T16:46:33.177Z",
+  "currentPhase": "planning",
+  "activeSessions": [],
+  "pendingQuestions": [],
+  "taskProgress": {},
+  "notifications": [],
+  "locks": {}
+}

package/ai-dev-team/.ada-version

@@ -0,0 +1,6 @@
+{
+  "packageVersion": "0.1.9",
+  "workspaceVersion": "0.1.9",
+  "template": "web-dev",
+  "lastUpgrade": "2026-01-24T16:43:39.762Z"
+}

package/ai-dev-team/.current-template

@@ -0,0 +1 @@
+web-dev

package/ai-dev-team/.sessions/logs/20260124-014551-00f04724.log

@@ -0,0 +1,5 @@
+[2026-01-24 16:45:51] [INFO] 세션 시작: role=manager, tool=claude, template=web-dev
+[2026-01-24 16:45:51] [INFO] 세션 등록: 20260124-014551-00f04724
+[2026-01-24 16:45:51] [INFO] 시스템 프롬프트 저장: D:\development-code\artifact-driven-agent\ai-dev-team\.sessions\20260124-014551-00f04724\system-prompt.md
+[2026-01-24 16:45:51] [INFO] claude CLI 실행 (automation: perfect, captureOutput: false)
+[2026-01-24 16:46:10] [INFO] 세션 종료 (completed): 정상 종료

package/ai-dev-team/.sessions/logs/20260124-014623-cb2b1d44.log

@@ -0,0 +1,5 @@
+[2026-01-24 16:46:23] [INFO] 세션 시작: role=manager, tool=codex, template=web-dev
+[2026-01-24 16:46:23] [INFO] 세션 등록: 20260124-014623-cb2b1d44
+[2026-01-24 16:46:23] [INFO] 시스템 프롬프트 저장: D:\development-code\artifact-driven-agent\ai-dev-team\.sessions\20260124-014623-cb2b1d44\system-prompt.md
+[2026-01-24 16:46:23] [INFO] codex CLI 실행 (automation: manual, captureOutput: false)
+[2026-01-24 16:46:33] [INFO] 세션 종료 (completed): 정상 종료

package/ai-dev-team/ada.config.json

@@ -0,0 +1,15 @@
+{
+  "version": "1.0",
+  "defaults": {
+    "tool": "claude"
+  },
+  "roles": {
+    "manager": "claude",
+    "planner": "claude",
+    "architect": "claude",
+    "developer": "claude",
+    "reviewer": "claude",
+    "improver": "claude",
+    "documenter": "claude"
+  }
+}

package/ai-dev-team/artifacts/api.md

@@ -0,0 +1,212 @@
+# API Specification
+
+> Backend와 Frontend의 공식 계약 문서
+> 변경 시 rules/api-change.md 절차를 따른다
+
+---
+
+## 0. 문서 메타
+
+| 항목 | 값 |
+|------|-----|
+| 버전 | v1.0 |
+| Base URL | /api/v1 |
+| 최종 수정 | YYYY-MM-DD |
+
+---
+
+## 1. 공통 규칙
+
+### 1.1 HTTP 메서드
+
+| 메서드 | 용도 | 멱등성 |
+|--------|------|:------:|
+| GET | 조회 | ✅ |
+| POST | 생성 | ❌ |
+| PUT | 전체 수정 | ✅ |
+| PATCH | 부분 수정 | ❌ |
+| DELETE | 삭제 | ✅ |
+
+### 1.2 경로 규칙
+
+- 리소스명: 복수형 소문자 (예: `/users`, `/posts`)
+- 단일 리소스: `/{resource}/{id}`
+- 중첩 리소스: `/{parent}/{parentId}/{child}`
+
+---
+
+## 2. 인증/권한
+
+| 항목 | 값 |
+|------|-----|
+| Status | 사용 / 미사용 |
+| Scheme | Bearer Token / Cookie / API Key |
+| Token Location | Authorization: Bearer {token} |
+
+---
+
+## 3. 응답 규격 (Response Envelope)
+
+### 3.1 Success Response
+
+```json
+{
+  "success": true,
+  "data": { },
+  "error": null,
+  "meta": {
+    "requestId": "uuid",
+    "timestamp": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### 3.2 Failure Response
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "사용자에게 표시할 메시지",
+    "details": { }
+  },
+  "meta": {
+    "requestId": "uuid",
+    "timestamp": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+---
+
+## 4. 공통 에러 코드
+
+| HTTP | 에러 코드 | 설명 |
+|------|----------|------|
+| 400 | BAD_REQUEST | 잘못된 요청 |
+| 400 | VALIDATION_ERROR | 유효성 검사 실패 |
+| 401 | UNAUTHORIZED | 인증 필요 |
+| 403 | FORBIDDEN | 권한 없음 |
+| 404 | NOT_FOUND | 리소스 없음 |
+| 409 | CONFLICT | 충돌 |
+| 500 | INTERNAL_ERROR | 서버 오류 |
+
+---
+
+## 5. 페이지네이션
+
+### Request
+
+```
+GET /resources?page=1&size=20&sort=createdAt,desc
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "content": [...],
+    "page": {
+      "number": 1,
+      "size": 20,
+      "totalElements": 100,
+      "totalPages": 5
+    }
+  }
+}
+```
+
+---
+
+## 6. API 엔드포인트 정의
+
+### 6.1 [리소스명]
+
+#### GET /resources
+
+**설명:** 목록 조회
+
+**Request:**
+```
+Query Parameters:
+- page: number (default: 1)
+- size: number (default: 20)
+```
+
+**Response (200):**
+```json
+{
+  "success": true,
+  "data": {
+    "content": [
+      {
+        "id": "uuid",
+        "name": "string",
+        "createdAt": "datetime"
+      }
+    ],
+    "page": { ... }
+  }
+}
+```
+
+**에러:**
+| 상황 | 코드 |
+|------|------|
+| 잘못된 파라미터 | BAD_REQUEST |
+
+---
+
+#### POST /resources
+
+**설명:** 생성
+
+**Request:**
+```json
+{
+  "name": "string (required)",
+  "description": "string (optional)"
+}
+```
+
+**Response (201):**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "uuid",
+    "name": "string",
+    "createdAt": "datetime"
+  }
+}
+```
+
+**에러:**
+| 상황 | 코드 |
+|------|------|
+| 필수 필드 누락 | VALIDATION_ERROR |
+| 중복 | CONFLICT |
+
+---
+
+## 7. API 목록 요약
+
+| 메서드 | 경로 | 설명 | 상태 | Task |
+|--------|------|------|:----:|------|
+| GET | /resources | 목록 조회 | ✅ | TASK-001 |
+| POST | /resources | 생성 | ⏳ | TASK-001 |
+| GET | /resources/{id} | 단일 조회 | 📋 | TASK-002 |
+
+상태: ✅ 완료 / ⏳ 진행중 / 📋 예정
+
+---
+
+## 8. 변경 이력
+
+| Task | 날짜 | 변경 내용 |
+|------|------|----------|
+| [TASK-001] | YYYY-MM-DD | 초기 API 작성 |