@wooojin/forgen 0.1.0

package/skills/api-design/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: api-design
+description: This skill should be used when the user asks to "api design,api 설계,REST,GraphQL,엔드포인트,endpoint". Design REST/GraphQL APIs with resource modeling, error handling, and versioning
+---
+
+<!-- forgen-managed -->
+
+<Purpose>
+REST 또는 GraphQL API를 체계적으로 설계합니다.
+리소스 모델링부터 엔드포인트 설계, 에러 핸들링, 버전 관리, 문서화까지
+API 라이프사이클 전체를 다룹니다.
+</Purpose>
+
+<Steps>
+1. **리소스 모델링**: 도메인 엔티티를 API 리소스로 변환합니다
+   - 핵심 도메인 엔티티 식별 (명사 기반)
+   - 리소스 간 관계 매핑 (1:1, 1:N, N:M)
+   - 중첩 리소스 vs 독립 리소스 결정
+   - 리소스 표현(representation) 스키마 정의
+   - 필수/선택 필드 구분 및 타입 명시
+
+2. **엔드포인트 설계**: URL 구조와 HTTP 메서드를 결정합니다
+   - RESTful URL 컨벤션 적용 (복수형 명사, 계층 구조)
+   - HTTP 메서드 매핑 (GET/POST/PUT/PATCH/DELETE)
+   - 쿼리 파라미터 설계 (필터링, 정렬, 페이지네이션)
+   - 페이지네이션 전략 선택 (cursor vs offset)
+   - 벌크 작업 엔드포인트 필요 여부 결정
+   - HATEOAS 링크 포함 여부 결정
+   - GraphQL의 경우: Query/Mutation/Subscription 분리
+
+3. **에러 핸들링**: 일관된 에러 응답 체계를 구축합니다
+   - HTTP 상태 코드 매핑 (400, 401, 403, 404, 409, 422, 429, 500)
+   - 에러 응답 스키마 정의 (code, message, details, trace_id)
+   - 비즈니스 에러 코드 체계 설계
+   - 유효성 검증 에러 상세 포맷 (필드별 에러 목록)
+   - Rate limiting 응답 헤더 (X-RateLimit-Limit, Remaining, Reset)
+   - 에러 메시지의 국제화(i18n) 전략
+
+4. **버전 관리**: API 진화 전략을 수립합니다
+   - 버전 관리 방식 선택 (URL path vs Header vs Query param)
+   - Breaking change 정의 및 마이그레이션 가이드
+   - Deprecation 정책 (최소 6개월 유예기간 권장)
+   - Sunset 헤더 및 공지 절차
+   - 하위 호환성 유지 전략
+
+5. **보안 설계**: API 보안 정책을 수립합니다
+   - 인증 방식 선택 (Bearer Token, API Key, OAuth 2.0)
+   - 인가 모델 설계 (RBAC, ABAC, Scope 기반)
+   - Rate limiting 정책 (엔드포인트별 차등 적용)
+   - CORS 정책 설정
+   - 입력 검증 규칙 (크기 제한, 타입 검증, 범위 검증)
+   - 민감 데이터 마스킹 규칙
+
+6. **문서화**: API 명세를 작성합니다
+   - OpenAPI 3.0+ (REST) 또는 GraphQL Schema 작성
+   - 각 엔드포인트별 요청/응답 예시
+   - 인증 방법 가이드
+   - SDK 코드 샘플 (curl, JavaScript, Python)
+   - 변경 이력(changelog) 관리
+</Steps>
+
+## 에이전트 위임
+
+`architect` 에이전트(Opus 모델)에 위임하여 API 아키텍처를 설계합니다:
+
+```
+Agent(
+  subagent_type="architect",
+  model="opus",
+  prompt="API DESIGN TASK
+
+API를 체계적으로 설계하세요.
+
+Domain: [도메인/서비스 설명]
+Type: [REST / GraphQL / Both]
+
+Design Checklist:
+1. 리소스 모델링 (엔티티, 관계, 스키마)
+2. 엔드포인트 설계 (URL, 메서드, 파라미터)
+3. 에러 핸들링 (상태 코드, 에러 스키마)
+4. 버전 관리 전략
+5. 보안 설계 (인증, 인가, Rate limiting)
+6. OpenAPI/GraphQL 스키마 초안
+
+Output: API 설계 문서:
+- 리소스 모델 다이어그램
+- 엔드포인트 목록 (메서드, URL, 설명)
+- 요청/응답 스키마
+- 에러 코드 매핑
+- 보안 정책 요약"
+)
+```
+
+## External Consultation (Optional)
+
+architect 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자문할 수 있습니다.
+
+### Protocol
+1. **자체 API 설계를 먼저 완료** -- 독립적으로 설계 수행
+2. **검증을 위한 자문** -- Claude Task 에이전트를 통해 설계 교차 확인
+3. **비판적 평가** -- 외부 제안을 맹목적으로 수용하지 않음
+4. **우아한 폴백** -- 위임이 불가능할 경우 절대 차단하지 않음
+
+### 자문이 필요한 경우
+- 대규모 마이크로서비스 간 API 경계 설계
+- 복잡한 인증/인가 플로우
+- 실시간 통신이 필요한 API (WebSocket, SSE)
+- 외부 파트너 공개 API 설계
+
+### 자문을 생략하는 경우
+- 단순 CRUD API
+- 내부 서비스 간 API
+- 잘 알려진 패턴의 적용
+- 프로토타입 수준의 API
+
+## API 설계 체크리스트
+
+### 리소스 설계 (5개)
+- [ ] 리소스 명명이 복수형 명사로 일관됨
+- [ ] 리소스 간 관계가 명확히 정의됨
+- [ ] 필수/선택 필드가 구분됨
+- [ ] 데이터 타입과 포맷이 명시됨 (ISO 8601 날짜 등)
+- [ ] 리소스 표현이 과도한 중첩 없이 평탄화됨
+
+### 엔드포인트 설계 (5개)
+- [ ] HTTP 메서드가 의미에 맞게 사용됨
+- [ ] URL 경로가 계층적이고 예측 가능함
+- [ ] 페이지네이션이 목록 엔드포인트에 적용됨
+- [ ] 필터링/정렬 파라미터가 일관됨
+- [ ] 멱등성(idempotency)이 보장됨 (PUT, DELETE)
+
+### 에러 핸들링 (4개)
+- [ ] HTTP 상태 코드가 의미에 맞게 사용됨
+- [ ] 에러 응답 포맷이 전체 API에서 일관됨
+- [ ] 유효성 검증 에러에 필드별 상세 정보 포함
+- [ ] 비즈니스 에러 코드가 체계적으로 분류됨
+
+### 보안 (4개)
+- [ ] 인증 방식이 결정되고 문서화됨
+- [ ] Rate limiting이 적용됨
+- [ ] 입력 크기 제한이 설정됨
+- [ ] CORS 정책이 명시됨
+
+<Output>
+```
+API DESIGN DOCUMENT / API 설계 문서
+====================================
+
+Service: [서비스명]
+API Type: [REST / GraphQL]
+Version: v1
+Base URL: https://api.example.com/v1
+
+RESOURCE MODEL / 리소스 모델
+-----------------------------
+1. [Resource Name]
+   - id: string (UUID)
+   - name: string (required, max 255)
+   - created_at: string (ISO 8601)
+   - [관계]: [관계 타입] -> [대상 리소스]
+
+ENDPOINTS / 엔드포인트
+-----------------------
+| Method | Path                  | Description       | Auth |
+|--------|-----------------------|-------------------|------|
+| GET    | /resources            | 리소스 목록 조회   | Yes  |
+| POST   | /resources            | 리소스 생성        | Yes  |
+| GET    | /resources/:id        | 리소스 상세 조회   | Yes  |
+| PUT    | /resources/:id        | 리소스 전체 수정   | Yes  |
+| DELETE | /resources/:id        | 리소스 삭제        | Yes  |
+
+ERROR SCHEMA / 에러 스키마
+---------------------------
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "입력 데이터가 유효하지 않습니다",
+    "details": [
+      { "field": "email", "message": "유효한 이메일 형식이 아닙니다" }
+    ],
+    "trace_id": "abc-123"
+  }
+}
+
+ERROR CODES / 에러 코드
+-------------------------
+| HTTP | Code               | Description              |
+|------|--------------------|--------------------------|
+| 400  | VALIDATION_ERROR   | 입력 유효성 검증 실패     |
+| 401  | UNAUTHORIZED       | 인증 필요                |
+| 403  | FORBIDDEN          | 권한 부족                |
+| 404  | NOT_FOUND          | 리소스 없음              |
+| 409  | CONFLICT           | 리소스 충돌              |
+| 429  | RATE_LIMITED       | 요청 한도 초과           |
+
+VERSIONING / 버전 관리
+-----------------------
+Strategy: [URL path / Header / Query param]
+Current: v1
+Deprecation Policy: [정책 설명]
+
+SECURITY / 보안
+----------------
+Authentication: [Bearer Token / API Key / OAuth 2.0]
+Rate Limiting: [요청/분]
+CORS: [허용 도메인]
+```
+</Output>
+
+<Policy>
+- RESTful 원칙을 준수하되 실용성을 우선합니다
+- 일관성이 가장 중요합니다 -- 예외 없는 규칙이 이해하기 쉬운 API를 만듭니다
+- 에러 응답은 클라이언트가 자동으로 처리할 수 있을 만큼 구조화합니다
+- 보안은 설계 단계에서 반드시 포함합니다 (사후 추가 금지)
+- OpenAPI 스키마는 코드와 동기화 상태를 유지합니다
+- Breaking change는 반드시 버전 업과 마이그레이션 가이드를 동반합니다
+</Policy>
+
+## 다른 스킬과의 연동
+
+**코드 리뷰 연동:**
+```
+/forgen:code-review src/api/
+```
+설계된 API의 구현 코드를 리뷰
+
+**보안 리뷰 연동:**
+```
+/forgen:security-review src/api/
+```
+API 엔드포인트의 보안 취약점 점검
+
+**TDD 연동:**
+```
+/forgen:tdd API 엔드포인트 통합 테스트
+```
+API 엔드포인트별 테스트 작성
+
+## Best Practices
+
+- **API 먼저 설계** -- 구현 전에 명세를 확정
+- **일관된 컨벤션** -- 네이밍, 에러 포맷, 페이지네이션을 통일
+- **하위 호환성** -- 기존 클라이언트를 깨뜨리지 않는 변경
+- **적절한 상태 코드** -- 200으로 모든 것을 처리하지 않음
+- **과도한 노출 방지** -- 필요한 필드만 응답에 포함
+
+<Arguments>
+## 사용법
+`/forgen:api-design {설계 대상}`
+
+### 예시
+- `/forgen:api-design 사용자 관리 REST API`
+- `/forgen:api-design 상품 주문 시스템 GraphQL API`
+- `/forgen:api-design 기존 /api/users 엔드포인트 v2 설계`
+- `/forgen:api-design 외부 파트너용 공개 API`
+
+### 인자
+- 설계할 API의 도메인, 타입(REST/GraphQL), 요구사항을 설명
+- 인자 없으면 프로젝트 컨텍스트에서 API 설계 요구사항을 파악
+</Arguments>
+
+$ARGUMENTS

package/skills/architecture-decision/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: architecture-decision
+description: This skill should be used when the user asks to "adr,architecture decision,아키텍처 결정,설계 결정,기술 결정". Architecture Decision Record (ADR) creation with alternatives evaluation and consequence analysis
+---
+
+<!-- forgen-managed -->
+
+<Purpose>
+아키텍처 결정 기록(ADR)을 체계적으로 작성합니다.
+의사결정의 컨텍스트, 대안 평가, 결정, 결과를 구조화하여 기록하고
+미래의 개발자가 "왜 이렇게 결정했는가"를 이해할 수 있도록 합니다.
+</Purpose>
+
+<Steps>
+1. **컨텍스트 수집**: 결정이 필요한 배경을 정리합니다
+   - 해결하려는 문제/요구사항 정의
+   - 현재 시스템 상태 및 제약 조건
+   - 비즈니스 요구사항과 기술 요구사항 구분
+   - 이해관계자 식별 (누가 영향을 받는가)
+   - 결정의 긴급도와 중요도
+   - 관련 기존 ADR 참조
+   - 비기능 요구사항 (성능, 보안, 확장성, 비용)
+
+2. **대안 탐색**: 가능한 선택지를 열거합니다
+   - 최소 3개 이상의 대안 도출
+   - 각 대안에 대한 간략한 설명
+   - "아무것도 하지 않기" 옵션 포함 (현상 유지)
+   - 업계 사례 및 벤치마크 조사
+   - 기존 기술 스택과의 호환성 확인
+   - 팀 역량 및 학습 곡선 고려
+   - 라이선스/비용 확인
+
+3. **대안 평가**: 정량적/정성적 기준으로 비교합니다
+   - 평가 기준 정의:
+     * 기술 적합성 (요구사항 충족도)
+     * 복잡도 (구현 난이도, 운영 부담)
+     * 성능 (응답 시간, 처리량, 리소스)
+     * 확장성 (수평/수직 확장 가능성)
+     * 보안 (취약점, 인증/인가)
+     * 비용 (초기 비용, 운영 비용, 기회 비용)
+     * 생태계 (커뮤니티, 문서, 도구)
+     * 팀 역량 (경험, 학습 곡선)
+   - 가중치 부여 (프로젝트별 우선순위에 따라)
+   - 각 대안의 장단점 분석
+   - PoC(Proof of Concept) 필요 여부 결정
+
+4. **결정**: 최종 선택과 근거를 명시합니다
+   - 선택된 대안과 핵심 이유
+   - 결정을 뒤집을 수 있는 조건 (reversibility)
+   - 수용한 트레이드오프 명시
+   - 거부된 대안과 거부 이유
+   - 결정에 대한 팀 합의 수준
+
+5. **결과 분석**: 결정의 예상 영향을 기록합니다
+   - 긍정적 결과 (해결되는 문제)
+   - 부정적 결과 (새로 발생하는 제약/부담)
+   - 리스크 (무엇이 잘못될 수 있는가)
+   - 리스크 완화 전략
+   - 후속 결정이 필요한 사항
+   - 모니터링 포인트 (결정의 효과를 어떻게 측정할 것인가)
+
+6. **기록 및 공유**: ADR을 작성하고 공유합니다
+   - ADR 번호 및 제목 부여 (ADR-NNN: [제목])
+   - 상태 설정 (Proposed → Accepted → Deprecated → Superseded)
+   - ADR 저장소에 등록 (docs/adr/ 또는 .adr/)
+   - 이해관계자에게 공유 및 피드백 수집
+   - 관련 코드에 ADR 참조 주석 추가
+</Steps>
+
+## 에이전트 위임
+
+`architect` 에이전트(Opus 모델)에 위임하여 아키텍처 분석을 수행합니다:
+
+```
+Agent(
+  subagent_type="architect",
+  model="opus",
+  prompt="ARCHITECTURE DECISION TASK
+
+아키텍처 결정 기록(ADR)을 작성하세요.
+
+Decision: [결정 주제]
+Context: [배경 및 제약 조건]
+
+ADR Checklist:
+1. 컨텍스트 정리 (문제, 제약, 요구사항)
+2. 대안 탐색 (최소 3개 + 현상 유지)
+3. 대안 평가 (기준별 비교표)
+4. 결정 및 근거 (선택 이유, 트레이드오프)
+5. 결과 분석 (긍정/부정, 리스크)
+6. ADR 문서 작성
+
+Output: ADR 문서:
+- 번호 및 제목
+- 상태 (Proposed/Accepted)
+- 컨텍스트
+- 대안 비교표
+- 결정 및 근거
+- 결과 및 리스크"
+)
+```
+
+## External Consultation (Optional)
+
+architect 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자문할 수 있습니다.
+
+### Protocol
+1. **자체 분석을 먼저 완료** -- 독립적으로 대안 평가
+2. **검증을 위한 자문** -- Claude Task 에이전트를 통해 분석 교차 확인
+3. **비판적 평가** -- 외부 제안을 맹목적으로 수용하지 않음
+4. **우아한 폴백** -- 위임이 불가능할 경우 절대 차단하지 않음
+
+### 자문이 필요한 경우
+- 되돌리기 어려운 결정 (데이터베이스 선택, 프레임워크 변경)
+- 조직 전체에 영향을 미치는 결정
+- 비용이 큰 기술 투자 결정
+- 팀 내 의견이 분분한 결정
+
+### 자문을 생략하는 경우
+- 단순 라이브러리 선택 (유사한 기능, 낮은 영향)
+- 내부 구현 세부 사항
+- 잘 알려진 패턴 적용
+- 쉽게 되돌릴 수 있는 결정
+
+## ADR 체크리스트
+
+### 완전성 (5개)
+- [ ] 문제/요구사항이 명확히 정의됨
+- [ ] 최소 3개 대안이 탐색됨
+- [ ] 평가 기준이 명시됨
+- [ ] 선택 근거가 구체적으로 설명됨
+- [ ] 트레이드오프가 명시적으로 기록됨
+
+### 품질 (4개)
+- [ ] 비기능 요구사항 (성능, 보안, 비용)이 고려됨
+- [ ] 리스크와 완화 전략이 포함됨
+- [ ] 결정을 뒤집을 수 있는 조건이 명시됨
+- [ ] 후속 결정 사항이 식별됨
+
+### 프로세스 (3개)
+- [ ] 이해관계자와 공유됨
+- [ ] 피드백이 수집되고 반영됨
+- [ ] 관련 코드에 ADR 참조가 추가됨
+
+## ADR 상태 흐름
+
+```
+[Proposed] → [Accepted] → [Deprecated] (더 이상 관련 없음)
+                       → [Superseded by ADR-NNN] (새 결정으로 대체)
+```
+
+## 결정 되돌림 가능성 분류
+
+| 분류 | 설명 | 예시 | 투자 수준 |
+|------|------|------|-----------|
+| **Type 1** (비가역) | 되돌리기 매우 어렵거나 불가능 | DB 엔진, 프로그래밍 언어 | 심층 분석 필요 |
+| **Type 2** (가역) | 비교적 쉽게 되돌릴 수 있음 | 라이브러리, 내부 패턴 | 신속한 결정 가능 |
+
+## 평가 매트릭스 템플릿
+
+| 기준 (가중치) | 대안 A | 대안 B | 대안 C | 현상 유지 |
+|---------------|--------|--------|--------|-----------|
+| 기술 적합성 (30%) | 9 | 7 | 8 | 3 |
+| 복잡도 (20%) | 6 | 8 | 5 | 10 |
+| 성능 (15%) | 8 | 7 | 9 | 5 |
+| 확장성 (15%) | 9 | 6 | 8 | 4 |
+| 비용 (10%) | 5 | 8 | 6 | 10 |
+| 팀 역량 (10%) | 7 | 9 | 5 | 10 |
+| **가중 합계** | **7.6** | **7.3** | **7.0** | **5.8** |
+
+<Output>
+```
+ARCHITECTURE DECISION RECORD / 아키텍처 결정 기록
+===================================================
+
+ADR-NNN: [결정 제목]
+Status: [Proposed / Accepted / Deprecated / Superseded by ADR-NNN]
+Date: YYYY-MM-DD
+Deciders: [결정 참여자]
+
+CONTEXT / 컨텍스트
+--------------------
+[해결하려는 문제와 배경 설명]
+
+Requirements:
+- [기능 요구사항 1]
+- [비기능 요구사항 (성능, 보안, 비용)]
+
+Constraints:
+- [제약 조건 1]
+- [제약 조건 2]
+
+ALTERNATIVES / 대안
+---------------------
+### 대안 A: [이름]
+[설명]
+- Pros: [장점]
+- Cons: [단점]
+
+### 대안 B: [이름]
+[설명]
+- Pros: [장점]
+- Cons: [단점]
+
+### 대안 C: [이름] (현상 유지)
+[설명]
+- Pros: [장점]
+- Cons: [단점]
+
+EVALUATION / 평가
+-------------------
+| 기준 (가중치) | 대안 A | 대안 B | 대안 C |
+|---------------|--------|--------|--------|
+| [기준 1] (N%) | N/10   | N/10   | N/10   |
+| [기준 2] (N%) | N/10   | N/10   | N/10   |
+| **합계**      | **N**  | **N**  | **N**  |
+
+DECISION / 결정
+-----------------
+**대안 A를 선택합니다.**
+
+Rationale: [핵심 선택 이유]
+
+Trade-offs accepted:
+- [수용한 트레이드오프 1]
+- [수용한 트레이드오프 2]
+
+Reversibility: [Type 1 (비가역) / Type 2 (가역)]
+Reversal condition: [이 결정을 뒤집어야 하는 조건]
+
+CONSEQUENCES / 결과
+---------------------
+Positive:
+- [긍정적 결과 1]
+- [긍정적 결과 2]
+
+Negative:
+- [부정적 결과 1]
+- [부정적 결과 2]
+
+Risks:
+- [리스크 1] → 완화: [완화 전략]
+- [리스크 2] → 완화: [완화 전략]
+
+Follow-up decisions needed:
+- [후속 결정 1]
+- [후속 결정 2]
+
+MONITORING / 모니터링
+-----------------------
+- [효과 측정 지표 1]
+- [효과 측정 지표 2]
+- Review date: YYYY-MM-DD (3개월 후 재검토)
+```
+</Output>
+
+<Policy>
+- 최소 3개 대안을 비교합니다 ("현상 유지" 포함)
+- 정량적 평가 기준을 사용합니다 (직관이 아닌 데이터 기반)
+- 트레이드오프를 명시적으로 기록합니다 -- 모든 결정에는 대가가 있음
+- 결정을 뒤집을 수 있는 조건을 미리 정의합니다
+- ADR은 코드와 함께 버전 관리합니다 (docs/adr/)
+- 폐기된 ADR도 삭제하지 않습니다 -- 역사적 맥락을 보존
+</Policy>
+
+## 다른 스킬과의 연동
+
+**코드 리뷰 연동:**
+```
+/forgen:code-review ADR에 따른 구현 검증
+```
+아키텍처 결정이 구현에 올바르게 반영되었는지 검증
+
+**문서화 연동:**
+```
+/forgen:documentation ADR 기반 아키텍처 문서
+```
+ADR을 바탕으로 아키텍처 설명 문서 작성
+
+**보안 리뷰 연동:**
+```
+/forgen:security-review ADR의 보안 영향 분석
+```
+아키텍처 결정의 보안 관점 검토
+
+## Best Practices
+
+- **결정 기록** -- 구두 합의보다 문서화된 ADR
+- **미래의 나를 위해** -- 6개월 후 맥락을 잊은 자신을 독자로 상정
+- **간결하게** -- ADR은 1~2페이지가 적당
+- **적시에** -- 결정 시점에 작성, 나중에 "기억해서" 쓰지 않음
+- **갱신** -- 상황 변화 시 ADR 상태를 업데이트
+
+<Arguments>
+## 사용법
+`/forgen:architecture-decision {결정 주제}`
+
+### 예시
+- `/forgen:architecture-decision 상태 관리 라이브러리 선택`
+- `/forgen:architecture-decision 모놀리스 → 마이크로서비스 전환`
+- `/forgen:architecture-decision 인증 방식 결정 (JWT vs Session)`
+- `/forgen:architecture-decision 데이터베이스 선택 (PostgreSQL vs MongoDB)`
+
+### 인자
+- 결정이 필요한 주제, 배경, 제약 조건 등을 설명
+- 인자 없으면 현재 프로젝트에서 문서화가 필요한 아키텍처 결정을 식별
+</Arguments>
+
+$ARGUMENTS