Harness 실전 적용기

이 글에서 다룰 것

앞의 세 글은 각각 왜 하네스가 필요한지(통제 구조), 어떤 기법이 있는지(결정론 8기법), 왜 TDD가 핵심인지(검증 수단)를 다뤘어요. 그럼 이 조각들이 실제로 하나의 워크플로로 어떻게 맞물리는지 궁금하시죠? 이 글이 그걸 끝에서 끝까지 따라가요.

환경 셋업 → 기획 → TDD 사이클 → 완성, 그리고 이 전체를 감싸는 자동화 루프까지. 각 단계가 무슨 자산을 남기고, 왜 그 순서인지를 흐름으로 짚어볼게요. 한 기능을 처음부터 PR 머지까지 통과시키는 동안 하네스가 어떻게 도는지, 한 장의 지도처럼 보는 게 목표예요.

핵심 메시지

"AI에게 잘 부탁하기"가 아니라, AI가 따를 워크플로 자체를 코드로 박는다. Skill은 절차를, Hook은 강제를, Agent는 격리를 담당한다.

매 단계가 자동화 자산(Skill·Hook·Subagent)을 하나씩 추가하고, 이게 다 쌓이면 /feature-planner → /tdd-auto-loop → /create-pr 한 줄 명령으로 spec → 이슈 → 구현 → PR이 굴러가요. 손에 남는 건 코드가 아니라 워크플로 그 자체고요.

---

세 가지 자동화 단위 - 워크플로의 골조

본격적으로 들어가기 전에, 전체를 관통하는 빌딩 블록 셋만 짚고 갈게요. 이 셋의 역할 분리가 글 전체를 관통하거든요.

특히 Subagent를 "독립 세션"으로 격리하는 이유 — 구현한 AI가 자기 코드를 자기가 채점하지 못하게 하려는 거예요. 이게 뒤에 나올 AC 검증과 자율 루프의 핵심 멘탈 모델이에요.

---

전체 워크플로 - 한 화면에

나만의 AI 하네스 워크플로우 — 4단계 + META 자동화 2

환경 셋업 → 요구사항·설계 → TDD 사이클 → 완성, 그리고 이를 감싸는 META 자동화 2단계. 아래 텍스트 흐름과 1:1로 대응해요.

[Phase 0] 환경 셋업
  /init → CLAUDE.md · Mermaid Hook · husky · commitlint
        │
        ▼
[Phase 1] 기획 (/feature-planner로 압축)
  spec-original → AI 인터뷰 → spec-fixed
    → 디자인 이미지 → design.md → 디자인 시스템 + 토큰 hook
    → PRD + ADR(4요소)
    → 수직 슬라이싱 → 이슈 N개 → gh CLI로 GitHub Issues 등록
        │
        ▼
[Phase 2] TDD 사이클 (이슈 단위 반복, /tdd-loop·/tdd-auto-loop로 압축)
  /test-scenarios → /tdd-red → /tdd-green
    → (AC 검증 agent, 독립 세션) → /tdd-refactor → /security-review → commit
        │
        ▼
[Phase 3-4] E2E + PR + CI
  /e2e-write (Playwright) → /create-pr
    → GitHub Actions CI → 브랜치 보호 → main 머지 → docs 정리
        │
        ▼
[Phase 5-6] 자동화 루프 (점진적)
  /tdd-loop      — 순서만 자동화, 승인 게이트 유지
  /tdd-auto-loop — 의사결정까지 자동화, subagent spawn + STOP 조건
        │
        ▼
[Phase 7] 자산을 살아 있게
  운영 4원칙(가지치기·팀공유·측정·회고) + 메트릭 2개

이 그림이 전체의 단일 지도예요. 아래 모든 단계는 이 그림의 한 칸을 자기 자산으로 만들어가는 과정이고요.

---

Phase 0 - 환경 셋업: 가드레일부터 박기

가장 먼저 하는 건, AI가 무슨 코드를 짜든 저장·커밋 시점에 환경이 거부할 수 있게 만드는 거예요.

이 단계가 끝나면, 사람이 일일이 검수 안 해도 형식 일탈은 0이 돼요. 이후의 모든 자동화가 이 가드레일 위에서 도니까, 처음에 합격선을 박아두는 게 그렇게 중요한 거죠.

---

Phase 1 - 기획을 스킬로 압축

여기서 처음으로 "스킬을 만든다"는 메타 작업이 등장해요.

이 네 절차를 통째로 /feature-planner 스킬 하나로 묶어요. 그러면 다음 기능부턴 /feature-planner 한 번 = spec → design → PRD → 이슈가 자동으로 진행되죠.

스킬을 만들 때 기억할 건 세 가지예요. SKILL.md에 실행 순서와 산출물을 적고, 콜드 세션(아무 기억 없는 새 대화)에서도 같은 결과가 나오게 자체완결형으로 쓰고, 자동화하면 안 될 사람의 판단 지점은 승인 게이트로 명시적으로 멈춰두기. 이 "여러 단계를 1개 명령으로 묶는" 패턴은 뒤의 /tdd-loop에서 똑같이 재사용돼요.

---

Phase 2 - TDD 사이클을 스킬·Agent로

이제 이슈마다 이 스킬들을 차례로 돌려요.

/test-scenarios → /tdd-red → /tdd-green → (AC 검증 agent) → /tdd-refactor → /security-review → commit

TDD 사이클 6단계 디테일

여기서 핵심은 AC 검증만 스킬이 아니라 Agent(@ac-verifier)라는 점이에요. 정해진 절차는 스킬, 탐색적 판단은 에이전트인 거죠.

왜 AC 검증만 독립 세션으로 떼어냈을까요? 같은 세션에서 채점하면 "내가 짠 거니까 통과지" 하는 편향이 끼어들거든요. 구현하는 AI와 채점하는 AI를 분리해야 그 편향이 빠져요. 결과적으로 이슈 1개당 PR 1개, 사람은 "테스트 통과했나?"만 보면 되고요.

---

Phase 3-4 - E2E + PR + CI

테스트 피라미드로 보면, 단위 테스트(Phase 2)가 바닥이고 E2E가 정점이에요. E2E는 골든 패스만 좁게 잡아요 — 회귀는 이미 단위 테스트가 잡고 있으니, E2E는 사용자 흐름의 신호 역할만 하면 되거든요. 첫 main 머지까지 끝나면, 한 기능이 처음부터 끝까지 워크플로를 통과한 완전한 한 사이클이 손에 잡혀요.

---

Phase 5 - 컨테이너 스킬로 사이클을 한 줄에

/tdd-loop — Phase 2~4의 스킬들을 7단계 순서로 호출하는 컨테이너 스킬이에요. 새 기능을 넣는 게 아니라 순서만 보장하고, 각 스킬 안의 승인 게이트는 그대로 둬요. /feature-planner와 똑같은 패턴이죠. 달라지는 건 손 누르는 횟수 — 7번이 1번이 돼요. 사이클 진입의 마찰이 사라지는 거예요.

---

Phase 6 - 자율 루프: subagent 오케스트레이션

/tdd-auto-loop — 이슈 번호를 넣으면 subagent를 순차로 spawn해서 PR URL까지 뽑아요. 메인 세션은 오케스트레이터로만 남고, 코드 본문을 직접 읽지 않아요. 각 단계는 subagent가 실행하고, 결과 JSON만 메인에 쌓이죠.

여기서 중요한 게 하나 있어요. STOP 조건이 SKILL.md의 본체라는 거예요. "잘 진행하는 법"이 아니라 *"멈춰야 할 때 멈추는 법"*이 핵심이거든요 — AC 누락, 시나리오 5개 미만, Green 3회 실패, npm test 미통과, severity ≥ high, commitlint 실패… 이런 조건마다 멈추게 박아둬요.

그리고 왜 곧장 자율 루프로 안 가고 Phase 5(컨테이너)를 거칠까요? 순서 자동화(낮은 위험)에 익숙해진 다음 의사결정 자동화(높은 위험)로 넘어가야 안전하거든요. 자동화 강도를 한 단계씩 안전하게 올리는 거예요.

---

Phase 7 - 만든 워크플로를 살아 있게

하네스는 한 번 만들고 끝이 아니에요. 운영해야 하죠.

솔직한 한계도 있어요. "처음 3개월은 오히려 느려요" — ROI는 6개월부터예요. 그러니 한 번에 다 갈지 말고 1 Phase씩 도입하는 게 좋아요. 외부 framework(superpowers·spec-kit·BMAD 등)는 참조로 적극 활용하되, 종속되진 마시고요. 외부 framework는 빌려 쓰는 것, 내 워크플로는 키워가는 것이에요.

---

흐름을 관통하는 3가지 패턴

이 워크플로가 "TDD 절차"가 아니라 하나의 하네스인 이유는, 같은 패턴이 다른 단계에서 반복되기 때문이에요.

① 절차 → 스킬로 압축. /feature-planner(기획 4절차)와 /tdd-loop(TDD 7절차)가 같은 "컨테이너" 패턴이에요. 한번 익힌 패턴을 다른 단계에 그대로 적용하죠.

② 자동화 강도의 단계적 격상. Hook(형식) → Agent 격리(채점) → 오케스트레이션(흐름). 각 단계는 이전 단계의 안전망 위에서만 작동해요.

③ "제안 vs 강제"의 이중화. CLAUDE.md·SKILL.md는 제안(높은 확률, 보장 X), Hook·CI Gate·독립 Agent는 강제(보장). 이 이중화가 전체 신뢰 모델의 골격이에요.

---

마무리 - 가드레일 하나부터

워크플로 전체를 통과하고 나면 손에 남는 건 분명해요 — Skill 한 묶음 + Hook 몇 종 + 검증 Agent + CLAUDE.md + CI Gate. 이게 곧 나만의 하네스고, 다음 기능부턴 이 위에서 굴러가요.

얼마 전까지: 코딩하는 사람. 이제부터: 엔지니어링을 지휘하는 사람.

8가지 기법도, TDD도, 통제 구조도 결국 이 한 흐름으로 모여요. 전부를 한 번에 갖출 필요 없어요. Phase 0의 가드레일 하나부터 박고, 한 단계씩 위로 쌓아 올리면 됩니다.

---

위 흐름을 한 강의에서 한 줄 한 줄 직접 빌드업하는 18강 코스로도 정리돼 있어요. 손으로 따라 만들어 보고 싶다면 나만의 Claude Code 하네스 코스를 참고하세요.