milestone-execute

name	milestone-execute
description	마일스톤 다음 단계 실행. milestone.md의 미완료 Phase를 기준 문서와 코드베이스 컨텍스트 기반으로 구현한다. "다음 작업", "마일스톤 실행", "Phase 진행" 등의 요청 시 사용

워크플로우: 마일스톤 Phase 실행

목표: milestone.md에서 다음 미완료 Phase를 식별하고, 해당 Phase와 연결된 기준 문서 및 코드베이스를 참고하여 실제 코드를 구현합니다.

1단계: 컨텍스트 로드

프로젝트 루트에서 다음 정보를 읽습니다:

1. milestone.md — 작업 목록 및 진행 상태 (필수)
2. 사용자 메시지에서 지정한 기준 문서 (선택)
3. milestone.md 상단의 기반 문서 목록 (선택)
4. 구현 대상과 관련된 코드/테스트/설정 파일 (선택)

• milestone.md가 없으면 milestone 스킬을 먼저 실행하도록 안내합니다.
• 기준 문서가 없더라도 milestone 항목의 목표/검증이 충분하면 실행을 계속합니다.
• 구현 방향이 모호하면 필요한 정보만 최소 질문으로 확인합니다.

2단계: 대상 Phase 판별

• 인자로 Phase 번호가 주어진 경우: 해당 Phase를 대상으로 선택합니다.
• 인자가 없는 경우: milestone.md에서 첫 번째 미완료([ ]) 항목이 포함된 Phase를 자동 선택합니다.
• 모든 Phase가 완료된 경우: 사용자에게 "모든 마일스톤이 완료되었습니다"를 알리고 종료합니다.

선택된 Phase와 포함된 작업 항목들을 사용자에게 보여주고 진행 여부를 확인합니다.

3단계: 태스크 리스트 생성

해당 Phase의 미완료 체크박스 항목들을 내부 태스크 리스트로 등록합니다.

• subject: 체크박스의 볼드 텍스트 (작업 제목)
• description: 해당 항목의 목표/포함 내용/검증 기준 + 기준 문서에서 관련 근거 + 예상 코드 영향 범위
• activeForm: 작업 제목의 현재진행형 (예: "조건부 서식 데이터 모델 구현" → "조건부 서식 데이터 모델 구현 중")

이미 완료([x])된 항목은 건너뜁니다.

4단계: 구현 실행 (병렬+순차 하이브리드)

4-A: 의존성 분석

Phase의 모든 미완료 태스크를 검토하여 실행 그래프(Layer)를 생성합니다.

의존 관계 판정 기준:

관계	판정	근거
같은 파일 수정	순차	동시 수정 시 충돌
export → import 관계	순차	선행 타입/함수가 있어야 후행 구현 가능
다른 디렉토리, 독립 기능	병렬	충돌 없음
공통 컨텍스트만 참조 (읽기 전용)	병렬	충돌 없음

Layer 생성 예시:

Layer 1: [Task A, Task B]  ← 독립적, 병렬 실행
Layer 2: [Task C]           ← Task A의 export를 import
Layer 3: [Task D, Task E]  ← Task C 완료 후 독립적, 병렬 실행

각 태스크에 선행/후행 관계를 명시하여 의존성을 기록합니다.

4-B: 작업 성격별 전문성 매핑

각 태스크의 성격에 따라 적절한 관점으로 실행합니다:

태스크 성격	권장 전문성	판단 기준
React 컴포넌트 UI 구현	프런트엔드 구현 관점	JSX, 스타일, 이벤트 핸들링
타입 정의, 제네릭, 유틸리티 타입	TypeScript 설계 관점	type, interface, 제네릭 제약
API 로직, 비즈니스 로직, 훅	애플리케이션 로직 관점	데이터 처리, 상태 관리
복잡한 아키텍처 결정 포함	아키텍처 리뷰 관점	설계 판단이 필요한 경우
보일러플레이트, 설정 파일	실용적 구현 관점	단순 반복 작업

4-C: 병렬+순차 하이브리드 실행

Layer별로 실행합니다:

Layer 내 (병렬):

• 독립 태스크들은 병렬로 동시 실행합니다.
• 각 태스크에 전달할 정보:
  • 해당 태스크의 description (목표, 구현 상세, 검증 기준)
  • 기준 문서의 관련 섹션 요약
  • 준수 사항 (AGENTS.md 패턴, FSD 원칙, 기존 코드 컨벤션)

Layer 간 (순차):

• 선행 Layer의 모든 태스크 완료 확인 후 다음 Layer 실행
• 각 Layer 완료 시 중간 검증 실행:

  pnpm typecheck
  

• typecheck 실패 시: 오류를 분석하고 수정한 후 다음 Layer로 진행

단일 태스크 또는 순차 의존만 있는 경우:

• 오케스트레이터가 직접 순차 구현 (기존 방식 유지)

각 태스크 완료 시 내부 태스크 리스트에서 상태를 completed로 갱신합니다.

컨텍스트 관리 규칙

• 각 태스크에서 필요한 파일만 로드하고, 무관한 문서는 불필요하게 확장하지 않습니다.
• 긴 문서는 먼저 핵심 요구/제약/검증만 요약해 태스크 컨텍스트를 압축합니다.
• 컨텍스트가 비대해지면 중간 요약을 갱신한 뒤 다음 태스크로 진행합니다.

구현 시 준수 사항

• AGENTS.md의 아키텍처 패턴 및 디렉토리 구조를 따릅니다.
• FSD 원칙을 준수합니다.
• 기존 코드베이스의 패턴과 컨벤션을 따릅니다.
• 보안 취약점을 도입하지 않습니다.

5단계: 검증

각 작업 항목의 "검증" 기준을 우선 적용해 검증을 수행합니다.

• pnpm run typecheck — 타입 검사
• pnpm run lint — 린트 검사
• pnpm run test:unit — 관련 단위 테스트 실행 (테스트가 있는 경우)

검증 실패 시:

1. 오류를 분석하고 수정합니다.
2. 수정 후 다시 검증합니다.
3. 반복적으로 실패하면 사용자에게 보고하고 판단을 요청합니다.

6단계: 마일스톤 업데이트

모든 작업이 완료되면 milestone-update 스킬을 호출하여:

• 완료된 체크박스를 [x]로 업데이트합니다.
• 세션 노트에 구현 요약을 추가합니다.

7단계: 결과 보고

실행 결과를 사용자에게 보고합니다:

• 완료된 Phase 번호 및 제목
• 구현된 작업 항목 목록
• 실행 방식 요약 (병렬 Layer 수, 적용한 전문성 관점)
• 검증 결과
• 다음 미완료 Phase 안내 (있는 경우)