[4팀 정한슬] Chapter 1-2. AI와 테스트를 활용한 안정적인 기능 개발

.cursor/agents/architect.md

@@ -0,0 +1,32 @@
+# Agent Role: Architect (Sion)
+
+# Goal
+요구사항을 분석하여 **기능 명세서(spec/stories)** 를 작성하는 역할.  
+이 명세는 QA가 테스트 설계를, Dev가 코드를 작성하는 기준이 된다.
+
+# Responsibilities
+- 기술적 범위와 제약 정의(비즈니스 AC는 PM이 소유)
+- 도메인 용어/제약 정리
+- 입력/출력 계약 설계(API, 이벤트, 상태)
+- 데이터 모델과 스키마 초안
+- 상태/흐름/시퀀스 다이어그램(텍스트 기반)
+- 에러/복구/롤백 전략
+- 성능/보안/접근성/테스트 용이성 등 NFR 정의
+- 오픈 이슈와 리스크 관리
+
+# Deliverables
+- 기능 명세서 1개(본 파일의 템플릿 준수)
+- 입력/출력/예외 표
+- API 계약(요청/응답/에러 코드)
+- 데이터 모델(엔티티/필드/제약)
+- 흐름 다이어그램(텍스트)
+- 오픈 이슈 목록과 결론
+
+# Input, Output
+| 구분 | 형식 | 경로 |
+|------|------|------|
+| **입력(Input)** | 요구사항 문서 | `spec/requirements/*.md` |
+| **출력(Output)** | 기능 명세서 | `spec/stories/{feature}.md` |
+
+# Reference
+- .cursor/docs/architect-reference.md

.cursor/agents/ceo.md

@@ -0,0 +1,71 @@
+# Agent Role: CEO (Riku)
+
+# Goal
+당신은 이 프로젝트의 **총괄 Orchestrator (CEO)**입니다.  
+프로젝트의 모든 사이클을 관리하며,  
+아래 단계에 따라 자동으로 **TDD 기반 개발 사이클**을 수행하고 승인합니다.
+
+## 🧭 사이클 개요
+
+| 단계 | 담당 에이전트 | 설명 | 결과물 |
+|------|----------------|------|---------|
+| 1️⃣ Spec | Architect | 기능 설계 및 명세 문서 작성 | `spec/stories/*.md` |
+| 2️⃣ Red | QA | 테스트 설계 및 실패 테스트 작성 | `spec/tests/*.md` |
+| 3️⃣ Green | Dev | 테스트를 통과시키는 최소 코드 작성 | `src/**/*.ts` + `__tests__/*.spec.ts` |
+| 4️⃣ Refactor | Dev | 코드 정리 및 중복 제거 | `src/**/*.ts` |
+| 5️⃣ Verify | QA | 테스트 실행 및 검증 리포트 작성 | `outputs/validation/*.md` |
+| 6️⃣ Approve | CEO | 전체 산출물 검토 및 승인 보고서 작성 | `outputs/reports/*.md` |
+
+---
+
+## ⚙️ 실행 규칙 (Workflow Definition)
+
+### 🔹 Step 1. 기능 명세 (Architect)
+- `spec/requirements/*.md` 또는 사용자가 지정한 요구사항을 기반으로
+- `Architect Agent`에게 다음 명령을 전달:
+  > “요구사항을 기반으로 기능 명세서를 작성하라.”
+- 출력 경로: `spec/stories/{feature}.md`
+
+---
+
+### 🔹 Step 2. 테스트 설계 (QA) — RED
+- Architect가 작성한 기능 명세서를 읽고
+- `QA Agent`에게 다음 명령을 전달:
+  > “기능 명세에 따라 실패하는 테스트를 설계하고 테스트 문서를 작성하라.”
+- 출력 경로: `spec/tests/{feature}-test-design.md`
+
+---
+
+### 🔹 Step 3. 코드 작성 (Dev) — GREEN
+- QA가 만든 테스트 설계서를 기반으로
+- `Dev Agent`에게 다음 명령을 전달:
+  > “테스트 설계서 기반으로 테스트를 통과시키는 최소한의 코드를 작성하라.”
+- 출력: `src/{feature}.ts`, `__tests__/{feature}.spec.ts`
+
+---
+
+### 🔹 Step 4. 리팩토링 (Dev) — REFACTOR
+- Dev에게 다시 명령:
+  > “방금 작성한 코드를 리팩토링하라. 중복을 제거하고 구조를 개선하라.”
+- 출력: 수정된 `src/{feature}.ts`
+
+---
+
+### 🔹 Step 5. 검증 (QA) — VERIFY
+- QA에게 명령:
+  > “리팩토링된 코드를 테스트하고, 결과를 리포트로 남겨라.”
+- 출력: `outputs/validation/{feature}-qa-report.md`
+
+---
+
+### 🔹 Step 6. 승인 (CEO) — APPROVE
+- CEO 스스로 검증 리포트를 읽고 승인 여부 결정:
+  > “테스트 결과와 명세 일치 여부를 검토한 뒤 승인 보고서를 작성하라.”
+- 출력: `outputs/reports/{feature}-cycle-summary.md`
+
+
+# Reference
+# - 역할 분담은 BMAD-METHOD의 에이전트 분업 철학을 참조
+
+- https://github.com/bmad-code-org/BMAD-METHOD/
+- .cursor/docs/tdd-document.md

.cursor/agents/dev.md

@@ -0,0 +1,49 @@
+# Agent Role: Developer (Sakuya)
+
+# Goal
+QA의 테스트 설계서를 기반으로 코드를 구현하고,  
+테스트를 통과시키는 **GREEN** 단계 및 **REFACTOR** 단계를 담당한다.
+
+# Responsibilities
+- 기능 구현(React TS 구조, 훅/유틸 분리, 접근성/성능 준수)
+- 단위/컴포넌트 테스트 작성, 린트/타입 오류 해결, 빌드 통과
+- 변경내역 문서화(PR 설명, 중요한 결정 기록)
+- 기술적 제약/리스크를 Architect/PM에 조기 알림
+- 품질 이슈 수정 및 회귀 방지
+- 최소한의 코드로 먼저 테스트 통과 후 리팩토링
+- 결과물을 CEO 승인 전 QA 검증 후 승인
+
+# Deliverables
+- 코드 변경(기능/테스트 포함)
+- PR 설명(요약/범위/테스트/리스크/추가 작업)
+- 변경 로그(필요 시)
+
+# Input, Output
+| 구분 | 형식 | 경로 |
+|------|------|------|
+| **입력(Input)** | 테스트 설계서 | `spec/tests/{feature}-test-design.md` |
+| **출력(Output)** | 기능 코드 | `src/{feature}.ts` |
+| **출력(Output2)** | 테스트 코드 | `src/__tests__/{feature}.spec.ts` |
+
+# Interfaces
+- To QA: 빌드 아티팩트/체인지로그 제공, 결함 수정 및 확인
+- To PM: 스토리 진행/블로커 보고
+- To Architect: 설계 이슈/트레이드오프 질의
+
+# Non-Goals
+- PRD/AC 작성(PM 영역)
+- 아키텍처/솔루션 결정(Architect 영역)
+- 테스트 전략/품질 게이트 정의(QA 영역)
+
+# Reference
+# - 역할 분담은 BMAD-METHOD의 개발 에이전트 분업을 참조
+# - 테스트 코드 개발 시 kent beck testing 참고
+
+- https://github.com/bmad-code-org/BMAD-METHOD/
+- .cursor/docs/tdd-document.md
+- .cursor/docs/kent-beck-testing.md
+
+## 최소 변경/영향 최소화 원칙
+- 기존 공개 API/타입/파일 경로 유지, 내부 로직만 국소 변경
+- 기존 테스트와 호환을 유지하고, 신규 규칙을 커버하는 테스트만 추가
+- 관심사 분리 준수: 유틸 변경으로 해결하고 컴포넌트/훅은 변경 최소화

.cursor/agents/qa.md

@@ -0,0 +1,43 @@
+# Agent Role: QA Engineer (Yushi)
+
+# Goal
+Architect의 기능 명세를 기반으로 테스트 설계를 수행한다.  
+TDD 사이클의 **RED** (실패 테스트)와 **VERIFY** (검증) 단계를 담당한다.
+
+# Responsibilities
+- 테스트 전략/계획 수립(범위, 기법, 환경, 데이터, 게이트)
+- AC 기반 테스트 케이스 설계, NFR 기반 비기능 테스트(성능/접근성/보안) 계획
+- 테스트 환경/데이터 관리, 실행 및 자동화 파이프라인 연계
+- 결함 리포팅(재현 절차/로그/우선순위) 및 트라이애지 주도
+- 품질 게이트 정의 및 릴리스 사전/사후 검증, 서명
+
+# Deliverables
+- Test Plan(전략/범위/환경/게이트)
+- Test Case Matrix(스토리/AC 매핑, 엣지/회귀 포함)
+- Test Execution Report 및 Release Sign-off
+
+# Input, Output
+| 구분 | 형식 | 경로 |
+|------|------|------|
+| **입력(Input)** | 기능 명세서 | `spec/stories/{feature}.md` |
+| **출력(Output)** | 검증 리포트 | `outputs/{feature}-qa-report.md` |
+
+# Interfaces
+- To Dev: 결함 리포트/재현 절차/우선순위 전달, 수정 확인
+- To PM: 품질 상태/AC 충족 여부 보고, 출시 리스크 공유
+- To CEO: 릴리스 권고 요약
+- From Architect: 테스트 가능성 관련 제약/리스크 인수
+
+# Reference
+# - 역할 분담은 BMAD-METHOD의 QA/품질 게이트 철학을 참조
+# - 테스트 코드 설계 시 kent beck testing 참고
+
+- .cursor/docs/testing-library-queries-priority.md
+- https://github.com/bmad-code-org/BMAD-METHOD/
+- .cursor/docs/kent-beck-testing.md
+
+## 최소 변경/영향 최소화 테스트 전략
+- 구현 변경을 강제하지 않는 테스트 작성(기존 공개 API/시그니처 유지)
+- 새로운 규칙을 드러내는 케이스만 추가하고, 기존 케이스와 충돌하지 않도록 구성
+- 겹침(overlap) 미검증 정책을 전제(겹침 관련 단언 금지)
+- .cursor/docs/tdd-document.md

.cursor/checklist/ceo-approval-checklist.md

@@ -0,0 +1,60 @@
+# 🧾 CEO 승인 체크리스트
+
+> Purpose: 각 에이전트의 1차 자체 점검 결과를 종합 검토하여 최종 승인/보류/반려를 결정합니다.
+
+---
+
+## 1️⃣ 산출물 수령 확인
+| 에이전트 | 산출물 | 링크/경로 | 자체 점검 결과 | 확인 |
+|---------|--------|-----------|----------------|------|
+| 테스트설계 | 테스트 시나리오 명세 · 체크리스트 | `.cursor/outputs/test-design-review.md` | ✅/⚠️ | ☐ |
+| 테스트코드 | 테스트 코드 · 커버리지 | `.cursor/outputs/test-code-review.md` | ✅/⚠️ | ☐ |
+| 코드작성 | 변경 코드 · 타입/상수 | `.cursor/outputs/code-implementation-review.md` | ✅/⚠️ | ☐ |
+| 리팩토링 | 변경 전/후 요약 · 회귀 목록 | `.cursor/outputs/refactoring-review.md` | ✅/⚠️ | ☐ |
+| 오케스트레이션 | 파이프라인 로그 · 링크 모음 | `.cursor/outputs/orchestration-review.md` | ✅/⚠️ | ☐ |
+
+---
+
+## 2️⃣ 품질 게이트
+| 항목 | 기준 | 증빙 | 통과 |
+|------|------|------|------|
+| 린트 | `pnpm lint` 경고/에러 0 | 로그 | ☐ |
+| 테스트 | `pnpm test` 전부 통과, 커버리지 목표 | 리포트 | ☐ |
+| 빌드 | `pnpm build` 성공 | 로그 | ☐ |
+
+---
+
+## 3️⃣ 도메인·규칙 준수
+| 항목 | 기준 | 통과 |
+|------|------|------|
+| 날짜/시간 | ISO/UTC/24시간, 윤년/월경계 | ☐ |
+| 반복 일정 | 종료일 제한, 31일/2월29일, 단일/전체 수정/삭제 | ☐ |
+| 접근성 | id/aria-label/시맨틱, Material-UI 패턴 | ☐ |
+| 타입 | any 금지, 명시적 타입, JSDoc | ☐ |
+| 아키텍처 | 훅/유틸/컴포넌트 경계 | ☐ |
+
+---
+
+## 4️⃣ 리스크 및 의사결정
+| 리스크 | 영향 | 대응 | 상태 |
+|--------|------|------|------|
+|  |  |  |  |
+
+---
+
+## 5️⃣ 최종 결정
+- 승인/보류/반려: 
+- 비고: 
+- 승인자: CEO 
+- 일자: 
+
+---
+
+## 📚 참고 문서
+- `.cursor/docs/tdd-document.md`
+- `.cursorrules`
+
+## 🧾 제출 지침
+- 최종 승인 결과는 `.cursor/outputs/ceo-approval.md`에 기록합니다.
+
+

.cursor/checklist/code-implementation-agent-checklist.md

@@ -0,0 +1,95 @@
+# 🧩 코드작성 에이전트 검증 체크리스트
+
+> Purpose: 테스트 주도 구현 시, 아키텍처·타입·접근성·성능·도메인 규칙을 준수했는지 검증합니다. (1차 자체 점검 → CEO 승인)
+
+---
+
+## 1️⃣ 요구사항 명확성
+| 번호 | 항목 | 설명 | 점검 |
+|------|------|------|------|
+| 1-1 | TDD 흐름 | 실패 테스트 → 최소 구현 → 리팩토링 순서 준수 | ☐ |
+| 1-2 | 도메인 적합 | 캘린더 용어/규칙(ISO/UTC/24시간/윤년/월경계) 반영 | ☐ |
+
+---
+
+## 2️⃣ 입력·출력 정의
+| 번호 | 항목 | 설명 | 점검 |
+|------|------|------|------|
+| 2-1 | 명시적 타입 | 인터페이스/유니온/반환 타입 명시, any 금지 | ☐ |
+| 2-2 | API I/O | 오류 처리/로딩 상태/사용자 피드백 일관 | ☐ |
+
+---
+
+## 3️⃣ 처리 로직 구체성
+| 번호 | 항목 | 설명 | 점검 |
+|------|------|------|------|
+| 3-1 | 관심사 분리 | 훅=로직, 유틸=순수함수, 컴포넌트=UI | ☐ |
+| 3-2 | 훅 패턴 | 객체 반환, 로딩/에러 상태, useCallback/useMemo 사용 | ☐ |
+| 3-3 | 유틸 품질 | 순수성, 명명된 상수, 50줄 이하, 중복 제거 | ☐ |
+| 3-4 | 반복 일정 | 종료일 제한, 31일/2월29일, 그룹 수정/삭제 처리 | ☐ |
+| 3-5 | 겹침/시간 검증 | 시작<종료, 겹침 탐지, 잘못된 조합 금지 | ☐ |
+
+---
+
+## 4️⃣ 에러 및 예외 처리
+| 번호 | 항목 | 설명 | 점검 |
+|------|------|------|------|
+| 4-1 | 사용자 피드백 | 폼 에러 헬퍼텍스트/다이얼로그, 접근성 속성 제공 | ☐ |
+| 4-2 | 로깅 | 개발 단계 콘솔/에러 로깅 기준 일관 | ☐ |
+
+---
+
+## 5️⃣ 테스트 기반성
+| 번호 | 항목 | 설명 | 점검 |
+|------|------|------|------|
+| 5-1 | 테스트 통과 | 신규/기존 테스트 모두 통과 | ☐ |
+| 5-2 | 커버리지 영향 | 의미 있는 라인 증가, 미달 사유 기록 | ☐ |
+
+---
+
+## 6️⃣ 문서 품질·코드 스타일
+| 번호 | 항목 | 설명 | 점검 |
+|------|------|------|------|
+| 6-1 | JSDoc | 복잡 함수에 JSDoc, 반환/파라미터 타입 기술 | ☐ |
+| 6-2 | ESLint/TS | 경고/에러 0, 엄격 TS 규칙 준수 | ☐ |
+| 6-3 | Import 순서 | 외부 → 내부(hooks/utils/types) 순서 | ☐ |
+
+---
+
+## 7️⃣ 성능·접근성
+| 번호 | 항목 | 설명 | 점검 |
+|------|------|------|------|
+| 7-1 | 렌더 최적화 | 불필요 리렌더 방지, 핸들러 useCallback | ☐ |
+| 7-2 | 접근성 | id/aria-label/시맨틱 요소, Material-UI 패턴 준수 | ☐ |
+
+---
+
+## 8️⃣ 프롬프트 품질
+| 번호 | 항목 | 설명 | 점검 |
+|------|------|------|------|
+| 8-1 | 산출물 명시 | 변경 파일, 타입 정의, 훅/유틸 경계 설명 | ☐ |
+| 8-2 | 금지사항 | 컴포넌트에 비즈니스 로직, any, 매직 넘버 금지 | ☐ |
+
+---
+
+## 📎 산출물
+- 변경된 소스 목록과 요약(아키텍처 영향 포함)
+- 타입/상수 추가 목록
+- 사용자 피드백(에러/로딩) 확인 캡처 또는 설명
+
+---
+
+## 📚 참고 문서
+- `.cursor/docs/tdd-document.md` — TDD 사이클과 구조/행동 커밋 분리
+- `.cursorrules` — 훅/유틸/컴포넌트 경계·접근성·타입·도메인 규칙
+
+## 🧾 제출 지침
+- 본 체크리스트로 1차 자체 점검 완료 후 결과 보고서를 다음 경로에 작성:
+  - `.cursor/outputs/code-implementation-review.md`
+- 보고서에는 다음을 포함:
+  - 변경 파일 목록과 영향 범위
+  - 규칙 준수 근거(코드 스니펫/라인 참조)
+  - 명령/로그: `pnpm lint`, `pnpm build`
+
+
+