명세와 하네스

채널톡의 AI 총괄(CAIO) 이경훈 이사는 한 문장으로 커리어를 바꿨다. "AI가 사람을 대체하는 게 아니라, AI를 잘 쓰는 사람이 못 쓰는 사람을 대체한다." 그의 회사가 토큰 무제한 정책을 도입한 뒤, 한 개발자는 수천만 원어치 토큰으로 혼자 10명분의 일을 해냈다. 마법이 아니다. 그 결과의 전제는 단 두 가지였다 — 명확한 지시, 그리고 결과물을 리뷰하는 능력.

AI는 지금 당신이 고용할 수 있는 가장 일 잘하는 새 직원이자 외주다. 그런데 우리는 새 직원에게 의뢰서도 없이 "알아서 잘 만들어줘"라고 말하지 않는다. 이 글은 코드를 한 줄도 치기 전에 깔아두는 여섯 장의 종이에 관한 것이다. 로드맵, 의뢰서(RFP), 설계도(PRD), 결과물을 검증할 시험지(테스트), 그리고 AI가 사고를 치지 못하게 막는 물리적 울타리(하네스)와 그 설정(settings.json).

왜 로드맵부터인가. 인간의 워킹 메모리는 한 번에 3~4개의 정보 덩어리만 처리한다(Cowan, 2001). 처음부터 PRD를 쓰려고 하면 "왜 만드는지", "무엇을 만드는지", "어떻게 만드는지"를 동시에 결정해야 해서 뇌가 과부하된다. 로드맵은 그중 "왜·어디까지"만 떼어 한 장에 담는 고수준 지도다. 세부 할 일 목록이 아니다.

개인이나 소규모 프로젝트에서 정교한 로드맵은 과잉이다. 최소 구성은 세 가지뿐이다 — 범위, 비범위, 그리고 마일스톤 3~5개. 이 중 가장 중요한 것은 비범위다. "이번에 만들지 않는 것"을 적는 순간, 만들다 보면 끝없이 불어나는 범위 크리프(scope creep)가 막힌다.

로드맵이 지도라면, RFP는 그 지도를 들고 새 직원에게 건네는 발주서다. RFP(Request for Proposal, 제안요구사항서)는 원래 발주자가 외부 업체에 "이런 게 필요하다"고 보내는 공식 문서다. 표준 구성은 배경·범위·요구사항·제약·평가기준·타임라인. AI 개발로 번역하면 RFP는 "AI에게 건네는 작업 의뢰서"가 된다.

여기서 많은 사람이 헷갈리는 구분이 있다. RFP와 PRD는 다르다. RFP는 "무엇을 원하는가"(요구)이고, PRD는 "무엇을 만들 것인가"(제품 정의)다. RFP가 먼저 나오고, PRD는 그 의뢰서를 받은 사람이 "그럼 이렇게 만들겠다"고 답한 설계도다. RFP는 질문, PRD는 답이다.

전통적인 RFP의 여섯 요소를 AI 작업 의뢰서로 다시 매핑하면 다섯 가지로 압축된다. 비범위는 로드맵에서 이미 정의했으니, 여기서는 제약과 성공기준에 흡수시킨다.

의뢰서(RFP)를 받은 팀은 "그럼 이렇게 만들겠습니다"라는 설계도를 쓴다. 그게 PRD(Product Requirements Document, 제품 요구사항 문서)다. 2025년 9월, GitHub과 Microsoft가 Spec Kit이라는 도구를 공개하면서 한 가지 원칙이 공식화됐다 — "스펙이 진실의 원천이고, 코드는 거기서 파생되는 이차 산출물이다." 이것이 스펙 주도 개발(SDD, Spec-Driven Development)이다.

SDD의 흐름은 추상도가 한 단계씩 낮아지는 구체화다. 원칙을 정하고(constitution), 무엇을·왜를 정의하고(specify), 기술 아키텍처를 짜고(plan), 원자적 태스크로 쪼갠 뒤(tasks), 마지막에 코드를 생성한다(implement). RFP에서 PRD로, PRD에서 태스크로 — 같은 사다리를 계속 내려가는 것이다.

데이터는 이 방식이 단순한 형식주의가 아님을 보여준다. 스펙을 먼저 잡으면 재작업과 해명 루프가 줄어 오류가 감소한다(초기 연구에서 최대 50%). 반대로 스펙도 검증도 없이 코드부터 뽑으면, 그 코드의 절반 가까이가 OWASP Top 10 취약점을 안고 나온다.

PRD의 핵심은 모호함을 없애는 것이다. "주문 기능"이라고 쓰면 AI가 상상으로 채운다. 대신 Given-When-Then 형식으로 관찰 가능한 결과를 못 박는다.

그리고 우선순위를 P0/P1/P2로 나눈다. 가장 흔한 실수는 모든 것을 P0로 지정하는 것이다. 진짜 MVP에 필요한 것만 P0다.

스펙을 쓰는 행위 자체가 "명확한 지시" 능력을 단련시킨다. 채널톡의 이경훈 이사가 말한 "AI를 잘 쓰는 사람 = 명확히 지시하고 결과물을 리뷰할 수 있는 사람"의 그 지시력은, PRD를 한 번 써보면 눈에 띄게 자란다.

PRD가 "무엇을 만들지"를 정했다. 그런데 AI가 그걸 제대로 만들었는지는 어떻게 아는가. 눈으로 코드를 읽어서? AI가 하루에 쏟아내는 코드를 전부 읽을 수는 없다. 답은 테스트다. 그리고 순서가 핵심이다 — 코드보다 테스트를 먼저 쓴다.

테스트 주도 개발(TDD)의 창시자 Kent Beck이 AI 코딩을 두고 남긴 말이 정곡을 찌른다.

"그냥 만들어 줘"라고 하면, AI는 자기가 짠 코드에 맞춰 통과하는 테스트를 슬쩍 끼워 넣거나, 잘 되는 경우(해피 패스)만 통과시키고 예외는 환각으로 넘긴다. 심하면 실패하는 테스트를 지워서 초록불을 만든다. 그래서 사람이 테스트를 먼저 못 박고, AI에게는 "이 빨간 테스트를 초록으로 만들어"라고 시킨다. 그 순간 테스트는 AI의 채점 기준이자 결승선이 된다.

TDD는 세 박자로 돈다. Red — 코드를 짜기 전에 "이렇게 동작해야 한다"는 테스트를 먼저 쓴다. 기능이 없으니 당연히 실패한다(빨강). 이 빨강은 "내가 뭘 만들지 정확히 정했다"는 신호다. Green — 그 테스트를 통과시키는 가장 단순한 코드를 짠다. 멋지게 말고, 일단 초록불이 켜지게만. Refactor — 초록불 상태에서 코드를 다듬는다. 테스트가 지켜보고 있으니, 잘못 건드리면 즉시 빨강으로 알려준다.

여기서 핵심 통찰. 코드는 AI가 언제든 다시 써주는 초안이지만, 테스트는 "이 소프트웨어는 이렇게 동작한다"를 못 박은 계약이다. 초안은 찢고 다시 써도, 계약서가 그대로면 결과물은 바뀌지 않는다. 그래서 AI 시대에는 코드보다 테스트가 더 오래 살아남는 자산이다.

국내 개발자 커뮤니티(GeekNews)에서도 AI 시대의 방법론으로 SDD와 TDD의 결합이 논의된다. 스펙으로 "무엇을"을 정의하고(Red 단계의 테스트로 옮긴 뒤), AI가 통과시킬 때까지 구현하고(Green), 사람이 설계를 다듬는(Refactor) 선순환이다. 둘은 경쟁이 아니라 보완이다.

그런데 위 프롬프트도 결국 부탁이다. AI가 규칙을 어기고 실패하는 테스트를 지워버릴 수도 있다. 그래서 이 규율은 hook으로 강제해야 진짜가 된다 — 그 방법은 다음 Part에서 다룬다.

여기까지 우리는 AI에게 로드맵·의뢰서·스펙·테스트를 "써 달라"고 했다. 그런데 그건 전부 부탁이다. 스펙대로 만들지, 테스트를 먼저 쓸지, 위험한 명령을 피할지 — 결국 AI의 선의에 달렸다. 하네스(harness)는 이 부탁을 강제로 바꾸는 층이다. 위험 명령 차단만이 아니라, 스펙과 테스트 규율까지 도구가 실행되기 전에 강제한다.

원리는 하나다 — 말이 아니라, 도구가 실행되기 직전에 막는다. 아래부터는 가장 흔한 "안전" 차단으로 그 원리를 보고, 같은 방식이 테스트와 스펙에도 그대로 적용된다.

새 직원에게 "저 빨간 버튼은 누르지 마세요"라고 말하는 것과, 그 버튼에 안전 덮개를 씌우는 것은 다르다. 전자는 직원의 기억과 선의에 의존하고, 후자는 누를 수 없게 만든다. AI 가드레일도 똑같다.

CLAUDE.md에 "rm -rf 하지 마"라고 쓰는 것은 말이다. AI는 그것을 읽지만, 맥락에 따라 무시할 수도 있고, 프롬프트 인젝션으로 우회될 수도 있다 — 모델의 선의에 의존한다. 앞서 봤듯 AI가 생성한 코드의 절반 가까이가 OWASP Top 10 보안 취약점을 안고 나온다(Veracode, 2025). AI가 위험을 "선택"한 게 아니다 — 시키지 않으면 보안을 챙기지 않을 뿐이다. 그러니 부탁만으로는 부족하다. 하네스(harness) 차원에서 물리적으로 막아야 한다. 도구가 실행되기 전에 차단되면, 모델은 애초에 선택할 수조차 없다.

Claude Code에는 물리적 차단을 위한 두 가지 도구가 있다. 하나는 settings.json의 권한(permissions) deny 규칙, 다른 하나는 PreToolUse hook이다.

먼저 권한. permissions는 allow(자동 허용), ask(매번 확인), deny(차단) 세 배열로 나뉜다. 평가는 deny → ask → allow 순으로, 가장 먼저 매칭되는 규칙이 이긴다. 위험한 것을 deny에 넣으면 그걸로 잠긴다.

{
  "permissions": {
    "deny":  ["Bash(rm -rf *)", "Read(.env)"],
    "ask":   ["Bash(git push *)"],
    "allow": ["Bash(npm run *)"]
  }
}

다음은 hook. hook은 세션의 특정 순간(도구 실행 전후, 세션 시작·종료 등)에 자동으로 실행되는 명령이다. 그중 PreToolUse는 도구가 실행되기 직전에 끼어들어 차단할 수 있는 핵심 이벤트다. 차단하는 방법은 두 가지다 — 검사 스크립트가 exit code 2로 종료하면 그 도구 호출이 막히고 이유가 Claude에게 전달된다. 또는 hook이 JSON으로 permissionDecision을 "deny"로 반환해도 된다.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "~/.claude/hooks/block.sh" }]
    }]
  }
}

matcher는 어떤 도구에 hook을 걸지 정하는 필터다("Bash", "Edit|Write" 같은 패턴, 정규식도 된다). 검사 스크립트는 표준 입력으로 도구 정보가 담긴 JSON을 받아 명령어를 들여다보고, 위험하면 차단하고 아니면 통과시킨다.

그런데 이 모든 규칙을 어디에 둘 것인가. settings.json은 놓이는 위치가 곧 적용 범위(스코프)다. 그리고 위치마다 우선순위가 다르다.

같은 원리를 테스트와 스펙에도 적용한다. 테스트는 Stop hook으로 강제한다 — Claude가 응답을 끝내려는 순간 hook이 테스트를 돌리고, 실패하면 종료를 막아(무엇이 실패했는지 이유로 전달) green이 될 때까지 고치게 만든다. 그리고 AI가 실패하는 테스트를 지우지 못하도록 테스트 파일을 deny로 잠근다. 스펙은 PreToolUse hook이 spec.md가 비어 있으면 구현 편집을 막고, SessionStart hook이 매 세션 스펙을 자동으로 물려준다.

{
  "hooks": {
    "Stop": [{
      "hooks": [{ "type": "command", "command": "~/.claude/hooks/run-tests.sh" }]
    }]
  }
}

여기까지의 여섯 장을 한 번의 프롬프트로 받고 싶다면, 아래를 쓴다. 로드맵부터 가드레일까지 골격을 순서대로 생성한다. 받은 뒤에는 반드시 직접 읽고, 어색한 곳을 고쳐 당신의 언어로 만든다 — 결과물을 리뷰하는 그 능력이, AI를 잘 쓰는 사람의 마지막 조건이다.