source-command-implement

name	source-command-implement
description	tasks/테스트 기반으로 기능을 구현하고, 전문 에이전트 병렬 자체 검증으로 자기완결한다. 빌드·커밋 안 함.

source-command-implement

Use this skill when the user asks to run the migrated source command implement.

Command Template

/feature 설계와 /tdd 테스트가 준비된 뒤 실제 구현을 수행하는 단계 전용 스킬. tdd.md가 비워둔 "(구현 단계는 일반 대화로 — 별도 스킬 없음)" 공백을 채운다.

핵심 구조: 구현 본체는 메인 스레드 단일 실행(병렬 writer 간 파일 충돌·불일치 방지)이고, 병렬은 ① 구현 전 조사(Explore 병렬)와 ② 구현 후 자체 검증(전문 에이전트 병렬) 두 군데에만 쓴다.

자체 검증(영역별 4관점) → 수정 후, CTO 에이전트가 통합·아키텍처 관점의 최종 게이트를 한 번 더 거쳐 자기완결한다. 발견한 🔴/🟡는 이 스킬이 직접 수정한다. 그 뒤 /code-review·/tdd regression 같은 전문 검증은 사용자가 별도 이터레이션으로 돌린다 — 자동 제안하지 않는다.

사용

• /implement — 직전 컨텍스트(방금 끝낸 /feature 산출물 또는 /tdd로 박은 red 테스트)에서 대상 자동 판단.
• /implement <slug 또는 설명> — 대상 명시. 예: /implement 30s-replay, /implement notion 페이지 ID 파서.
• /implement <slug> task N — 특정 태스크만.

다른 스킬과의 분리

• /feature — 설계 문서만. 코드 안 건드림.
• /tdd — 테스트 파일만. 구현 안 함.
• /implement ← 여기. 구현 + 자체 검증 + 자체 발견 수정. 빌드·커밋 안 함.
• /code-review — 변경분 정적 리뷰 리포트. 별도 이터레이션, 사용자가 호출.
• /build — 빌드 + 수동 테스트 체크리스트.
• /push — 푸시 + 문서 신선도.

절차

1. 대상·범위 결정

• 인자 또는 직전 컨텍스트에서 구현 대상 확정.
  • /feature 산출물이면 docs/features/<slug>/tasks.md를 읽어 태스크·검증 항목·구현 순서를 파악.
  • /tdd red 테스트면 그 테스트 파일을 green으로 만드는 게 목표 — 시그니처는 테스트가 이미 결정.
  • 자연어 설명이면 영향 영역을 스스로 정의.
• tasks.md가 있으면 그 안의 "검증" 체크박스와 "테스트 계획"을 이번 구현의 완료 기준으로 채택한다.
• 멀티 태스크면 TaskCreate로 태스크 목록을 만들어 진행 추적. 단계마다 완료 즉시 마킹.

2. 구현 전 조사 (Explore 병렬)

구현에 손대기 전, 영향 영역의 기존 패턴·참조 파일을 병렬로 수집한다. 여기서만 병렬을 쓰는 이유: 조사는 read-only라 충돌이 없다.

영역별로 Explore 에이전트를 동시에 띄워 각각:

• 변경 대상과 같은 역할의 기존 구현 경로·시그니처 (패턴 복제용)
• 건드릴 타입·메시지·store 키의 현재 정의와 사용처
• 관련 AGENTS.md / docs/ARCHITECTURE.md 제약 (해당 영역만)

대상이 한 파일·한 영역에 집중되면 Explore 없이 직접 Read해도 무방.

착수 전 회고 조회 (메인, 값싸다). Explore와 병행해, 변경 대상 파일·영역 키워드로 docs/POSTMORTEM.md를 grep한다 — 이 파일은 같은 자리에서 반복해 터진 버그의 재발 방지 신호(grep 패턴·file:func)를 담는다. 매칭 항목의 증상·근본 원인·재발 방지를 읽고, 이번 구현이 그 함정을 다시 밟지 않는지 구현 중 체크리스트로 삼는다. 매칭 0이면 한 줄로 넘어간다.

grep -ni -e '<변경 파일명>' -e '<영역 키워드>' docs/POSTMORTEM.md

예: StyleCssView·CSS 뷰 변경이면 -e StyleCssView -e 'CSS 뷰' -e cross-origin. (영역 키워드는 회고 제목의 반복어 — cross-origin·picker·slack·i18n·마이그레이션·user gesture·capture 등.)

3. 구현 (메인 스레드 단일)

조사 결과를 손에 쥔 채 메인 스레드에서 순차 구현한다. 서브에이전트에게 쓰기 작업을 넘기지 않는다 (여러 에이전트가 src/store·src/types·src/sidepanel을 동시에 고치면 edit 경합·상태 불일치).

• tasks.md의 구현 순서 권장을 따르되, 의존 관계가 분명하면 재정렬 OK.
• 기존 패턴을 복제한다 — size·variant·className·구조·에러 처리 방식을 같은 역할의 기존 코드와 일치시킨다.
• 외과적: 요청·tasks 범위 밖 인접 코드 리팩터 금지. 기존 dead code는 건드리지 않는다 (내 변경이 만든 고아만 제거).
• 최소 구현: tasks를 충족하는 가장 단순한 구조. 요청 안 한 유연성·설정·미래 대비 추상화 금지.
• 주석 최소화: src/components/ui/ 이외엔 WHY가 비자명할 때만 한 줄.
• 경로: @/ → src/.
• UI: 직접 스타일링 금지 — shadcn/ui 우선, 없으면 설치 필요를 보고에 명시(설치 자체는 사용자 판단). Tailwind는 shadcn CSS 변수. CTA 버튼은 default(h-9) 통일, xl은 랜딩/온보딩 전용. IconButton은 패널/헤더 h-8 w-8, Input·Textarea 우측 직결만 h-9 w-9. 탭 컨텐츠는 data-[state=inactive]:hidden.
• bugshot 특유의 동시 갱신 지점을 한 번에 맞춘다:
  • 새 메시지 타입 → BgRequest union + handler + BG_REQUEST_TYPES Set 3곳 동시.
  • 사용자 노출 텍스트 → i18n ko/en 동시.
  • 새 store 키 → session-keys 상수 + 마이그레이션 체인.
  • 플랫폼 어댑터 변경 → 다른 플랫폼과 패턴 대칭 유지.

4. 테스트 green 확인

• /tdd로 박은 테스트가 있으면 pnpm test --run <테스트파일>로 red → green 전환 확인.
• tasks.md "테스트 계획"의 단위 테스트 대상이 있는데 테스트가 아직 없으면, 해당 순수 함수의 테스트를 작성하고 통과 확인 (AGENTS.md "테스트 우선" 원칙 — 테스트 없이 코드만 변경하지 않는다).
  • 위치: 대상과 같은 디렉터리의 __tests__/*.test.ts. 도구: Vitest. 기존 파일에 케이스 추가가 자연스러우면 신규 생성 금지.
• 마지막에 pnpm test --run 전체 통과 + pnpm typecheck 통과 확인.
• pnpm build는 돌리지 않는다 (빌드는 /build·명시 요청 전용).

5. 자체 검증 (전문 에이전트 병렬)

구현이 끝나면 이번 변경분을 전문 에이전트 병렬로 검증한다. /code-review와 같은 4관점을 쓰되, 결정적 차이는 구현 맥락을 함께 전달한다는 점 — 외부 시각의 사후 리뷰가 아니라 "방금 이 tasks/테스트를 보고 구현했는데 의도대로 됐나"를 본다.

base: git diff (working tree, 아직 미커밋). 변경 영역에 해당하는 에이전트만 활성화.

키워드	관점	핵심
ui	UI/UX·i18n	shadcn/ui, 버튼 사이즈(default/xl), IconButton(h-8/h-9), Tailwind 변수, data-[state=inactive]:hidden, ko/en 대칭, 같은 역할 패턴 일치
security	인증·MV3	OAuth proxy 경유, 토큰 갱신, user gesture 보존, MAIN world self-contained, env 가드
dataflow	세션·picker·이슈	editor:${tabId} 키, phase별 보존 룰, 섹션 구성, 토큰 resolve, 마이그레이션 멱등성, 메시지 union 3곳 일치
codehealth	스타일·품질	@/ 경로, 주석 최소화, 데드 코드, 불필요한 추상화·shim, race condition

각 검증 에이전트(subagent_type: general-purpose)에게 전달:

• 이번 git diff 중 자기 영역 변경 파일
• 구현 의도: tasks.md의 해당 태스크 + "검증" 체크 항목 (= 통과해야 할 기준)
• 패턴 비교용 참조 파일 경로 (3단계 조사에서 확보한 것)
• 체크 가이드(위 표) + 공통 원칙(더 단순한 방법·외과적 변경·패턴 일관성)

에이전트는 파일:줄 — 요약 (근거) + 시급도(🔴/🟡/⚪)로 보고. 변경이 한 영역에 집중되면 단일 에이전트로 충분.

6. 자체 발견 수정 (자기완결 루프)

검증 결과를 시급도로 처리:

• 🔴 심각(동작 깨짐·데이터 손실·보안·게이트 위반) — 즉시 수정.
• 🟡 권장(컨벤션 위반·회귀 위험·일관성 깨짐) — 즉시 수정.
• ⚪ 사소(스타일·취향) — 수정 안 하고 보고만. 사용자 판단에 맡긴다.

수정 후 4단계 테스트·typecheck를 재실행해 green 유지 확인. 새 🔴/🟡가 또 나오면 한 번 더 루프 (최대 2회 — 이후엔 남은 항목을 보고하고 종료, 무한 루프 금지).

7. CTO 최종 게이트 (통합 리뷰 + 수정)

영역별 4관점이 각자 자기 구역만 보느라 놓치는 크로스-커팅 이슈를 단일 CTO 에이전트가 총괄 점검한다. /feature-review의 CTO 관점을 구현 결과물에 맞춰 차용.

CTO 에이전트(subagent_type: general-purpose, "CTO" 페르소나)에게 전달:

• 5·6단계를 거친 현재 git diff 전체 (4관점 수정이 반영된 상태)
• tasks.md + (있으면) design.md의 설계 의도·대안 검토·위험 요소
• 4관점 검증에서 나온 발견·수정 요약 (중복 점검 방지)

CTO가 보는 것 (영역별 세부 체크는 반복하지 않는다 — 5단계에서 이미 끝남):

• 아키텍처 정합성: 변경이 store·message·adapter 패턴과 전체적으로 맞물리는가. 한 곳만 고치고 대칭 짝을 빠뜨리지 않았나 (어댑터·union·i18n 짝).
• 설계 의도 부합: design.md/tasks.md가 의도한 접근으로 구현됐나. 도중에 더 복잡한 우회로로 샜는가.
• 오버엔지니어링: 요청 안 한 유연성·추상화·shim이 끼었나. 더 단순한 구조가 가능한가.
• 통합 위험: 기존 플로우 회귀, user gesture 체인, 마이그레이션 멱등성 등 영역을 가로지르는 위험.

CTO는 파일:줄 — 요약 (근거) + 시급도로 보고만 한다 (쓰기는 메인 스레드만). 메인 스레드가 🔴/🟡를 수정하고 ⚪는 보고에 남긴 뒤, 4단계 테스트·typecheck를 재확인한다. 변경이 작거나 4관점에서 통합 이슈가 이미 정리됐으면 CTO 게이트는 "이슈 없음" 한 줄로 통과해도 무방.

8. tasks.md 갱신 + 보고 + 종료

구현 대상에 docs/features/<slug>/tasks.md가 있으면, 이번 구현으로 실제 충족한 태스크·검증 체크박스를 [x]로 갱신한다 (통과 확인된 것만 — 미충족은 [ ] 유지). tasks.md가 없으면 스킵. (파일 편집만 — 커밋은 안 한다.)

대상: <slug 또는 설명>
구현 태스크: <N개 완료 / tasks.md 기준>

변경 파일:
- <경로> — <한 줄 요약>
...

자체 검증(4관점): <활성 에이전트> / 발견 🔴 X · 🟡 Y · ⚪ Z
- 수정함: <🔴/🟡 항목 한 줄씩>
- 미수정(⚪): <항목 한 줄씩 — 사용자 판단>

CTO 최종 게이트: 이슈 없음 / 발견 🔴 X · 🟡 Y · ⚪ Z
- 수정함: <항목 한 줄씩>

테스트: pnpm test 전체 green (N tests) / typecheck 통과
tasks.md 검증 항목: <충족 / 미충족 — 이유>
가이드 영향: <없음 / 갱신 필요 ⚠️ — 대상 guide 페이지(ko·en). `/guide`로 처리 권장>
e2e 영향: <없음 / 시나리오 추가·갱신 필요 ⚠️ — 대상 spec. `/e2e-write`로 처리>

• 이번 구현이 사용자 노출 UX·기능을 바꿨으면(새 버튼·라벨·플로우·설정·캡처/로그 동작 등) 보고의 "가이드 영향"에 갱신 대상 guide 페이지(ko·en)를 명시한다. tasks.md에 "가이드 영향" 항목이 있으면 그걸 그대로 채택. 실제 가이드 작성은 하지 않는다 — 플래그만 남긴다(가이드 작성은 /guide 전용, AUTHORING.md 규칙 적용).
• 이번 구현이 e2e 시나리오로 판정 가능한 플로우를 추가·변경했으면(tasks.md "e2e 시나리오" 항목 포함) 보고의 "e2e 영향"에 대상 spec을 명시한다. 실제 spec 작성은 하지 않는다 — 플래그만 남긴다(spec 작성·green은 /e2e-write 전용 — 실행-수정 루프가 필요).
• 보고 후 종료. 빌드·커밋·푸시 안 함.
• /code-review·/tdd regression 등 후속 스킬을 자동 제안·실행하지 않는다. 추가 검증 이터레이션은 사용자가 직접 시작한다.

금지 사항

• 서브에이전트로 쓰기 작업 위임 금지 — 구현 본체는 메인 스레드만. 병렬은 조사(Explore)·검증(general-purpose)에만.
• 빌드·커밋·푸시 금지 — pnpm build 안 돌리고, staging·commit 안 한다.
• 범위 밖 리팩터 금지 — tasks/요청과 무관한 인접 코드 개선 섞지 않는다.
• ⚪ 사소 항목 임의 수정 금지 — 보고만. 수정은 사용자 판단.
• 후속 스킬 자동 제안 금지 — "이제 /code-review 돌릴까요?" 금지.
• 테스트 없이 종료 금지 — 순수 함수 변경 시 관련 테스트 통과 확인이 완료 조건.
• 무한 검증 루프 금지 — 수정 루프 최대 2회. 남으면 보고하고 종료.