「됐다」를 말이 아니라 파일로 증명한다 — 딜리버리 관문과 문서 표준

앞 편은 되돌리는 값이 큰 결정 다섯 개를 문서로 남겼다. 이 편은 그 문서들을 들고 실제로 만들기 시작하는 단계를 다룬다. 다만 설계가 끝났다고 곧바로 착수하지는 않는다. 그 사이에 세 개의 관문과 한 번의 사람 승인이 놓여 있다.

이 단계가 앞의 어느 단계와도 다른 점이 하나 있다. 여기서는 조건을 채우지 못하면 파일이 만들어지지 않는다. 권고가 아니라 쓰기 실패다. 다루는 것은 그 차단 장치와, 관문을 통과한 뒤에 나오는 요구사항 문서의 표준까지다. 그 표준을 팀 전체가 공유하는 자산으로 만드는 일은 뒤의 편이 맡는다.

딜리버리 단계에 들어오는 것과 나오는 것

마지막 줄이 이 단계의 성격을 정한다. 앞 편들의 게이트가 「판정을 낸다」였다면 여기는 판정이 없으면 다음 산출물이 물리적으로 존재하지 않는다.

세 관문을 지나야 문서가 생긴다

관문에서 산출물까지가 한 줄로 이어져 있다. 앞 칸이 막히면 뒤 칸은 실행되지 않는다.

세 관문의 순서에는 이유가 있다. 고통이 실재하지 않으면 범위를 좁힐 대상 자체가 없고, 범위가 정해지지 않으면 한 건에 드는 값을 계산할 수 없다. 앞의 것이 뒤의 것을 계산 가능하게 만드는 순서다.

사람 승인이 관문 뒤에 따로 놓인 것도 우연이 아니다. 셋이 전부 초록이어도 그것은 「막을 이유가 없다」는 뜻이지 「지금 해야 한다」는 뜻이 아니다. 자동으로 통과시킬 수 있는 자리가 아니다.

설득이 아니라 차단이다

마지막 줄이 이 시리즈 전체에서 되풀이되는 분업이다. 판단하는 자리에 확률적으로 답하는 것을 두지 않는다.

훅 자체는 짧다. 개인 작업 흐름에도 그대로 붙일 수 있는 크기다.

# hooks/gate_lite.py — 파일 쓰기 직전에 도는 검사
event = json.load(sys.stdin)
target = event["tool_input"]["file_path"]

if target.endswith("PRD.md") and not os.path.exists("harness/approved"):
    print("차단: 승인 기록이 없다", file=sys.stderr)
    sys.exit(2)   # 2 로 끝내면 쓰기 동작 자체가 취소된다

핵심은 마지막 줄의 종료 코드다. 0 으로 끝나면 통과, 1 이면 오류로 기록되지만 흐름은 이어지고, 2 여야 쓰기가 취소된다. 세 값의 차이가 곧 「경고」와 「차단」의 차이다. 이 훅을 쓰기 도구에 걸어 두면 승인 파일이 생기기 전까지 요구사항 문서는 만들어질 수 없다.

「완료」를 먼저 정하고 파일로 확인한다

둘째 줄과 셋째 줄은 층이 다르다. 목표는 몇 달 뒤에 판정되고 완료 조건은 이번 주에 판정된다. 이번 주에 판정할 수 없는 것을 완료 조건 자리에 적으면 그 주는 끝나지 않는다.

조건을 적어 두는 것만으로는 부족하다. 채워졌는지를 누가 확인하느냐가 남는다.

한쪽 방향으로만 바꾼다는 것이 이 장치의 요점이다. 완료를 취소하는 일은 사람이 하고, 자동으로 도는 부분은 채워진 것을 채워졌다고 표시하는 데까지만 관여한다. 판정의 근거가 파일의 존재라서 결과가 실행할 때마다 달라지지 않는다.

승인된 것만 다음 도구로 넘어간다

마지막 줄이 앞의 차단 장치와 짝을 이룬다. 문서 생성만 막고 전달을 열어 두면 검증되지 않은 내용이 다른 경로로 새어 나간다. 막을 자리를 하나라도 열어 두면 나머지 차단이 무의미해진다.

건너뛰면 무엇을 치르는가

다섯 줄 가운데 마지막이 가장 늦게 드러나고 가장 고치기 어렵다. 앞의 넷은 지연이나 낭비로 눈에 보이지만, 마지막 것은 아무 일도 일어나지 않는 것처럼 보이는 동안 진행된다. 소리 내어 실패하기가 이 자리를 겨냥한 원칙이다.

무엇을 맡기고 무엇을 직접 하는가

넷째 줄이 이 표에서 가장 미묘하다. 파일이 있는지는 기계가 정확히 알지만, 그 파일이 조건을 실제로 증명하는지는 알지 못한다. 결정론적으로 판정되는 것과 판정된 값이 옳은 것은 다른 문제다.

요구사항 문서를 매번 새로 쓰지 않으려면

여기부터가 관문을 통과한 뒤의 이야기다. 승인이 떨어지면 문서를 쓰기 시작하는데, 그 문서를 매번 백지에서 시작하지 않는 방법이 있다.

셋째 줄이 이 장의 전제다. 일반형 골격이 나쁜 것이 아니라, 그것이 내가 매번 빠뜨리는 항목을 알지 못한다는 것이 문제다. 표준을 고정하는 이유는 좋은 문서를 쓰기 위해서가 아니라 같은 자리를 반복해서 비우지 않기 위해서다.

골격은 여섯 항목이다

여섯 가운데 ④와 ⑤가 이 골격의 무게중심이다. 좋은 요구사항 문서는 비범위와 지표가 있는 기획서다. 기능 목록이 아니라 「왜 · 누구에게 · 무엇을 하지 않는가」가 적힌 문서라는 뜻이다.

⑤의 지표가 한 쌍인 것도 의도된 구성이다. 올릴 지표만 두면 그것을 올리기 위해 다른 것을 망가뜨리는 선택이 정당해 보이기 시작한다. 떨어뜨리면 안 되는 지표는 그 선택지를 미리 닫는다.

표준을 파일 하나에 박는다

골격을 정했다면 그것을 머리에 두지 않고 파일로 적어 둔다. 다음은 그 파일의 뼈대다.

---
name: prd-writer
description: 검증을 마친 문제를 기능으로 옮기기 전에, 고정된 섹션과
  완료 조건으로 초안을 빠르게 뽑고 싶을 때 쓴다.
---

## 규약
   확인되지 않은 수치에는 [리서치], 추정에는 [가정], 정한 것에는 [결정].
   단정하지 않는다. 모르면 되묻는다.

## 입력
   문제 한 문단 + (있으면) 앞 단계의 조사 요약

## 섹션 — 이 여섯 개를 이 순서로 고정한다
   1 문제  2 사용자와 지불자  3 해결(기능 셋 이내)
   4 범위와 비범위  5 성공 지표  6 위험과 가정

## 완료 조건
   비범위가 있다 · 지표가 측정 가능하다 · 미검증에 라벨이 있다 · 기능이 셋 이내다

## 거를 것
   기능 나열 · 확인 안 된 수치의 단정 · 열린 범위 · 비범위 없음

읽어 보면 알겠지만 특별한 문법이 없다. 사람이 읽는 지시문 그대로이고, 그것을 매번 다시 타이핑하는 대신 정해진 위치에 두는 것이 전부다. 표준이 표준으로 작동하는 조건은 정교함이 아니라 위치의 고정이다.

세 라벨은 그대로 쓴다. [리서치]는 아직 찾지 않은 것, [가정]은 참이라 치고 진행하는 것, [결정]은 이미 정해 논의를 닫은 것이다. 셋을 구분해 두면 나중에 문서를 다시 열었을 때 어느 문장이 검증을 기다리는 중인지가 한눈에 갈린다.

좋은 문서와 나쁜 문서를 가르는 여덟 줄

여덟 줄을 관통하는 것은 분량이 아니다. 나쁜 쪽이 짧아서 나쁜 것이 아니라 되묻는 질문에 답할 수 없어서 나쁘다. 좋은 쪽은 전부 「그건 어떻게 아느냐」에 답을 가지고 있다.

채워진 예시 하나

가상 데이터로 만든 예시다. 시니어 만성질환 관리를 소재로 여섯 칸을 채우면 이 정도가 된다.

여섯째 줄이 이 예시에서 가장 중요하다. 가정을 적는 것으로 끝내지 않고 그것을 깨 볼 방법을 붙였다. 다섯 명이라는 크기는 통계적 유의성을 얻으려는 것이 아니라, 매일 쓴다는 전제가 틀렸다면 그 정도로도 드러나기 때문이다.

표준이 표준으로 작동하는지

표준을 적어 두는 양식은 여섯 칸이면 충분하다.

⑤가 비어 있으면 나머지 다섯 칸이 잘 채워져 있어도 결과가 흔들린다. 「기능 셋 이내」 같은 문장은 사람마다 다르게 읽히지만, 채워진 예시 하나는 그 폭을 좁힌다.

그리고 이 표준이 제대로 작동하는지는 네 가지로 확인한다.

넷 가운데 하나가 미달이면 분량을 늘리지 말고 그 항목 하나를 먼저 채운다. 미달인 채로 길어진 문서는 미달인 사실을 덮을 뿐이다.

이 편이 쓴 용어

지도편이 묶어 둔 어휘 가운데, 이 편의 논지가 기대고 있는 것만 뽑았다.

정리

세 가지가 이 편에 남는다.

첫째, 규칙은 문장이 아니라 차단 장치에 산다. 「승인 전에는 쓰지 마세요」라고 적어 두면 지켜지지 않지만, 쓰기 직전에 검사하는 훅은 승인 기록이 없으면 파일을 만들지 않는다. 종료 코드 하나가 경고와 차단을 가른다.

둘째, 완료는 선언이 아니라 존재로 확인한다. 무엇이 있으면 참인지를 미리 파일로 적어 두면, 「됐다」는 말이 아니라 그 파일이 완료를 증명한다. 증거가 없으면 완료가 거부되므로 부채가 보이지 않는 곳으로 쌓이지 않는다.

셋째, 표준의 값어치는 정교함이 아니라 고정에서 나온다. 여섯 항목 골격에 특별한 것은 없다. 그것이 매번 같은 자리에 있어서, 내가 반복해서 비우던 칸이 비었다는 사실이 드러난다는 것이 전부다.

다음 편은 만든 것을 내보낸 뒤의 이야기로 넘어간다. 무엇을 측정할지 하나만 고르는 일, 그리고 그 수치를 다시 처음 단계의 입력으로 되돌리는 고리가 거기서 갈린다.