@su-record/vibe 0.1.0

package/templates/constitution-template.md

@@ -0,0 +1,193 @@
+# Project Constitution
+
+이 문서는 프로젝트의 핵심 원칙과 코딩 표준을 정의합니다.
+
+---
+
+## 언어 설정
+
+**기본 언어**: 한국어 (ko)
+
+변경하려면 `.sutory/config.json`에서 수정:
+```json
+{
+  "language": "ko"  // "en"으로 변경 가능
+}
+```
+
+---
+
+## 1. 프로젝트 원칙
+
+### 가치 (Values)
+1. **사용자 중심**: 사용자 경험을 최우선으로
+2. **품질**: 빠른 것보다 올바른 것
+3. **간결함**: 복잡함보다 단순함
+4. **협업**: 개인보다 팀
+
+### 의사결정 기준
+1. 보안 > 성능 > 편의성
+2. 명확함 > 영리함
+3. 테스트 가능 > 추상적 설계
+
+---
+
+## 2. 코딩 표준
+
+### 공통 원칙
+- **DRY**: Don't Repeat Yourself
+- **SRP**: Single Responsibility Principle
+- **YAGNI**: You Aren't Gonna Need It
+- **함수 ≤30줄** (권장), ≤50줄 (허용)
+- **Cyclomatic Complexity ≤10**
+- **Cognitive Complexity ≤15**
+
+### 네이밍 규칙
+- 변수: 명사 (`userData`, `userList`)
+- 함수: 동사+명사 (`fetchData`, `updateUser`)
+- Boolean: `is/has/can` (`isLoading`, `hasError`)
+- 상수: `UPPER_SNAKE_CASE` (`MAX_RETRY_COUNT`)
+
+---
+
+## 3. 품질 기준 (TRUST 5)
+
+### T - Test-first
+- ✅ Contract Testing (최우선)
+- ✅ Integration Testing (70%+ 커버리지)
+- 🔵 Unit Testing (순수 함수만)
+
+### R - Readable
+- 한국어 주석 및 docstring
+- 명확한 변수명
+- 복잡한 로직은 주석으로 설명
+
+### U - Unified
+- 일관된 코딩 스타일
+- 프로젝트 전체 동일한 패턴
+
+### S - Secured
+- SQL Injection 방지
+- XSS 방지
+- 민감 정보 환경 변수로 관리
+
+### T - Trackable
+- Git commit 메시지 명확히
+- TODO/FIXME 주석 활용
+- 중요 결정사항 문서화
+
+---
+
+## 4. 기술 스택
+
+### Backend
+- Language: {Python 3.11+ / Node.js / etc.}
+- Framework: {FastAPI / Express / etc.}
+- Database: {PostgreSQL / MongoDB / etc.}
+
+### Frontend
+- Framework: {Flutter / React / etc.}
+- State Management: {Provider / Redux / etc.}
+
+### Infrastructure
+- Hosting: {Cloud Run / Vercel / etc.}
+- CI/CD: {GitHub Actions / etc.}
+
+---
+
+## 5. Git 워크플로우
+
+### 브랜치 전략
+- `main`: 프로덕션
+- `develop`: 개발 (기본 브랜치)
+- `feature/{기능명}`: 새 기능
+- `fix/{버그명}`: 버그 수정
+
+### Commit 메시지 규칙
+```
+feat: 새 기능 추가
+fix: 버그 수정
+docs: 문서 수정
+refactor: 리팩토링
+test: 테스트 추가/수정
+chore: 빌드, 설정 변경
+```
+
+### PR 규칙
+1. SPEC 기반 개발
+2. 코드 리뷰 필수
+3. 테스트 통과 확인
+4. SPEC 검증 완료
+
+---
+
+## 6. 코드 리뷰 기준
+
+### 필수 체크
+- [ ] SPEC 요구사항 충족
+- [ ] TRUST 5 준수
+- [ ] 테스트 작성 및 통과
+- [ ] 문서화 완료
+- [ ] 보안 이슈 없음
+
+### 권장 사항
+- [ ] 성능 최적화 고려
+- [ ] 확장성 고려
+- [ ] 에러 처리 완비
+
+---
+
+## 7. 문서화 규칙
+
+### 코드 주석
+- 모든 함수: 한국어 docstring
+- 복잡한 로직: 인라인 주석
+- TODO/FIXME: 이슈 번호 포함
+
+### API 문서
+- OpenAPI (Swagger) 자동 생성
+- 예시 Request/Response 포함
+
+### README
+- 프로젝트 개요
+- 설치 및 실행 방법
+- 주요 기능 설명
+
+---
+
+## 8. 보안 정책
+
+### 인증
+- JWT 기반 인증
+- 토큰 유효 기간: {기간}
+- Refresh 토큰 사용
+
+### 권한
+- Role-based Access Control
+- 최소 권한 원칙
+
+### 데이터 보호
+- 개인정보 암호화
+- HTTPS 필수
+- 환경 변수로 비밀 관리
+
+---
+
+## 9. 성능 목표
+
+### 응답 시간
+- API: P95 < 500ms
+- 웹페이지: FCP < 1.5s
+
+### 가용성
+- Uptime: 99.9%
+- RTO: 1시간
+- RPO: 15분
+
+---
+
+## 10. 변경 이력
+
+| 날짜 | 변경 내용 | 작성자 |
+|------|-----------|--------|
+| {날짜} | 문서 생성 | {이름} |

package/templates/plan-template.md

@@ -0,0 +1,237 @@
+# PLAN: {기능명}
+
+## Metadata
+- **SPEC**: `specs/{기능명}.md`
+- **작성일**: {YYYY-MM-DD}
+- **작성자**: {이름}
+- **담당 에이전트**: {Backend Python Expert | Frontend Flutter Expert | etc.}
+
+---
+
+## 1. 기술 스택 선정
+
+### 선택된 기술
+| 항목 | 기술 | 이유 |
+|------|------|------|
+| 백엔드 | {기술} | {이유} |
+| 프론트엔드 | {기술} | {이유} |
+| 데이터베이스 | {기술} | {이유} |
+| 외부 서비스 | {기술} | {이유} |
+
+### 대안 기술 (검토 후 제외)
+- **{기술 A}**: 제외 이유
+- **{기술 B}**: 제외 이유
+
+---
+
+## 2. 아키텍처 설계
+
+### High-level Architecture
+```
+[Client] → [API Gateway] → [Service] → [Database]
+                    ↓
+              [External API]
+```
+
+### 컴포넌트 설계
+- **Component 1**: {역할}
+- **Component 2**: {역할}
+
+### 데이터 흐름
+1. 사용자 요청
+2. 검증
+3. 처리
+4. 응답
+
+---
+
+## 3. API 설계
+
+### Endpoint 1: {이름}
+```
+POST /api/v1/resource
+Headers:
+  Authorization: Bearer {token}
+  Content-Type: application/json
+
+Request:
+{
+  "field1": "value"
+}
+
+Response (200):
+{
+  "id": "...",
+  "status": "success"
+}
+
+Error (400):
+{
+  "error": "Invalid request",
+  "details": "..."
+}
+```
+
+---
+
+## 4. 데이터베이스 스키마
+
+### 테이블: {이름}
+```sql
+CREATE TABLE resource (
+  id UUID PRIMARY KEY,
+  field1 VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL,
+  INDEX idx_field1 (field1)
+);
+```
+
+### 인덱스 전략
+- `idx_field1`: 조회 성능 향상
+
+---
+
+## 5. 외부 서비스 통합
+
+### Service 1: {이름}
+- **용도**: {목적}
+- **비용**: 월 ${금액} (예상 {건}건 기준)
+- **API 문서**: {URL}
+- **인증 방식**: {방법}
+
+---
+
+## 6. 보안 설계
+
+### 인증 (Authentication)
+- 방식: JWT
+- 토큰 유효 기간: 1시간
+- Refresh 토큰: 7일
+
+### 권한 (Authorization)
+- Role-based Access Control (RBAC)
+- Roles: Admin, User, Guest
+
+### 데이터 보호
+- 개인정보 암호화: AES-256
+- 전송 암호화: TLS 1.3
+
+---
+
+## 7. 성능 최적화 전략
+
+### 캐싱
+- Redis 캐시: {대상 데이터}
+- TTL: {시간}
+
+### 데이터베이스 최적화
+- 인덱싱: {컬럼}
+- 커넥션 풀: {크기}
+
+### 비동기 처리
+- 무거운 작업: 백그라운드 Job
+
+---
+
+## 8. 에러 처리 전략
+
+### 에러 분류
+| 코드 | 유형 | 처리 |
+|------|------|------|
+| 400 | Bad Request | 입력 검증 에러 메시지 |
+| 401 | Unauthorized | 로그인 필요 |
+| 403 | Forbidden | 권한 없음 |
+| 404 | Not Found | 리소스 없음 |
+| 500 | Server Error | 로그 + 일반 메시지 |
+
+### 재시도 전략
+- 네트워크 에러: 3회 재시도 (Exponential Backoff)
+- 외부 API 에러: 1회 재시도
+
+---
+
+## 9. 모니터링 및 로깅
+
+### 메트릭
+- 응답 시간: P50, P95, P99
+- 에러율: 5분 단위
+- 처리량: RPS
+
+### 로깅
+- 레벨: INFO, ERROR
+- 포맷: JSON (Structured Logging)
+- 보관 기간: 30일
+
+### 알림
+- 에러율 > 5%: Slack 알림
+- 응답 시간 > 3초: 경고
+
+---
+
+## 10. 테스트 전략
+
+### Contract Testing
+- Pydantic/Zod 스키마로 API 계약 검증
+
+### Integration Testing
+- 핵심 경로: {경로 1}, {경로 2}
+- 목표 커버리지: 70%
+
+### Load Testing
+- 목표: {TPS}
+- 도구: Locust / k6
+
+---
+
+## 11. 배포 전략
+
+### 환경
+- Development: 로컬 Docker
+- Staging: Cloud Run (1 instance)
+- Production: Cloud Run (auto-scale 1-10)
+
+### CI/CD
+- GitHub Actions
+- 자동 테스트 → 자동 배포
+
+### Rollback 계획
+- 이전 버전으로 즉시 롤백 가능
+
+---
+
+## 12. 비용 예측
+
+| 항목 | 월 비용 | 근거 |
+|------|---------|------|
+| Cloud Run | ${금액} | {근거} |
+| Database | ${금액} | {근거} |
+| 외부 API | ${금액} | {근거} |
+| **총계** | **${금액}** | |
+
+---
+
+## 13. 마일스톤
+
+| 단계 | 내용 | 예상 시간 |
+|------|------|-----------|
+| 1 | {작업} | {시간} |
+| 2 | {작업} | {시간} |
+| 3 | {작업} | {시간} |
+
+---
+
+## 14. 리스크 및 완화 방안
+
+### 리스크 1: {제목}
+- **확률**: High | Medium | Low
+- **영향**: High | Medium | Low
+- **완화 방안**: {방법}
+
+---
+
+## 15. 다음 단계
+
+1. SPEC 재검토 및 승인
+2. TASKS 문서 생성
+   → `sutory tasks "{기능명}"`
+3. 구현 시작

package/templates/spec-template.md

@@ -0,0 +1,142 @@
+# SPEC: {기능명}
+
+## Metadata
+- **작성일**: {YYYY-MM-DD}
+- **작성자**: {이름}
+- **상태**: DRAFT
+- **우선순위**: {HIGH | MEDIUM | LOW}
+- **언어**: {ko | en}
+- **담당 에이전트**: {에이전트명}
+- **기술 스택**: {프로젝트 기술 스택 요약}
+
+---
+
+## 1. 기능 개요
+
+{1-2문장으로 요약}
+
+### 배경 (Background)
+{왜 이 기능이 필요한가}
+
+### 목표 (Goals)
+- 목표 1
+- 목표 2
+
+### 비목표 (Non-Goals)
+- 이번에 하지 않을 것 1
+- 이번에 하지 않을 것 2
+
+### 기술 스택 컨텍스트
+
+**기존 기술:**
+- 백엔드: {FastAPI, Django, Express 등}
+- 프론트엔드: {React, Flutter, Vue 등}
+- 데이터베이스: {PostgreSQL, MySQL, MongoDB 등}
+- 인프라: {GCP, AWS, Azure 등}
+
+**이번 기능에 필요한 새 기술:**
+- {새 라이브러리/서비스 1} - {사유}
+- {새 라이브러리/서비스 2} - {사유}
+
+**외부 API/서비스 연동:**
+- {서비스명} - {용도}
+
+**제약사항:**
+- 비용 한도: {금액}
+- 성능 요구사항: {목표 응답 시간, 처리량 등}
+
+---
+
+## 2. 사용자 스토리
+
+### Story 1: {스토리 제목}
+**As a** {사용자 역할}
+**I want** {원하는 기능}
+**So that** {이유/가치}
+
+#### Acceptance Criteria
+- [ ] {검증 가능한 조건 1}
+- [ ] {검증 가능한 조건 2}
+
+---
+
+## 3. Requirements (EARS 형식)
+
+### REQ-001: {요구사항 제목}
+
+**WHEN** {특정 조건}
+**THEN** {시스템 동작} (SHALL | SHOULD | MAY)
+
+#### Acceptance Criteria
+- [ ] {테스트 가능한 기준 1}
+- [ ] {테스트 가능한 기준 2}
+
+#### Example
+```
+Input: {...}
+Output: {...}
+```
+
+---
+
+## 4. 비기능 요구사항
+
+### 성능 (Performance)
+- 응답 시간: {목표}
+- 처리량: {목표}
+
+### 보안 (Security)
+- 인증: {방식}
+- 권한: {규칙}
+
+### 확장성 (Scalability)
+- 예상 성장률: {수치}
+
+---
+
+## 5. 데이터 모델 (초안)
+
+### Entity: {이름}
+```json
+{
+  "field1": "type",
+  "field2": "type"
+}
+```
+
+---
+
+## 6. API 계약 (초안)
+
+### Endpoint: {이름}
+```
+POST /api/v1/resource
+Request: {...}
+Response: {...}
+```
+
+---
+
+## 7. Out of Scope
+
+- ❌ {제외 항목 1}
+- ❌ {제외 항목 2}
+
+---
+
+## 8. 검증 체크리스트
+
+- [ ] 모든 요구사항이 테스트 가능한가?
+- [ ] SHALL/SHOULD/MAY가 명확한가?
+- [ ] Acceptance Criteria가 구체적인가?
+- [ ] 성능 목표가 측정 가능한가?
+
+---
+
+## 9. 승인
+
+- [ ] 사용자 승인
+- [ ] 기술 리뷰 완료
+
+승인일: ____________
+승인자: ____________

package/templates/tasks-template.md

@@ -0,0 +1,132 @@
+# TASKS: {기능명}
+
+## Metadata
+- **SPEC**: `specs/{기능명}.md`
+- **PLAN**: `plans/{기능명}-plan.md`
+- **작성일**: {YYYY-MM-DD}
+- **총 예상 시간**: {시간}
+
+---
+
+## 진행 상황
+
+- **전체**: 0 / {총 작업 수}
+- **완료**: 0
+- **진행 중**: 0
+- **대기**: {총 작업 수}
+
+**진행률**: 0%
+
+---
+
+## 작업 목록
+
+### Phase 1: 기반 설정
+
+#### Task 1-1: {작업명}
+- **상태**: ⬜ 대기 | 🟡 진행 중 | ✅ 완료
+- **담당**: {에이전트명}
+- **예상 시간**: {시간}
+- **우선순위**: HIGH | MEDIUM | LOW
+- **의존성**: 없음 | Task {번호}
+
+**설명**:
+{무엇을 해야 하는지}
+
+**Acceptance Criteria**:
+- [ ] {검증 기준 1}
+- [ ] {검증 기준 2}
+
+**참고 파일**:
+- `path/to/file1`
+- `path/to/file2`
+
+**완료 일시**: _________
+
+---
+
+#### Task 1-2: {작업명}
+...
+
+---
+
+### Phase 2: 핵심 기능 구현
+
+#### Task 2-1: {작업명}
+...
+
+---
+
+### Phase 3: 통합 및 테스트
+
+#### Task 3-1: {작업명}
+...
+
+---
+
+## 의존성 그래프
+
+```
+Task 1-1 → Task 1-2 → Task 2-1
+                    ↘
+Task 1-3 → Task 2-2 → Task 3-1
+```
+
+---
+
+## 체크리스트
+
+### 코드 작성
+- [ ] 모든 함수에 type hints
+- [ ] 한국어 docstring
+- [ ] ≤30 lines per function
+- [ ] TRUST 5 준수
+
+### 테스트
+- [ ] Contract tests (API 스키마)
+- [ ] Integration tests (핵심 경로)
+- [ ] 목표 커버리지 달성 (70%+)
+
+### 문서
+- [ ] API 문서 업데이트
+- [ ] README 업데이트
+- [ ] CHANGELOG 업데이트
+
+### SPEC 검증
+- [ ] REQ-001 충족
+- [ ] REQ-002 충족
+- [ ] REQ-003 충족
+- [ ] 성능 목표 달성
+
+---
+
+## 마일스톤
+
+| 날짜 | 마일스톤 | 완료 |
+|------|----------|------|
+| {날짜} | Phase 1 완료 | ⬜ |
+| {날짜} | Phase 2 완료 | ⬜ |
+| {날짜} | Phase 3 완료 | ⬜ |
+| {날짜} | SPEC 검증 완료 | ⬜ |
+
+---
+
+## 변경 이력
+
+| 날짜 | 변경 내용 | 작성자 |
+|------|-----------|--------|
+| {날짜} | 문서 생성 | {이름} |
+
+---
+
+## 다음 단계
+
+구현 시작:
+```bash
+sutory implement "{기능명}"
+```
+
+또는 특정 에이전트 지정:
+```bash
+sutory implement "{기능명}" --agent backend-python-expert
+```