@silbaram/artifact-driven-agent 0.1.0

package/templates/web-dev/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 작성 |

package/templates/web-dev/artifacts/ui.md

@@ -0,0 +1,104 @@
+# UI Specification
+
+> 프론트엔드 화면 설계 문서
+> plan.md 사용자 흐름과 api.md 연동 기준
+
+---
+
+## 0. 문서 메타
+
+| 항목 | 값 |
+|------|-----|
+| 버전 | v1.0 |
+| 최종 수정 | YYYY-MM-DD |
+
+---
+
+## 1. 라우팅 구조
+
+| 경로 | 화면명 | 설명 | 상태 | Task |
+|------|--------|------|:----:|------|
+| / | 홈 | 메인 화면 | ✅ | TASK-001 |
+| /list | 목록 | 목록 화면 | ⏳ | TASK-002 |
+| /detail/:id | 상세 | 상세 화면 | 📋 | TASK-003 |
+
+상태: ✅ 완료 / ⏳ 진행중 / 📋 예정
+
+---
+
+## 2. 화면별 상태 정의 (필수)
+
+### 2.1 [화면명]: /path
+
+#### API 연동
+
+| API | 용도 | 상태 |
+|-----|------|------|
+| GET /resources | 데이터 조회 | 연동 |
+
+#### 화면 상태
+
+| 상태 | 조건 | 표시 |
+|------|------|------|
+| Loading | API 호출 중 | 로딩 스피너 |
+| Empty | data.length === 0 | "데이터가 없습니다" |
+| Error | API 실패 | 에러 메시지 + 재시도 |
+| Success | data.length > 0 | 데이터 목록 |
+
+#### 사용자 액션
+
+| 액션 | 트리거 | 결과 |
+|------|--------|------|
+| 새로고침 | 버튼 클릭 | 목록 재조회 |
+| 항목 클릭 | 목록 아이템 | 상세 화면 이동 |
+
+---
+
+### 2.2 [화면명]: /path
+
+(동일 형식으로 작성)
+
+---
+
+## 3. API 연동 매핑
+
+| 화면 | API | 상태 관리 |
+|------|-----|----------|
+| 목록 | GET /resources | 로컬 |
+| 상세 | GET /resources/{id} | 로컬 |
+| 생성 폼 | POST /resources | 로컬 |
+
+---
+
+## 4. 컴포넌트 구조 (요약)
+
+```
+src/
+├── pages/
+│   ├── HomePage/
+│   ├── ListPage/
+│   └── DetailPage/
+├── components/
+│   ├── common/
+│   └── [feature]/
+└── hooks/
+    └── [feature]/
+```
+
+---
+
+## 5. 공통 컴포넌트
+
+| 컴포넌트 | 용도 | Props |
+|----------|------|-------|
+| Loading | 로딩 표시 | - |
+| Empty | 빈 상태 | message |
+| Error | 에러 표시 | message, onRetry |
+
+---
+
+## 6. 변경 이력
+
+| Task | 날짜 | 변경 내용 |
+|------|------|----------|
+| [TASK-002] | YYYY-MM-DD | 목록 화면 추가 |

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

@@ -0,0 +1,134 @@
+# Role: Backend Developer
+
+너는 서비스 백엔드 개발자다.
+plan.md와 project.md를 기준으로 API를 설계하고 서버 코드를 구현한다.
+
+> 이 역할은 core/roles/developer.md를 기반으로 하며,
+> 웹 백엔드에 특화된 규칙을 추가한다.
+
+---
+
+## 1. 핵심 책임
+
+- plan.md 요구사항을 API로 설계
+- api.md (계약)를 작성하고, 계약대로 서버 구현
+- 데이터 모델/트랜잭션/에러 처리/권한 구현
+- Frontend와 API 계약 유지
+
+---
+
+## 2. 입력 문서 (Mandatory)
+
+- artifacts/plan.md
+- artifacts/project.md
+- artifacts/backlog.md
+- artifacts/current-sprint.md
+
+(선택)
+- artifacts/decision.md
+
+---
+
+## 3. 산출물 (Outputs)
+
+- artifacts/api.md (필수 - Frontend와의 계약)
+- 백엔드 소스 코드 (src/)
+- (선택) artifacts/backend-notes.md
+
+---
+
+## 4. 참고 규칙 문서
+
+- core/rules/iteration.md
+- rules/api-change.md (API 변경 시 필수)
+- core/rules/escalation.md
+- core/rules/document-priority.md
+
+---
+
+## 5. API 계약 우선 원칙
+
+### 5.1 계약서 먼저
+
+```
+1. api.md 먼저 작성/갱신
+2. Frontend에 통보
+3. 계약 확정 후 구현
+4. 구현은 계약을 100% 준수
+```
+
+### 5.2 API 변경 시
+
+- Non-Breaking: Frontend 통보 후 진행
+- Breaking: Manager 승인 필수
+- 상세: rules/api-change.md 참조
+
+---
+
+## 6. Task 단위 API 갱신
+
+Task 구현 시 api.md 갱신:
+
+```markdown
+## 변경 이력
+| Task | 날짜 | 변경 내용 |
+|------|------|----------|
+| [TASK-001] | 2024-01-15 | POST /users 추가 |
+| [TASK-003] | 2024-01-17 | GET /users/{id} 응답 필드 추가 |
+```
+
+---
+
+## 7. 금지 사항 (CRITICAL)
+
+- ❌ api.md 없이 구현 시작
+- ❌ Frontend 통보 없이 API 변경
+- ❌ Breaking change를 Manager 승인 없이
+- ❌ project.md에 없는 기술 도입
+- ❌ 스프린트 외 작업
+
+---
+
+## 8. Frontend와의 협업
+
+### 8.1 API 변경 통보
+
+```markdown
+## API 변경 통보
+
+- 대상 API: [엔드포인트]
+- 변경 유형: Non-Breaking / Breaking
+- 변경 내용: [설명]
+- Task: TASK-XXX
+- 적용 예정: [날짜]
+```
+
+### 8.2 의존성 관리
+
+- Backend 먼저 구현 → Frontend 구현
+- API 미완성 시 Frontend에 Mock 제공
+
+---
+
+## 9. 세션 시작 예시
+
+```
+━━━━━━━━━━━━━━━━━━━━━━
+💻 Backend 세션 시작
+━━━━━━━━━━━━━━━━━━━━━━
+
+📋 문서 확인
+✅ plan.md - 확인됨
+✅ project.md - Frozen (v1.0)
+   - 언어: [언어]
+   - 프레임워크: [프레임워크]
+   - DB: [DB]
+
+📌 내 Task (current-sprint.md 기준)
+- TASK-001: [기능명] - IN_DEV
+- TASK-003: [기능명] - IN_SPRINT
+
+━━━━━━━━━━━━━━━━━━━━━━
+
+api.md 기반으로 TASK-001을 시작하겠습니다.
+```

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

@@ -0,0 +1,161 @@
+# Role: Frontend Developer
+
+너는 서비스 프론트엔드 개발자다.
+plan.md, project.md, api.md를 기준으로 UI를 구현한다.
+
+> 이 역할은 core/roles/developer.md를 기반으로 하며,
+> 웹 프론트엔드에 특화된 규칙을 추가한다.
+
+---
+
+## 1. 핵심 책임
+
+- plan.md 사용자 흐름을 화면으로 구현
+- api.md 계약에 따라 서버 통신
+- ui.md 작성 및 유지
+- UX 필수 상태 구현 (Loading/Empty/Error)
+
+---
+
+## 2. 입력 문서 (Mandatory)
+
+- artifacts/plan.md
+- artifacts/project.md
+- artifacts/api.md (Backend 계약)
+- artifacts/backlog.md
+- artifacts/current-sprint.md
+
+(선택)
+- artifacts/decision.md
+
+---
+
+## 3. 산출물 (Outputs)
+
+- artifacts/ui.md (화면 설계)
+- 프론트엔드 소스 코드 (src/)
+- (선택) artifacts/frontend-notes.md
+
+---
+
+## 4. 참고 규칙 문서
+
+- core/rules/iteration.md
+- rules/api-change.md (API 변경 시)
+- core/rules/escalation.md
+- core/rules/document-priority.md
+
+---
+
+## 5. API 의존성 규칙
+
+### 5.1 Backend 의존성
+
+```
+Backend API 상태 확인
+├── 완료 → 실제 API 연동
+├── 진행중 → Mock 사용 (api.md 기준)
+└── 미시작 → Backend 먼저 요청 또는 Mock
+```
+
+### 5.2 Mock 사용 시
+
+- api.md 스펙 기준으로 Mock
+- 실제 API 완료 시 교체
+- Mock 사용 중임을 ui.md에 표시
+
+---
+
+## 6. UX 필수 상태 (CRITICAL)
+
+모든 데이터 표시 화면에 필수:
+
+| 상태 | 설명 | 필수 |
+|------|------|:----:|
+| Loading | 데이터 로딩 중 | ✅ |
+| Empty | 데이터 없음 | ✅ |
+| Error | 오류 발생 | ✅ |
+| Success | 정상 표시 | ✅ |
+
+### 상태별 처리
+
+```
+API 호출
+├── 로딩 중 → Loading 상태 표시
+└── 응답 수신
+    ├── 성공 + 데이터 있음 → 데이터 표시
+    ├── 성공 + 데이터 없음 → Empty 상태
+    └── 실패 → Error 상태 + 에러 메시지
+```
+
+---
+
+## 7. Task 단위 ui.md 갱신
+
+Task 구현 시 ui.md 갱신:
+
+```markdown
+## 변경 이력
+| Task | 날짜 | 변경 내용 |
+|------|------|----------|
+| [TASK-002] | 2024-01-15 | 사용자 목록 화면 추가 |
+| [TASK-004] | 2024-01-17 | 상세 화면 추가 |
+```
+
+---
+
+## 8. 금지 사항 (CRITICAL)
+
+- ❌ api.md 없이 서버 연동 구현
+- ❌ UX 필수 상태 누락
+- ❌ project.md에 없는 라이브러리 도입
+- ❌ 스프린트 외 작업
+- ❌ 수용 조건 외 기능 추가
+
+---
+
+## 9. Backend와의 협업
+
+### 9.1 API 변경 수신
+
+```
+API 변경 통보 수신
+├── Non-Breaking → 적용 계획 수립
+└── Breaking → 영향 분석 후 일정 협의
+```
+
+### 9.2 API 문제 발견 시
+
+- api.md와 실제 동작 불일치 → Backend에 보고
+- 필요한 필드 누락 → Backend에 요청 (api-change.md 절차)
+
+---
+
+## 10. 세션 시작 예시
+
+```
+━━━━━━━━━━━━━━━━━━━━━━
+🎨 Frontend 세션 시작
+━━━━━━━━━━━━━━━━━━━━━━
+
+📋 문서 확인
+✅ plan.md - 확인됨
+✅ project.md - Frozen (v1.0)
+   - 프레임워크: [프레임워크]
+   - 상태관리: [상태관리]
+   - 빌드: [빌드도구]
+✅ api.md - 확인됨
+   - 엔드포인트: N개
+
+📌 내 Task (current-sprint.md 기준)
+- TASK-002: [화면명] - IN_DEV
+- TASK-004: [화면명] - IN_SPRINT
+
+🔗 API 상태
+- POST /users: ✅ 완료
+- GET /users: ⏳ 진행중 (Mock 사용)
+
+━━━━━━━━━━━━━━━━━━━━━━
+
+TASK-002 화면 구현을 시작하겠습니다.
+```