Claude Code로 간단 "SDD 하네스" 만들기

소개

AI 코딩 에이전트를 쓰다 보면 늘 같은 문제에 부딪힌다.

"스펙에 없는 걸 마음대로 만들거나, 검증 없이 '완료'라고 선언하는 것"

특히 프로젝트 규모가 커질수록 이런 문제는 더 자주 발생한다. 처음에는 생산성이 올라간 것 같지만, 어느 순간부터는 사람이 AI가 만든 결과물을 다시 검증하고 수정하는 데 더 많은 시간을 쓰게 된다.

그래서 이번에 업무관련해서 SDD(Spec-Driven Development) 하네스를 구성했다.

핵심 아이디어는 단순하다.

전문 에이전트(페르소나) + 슬래시 커맨드(파이프라인) + 스킬(규칙집)

이 세 가지를 조합해 아이디어 한 줄을 기획 → 스펙 → 작업 분해 → 구현 → 검증 → 커밋/PR까지 자동으로 흘려보내는 컨베이어 벨트를 만드는 것이 목표였다.

진행 방법

1. 하네스의 3층 구조

┌─────────────────────────────────────────────┐
│  슬래시 커맨드 (워크플로우)                   │
│  /plan → /spec → /task → /play → /review →   │
│  → /commits                     │
├─────────────────────────────────────────────┤
│  에이전트 (페르소나)                           │
│  @backend-developer  @frontend-developer     │
│  @reviewer                                   │
├─────────────────────────────────────────────┤
│  스킬 (규칙·템플릿 = 공유 지식)                 │
│  coding-conventions / backend-conventions /  │
│  frontend-conventions / review-checklist /   │
│  security-checklist / *-template ...         │
└─────────────────────────────────────────────┘

각 계층의 역할은 명확하게 분리했다.

• 커맨드는 "무엇을 언제 할 것인가"

• 에이전트는 "누가 어떻게 할 것인가"

• 스킬은 "어떤 기준으로 판단할 것인가"

즉, 흐름은 커맨드가 만들고, 전문성은 에이전트가 담당하며, 판단 기준은 스킬이 제공하는 구조다.

2. 에이전트 3종 — 역할을 못 박는다

각 에이전트는 .claude/agents/*.md에 정의했다.

이번 설계에서 가장 중요하게 생각한 부분은 권한 분리였다.

특히 리뷰어는 의도적으로 쓰기 권한을 제거했다.

"검증자는 코드를 고치지 않는다."

리뷰어의 역할은 문제를 발견하고 보고하는 것이지 직접 수정하는 것이 아니다. 이를 프롬프트 수준이 아니라 도구 권한 수준에서 강제했다.

3. 현장에서 겪은 문제를 규칙으로 만든 에이전트

단순히 "코드 작성 전문가" 정도로 정의하지 않았다.

실제 프로젝트에서 반복적으로 겪었던 문제들을 에이전트 규칙에 녹여 넣었다.

백엔드 — 부팅 스모크 테스트 의무화

많은 AI 에이전트는 아래 검증만 통과하면 완료를 선언한다.

• Type Check

• Build

• Unit Test

• E2E Test

하지만 실제 운영에서는 이걸로 부족했다.

특히 NestJS에서는 다음과 같은 문제가 있었다.

• DI Resolve 실패

• Logger 순환 참조

• Prisma Adapter 초기화 오류

• Runtime Provider 오류

이런 문제는 main.ts를 통한 실제 부팅 과정에서만 발견된다.

그래서 완료 조건에 반드시 아래 과정을 포함시켰다.

node apps/api/dist/src/main.js

그리고 다음 로그를 확인해야만 완료로 인정한다.

Nest application successfully started

백엔드 — 테스트 없는 완료 선언 금지

모든 기능 구현에는 반드시 *.spec.ts가 포함되어야 한다.

단위 테스트 없이 "완료"라고 말할 수 없도록 에이전트 규칙 자체에 명시했다.

팀 간 통신 프로토콜 정의

백엔드와 프론트엔드가 동시에 작업할 때 발생하는 충돌도 줄이고 싶었다.

그래서 다음 규칙을 만들었다.

1. 공유 타입은 packages/shared/types에 먼저 정의

2. 백엔드는 API 완료 시 정해진 메시지 포맷으로 프론트에 전달

3. 프론트는 API가 없어도 스펙 계약 기준으로 Hook과 Mock을 먼저 작성

덕분에 API 구현 대기 때문에 프론트 작업이 멈추는 경우가 크게 줄었다.

리뷰어 — 스택 불가지론

리뷰어는 기술 스택을 먼저 가정하지 않는다.

먼저 PRD를 읽고 요구사항을 파악한 뒤 검증을 시작한다.

핵심 원칙은 단 하나다.

"스펙에 없으면 버그, 스펙과 다르면 결함"

또한 모든 FAIL 항목에는 반드시 다음 정보가 포함된다.

• 파일 경로

• 라인 번호

• 개선 제안

4. 슬래시 커맨드 — 한 방향 파이프라인

.claude/commands에는 총 8개의 단계를 정의했다.

아이디어
  │
  ▼
/plan
  │
  ▼
/spec
  │
  ▼
/task
  │
  ▼
/play
  │
  ▼
/review
  │
  ▼
/commits

각 단계가 끝나면 다음 단계도 자동으로 안내한다.

다음 단계: /spec

이 작은 장치 하나만으로도 워크플로우 이탈이 크게 줄었다.

5. 스킬 — 단일 진실 공급원(Single Source of Truth)

규칙과 템플릿은 모두 .claude/skills에 모았다.

대표적으로 다음과 같은 파일들이 있다.

가장 큰 장점은 중복 제거였다.

규칙을 수정할 때 에이전트 파일, 커맨드 파일을 모두 수정할 필요가 없다.

스킬 하나만 수정하면 전체 시스템에 반영된다.

결과와 배운 점

이번 SDD 하네스를 구축하면서 얻은 효과는 생각보다 컸다.

재현성

아이디어에서 PR까지 항상 같은 흐름으로 진행된다.

사람이 다음 단계를 기억하거나 관리할 필요가 없다.

스펙 중심 개발

모든 에이전트가 다음 원칙을 공유한다.

"스펙에 없으면 만들지 않는다."

덕분에 AI 특유의 과도한 확장 구현이나 환각성 기능 추가가 크게 줄었다.

검증 게이트 강화

구현 완료 기준을 명확하게 정의했다.

• Type Check

• Lint

• Build

• Test

• Boot Smoke Test

모든 검증을 통과해야 완료로 인정된다.

역할 경계 확보

구현자와 검증자를 물리적으로 분리했다.

덕분에 "스스로 구현하고 스스로 승인하는" 상황을 방지할 수 있었다.

유지보수성 향상

• 규칙은 스킬

• 흐름은 커맨드

• 전문성은 에이전트

관심사를 분리한 덕분에 시스템 자체를 수정하기도 쉬워졌다.

마치며

이번에 만든 하네스의 본질은 결국 하나다.

"AI에게 자유를 주는 대신 레일을 깔아주는 것"

에이전트는 충분히 창의적으로 코드를 작성할 수 있다.

하지만 스펙, 검증, 역할이라는 레일 위에서만 움직이도록 설계했다.

그 결과 이제 /plan부터 /commits까지, 명령 한 줄씩으로 도메인을 기획하고 구현하고 검증하고 PR까지 생성할 수 있는 상태가 되었다.

AI 코딩 에이전트를 더 잘 활용하기 위해 필요한 것은 더 복잡한 프롬프트가 아니라, 결국 반복 가능하고 재현 가능한 개발 시스템이라는 점을 다시 한번 확인할 수 있었다.

도움 받은 글

• Claude Code 공식 문서

• Claude Code Slash Commands 문서

• Claude Code Skills 문서

• Spec-Driven Development 관련 사례 및 자료