데일리 밥

Agent Skills /build 와 /test 쓰는 법 — 한 조각씩 만들고 테스트로 증명하기 [4/6]

Daily BaapIT/전자기기

계획까지는 세웠는데, 「시작해」라고 하면 Claude Code 가 파일 열 개를 한 번에 갈아엎고 「다 됐습니다」라고 하는 게 불안하신가요?

Agent Skills 의 /build 는 계획의 작업 하나만 처리하고 멈춰요. 그 하나도 「실패하는 테스트를 먼저 쓰고 → 통과시키고 → 전체 테스트와 빌드를 돌리고 → 커밋」하는 순서로요. 전체를 한 번에 맡기고 싶으면 /build auto 가 있는데, 그것도 사람 승인을 한 번 받고 시작하고, 멈춰야 할 상황을 정해 두고 있어요. /test 는 그 안의 테스트 부분만 따로 부르는 명령이에요.

이 시리즈 — ① 설치와 첫 확인 · ② /spec — 만들 것을 먼저 문서로 · ③ /plan — 일을 한 번에 끝낼 크기로 · ④ /build 와 /test(이 글) · ⑤ /review 와 /ship · ⑥ 알아서 켜지는 스킬과 한계

/build — 작업 하나, 여덟 단계, 그리고 멈춤

/build 는 incremental-implementation 과 test-driven-development 두 스킬을 함께 불러요. 명령 정의(commands/build.toml)에 적힌 기본 동작은 이 여덟 단계예요.

  1. 계획(tasks/plan.md)에서 다음 대기 중인 작업을 고른다
  2. 그 작업의 수용 기준을 읽는다
  3. 관련 코드·패턴·타입을 읽어 둔다
  4. 기대 동작을 담은 실패하는 테스트를 쓴다 (RED)
  5. 그 테스트를 통과시키는 최소한의 코드를 쓴다 (GREEN)
  6. 전체 테스트를 돌려 다른 곳이 깨지지 않았는지 본다
  7. 빌드를 돌려 컴파일되는지 본다
  8. 커밋하고, 작업을 완료로 표시하고, 멈춘다

여덟 번째가 이 명령의 성격이에요. 다음 작업은 사용자가 다시 /build 를 쳐야 시작해요. 그래서 작업 사이사이에 사람이 결과를 보고 방향을 바꿀 수 있어요.

「조금씩」의 규칙 — 증분 구현 스킬

incremental-implementation 스킬 원문은 「구현 → 테스트 → 확인 → 커밋 → 다음 조각」을 한 바퀴로 그려요. 조각을 어떻게 자르는지가 핵심이에요.

세로로 자른다. DB 전부 → API 전부 → 화면 전부 순서(가로)가 아니라, 「할 일 하나 만들기」라는 기능 한 줄을 DB·API·화면까지 관통해서 끝내고, 다음에 「목록 보기」를 관통하는 식이에요. 조각마다 실제로 되는 기능이 하나씩 생겨요.

위험한 것부터. 웹소켓이 될지 모르겠으면 그것부터 증명해요. 1번 조각에서 실패하면 2·3번에 들인 시간을 아끼니까요.

단순함이 먼저. 「알림 하나에 미들웨어 파이프라인 달린 이벤트 버스」 대신 「함수 호출 한 번」. 비슷한 줄 세 개가 이른 추상화보다 낫다고 적혀 있어요. 100줄로 될 것을 1,000줄로 썼으면 실패예요.

시킨 것만 건드린다. 고치는 파일 옆에 안 쓰는 import 가 보여도 고치지 않아요. 대신 이렇게 남겨요.

NOTICED BUT NOT TOUCHING:
- src/utils/format.ts 에 안 쓰는 import 가 있음 (이 작업과 무관)
- 인증 미들웨어 오류 메시지가 불친절함 (별도 작업)
→ 이것들을 작업으로 만들어 둘까요?

/test — 테스트가 곧 증거

/test 는 test-driven-development 스킬만 따로 불러요. 스킬 원문의 첫 문장이 이 스킬의 태도예요. 「테스트는 증거다. “된 것 같다”는 끝난 게 아니다.」

새 기능은 RED → GREEN → REFACTOR. 먼저 쓴 테스트는 반드시 실패해야 해요. 바로 통과하는 테스트는 아무것도 증명하지 않는다고 적혀 있어요. 그 다음 통과시키는 최소 코드, 그 다음 정리예요.

버그는 「증명부터」. 버그 신고가 오면 고치려 들지 말고, 그 버그를 재현하는 테스트를 먼저 써요. 그 테스트가 실패하는 것을 확인하고(버그가 있다는 증명), 고치고, 통과하는 것을 확인해요(고쳐졌다는 증명). 이걸 Prove-It 패턴이라고 불러요.

우리 프로젝트가 어떻게 테스트하는지부터 알아본다. 스킬은 npm test 를 가정하지 말라고 강조해요. package.json·pom.xml·pyproject.toml·Makefile 을 보고, ./gradlew·make test 같은 저장소에 든 실행기를 먼저 찾고, 기존 테스트가 어디 있고 어떻게 이름 붙였는지 따르라는 거예요. 저장소 README 는 이 스킬이 테스트 피라미드(단위 80 · 통합 15 · 종단 5)와 「DAMP over DRY」 같은 원칙도 담고 있다고 소개해요.

/build auto — 승인 한 번, 그리고 멈추는 조건

사양이 있고 계획을 검토할 여유가 있다면 /build auto 로 전체를 한 번에 돌릴 수 있어요. 명령 정의가 조건을 꽤 자세히 적어 두었어요.

  • 사양이 있어야 시작해요. 저장소 루트 SPEC.md, docs/SPEC.md, spec/ 아래만 인정해요. README 는 사양이 아니에요. 없으면 「/spec 부터 하라」고 멈춰요.
  • 작업 트리가 깨끗해야 해요. git status 에 사양·계획 파일 말고 다른 변경이 남아 있으면 멈추고 어떻게 할지 물어요. 작업마다 따로 커밋할 텐데, 관련 없는 변경이 섞이면 되돌리기가 깨지기 때문이에요.
  • 계획이 없으면 만들고, 먼저 커밋해요. 계획 파일이 첫 작업 커밋에 섞이지 않게요.
  • 승인은 분명한 말로만. 「approve」·「go」·「yes」 같은 확답만 승인이에요. 「괜찮아 보이네요」·「그런 것 같아요」는 승인이 아니라고 적혀 있어요. 이게 유일한 사람 관문이에요.
  • 작업마다 커밋, 필요한 파일만. git add -A 로 몽땅 담지 않고 그 작업이 건드린 파일과 상태 갱신만 담아요. 어느 지점으로든 깨끗하게 되돌릴 수 있게요.
  • 멈추는 조건. 테스트를 통과시킬 수 없거나 빌드가 깨지고 뻔한 해법이 없을 때, 사양이 모호할 때, 그리고 인증·권한 변경, 데이터 삭제·마이그레이션, 결제, 배포, 시크릿처럼 git revert 로 되돌릴 수 없는 일 앞에서는 멈추고 사람에게 확인을 받아요.

명령 정의는 한 가지를 분명히 해 둬요. 자동 모드가 작업당 더 빠르지는 않다는 거예요. 같은 테스트 주도 루프를 도는 건 같고, 사람이 작업 사이에 끼는 것만 없어질 뿐이에요.

뭔가 깨졌을 때 — 멈춰라 규칙

/build 도중 테스트가 깨지면 debugging-and-error-recovery 스킬이 붙어요. 첫 규칙이 「멈춰라」예요. 새 기능을 멈추고, 오류 출력과 재현 방법을 보존하고, 원인을 찾고, 고치고, 재발을 막는 테스트를 넣은 뒤에야 다시 진행해요. 「깨진 테스트를 두고 다음 기능으로 넘어가면 3번의 버그가 4·5·6번을 전부 틀리게 만든다」는 게 이유예요.

원인 찾기는 「재현 → 위치 → 최소화 → 수정 → 방어」 순서고, 전에는 되던 게 안 되면 git bisect 로 어느 커밋에서 깨졌는지 찾으라고 해요. 커밋을 작게 자주 한 것이 여기서 값을 해요. 스킬 원문

안 되는 경우

  • 테스트 도구가 없는 프로젝트예요. 스킬은 「이 저장소가 어떻게 테스트하는지 알아보라」고만 하고, 없을 때 무엇을 깔지는 정해 주지 않아요. 그런 프로젝트에서는 첫 /build 가 기능 구현이 아니라 테스트 환경 만들기가 될 수 있어요. 사양의 Testing Strategy 항목에 도구를 미리 적어 두면 그 방향으로 가요.
  • git 저장소가 아니면 /build auto 가 서요. 시작 조건이 git status 라서요. git init 을 먼저 하세요.
  • Claude Code 권한 설정에 걸려요. 테스트·빌드·커밋은 전부 셸 명령이에요. 명령 실행마다 확인을 받는 권한 모드라면 /build auto 라도 매번 멈춰서 물어요. 어디까지 자동으로 허용할지는 Claude Code 의 권한 문서를 보고 정하세요. 삭제·배포 같은 것까지 열어 두면 「멈추는 조건」의 의미가 없어져요.
  • /build 는 계획 파일을 읽어요. tasks/plan.md 가 없으면 무엇이 「다음 작업」인지 모르니, /plan 을 먼저 돌리거나 /build auto 로 계획까지 맡기세요.

이럴 땐 쓰지 마세요

설정 파일 한 줄, 문서 수정, 동작이 바뀌지 않는 정적 콘텐츠 변경에는 TDD 스킬 자체가 「쓰지 마라」고 적어 두었어요. 실패하는 테스트를 먼저 쓸 대상이 없으니까요. 그리고 코드 프로젝트가 아닌 폴더에서는 여덟 단계 중 테스트·빌드·커밋이 전부 헛돌아요.

✔ 요약

  • /build = 다음 작업 하나를 RED → GREEN → 전체 테스트 → 빌드 → 커밋, 그리고 멈춤
  • 조각은 세로로, 위험한 것부터, 단순하게, 시킨 것만
  • /test = 새 기능은 실패 테스트부터, 버그는 재현 테스트부터(Prove-It)
  • /build auto = 사양 필수 + 깨끗한 트리 + 분명한 승인 한 번, 되돌릴 수 없는 일 앞에서 멈춤
  • 깨지면 멈춰라 — 보존·재현·위치·최소화·수정·방어
  • 테스트 도구·git·권한 설정이 없으면 헛돈다
  • 2026년 9월 기준, 플러그인 버전 0.6.6

확인할 곳: /build 명령 정의 · incremental-implementation · test-driven-development · debugging-and-error-recovery · Claude Code — 권한

← 목록으로