Claude Code로 TDD 구현 ― tsumiki의 dev-impl 스킬
機械翻訳 / Machine-translated
cccskills
1日前・11分で読める
機械翻訳 / Machine-translated
원문: Claude Code로 TDD 구현 ― tsumiki의 dev-impl 스킬（cccskills）
스킬 페이지: dev-impl
이 글의 결론
tsumiki의 dev-impl을 도입하면, Claude Code 등의 에이전트가 먼저 테스트를 작성하고 실패하는지 확인합니다.
그 이후에 테스트가 통과하도록 구현을 진행하는 흐름입니다.
이 글에서는 계획에 따라 진행하는 일반 모드와, 직접 지시하는 퀵 모드의 차이를 설명합니다.
설치 방법과 의뢰문 예시, 사용 전에 알아두어야 할 전제 조건도 함께 정리했습니다.
계획된 작업을 지정하면 dev-impl은 테스트를 작성하고 실패를 확인한 후 구현에 들어갑니다.
의뢰문은 예를 들어 다음과 같습니다.
/dev-impl auth 001
에이전트는 먼저 docs/dev/context.md와 작업 파일을 읽습니다.
다음으로, 작업에 기재된 테스트 방침에서 테스트 코드를 작성하고, 실행하여 실패(Red)를 확인합니다.
그 위에 테스트를 통과하는 최소한의 구현을 작성하고, 성공(Green)을 확인하는 흐름입니다.
테스트가 통과한 후에는 파일의 줄 수, 보안, 성능, 커버리지를 점검합니다.
마지막으로 반환되는 것이 「확신도 리포트」입니다.
리포트에는 패키지별 커버리지와 임계값, 구현된 파일별 확인 필요도가 나열됩니다.
함께, 작업 파일의 상태가 done으로 업데이트됩니다.
dev-impl은 classmethod가 공개하는 tsumiki에 포함된 구현용 스킬입니다.
TDD(테스트를 먼저 작성한 후 구현하는 개발 방법론)를 가드레일로 삼고 있습니다.
테스트가 통과하기 전에 다음 단계로 나아가지 않는 것이, 이 스킬의 기본 규칙입니다.
모드는 2가지이며, 전달하는 인수의 형태로 전환됩니다.
| 모드 | 호출 방법 | 적합한 작업 |
|---|---|---|
| 일반 모드 | /dev-impl <plan-name> <task-id> | 계획(Plan)에 있는 작업을 하나 구현한다 |
| 퀵 모드 | /dev-impl "수정 지시" | 소규모 버그 수정, 기존 테스트에 케이스 추가, 가벼운 리팩터링 |
일반 모드는 tsumiki의 개발 흐름에서 계획 다음에 오는 공정입니다.
dev-context로 프로젝트를 분석하고, dev-plan으로 작업을 나눈 후, dev-impl로 작업을 하나씩 구현합니다.
검증은 dev-verify, 실패 시 조사는 dev-debug가 담당합니다.
퀵 모드는 Plan이 필요하지 않습니다.
관련 파일을 서브 에이전트로 찾고, 테스트와 구현을 수정한 후 테스트를 실행하여 확인합니다.
500줄 규칙 확인과 간결한 리포트도 포함됩니다.
테스트가 Green이 된 후에 수행하는 점검은 매번 동일한 항목입니다.
판단의 우선순위는 「품질 > 속도 > 토큰 소비」로 정해져 있습니다.
생성한 public 함수와 메서드에는 모두 「Intent 주석」이 붙습니다.
이 주석은 설계 판단의 근거가 어디에 있는지를 신호등과 같은 3단계로 나타내는 것입니다.
| 신호 | 의미 | 리뷰에서의 취급 |
|---|---|---|
| 파랑 | 작업 파일이나 context.md에서 명시된 판단 | 우선도 낮음 |
| 노랑 | 지시에서 추론한 타당한 판단 | 요확인 |
| 빨강 | 이전 공정에 근거가 없어 AI가 보완한 판단 | 사람의 확인 필수 |
보안과 성능에서 빨강이 붙은 문제는 수정 후 완료됩니다.
확신도 리포트에서도 파일이 동일한 3단계로 나뉘어 표시됩니다.
테스트와 구현의 진행 방식은 작업 파일에 기재된 복잡도에 따라 달라지는 구조입니다.
| 복잡도 | 진행 방식 |
|---|---|
| low | 테스트와 구현을 일괄로 작성하고, 테스트 실행으로 검증한다 |
| medium | 테스트, Red 확인, 구현, Green 확인의 순서로 진행한다 |
| high | 테스트를 하나씩 추가하고, 하나씩 Green으로 만든다 |
명령어 한 줄로 설치할 수 있습니다.
실행 시에는 Claude Code나 Codex 등 설치할 에이전트를 선택할 수 있습니다.
npx skills add https://github.com/classmethod/tsumiki --skill dev-impl
에이전트에게 설치해 달라고 하는 경우, 다음 내용을 그대로 전송해 주세요.
次の Agent Skill をインストールしてください。
https://github.com/classmethod/tsumiki/tree/main/skills/dev-impl
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/dev-impl/、Codex なら ~/.agents/skills/dev-impl/ に配置してください。
설치 위치는 모든 프로젝트에서 사용할지, 특정 프로젝트에서만 사용할지에 따라 선택합니다.
| 에이전트 | 모든 프로젝트에서 사용 | 특정 프로젝트에서만 사용 |
|---|---|---|
| Claude Code | ~/.claude/skills/dev-impl/ | 프로젝트의 .claude/skills/dev-impl/ |
| Codex | ~/.agents/skills/dev-impl/ | 프로젝트의 .agents/skills/dev-impl/ |
전체 리포지토리는 classmethod/tsumiki에서 확인할 수 있습니다.
호출에 사용할 수 있는 표현은 「작업을 구현」「테스트 퍼스트 구현」「구현을 시작」「퀵 수정」「quick fix」 등입니다.
dev-impl auth 001 로, 인증 플랜의 작업 001을 테스트 퍼스트로 구현해 주세요.
이 의뢰는 일반 모드입니다.
먼저 의존하는 작업이 모두 done인지 확인합니다.
그 이후 테스트 작성, Red 확인, 구현, Green 확인, 점검의 순서로 진행합니다.
마지막에 확신도 리포트가 반환되고, 작업 상태가 done이 됩니다.
quick fix: 로그인 폼에서 이메일 주소 앞뒤의 공백을 제거한 후 검증하도록 수정해 주세요.
이쪽은 퀵 모드입니다.
관련 파일을 찾아 테스트와 구현을 수정하고, 테스트를 실행하여 결과를 확인합니다.
반환되는 것은 간결한 리포트입니다.
퀵 수정으로, 기존 테스트에 페이지 번호가 0일 때의 케이스를 추가해 주세요.
이것도 퀵 모드 의뢰입니다.
기존 테스트에 케이스 추가는 이 모드의 용도에 포함됩니다.
추가한 테스트가 통과하도록 구현도 조정하고, 실행 결과를 보고합니다.
dev-impl은 단독으로는 완결되지 않으며, tsumiki의 다른 스킬이 생성하는 파일을 전제로 합니다.
도입 전에 다음 사항을 확인해 주세요.
라이선스는 MIT입니다.
첨부 파일은 SKILL.md와 references/impl-strategies.md 두 개뿐이므로, 도입 전에 내용을 읽어두면 안심할 수 있습니다.
dev-impl의 전후에 사용하는 스킬은 동일한 tsumiki 리포지토리에 갖추어져 있습니다.
dev-context는 기술 스택, 테스트 프레임워크, 코딩 규약을 분석하여 프로젝트의 컨텍스트를 생성합니다.
dev-impl이 읽는 context.md를 준비하는 공정입니다.
dev-plan은 요건에서 구현 계획을 만들어 작업으로 나눕니다.
일반 모드에서 지정하는 Plan과 작업은 여기서 만드는 것입니다.
dev-debug는 테스트 실패나 빌드 에러를 다루는 스킬입니다.
dev-impl로 3번 수정해도 테스트가 통과하지 않을 때 안내됩니다.
퀵 모드라면 Plan도 작업 파일도 필요하지 않습니다.
/dev-impl "수정 지시"의 형태로 직접 의뢰할 수 있습니다.
단, context.md가 없으면 dev-context를 안내받으므로, 미리 만들어 두면 진행이 빨라집니다.
오류를 분석하여 수정하는 사이클은 최대 3회까지입니다.
그래도 해결되지 않으면 dev-debug를 사용하도록 안내됩니다.
설치 명령어에서는 설치할 대상으로 Codex를 선택할 수 있습니다.
단, 절차에는 TodoWrite나 서브 에이전트의 모델 지정 등 Claude Code 전용 기능명이 포함되어 있습니다.
관련 파일이 500줄을 초과하면 책임 경계로 분할하는 규칙입니다.
테스트 파일도 함께 나누고, 분할 후 테스트를 재실행하여 성공을 확인합니다.
dev-impl은 테스트를 먼저 작성하는 습관을 AI와의 개발에 도입하는 스킬입니다.
계획된 작업은 일반 모드로, 소규모 수정은 퀵 모드로 진행합니다.
어느 모드든 테스트 실행 결과를 확인한 후 완료됩니다.
마지막에 반환되는 것은 근거의 강도를 3단계로 나타낸 리포트입니다.
자세한 정보는 cccskills 페이지에서 확인할 수 있습니다.
이 글은 cccskills의 읽을거리 「Claude Code로 TDD 구현 ― tsumiki의 dev-impl 스킬」의 전재입니다.
스킬의 상세 내용과 설치 방법은 cccskills의 dev-impl 페이지에 있습니다.