@silbaram/artifact-driven-agent 0.1.9 → 0.2.3

package/README.md

@@ -19,14 +19,17 @@
 
 AI 에이전트 실행 시, 시스템 프롬프트에 다음을 포함합니다:
 
-1. **모든 규칙 파일 내용** (rules/*.md)
-2. **핵심 산출물 내용** (plan.md, project.md, 현재 스프린트 Task 파일)
-3. **인터페이스 문서 내용** (api.md, ui.md 등)
+1. **역할 정의** - 역할의 책임과 권한
+2. **모든 규칙 파일 내용** (rules/*.md)
+3. **전문 스킬** (skills/*.md) - 역할에 지정된 기술 스택 가이드
+4. **핵심 산출물 내용** (plan.md, project.md, 현재 스프린트 Task 파일)
+5. **인터페이스 문서 내용** (api.md, ui.md 등)
 
 이를 통해 AI는:
 - 문서에 명시된 규칙을 따라야만 함
 - 현재 스프린트 범위를 벗어날 수 없음
 - project.md에 없는 기술을 추가할 수 없음
+- 프로젝트의 코딩 패턴과 스타일을 자동으로 준수
 
 **파일명만 나열하지 않고, 내용을 포함**하는 것이 핵심입니다.
 
@@ -44,13 +47,14 @@ npm install -g @silbaram/artifact-driven-agent
 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  # 전역 명령어 등록
+npm install        # 의존성 설치
+npm run build      # TypeScript 컴파일
+npm link           # 전역 명령어 등록
 ```
 
 ### 설치 확인
@@ -152,7 +156,7 @@ ada documenter claude         # Documenter가 docs/ 업데이트
 # 로컬 미리보기
 ada docs serve
 
-# GitHub Pages 배포
+# GitHub Pages 배포 (MkDocs 자동 배포 지원)
 ada docs publish
 ```
 
@@ -194,24 +198,38 @@ sprints/sprint-N/
 
 ```
 artifact-driven-agent/
-├── bin/cli.js              # CLI 진입점
+├── bin/
+│   └── cli.ts              # CLI 진입점 (TypeScript)
 ├── src/
-│   ├── commands/           # 명령어 구현
-│   │   ├── setup.js
-│   │   ├── run.js
-│   │   ├── sprint.js      # 스프린트 관리
-│   │   ├── sessions.js    # 세션 모니터링
-│   │   └── config.js      # 설정 관리
-│   └── utils/
-│       ├── files.js
-│       ├── config.js      # 설정 유틸리티
-│       └── sessionState.js
+│   ├── commands/           # 명령어 구현 (TypeScript)
+│   │   ├── setup.ts
+│   │   ├── run.ts
+│   │   ├── sprint.ts       # 스프린트 관리
+│   │   ├── sessions.ts     # 세션 모니터링
+│   │   └── config.ts       # 설정 관리
+│   ├── utils/
+│   │   ├── files.ts
+│   │   ├── config.ts       # 설정 유틸리티
+│   │   └── sessionState.ts
+│   ├── ui/
+│   │   ├── dashboard.ts    # 대시보드
+│   │   └── keyHandler.ts
+│   └── types/              # TypeScript 타입 정의
+│       ├── common.ts
+│       ├── session.ts
+│       ├── config.ts
+│       ├── task.ts
+│       └── index.ts
+├── dist/                   # 빌드 출력 (.js 파일)
+├── tsconfig.json           # TypeScript 설정
 ├── core/                   # 범용 핵심
 │   ├── roles/              # 6개 역할
 │   ├── artifacts/          # 산출물 템플릿
 │   │   └── sprints/
 │   │       └── _template/  # 스프린트 템플릿
-│   └── rules/              # 5개 규칙
+│   ├── rules/              # 5개 규칙
+│   └── skills/             # 🆕 스킬 템플릿
+│       └── _template/
 └── templates/              # 프로젝트 유형별
     ├── web-dev/
     ├── library/
@@ -248,7 +266,14 @@ ai-dev-team/
 │               └── task-005.md
 ├── roles/                  # core + template 병합
 ├── rules/
-├── ada.config.json         # 역할별 AI 도구 설정
+├── skills/                 # 🆕 역할별 전문 스킬
+│   ├── _template/
+│   │   └── SKILL.md
+│   ├── spring-boot/
+│   │   └── SKILL.md
+│   └── kotlin/
+│       └── SKILL.md
+├── ada.config.json         # 역할별 AI 도구 + 스킬 설정
 ├── .ada-status.json        # 멀티 세션 상태 파일
 └── .sessions/              # 세션 이력
     └── logs/
@@ -339,7 +364,7 @@ ada docs generate
 # 로컬 문서 서버 실행
 ada docs serve
 
-# GitHub Pages 배포
+# GitHub Pages 배포 (MkDocs 자동 배포 지원)
 ada docs publish
 ```
 
@@ -348,6 +373,54 @@ ada docs publish
 ada documenter claude
 ```
 
+### 스킬 관리
+
+스킬은 AI 도구의 **네이티브 스킬 시스템**을 통해 적용됩니다.
+
+| 도구 | 스킬 탐색 경로 |
+|------|---------------|
+| Claude Code | `.claude/skills/` |
+| Gemini CLI | `.gemini/skills/` |
+| Codex | `.agents/skills/` |
+
+```bash
+# 스킬 목록 (ada 저장소)
+ada skills list
+
+# 스킬 상세 정보
+ada skills info spring-boot
+
+# 스킬 적용 (네이티브 경로에 복사)
+ada skills apply spring-boot           # 모든 도구에 적용
+ada skills apply spring-boot claude    # 특정 도구에만 적용
+
+# 스킬 제거
+ada skills remove spring-boot          # 모든 도구에서 제거
+ada skills remove spring-boot gemini   # 특정 도구에서만 제거
+
+# 적용 상태 확인
+ada skills status
+
+# 대화형 적용/삭제 UI
+ada skills ui
+```
+
+**스킬 추가 방법:**
+커뮤니티나 GitHub에서 스킬을 다운로드하여 `ai-dev-team/skills/` 디렉토리에 추가합니다.
+
+```bash
+# 예시: GitHub에서 스킬 다운로드
+cd ai-dev-team/skills/
+git clone https://github.com/awesome-ada/spring-boot-skill.git spring-boot
+
+# 또는 직접 복사
+cp -r /path/to/spring-boot ai-dev-team/skills/
+
+# 확인 및 적용
+ada skills list
+ada skills apply spring-boot
+```
+
 ## 🔄 워크플로우
 
 ### 신규 프로젝트
@@ -582,6 +655,183 @@ ada config get roles.manager
 
 ---
 
+## 🎓 스킬 시스템
+
+역할별로 기술 스택, 패턴, 코딩 스타일 등의 전문 지식을 스킬로 정의하여 AI에게 자동으로 제공할 수 있습니다.
+
+### 개념
+
+**스킬(Skill)**은 특정 기술이나 패턴에 대한 가이드를 담은 마크다운 문서입니다.
+
+- 역할별로 필요한 스킬을 지정하면, AI 실행 시 자동으로 로드됩니다.
+- 프로젝트별 기술 스택 표준화 및 코딩 패턴 통일에 유용합니다.
+
+### 스킬 구조
+
+```
+ai-dev-team/skills/
+├── _template/              # 템플릿
+│   └── SKILL.md
+├── spring-boot/            # 사용자 생성 스킬
+│   ├── SKILL.md           # 메인 파일 (필수)
+│   ├── examples/          # 예시 코드 (선택)
+│   └── references/        # 참조 문서 (선택)
+└── kotlin/
+    └── SKILL.md
+```
+
+**SKILL.md 예시:**
+```yaml
+---
+name: spring-boot
+description: Spring Boot 백엔드 개발 시 Kotlin, REST API, JPA 패턴 적용
+---
+
+# Spring Boot + Kotlin 백엔드 개발
+
+## Controller 패턴
+- `@RestController` + `@RequestMapping` 사용
+- 경로는 복수형 명사 (`/api/users`)
+
+## Service 계층
+- `@Service` + `@Transactional` 조합
+
+## Repository
+- Spring Data JPA 사용
+```
+
+### 사용 방법
+
+**1. 스킬 다운로드 또는 생성:**
+
+커뮤니티에서 검증된 스킬을 다운로드하거나, 직접 생성합니다.
+
+```bash
+# 방법 1: 커뮤니티에서 다운로드 (권장)
+cd ai-dev-team/skills/
+git clone https://github.com/awesome-ada/spring-boot-skill.git spring-boot
+git clone https://github.com/awesome-ada/kotlin-skill.git kotlin
+
+# 방법 2: 직접 생성
+mkdir -p ai-dev-team/skills/spring-boot
+touch ai-dev-team/skills/spring-boot/SKILL.md
+code ai-dev-team/skills/spring-boot/SKILL.md
+```
+
+**2. 스킬 확인:**
+```bash
+ada skills list
+```
+
+**3. 스킬 적용 (네이티브 경로에 복사):**
+```bash
+# 모든 도구에 적용
+ada skills apply spring-boot kotlin
+
+# 또는 특정 도구에만 적용
+ada skills apply spring-boot claude
+
+# 적용 상태 확인
+ada skills status
+```
+
+**4. AI 실행:**
+```bash
+ada developer claude
+
+# → Claude가 .claude/skills/에서 스킬을 자동으로 로드
+# → 해당 패턴에 맞춰 코드 생성!
+```
+
+### 네이티브 스킬 경로
+
+각 AI 도구는 자체 스킬 탐색 경로에서 스킬을 자동으로 인식합니다:
+
+| 도구 | 스킬 탐색 경로 |
+|------|---------------|
+| Claude Code | `.claude/skills/` |
+| Gemini CLI | `.gemini/skills/` |
+| Codex | `.agents/skills/` |
+
+`ada skills apply` 명령은 ada 스킬 저장소의 스킬을 이 네이티브 경로로 복사합니다.
+
+```
+ai-dev-team/skills/spring-boot/    →    .claude/skills/spring-boot/
+                                   →    .gemini/skills/spring-boot/
+                                   →    .agents/skills/spring-boot/
+```
+
+### 작동 원리
+
+1. **스킬 저장**: `ai-dev-team/skills/`에 스킬 저장
+2. **스킬 적용**: `ada skills apply`로 네이티브 경로에 복사
+3. **AI 실행**: 각 AI 도구가 자체 스킬 경로에서 자동 로드
+
+이를 통해 AI는 프로젝트의 기술 스택과 코딩 패턴을 자동으로 따르게 됩니다.
+
+### 예시 시나리오
+
+**Spring Boot + Kotlin 프로젝트:**
+
+```bash
+# 1. 스킬 다운로드 (커뮤니티에서)
+cd ai-dev-team/skills/
+git clone https://github.com/awesome-ada/spring-boot-skill.git spring-boot
+git clone https://github.com/awesome-ada/kotlin-skill.git kotlin
+git clone https://github.com/awesome-ada/rest-api-skill.git rest-api
+
+# 2. 확인
+ada skills list
+
+# 3. 스킬 적용 (네이티브 경로에 복사)
+ada skills apply spring-boot
+ada skills apply kotlin
+ada skills apply rest-api
+
+# 4. 개발 실행
+ada developer claude
+
+# → Controller 작성 시 자동으로:
+#   - @RestController + @RequestMapping 패턴 사용
+#   - Kotlin data class 활용
+#   - REST API 네이밍 규칙 준수
+```
+
+**Python FastAPI 프로젝트:**
+
+```bash
+# 커뮤니티에서 스킬 다운로드
+cd ai-dev-team/skills/
+git clone https://github.com/awesome-ada/fastapi-skill.git fastapi
+git clone https://github.com/awesome-ada/pydantic-skill.git pydantic
+
+# 스킬 적용
+ada skills apply fastapi
+ada skills apply pydantic
+
+ada developer claude
+```
+
+### 스킬 관리 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `ada skills list` | 스킬 목록 (적용 상태 포함) |
+| `ada skills info <name>` | 스킬 상세 정보 |
+| `ada skills apply <name> [tool]` | 스킬 적용 (네이티브 경로에 복사) |
+| `ada skills remove <name> [tool]` | 스킬 제거 |
+| `ada skills status` | 도구별 적용 상태 확인 |
+| `ada skills ui` | 대화형 스킬 적용/삭제 |
+
+**지원 도구:** `claude`, `gemini`, `codex`
+
+**스킬 추가 방법:**
+- 커뮤니티 저장소에서 다운로드
+- 직접 `ai-dev-team/skills/<name>/SKILL.md` 생성
+- 팀 내부 스킬 공유
+
+---
+
 ## ⚠️ 핵심 원칙
 
 ### 금지 사항
@@ -666,14 +916,35 @@ ada config get roles.manager
 ```bash
 git clone https://github.com/silbaram/artifact-driven-agent.git
 cd artifact-driven-agent
-npm install
-npm link  # 전역 ada 명령어 등록
+npm install        # 의존성 설치
+npm run build      # TypeScript 컴파일
+npm link           # 전역 ada 명령어 등록
 ```
 
-### 테스트
+### 개발 스크립트
 
 ```bash
-npm test   # Node.js 내장 test runner 사용
+npm run build      # TypeScript 컴파일 (dist/ 생성)
+npm run dev        # TypeScript watch 모드 (개발 중)
+npm run typecheck  # 타입 체크만 실행
+npm test           # 테스트 실행 (Node.js 내장 test runner)
+```
+
+### 프로젝트 구조 (TypeScript)
+
+```
+artifact-driven-agent/
+├── bin/
+│   └── cli.ts              # CLI 진입점 (TypeScript)
+├── src/
+│   ├── commands/           # 명령어 구현 (.ts)
+│   ├── utils/              # 유틸리티 (.ts)
+│   ├── ui/                 # UI 컴포넌트 (.ts)
+│   └── types/              # TypeScript 타입 정의
+├── dist/                   # 빌드 출력 (npm run build)
+├── tsconfig.json           # TypeScript 설정
+├── core/                   # 프레임워크 핵심
+└── templates/              # 프로젝트 템플릿
 ```
 
 ---

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

@@ -1,10 +1,10 @@
-{
-  "version": "1.0",
-  "updatedAt": "",
-  "currentPhase": "idle",
-  "activeSessions": [],
-  "pendingQuestions": [],
-  "taskProgress": {},
-  "notifications": [],
-  "locks": {}
-}
+{
+  "version": "1.0",
+  "updatedAt": "",
+  "currentPhase": "idle",
+  "activeSessions": [],
+  "pendingQuestions": [],
+  "taskProgress": {},
+  "notifications": [],
+  "locks": {}
+}

package/ai-dev-team/README.md

@@ -1,44 +1,39 @@
-# AI Dev Team - 작업 디렉토리
-
-이 디렉토리는 AI 에이전트 기반 개발의 **작업 공간**입니다.
-
-## 📋 사용 방법
-
-### 1단계: 개발 스타일 세팅
-
-```bash
-# 대화형으로 템플릿 선택
-../scripts/ai-role.sh setup
-
-# 또는 직접 지정
-../scripts/ai-role.sh setup web      # 웹 서비스 개발
-../scripts/ai-role.sh setup library  # 라이브러리 개발
-../scripts/ai-role.sh setup game     # 게임 개발
-../scripts/ai-role.sh setup cli      # CLI 도구 개발
-```
-
-### 2단계: 역할 실행
-
-```bash
-# 대화형으로 역할/도구 선택
-../scripts/ai-role.sh
-
-# 또는 직접 지정
-../scripts/ai-role.sh backend claude
-../scripts/ai-role.sh planner codex
-```
-
-## 📁 세팅 후 구조
-
-```
-ai-dev-team/
-├── roles/           # Core + 템플릿 역할
-├── artifacts/       # Core + 템플릿 산출물 템플릿
-└── rules/           # Core + 템플릿 규칙
-```
-
-## ⚠️ 주의사항
-
-- `setup` 명령어는 기존 파일을 **덮어씁니다**
-- 산출물(artifacts/)의 내용은 프로젝트 진행 중 수정됩니다
-- 역할(roles/)과 규칙(rules/)은 수정하지 마세요
+# Artifact-Driven AI Agent Workspace
+
+이 디렉토리는 ADA 프레임워크를 통해 관리되는 AI 에이전트 기반 개발 공간입니다.
+
+## 📋 사용 방법
+
+### 1단계: 프로젝트 설정 (최초 1회)
+
+```bash
+ada setup web       # 웹 서비스 (React, Next.js 등)
+ada setup library   # 공통 라이브러리
+ada setup game      # 게임 개발
+ada setup cli       # CLI 도구
+```
+
+### 2단계: 에이전트 실행
+
+```bash
+# 기본 실행 (ada.config.json 설정 사용)
+ada run
+
+# 도구 지정 실행
+ada run developer claude
+ada run planner gemini
+```
+
+## 📁 주요 구조
+
+- `artifacts/`: `plan.md`, `backlog/`, `sprints/` 등 모든 산출물
+- `roles/`: 각 에이전트의 페르소나 및 책임 정의
+- `rules/`: 스프린트 운영 및 코드 품질 규칙
+- `skills/`: 역할별 전문 기술 스택 가이드 (Spring, React 등)
+- `ada.config.json`: 역할별 AI 도구 및 스킬 연결 설정
+
+## ⚠️ 주의사항
+
+- 모든 개발 판단은 `artifacts/` 내의 문서를 기준으로 합니다.
+- `roles/`와 `rules/`의 코어 파일은 직접 수정하지 말고, 설정이나 스킬 추가를 통해 제어하세요.
+- 스프린트 작업 완료 후 반드시 `ada sprint close`를 통해 정리하세요.