@silbaram/artifact-driven-agent 0.1.0

package/templates/library/artifacts/public-api.md

@@ -0,0 +1,197 @@
+# Public API Specification
+
+> 라이브러리의 공개 인터페이스 정의
+> 사용자에게 노출되는 모든 API를 문서화
+
+---
+
+## 0. 문서 메타
+
+| 항목 | 값 |
+|------|-----|
+| 라이브러리명 | [이름] |
+| 현재 버전 | v1.0.0 |
+| 최종 수정 | YYYY-MM-DD |
+
+---
+
+## 1. 개요
+
+### 1.1 라이브러리 소개
+
+[라이브러리 한 줄 설명]
+
+### 1.2 설치
+
+```bash
+# npm
+npm install [package-name]
+
+# pip
+pip install [package-name]
+
+# 기타
+[설치 명령]
+```
+
+### 1.3 빠른 시작
+
+```python
+# 기본 사용 예시
+import library
+
+result = library.main_function()
+```
+
+---
+
+## 2. 공개 API 목록
+
+| API | 설명 | 버전 | 상태 |
+|-----|------|------|:----:|
+| `mainFunction()` | 주요 기능 | v1.0.0 | ✅ |
+| `helperFunction()` | 보조 기능 | v1.0.0 | ✅ |
+| `oldFunction()` | 이전 기능 | v1.0.0 | ⚠️ Deprecated |
+
+상태: ✅ 안정 / ⚠️ Deprecated / 🧪 실험적
+
+---
+
+## 3. API 상세
+
+### 3.1 mainFunction
+
+```python
+def main_function(param1: str, param2: int = 10) -> Result:
+    """
+    주요 기능 설명
+    
+    Args:
+        param1: 첫 번째 파라미터 설명
+        param2: 두 번째 파라미터 (기본값: 10)
+    
+    Returns:
+        Result: 결과 객체
+    
+    Raises:
+        ValueError: param1이 빈 문자열인 경우
+        TypeError: param2가 정수가 아닌 경우
+    
+    Example:
+        >>> result = main_function("hello", 20)
+        >>> print(result.value)
+        'processed: hello'
+    """
+```
+
+**파라미터:**
+
+| 이름 | 타입 | 필수 | 기본값 | 설명 |
+|------|------|:----:|--------|------|
+| param1 | str | ✅ | - | 첫 번째 파라미터 |
+| param2 | int | ❌ | 10 | 두 번째 파라미터 |
+
+**반환값:**
+
+| 타입 | 설명 |
+|------|------|
+| Result | 결과 객체 |
+
+**예외:**
+
+| 예외 | 조건 |
+|------|------|
+| ValueError | param1이 빈 문자열 |
+| TypeError | param2가 정수 아님 |
+
+**예시:**
+
+```python
+# 기본 사용
+result = main_function("hello")
+
+# 옵션 지정
+result = main_function("hello", param2=20)
+```
+
+---
+
+### 3.2 helperFunction
+
+(동일 형식으로 작성)
+
+---
+
+## 4. 데이터 타입
+
+### 4.1 Result
+
+```python
+class Result:
+    value: str       # 처리 결과
+    status: str      # 상태 ("success" | "error")
+    metadata: dict   # 추가 정보
+```
+
+**필드:**
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| value | str | 처리 결과 |
+| status | str | 상태 |
+| metadata | dict | 추가 정보 |
+
+---
+
+## 5. 상수 및 설정
+
+### 5.1 상수
+
+| 상수 | 값 | 설명 |
+|------|-----|------|
+| DEFAULT_TIMEOUT | 30 | 기본 타임아웃 (초) |
+| MAX_RETRIES | 3 | 최대 재시도 횟수 |
+
+### 5.2 설정
+
+```python
+# 전역 설정
+library.configure(
+    timeout=60,
+    debug=True
+)
+```
+
+---
+
+## 6. Deprecated API
+
+> 다음 Major 버전에서 제거 예정
+
+### 6.1 oldFunction (Deprecated since v1.2.0)
+
+```python
+# ⚠️ Deprecated: main_function() 사용 권장
+def old_function(param):
+    ...
+```
+
+**대체 방법:**
+
+```python
+# Before (deprecated)
+old_function(param)
+
+# After (recommended)
+main_function(param)
+```
+
+---
+
+## 7. 변경 이력
+
+| 버전 | 날짜 | 변경 내용 | Task |
+|------|------|----------|------|
+| v1.0.0 | YYYY-MM-DD | 초기 릴리스 | - |
+| v1.1.0 | YYYY-MM-DD | helperFunction 추가 | TASK-003 |
+| v1.2.0 | YYYY-MM-DD | oldFunction deprecated | TASK-005 |

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

@@ -0,0 +1,180 @@
+# Role: Library Developer
+
+너는 라이브러리/SDK 개발자다.
+plan.md와 project.md를 기준으로 공개 API를 설계하고 라이브러리를 구현한다.
+
+> 이 역할은 core/roles/developer.md를 기반으로 하며,
+> 라이브러리 개발에 특화된 규칙을 추가한다.
+
+---
+
+## 1. 핵심 책임
+
+- plan.md 요구사항을 공개 API로 설계
+- public-api.md (공개 인터페이스) 작성 및 유지
+- 사용자 친화적인 API 설계
+- 하위 호환성 유지
+- 예제 코드 및 문서화
+
+---
+
+## 2. 입력 문서 (Mandatory)
+
+- artifacts/plan.md
+- artifacts/project.md
+- artifacts/backlog.md
+- artifacts/current-sprint.md
+
+(선택)
+- artifacts/decision.md
+
+---
+
+## 3. 산출물 (Outputs)
+
+- artifacts/public-api.md (공개 인터페이스 정의)
+- artifacts/examples.md (사용 예제)
+- artifacts/changelog.md (변경 이력)
+- 라이브러리 소스 코드 (src/)
+- (선택) artifacts/dev-notes.md
+
+---
+
+## 4. 참고 규칙 문서
+
+- core/rules/iteration.md
+- rules/versioning.md (버전 관리)
+- core/rules/escalation.md
+- core/rules/document-priority.md
+
+---
+
+## 5. 공개 API 설계 원칙
+
+### 5.1 API 우선 설계
+
+```
+1. public-api.md 먼저 작성
+2. 사용자 관점에서 검토
+3. 예제 코드 작성
+4. 구현 진행
+```
+
+### 5.2 API 품질 기준
+
+| 기준 | 설명 |
+|------|------|
+| 직관성 | 이름만으로 용도 파악 |
+| 일관성 | 유사 기능은 유사 패턴 |
+| 최소성 | 필요한 것만 공개 |
+| 확장성 | 미래 변경 고려 |
+
+### 5.3 하위 호환성
+
+- Public API 변경 시 Semantic Versioning 적용
+- Breaking change는 Major 버전 증가
+- Deprecation 경고 → 다음 Major에서 제거
+
+---
+
+## 6. Semantic Versioning (필수)
+
+```
+MAJOR.MINOR.PATCH
+
+MAJOR: 하위 비호환 변경
+MINOR: 하위 호환 기능 추가
+PATCH: 버그 수정
+```
+
+### 버전 증가 기준
+
+| 변경 유형 | 버전 |
+|----------|------|
+| 버그 수정 | PATCH |
+| 새 기능 (호환) | MINOR |
+| 새 기능 (비호환) | MAJOR |
+| API 제거 | MAJOR |
+| 동작 변경 | MAJOR |
+
+---
+
+## 7. 문서화 규칙
+
+### 7.1 public-api.md
+
+모든 공개 API 포함:
+- 함수/메서드 시그니처
+- 파라미터 설명
+- 반환값 설명
+- 예외/에러
+- 사용 예시
+
+### 7.2 examples.md
+
+주요 사용 시나리오:
+- 빠른 시작 (Quick Start)
+- 일반적인 사용 패턴
+- 고급 사용법
+
+### 7.3 changelog.md
+
+모든 버전의 변경 사항:
+- 추가된 기능
+- 변경된 기능
+- 제거된 기능
+- 버그 수정
+
+---
+
+## 8. Task 단위 문서 갱신
+
+Task 구현 시:
+
+```markdown
+## changelog.md
+### [Unreleased]
+- [TASK-001] 새 기능 추가: [설명]
+
+## public-api.md
+### 추가된 API
+- `newFunction()` - [설명] [TASK-001]
+```
+
+---
+
+## 9. 금지 사항 (CRITICAL)
+
+- ❌ public-api.md 없이 구현
+- ❌ 문서화 없이 공개 API 추가
+- ❌ 경고 없이 API deprecation
+- ❌ PATCH 버전에서 기능 추가
+- ❌ MINOR 버전에서 Breaking change
+- ❌ 스프린트 외 작업
+
+---
+
+## 10. 세션 시작 예시
+
+```
+━━━━━━━━━━━━━━━━━━━━━━
+📦 Library Developer 세션 시작
+━━━━━━━━━━━━━━━━━━━━━━
+
+📋 문서 확인
+✅ plan.md - 확인됨
+✅ project.md - Frozen (v1.0)
+   - 언어: [언어]
+   - 패키지 매니저: [매니저]
+   - 테스트: [프레임워크]
+
+📌 현재 버전: v1.2.0
+
+📌 내 Task (current-sprint.md 기준)
+- TASK-001: [기능명] - IN_DEV
+- TASK-003: [기능명] - IN_SPRINT
+
+━━━━━━━━━━━━━━━━━━━━━━
+
+public-api.md 기반으로 TASK-001을 시작하겠습니다.
+```

package/templates/library/rules/versioning.md

@@ -0,0 +1,186 @@
+# Versioning Rules (버전 관리 규칙)
+
+> 라이브러리 버전 관리 규칙
+> Semantic Versioning 2.0.0 기반
+
+---
+
+## 1. 버전 형식
+
+```
+MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
+
+예시:
+1.0.0
+2.1.3
+1.0.0-alpha.1
+1.0.0-beta.2+build.123
+```
+
+---
+
+## 2. 버전 증가 규칙
+
+### 2.1 MAJOR (주 버전)
+
+하위 호환되지 않는 변경 시 증가:
+
+| 변경 유형 | 예시 |
+|----------|------|
+| 공개 API 제거 | `removeFunction()` 삭제 |
+| 공개 API 시그니처 변경 | 파라미터 타입 변경 |
+| 동작 변경 | 반환값 의미 변경 |
+| 필수 파라미터 추가 | 기존 함수에 필수 인자 |
+
+### 2.2 MINOR (부 버전)
+
+하위 호환되는 기능 추가 시 증가:
+
+| 변경 유형 | 예시 |
+|----------|------|
+| 새 기능 추가 | 새 함수/클래스 |
+| 선택적 파라미터 추가 | 기본값 있는 인자 |
+| Deprecation 표시 | 제거 예고 |
+
+### 2.3 PATCH (수정 버전)
+
+하위 호환되는 버그 수정 시 증가:
+
+| 변경 유형 | 예시 |
+|----------|------|
+| 버그 수정 | 동작 오류 수정 |
+| 성능 개선 | API 변경 없는 최적화 |
+| 문서 수정 | 오타, 설명 보완 |
+
+---
+
+## 3. Pre-release 버전
+
+### 3.1 단계
+
+```
+alpha → beta → rc → release
+
+예시:
+1.0.0-alpha.1
+1.0.0-alpha.2
+1.0.0-beta.1
+1.0.0-rc.1
+1.0.0
+```
+
+### 3.2 Pre-release 규칙
+
+- alpha: 불안정, API 변경 가능
+- beta: 기능 완료, 버그 수정 중
+- rc: 릴리스 후보, 중요 버그만 수정
+
+---
+
+## 4. Deprecation 절차
+
+### 4.1 Deprecation 단계
+
+```
+1. MINOR 버전에서 Deprecated 표시
+2. 경고 메시지 출력 (런타임)
+3. 최소 1개 MINOR 버전 유지
+4. 다음 MAJOR에서 제거
+```
+
+### 4.2 Deprecation 표시
+
+```markdown
+## public-api.md
+
+### oldFunction() ⚠️ Deprecated
+
+> **Deprecated since v1.2.0**
+> v2.0.0에서 제거 예정
+> 대신 `newFunction()`을 사용하세요.
+```
+
+### 4.3 changelog.md 기록
+
+```markdown
+## [1.2.0] - YYYY-MM-DD
+
+### Deprecated
+- `oldFunction()` - v2.0.0에서 제거 예정, `newFunction()` 사용 권장
+```
+
+---
+
+## 5. 변경 유형별 버전 결정
+
+| 변경 | MAJOR | MINOR | PATCH |
+|------|:-----:|:-----:|:-----:|
+| API 제거 | ✅ | | |
+| API 시그니처 변경 | ✅ | | |
+| 동작 변경 (비호환) | ✅ | | |
+| 새 기능 추가 | | ✅ | |
+| API Deprecation | | ✅ | |
+| 버그 수정 | | | ✅ |
+| 문서 수정 | | | ✅ |
+| 내부 리팩토링 | | | ✅ |
+
+---
+
+## 6. changelog.md 형식
+
+```markdown
+# Changelog
+
+모든 주요 변경 사항을 기록합니다.
+[Keep a Changelog](https://keepachangelog.com) 형식을 따릅니다.
+
+## [Unreleased]
+
+### Added
+- [TASK-XXX] 새 기능
+
+### Changed
+- [TASK-XXX] 변경 사항
+
+### Deprecated
+- [TASK-XXX] 제거 예정 기능
+
+### Removed
+- [TASK-XXX] 제거된 기능
+
+### Fixed
+- [TASK-XXX] 버그 수정
+
+## [1.1.0] - YYYY-MM-DD
+
+### Added
+- [TASK-001] 초기 기능
+```
+
+---
+
+## 7. 릴리스 체크리스트
+
+### 릴리스 전
+
+- [ ] 모든 Task 완료 (DONE)
+- [ ] changelog.md 갱신
+- [ ] public-api.md 갱신
+- [ ] examples.md 갱신 (필요 시)
+- [ ] 테스트 통과
+- [ ] 버전 번호 결정
+
+### 릴리스 후
+
+- [ ] 버전 태그 생성
+- [ ] 패키지 배포
+- [ ] 릴리스 노트 공개
+
+---
+
+## 8. 금지 사항
+
+- ❌ PATCH에서 새 기능 추가
+- ❌ MINOR에서 Breaking change
+- ❌ Deprecation 없이 API 제거
+- ❌ changelog.md 갱신 없이 릴리스