implement

name	implement
description	요구사항을 마일스톤 단위로 분해하여 설계 문서 작성(D) → 코드 작성(A) → 아키텍처 검토(B) → 수정 루프를 오케스트레이션하는 스킬. 기능 구현, 리팩토링, UseCase 추가, 도메인 모델 변경 등 코드 작업이 필요한 모든 상황에서 사용한다. "구현해줘", "만들어줘", "추가해줘", "리팩토링", "implement", "/implement" 같은 요청에 이 스킬을 사용한다.

implement — 코드 작성 및 검토 오케스트레이션

사용자의 구현/리팩토링 요구사항을 마일스톤 단위로 분해하고, 각 마일스톤에 대해 기술설계 서브에이전트(D), 코드 작성 서브에이전트(A), 아키텍처 검토 서브에이전트(B) 를 오케스트레이션한다.

---

당신(메인 Claude)의 역할 — 오케스트레이터

주체	책임
당신 (메인 Claude)	요구사항 분석, 마일스톤 분할, D·A·B 위임, 반복 종료 판단, 사용자 보고
Agent D (subagent_type="design-writer")	마일스톤별 기술설계문서(TDD) 작성. write-tech-design-doc 스킬 사용
Agent A (subagent_type="code-writer")	Kotlin 코드 작성·수정, 테스트, 빌드 확인
Agent B (subagent_type="architecture-reviewer")	docs/backend/architecture/*·docs/backend/policies/* 준수 검토만. Read/Glob/Grep만 보유, 수정 권한 없음

에이전트 계약 문서 (입출력 규격의 단일 출처):

• D: references/design-writer-contract.md
• A: references/code-writer-contract.md
• B: references/architecture-reviewer-contract.md

절대 지켜야 할 제약

1. 당신은 파일을 직접 Read/Edit/Write 하지 않는다. 코드 작업은 전부 A에게, 설계 문서는 D에게 위임.
   • 예외: 사용자 요구사항 이해에 필요한 경우 docs/backend/README.md 같은 맵 문서 하나 정도 Read는 허용.
2. 당신은 검토를 직접 수행하지 않는다. 검토는 전부 B에게 위임.
3. D·A·B는 서로 호출하지 않는다. 모든 통신은 당신을 경유.
4. B 호출은 매번 새 인스턴스로 수행 (fresh context).
5. D 호출은 매번 새 인스턴스로 수행 (fresh context). A 호출은 마일스톤 첫 호출만 새 인스턴스로 수행. 같은 마일스톤 내 재호출(위반 수정, 체크포인트 재개)은 동일 인스턴스를 이어서 사용한다.

---

Phase 0: 요구사항 분석

1. 사용자 입력을 한 문장으로 재진술하여 이해 확인.

2. 애매하거나 중요한 정보가 누락되면 사용자에게 확인 질문 후 대기. 임의 추정하지 않음.

3. 사용자가 진행 중인 Uncommitted 작업을 언급하면, 새 작업과의 파일·도메인 충돌 가능성을 명시적으로 확인한다. 진행 방식(취소 작업 먼저 완료 / stash 후 재개 / 동시 진행)을 사용자에게 선택하게 한다.

4. 이전 실패 구현을 언급하면 (빌드 에러, 미완성 코드 등), 실패한 파일이 여전히 존재할 가능성을 확인하고 정리 방식(revert/stash/덮어쓰기)을 사용자에게 선택하게 한다.

5. 횡단 관심사 체크 — 요구사항에 아래 키워드나 패턴이 있으면 Phase 1에 반드시 반영한다:

   시그널	확인할 관심사
   개인정보·전화번호·주소·비밀번호·민감 데이터	인증·인가 처리 위치, 민감 정보 마스킹/노출 수준, 감사 로그 필요성
   이벤트 발행·알림·비동기·핸들러	트랜잭션 커밋 시점, 핸들러 실패·재처리 전략, 중복 이벤트 방지
   수백만 건·대량 데이터·통계·집계	N+1 쿼리 위험, 캐싱 전략, 인덱스, 배치·비동기 처리 필요성
   외부 PG·API 연동	재시도·타임아웃·멱등성·트랜잭션 경계
   DB 컬럼 추가·테이블 변경	마이그레이션 순서, 기존 데이터 호환성, 롤백 가능성
   API 추가·필드 변경	Swagger/OpenAPI 문서·하위 호환성
   여러 도메인 언급	도메인 간 의존 방향, 공유 객체 변경 파급 범위

   해당 항목이 있으면 Phase 1 마일스톤에 관련 설계·구현 단계를 포함시킨다. 별도 확인 질문 없이 합리적 가정을 명시하고 진행해도 된다.

6. 이해가 선명하면 Phase 1로.

7. .claude/checkpoints/ 하위에 1시간 이상 지난 디렉토리가 있으면 사용자에게 알린다:

   ⚠️ 이전 실행의 미완료 체크포인트가 있습니다: {run_id}
   선택: 1) 이어서 실행  2) 삭제 후 새로 시작
   

   사용자 응답 대기. 1번이면 해당 run_id를 재사용하고 Phase 2로 바로 진입. 2번이면 rm -rf .claude/checkpoints/{run_id} 후 Phase 1 진행.

Phase 1: 마일스톤 분할

분할 기준:

• 독립적으로 검토 가능한가 (B가 한 번에 의미 있는 검토 가능)
• 독립적으로 커밋 가능한가
• A의 컨텍스트가 감당 가능한가 (파일 10~15개 범위 권장)

규모별 기준:

• 경량 모드: 단일 파일·단일 식별자 변경(rename, typo fix, 상수 값 변경 등) → D와 B를 생략하고 A에게만 직접 위임. Phase 2에서 Step 2-3으로 바로 진입.
• 단일 CRUD / 단일 UseCase 추가 → 1 마일스톤
• 여러 도메인 걸친 기능 → 2~4 마일스톤
• 대규모 리팩토링 / 신규 서브시스템 → 5+ 마일스톤 (사용자에게 사전 확인)

각 마일스톤을 TaskCreate로 등록하고, 사용자에게 분할 결과 출력:

📋 마일스톤 계획 (각 마일스톤은 D(설계) → A(구현) → B(검토) 순서로 실행)
  M1/{total}: <제목>
  M2/{total}: <제목>
  ...

경량 모드일 경우:

📋 경량 모드 — D·B 생략, A 직접 위임
  M1/1: <제목>

규모가 크면 (5개 이상 마일스톤) 사용자에게 진행 여부 확인.

진행이 확정되면 즉시 Bash 도구로 아래 명령을 실행한다 (건너뛰지 않음):

run_id=$(date +%Y%m%d-%H%M) && mkdir -p ".claude/checkpoints/$run_id" && echo "$run_id"

출력된 값을 run_id로 보관한다. 이 단계를 생략하면 이후 모든 체크포인트 저장이 불가능하다.

---

Phase 2: 마일스톤별 순차 실행

각 마일스톤에 대해 아래 루프를 수행한다. iter는 해당 마일스톤의 A↔B 반복 횟수.

Step 2-1. 시작 알림

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 [M{n}/{total}] {마일스톤 제목} — 시작
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

해당 task를 TaskUpdate로 in_progress로 전환.

Step 2-2. Agent D 위임 (기술설계 문서 작성)

📝 기술설계 문서 작성 중... (Agent D)

Agent 도구 호출:

• subagent_type: design-writer
• description: [M{n}] 기술설계 문서 작성
• prompt: references/design-writer-contract.md — Input 섹션 형식으로 구성. 현재 마일스톤의 제목·요구사항·관련 레이어·도메인을 채운다. [체크포인트 파일] 필드에 .claude/checkpoints/{run_id}/design-writer-M{n}.md를 포함한다.

D의 응답을 받으면:

응답 첫 줄이 TDD_CREATED: 인 경우:

✅ TDD 작성 완료 · {tdd-path}

TDD 파일 경로와 설계 요약을 변수로 보관 (A에게 전달해야 함).

응답 첫 줄이 TDD_SKIPPED: 인 경우:

⏭️  TDD 스킵 · {reason}

→ Step 2-3으로.

Step 2-3. Agent A 위임 (코드 작성)

🔨 코드 작성 위임 중... (Agent A)

Agent 도구 호출:

• subagent_type: code-writer
• description: [M{n}] 코드 작성
• prompt: references/code-writer-contract.md — Input > Case A 형식으로 구성. 현재 마일스톤의 제목·요구사항·관련 레이어·도메인을 채우고, D 결과에 따라 [기술설계문서] 필드를 포함하거나 생략한다. [체크포인트 파일] 필드에 .claude/checkpoints/{run_id}/code-writer-M{n}.md를 포함한다.

A의 응답을 받으면:

✅ 코드 작성 완료 · 변경 파일 {N}개

변경 파일 목록을 변수로 보관 (B에게 전달해야 함).

Step 2-4. Agent B 위임 (아키텍처 검토)

🔍 아키텍처 규칙 검토 중... (Agent B, 시도 {iter}/5)

Agent 도구 호출:

• subagent_type: architecture-reviewer
• description: [M{n}] 규칙 검토
• prompt: references/architecture-reviewer-contract.md — Input 섹션 형식으로 구성. A가 반환한 변경 파일 목록과 핵심 설계 결정을 채운다. [체크포인트 파일] 필드에 .claude/checkpoints/{run_id}/arch-reviewer-M{n}-r{iter}.md를 포함한다. 레거시 패키지(레이어 구분 없는 기존 코드)에 작업을 추가하는 경우, B의 검토 범위를 이번에 새로 추가된 파일로 한정하고 기존 레거시 파일은 전달하지 않는다.

B의 응답을 받으면 아래 포맷으로 즉시 콘솔에 출력:

📋 검토 결과 (시도 {iter}/5):
  상태: ✅ PASS  또는  ⚠️ 위반 {K}건
  {위반이 있을 경우 각 항목을 한 줄씩 — 파일명 + 위반 규칙 요약}

B의 응답 처리:

• 응답이 PASS면 → Step 2-7으로 (마일스톤 완료)
• 위반 YAML이면 → Step 2-5로

Step 2-5. 위반 수정 위임 (A 재호출)

⚠️  위반 {K}건 발견 — 수정 적용 중... (Agent A, 시도 {iter}/5)

iter를 1 증가. iter > 5이면 Step 2-8 (escalation)로.

Agent 도구 호출:

• subagent_type: code-writer
• description: [M{n}] 위반 수정
• prompt: references/code-writer-contract.md — Input > Case B 형식으로 구성. B가 반환한 위반 YAML을 채운다. [체크포인트 파일] 필드에 .claude/checkpoints/{run_id}/code-writer-M{n}.md를 포함한다 (마일스톤 내 A 인스턴스를 이어 사용하므로 Case A와 동일 경로).

A의 응답을 받으면:

✅ 수정 완료 · 적용 {S}건 · 실패 {F}건

실패가 있으면 상세를 사용자에게 노출. → Step 2-6 (재검토).

Step 2-6. 재검토 (Step 2-4 반복)

🔍 재검토 중... (Agent B, 시도 {iter}/5)

Step 2-4와 동일한 B 위임. B의 응답을 받으면 Step 2-4와 동일한 포맷으로 콘솔에 출력한 뒤 처리:

• PASS → Step 2-7
• 위반 여전 → Step 2-5로 돌아가서 반복

Step 2-7. 마일스톤 완료

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 [M{n}/{total}] {제목} 완료 ({iter} 라운드)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

해당 task를 TaskUpdate로 completed로 전환. 다음 마일스톤으로.

Step 2-4.5. 설계 수준 위반 감지 (B 결과 처리 시)

B의 첫 번째 응답을 받았을 때, 위반 내용이 코드 수정이 아닌 설계 변경을 요구한다고 판단되면 A↔B 루프 진입 전에 사용자에게 알린다.

설계 수준 위반 시그널:

• "UseCase가 없음", "Controller가 Service를 직접 호출", "레이어 경계 위반이 구조적"
• "도메인 모델 부재", "Application 레이어 로직이 Domain에 있음"
• 수정 범위가 현재 마일스톤 범위를 초과하는 경우

⚠️ B 검토 결과 — 설계 수준 위반 감지

위반 요약: {B의 위반 설명}

이 위반은 단순 코드 수정으로 해결이 어렵습니다.
선택지:
  1. 이 마일스톤을 D(기술설계)부터 재시작 — TDD를 새로 작성 후 A→B
  2. 위반을 무시하고 A에게 수정 시도 (A↔B 루프 진입)
  3. 해당 마일스톤을 스킵하고 다음으로 진행

1번 선택 시 → Step 2-2로 돌아가 D를 새 인스턴스로 재호출.

Step 2-8. Escalation (5회 초과 시)

⛔ [M{n}] 자동 수렴 실패 — A↔B 루프 5회 초과

마지막 검토 결과 요약:
{B의 마지막 응답 요약 3~5줄}

선택지:
  1. 현재 상태로 커밋하고 수동 검토
  2. 메인 Claude가 직접 개입하여 수정
  3. D(기술설계)부터 재시작 — TDD를 새로 작성 후 A→B 재시도
  4. 요구사항을 재정의하고 해당 마일스톤 재시작
  5. 해당 마일스톤을 스킵하고 다음으로 진행
  6. 전체 중단

사용자 선택 대기. 사용자 응답에 따라 처리:

• 1, 2, 3, 4, 5, 6 각각에 맞는 후속 흐름 실행.
• 2번 선택 시에만 메인 Claude가 직접 Edit (이 경우에 한해 예외적으로 허용).
• 3번 선택 시 → Step 2-2로 돌아가 D를 새 인스턴스로 재호출.

---

Phase 3: 전체 완료 보고

모든 마일스톤이 완료되면 체크포인트 디렉토리를 정리한 뒤 최종 요약:

rm -rf .claude/checkpoints/{run_id}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✨ 구현 완료

마일스톤: {완료}/{총}
총 A↔B 라운드: {합계}
마일스톤별 라운드: M1={r1}, M2={r2}, ...

변경 파일 총 {N}개. 다음 단계 제안:
  1. `smart-commit` 스킬로 마일스톤 단위 커밋 그룹핑
  2. 또는 바로 커밋 작성
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

문서 업데이트 체크 — 아래 항목 중 해당 사항이 있으면 사용자에게 알린다:

변경 유형	업데이트 필요 문서
API 엔드포인트 추가·변경·삭제	Swagger/OpenAPI 명세, API 클라이언트 가이드
도메인 모델·DB 스키마 변경	ERD, 데이터 사전
외부 연동 추가	연동 명세서, 운영 매뉴얼
인증·인가 정책 변경	보안 정책 문서
성능 관련 인프라 변경 (캐싱, 인덱스, 배치)	운영 가이드, 모니터링 체크리스트

---

요약 — 한 번에 보기

[Phase 0] 요구 분석 → 불명확하면 사용자 확인
          Uncommitted 작업 / 이전 실패 구현 언급 시 정리 방식 확인
          횡단 관심사 체크 (보안·이벤트·성능·외부API·DB·문서·도메인 경계)
[Phase 1] 마일스톤 분할 → TaskCreate
          경량 모드(rename/typo) → D·B 생략, A 직접
[Phase 2] 각 M마다:
    D 위임(설계) →
      TDD_CREATED → A 위임(구현, TDD 참조) → B 위임(검토)
      TDD_SKIPPED → A 위임(구현)            → B 위임(검토)
        B 첫 결과가 설계 수준 위반 → 사용자에게 D 재시작 여부 확인
        PASS  → 다음 M
        위반  → A 위임(수정) → B 재검토 → ... (max 5 iter)
        5회↑ → 사용자 escalate (D 재시작 포함 6가지 선택지)
    (레거시 패키지 작업 시 B에 새 파일만 전달)
[Phase 3] 완료 보고 → 커밋 제안 → 문서 업데이트 체크