AI 에이전트 스펙 검증, 설계서를 새 세션이 못 찾은 이유

증상 — '한 줄만 치면 됩니다' 뒤에 새 세션이 그 한 줄을 못 읽었다

우리 협업 규칙의 핵심 문장은 '스펙이 곧 프롬프트'입니다. 설계서가 완성되면 구현 명령은 한 줄로 충분해야 하고, 그 한 줄이 규칙 문서에 그대로 적혀 있습니다.

스펙이 완성되면 구현 명령은 "W0 구현 가" 한 줄로 충분. 긴 구현 프롬프트가 필요하다면 스펙이 부실한 것.

이 규칙대로 2026년 7월 25일 영업 인프라 설계서를 다 쓰고 세션을 닫으면서 '한 줄만 치면 된다'고 안내했습니다. 대표가 새 터미널을 열어 그 한 줄을 쳤고, 새 세션은 설계서를 찾지 못했습니다. 문제를 발견한 쪽은 에이전트가 아니라 대표였습니다.

이 사이클은 사람 접점을 정확히 2번으로 묶어 둔 구조입니다. 첫 질문 1회, 스펙 리뷰 1회, 그 밖은 전부 에이전트가 자율로 갑니다. 그래서 두 접점 사이의 어딘가가 끊기면 사람은 그 사실을 다음 접점에서야 알게 되고, 이번에는 그 자리가 구현 시작점이었습니다.

이 문제는 승인 지점을 다룬 승인 게이트를 4개로 줄인 기록과 반대편에 있습니다. 그 글은 사람이 너무 자주 개입해서 생긴 비용을 다뤘고, 이 글은 개입을 줄인 뒤 그 빈자리에서 무엇이 끊겼는지를 다룹니다.

처음 의심한 것 — 스펙이 부실해서 한 줄이 안 먹힌다

규칙이 가리키는 첫 용의자는 스펙이었습니다. 위에 인용한 원칙이 '긴 구현 프롬프트가 필요하다면 스펙이 부실한 것'이라고 못 박아 두었으니, 한 줄이 통하지 않았다면 그 논리의 역방향은 하나입니다. 스펙에 무엇이 빠졌다.

이 가설은 그럴듯했습니다. 규칙은 설계서에 표준 구조 10섹션을 요구합니다. 목적과 설계 원칙, 전체 흐름, 컴포넌트별 계약, 상태·데이터 스키마, 실패 모드와 복구, 보안, 측정, 리팩토링 백로그, 논의 큐, 그리고 외부 사례 대조와 배선 백로그입니다. 열 칸 가운데 어느 하나가 얕으면 구현 세션이 스스로 결정을 만들어야 하고, 규칙은 그 상태를 '구현자가 발명해야 하는 누락된 결정'이라고 부릅니다.

만약 이 가설이 맞다면 처방은 정해져 있습니다. 설계 세션을 한 번 더 열어 얕은 섹션을 채우고, 다시 한 줄을 치게 하는 것입니다. 규칙에는 그 회귀도 허용돼 있습니다. 대표 피드백이 오면 근거 단계로 1회 되돌아갈 수 있고, 타임박스는 최대 2세션입니다.

그런데 이 처방을 실행하기 전에 한 가지가 걸렸습니다. 새 세션은 설계서가 얕다고 불평한 게 아니었습니다. 설계서를 열지 못했습니다.

스펙이 부실한지 무엇으로 재나 — 10섹션 대조와 grep 두 줄

스펙 부실 가설을 확인하는 수단은 두 가지였습니다. 하나는 설계서를 열어 10섹션 표준과 칸마다 대조하는 일이고, 다른 하나는 새 세션이 실제로 무엇을 읽을 수 있었는지 세는 일입니다. 둘 중 후자가 먼저 답을 냈습니다.

새 세션이 시작할 때 자동으로 읽는 파일은 하나입니다. 규칙 문서는 그 파일을 이렇게 설명합니다.

인덱스는 매 세션 자동 주입되는 유일한 파일 — 여기 없으면 못 찾는다

그러니 확인은 검색 명령 두 줄로 끝납니다. 프로젝트의 진행 큐 파일과 세션 기억 인덱스 파일에서 설계서 주제를 찍어 보면 됩니다. 결과는 두 파일 모두 0건이었습니다. 설계서 경로를 적은 곳이 어디에도 없었고, 그 사실은 설계서 내용을 한 줄도 읽지 않고도 확정할 수 있었습니다.

이 확인이 중요한 이유는 방향이 반대라는 데 있습니다. 스펙 부실 가설은 문서 안을 들여다보라고 하고, 실제 답은 문서 밖에 있었습니다. 안을 들여다보는 조사는 아무리 꼼꼼해도 이 답에 닿지 못합니다.

왜 스펙은 범인이 아니었나 — 읽히지 않은 문서는 부실할 기회도 없다

스펙 부실 가설의 알리바이는 순서에 있습니다. 설계서가 얕아서 생기는 실패는 세션이 설계서를 읽은 뒤에 나타납니다. 구현자가 빈칸을 스스로 채우거나, 되묻거나, 잘못 만듭니다. 7월 25일의 실패는 그보다 앞에서 일어났습니다. 새 세션은 한 줄을 받고 어디로 가야 할지 몰랐습니다.

규칙 문서는 이 상태에 이름을 붙였습니다. 설계서는 완성돼 있지만 그 설계서로 가는 인터페이스가 죽어 있는 상태입니다.

배선 없는 스펙 완료 선언 — 진입점 배선 생략 후 "W0 구현 가 하면 됩니다" 안내 = 새 세션이 설계서를 못 찾는 죽은 인터페이스 (2026-07-25 실증).

그러니 설계서가 10섹션을 다 채웠는지는 이 사고와 무관합니다. 다 채웠어도 같은 자리에서 끊겼을 것이고, 절반만 채웠어도 끊기는 자리는 같았을 겁니다. 부실 가설은 틀린 게 아니라 이 사고에 적용할 수 없는 가설이었고, 그 점에서 반증됐습니다.

한 가지 더 짚을 점이 있습니다. 규칙의 원칙 문장 자체가 이 오진을 유도했습니다. '한 줄이 안 통하면 스펙이 부실하다'는 문장은 스펙을 읽을 수 있다는 전제 위에서만 참입니다. 전제가 깨진 경우를 문장이 다루지 않았고, 그 빈칸에 첫 가설이 들어앉았습니다.

진짜 원인 — 설계서가 프로젝트 폴더 밖에 살았고, 그 길을 적은 곳이 0곳이었다

원인은 파일의 주소였습니다. 이 규칙에서 설계서는 프로젝트 저장소 안이 아니라 운영 문서 폴더에 저장합니다. 여러 저장소에 걸치는 시스템 설계라 한 저장소에 넣을 수 없었고, 그래서 설계서는 저장소 밖에서 살게 됐습니다.

새 세션은 저장소 안에서 열립니다. 그 세션이 저장소 밖 문서를 찾으려면 누군가 길을 적어 두어야 하는데, 7월 25일 이전 규칙에는 그 단계가 없었습니다. 스펙 초안 단계가 끝나면 곧바로 태스크 분해로 넘어갔고, 그 사이에 '설계서가 어디 있는지 적는' 칸이 비어 있었습니다.

이걸 사람의 실수로 부르면 다음에도 같은 일이 납니다. 스펙 작성 세션은 자기 규칙을 전부 지켰습니다. 10섹션을 썼고, 완료를 선언했고, 한 줄 명령을 안내했습니다. 빠진 것은 그 세션의 성실함이 아니라 규칙의 단계 하나였고, 그래서 고칠 대상도 규칙이었습니다.

고친 방법 — 배선 3곳과 완료 선언을 바꾸는 grep 2건

규칙에 단계를 하나 끼워 넣었습니다. 태스크 분해와 구현 사이에 '진입점 배선' 단계를 두고, 이 단계를 건너뛰면 스펙 완료를 선언할 수 없게 했습니다. 배선은 3곳이 의무입니다.

• 프로젝트 진행 큐 파일에 항목 1개 — 한 줄 명령의 문구, 설계서의 절대 경로, 첫 구현 단위 요약, 의존 순서, 그리고 '논의 큐는 미응답 시 기본값으로 작동한다'는 한 줄
• 프로젝트 기억 파일 신설 — 명령 문구에서 설계서 경로, 진입 순서, 핵심 결정 요약으로 이어지는 길. 그리고 매 세션 자동으로 읽히는 기억 인덱스 최상단에 1줄
• 설계서 머리에 역링크 — 어느 저장소의 진행 큐와 기억이 이 문서를 가리키는지 1줄. 배선이 끊겼을 때 감사하기 위한 줄입니다

그리고 완료의 정의를 바꿨습니다. 배선 뒤 진행 큐 파일과 기억 인덱스 파일에 검색 명령을 걸어 2건 모두 잡혀야 완료입니다. 1건이라도 비면 스펙은 끝난 게 아닙니다. 완료를 문장으로 선언하던 자리를 명령의 결과로 바꾼 셈이고, 이 검증은 사람이 읽고 판단하는 게 아니라 잡혔다 안 잡혔다 둘 중 하나로 떨어집니다.

구현이 여러 저장소에 걸치면 코드 변경이 가장 많은 저장소를 주 작업 저장소로 잡아 거기에 배선하고, 설계서 머리에 부 저장소를 적습니다. 그래서 대표가 칠 한 줄도 '주 작업 저장소에서 새 터미널에' 한 줄로 고정됐습니다.

이 수리가 지키는 것은 규칙의 약속 하나입니다. 사람 접점 2번. 접점을 늘려서 끊긴 자리를 사람이 확인하게 하는 대신, 끊길 수 없게 배선을 의무로 만들고 끊겼는지를 명령으로 재게 했습니다. 이런 종류의 설계를 검토받고 싶다면 상담에서 맥락을 남겨 주셔도 됩니다.

같은 실수를 막는 장치 ① — 만든 쪽이 '끝났다'고 말하지 못하게 한다

7월 25일 사고를 한 문장으로 줄이면 '만든 쪽이 완료를 선언했다'입니다. 스펙 작성 세션이 자기 산출물을 보고 끝났다고 판단했고, 그 판단을 검사하는 다른 눈이 없었습니다. 배선 단계는 이 문장의 한 사례만 막습니다. 같은 문장이 스펙 검토 자체에도 들어 있었습니다.

7월 30일 개정에서 스펙 초안과 대표 리뷰 사이에 교차검증 게이트를 새로 넣었습니다. 원칙은 한 줄입니다. 스펙을 만든 에이전트가 스펙을 검증하지 않습니다. 대신 스펙 파일만 받은 검토자 5명을 병렬로 띄웁니다. 각 검토자는 작성 세션의 논의도, 중간 결정도, 고려했던 대안도 모릅니다. 규칙은 이 조건을 검토자 프롬프트 첫 줄에 박아 두었습니다.

You have NEVER seen this document before. You have no conversation history with the author. Your only source of truth is the document itself.

검토자가 5명이라고 지적이 다 살아남지는 않습니다. 개정의 핵심은 지적 하나가 통과해야 하는 형식이었습니다. 규칙은 그 이유를 이렇게 적었습니다. 이 형식이 없으면 검토자가 '느낌'으로 지적을 만들고, 그 지적이 헛것인지 가려낼 수 없다는 것입니다. 그래서 지적마다 심각도 4단(P0·P1·P2·P3)과 확신도 앵커 5단(0·25·50·75·100)을 붙이고, 확신도 75 이상은 스펙 원문을 그대로 인용한 첫 증거를 요구합니다. 인용을 못 대면 50으로 강등되고, 50은 P0가 아니면 지적에서 빠집니다.

P3, 곧 문체나 취향 수준의 지적은 아예 내보내지 못합니다. 이미 스펙이 범위 밖이라고 선언한 항목을 놓치고 지적한 것, 검토자 자신의 선호를 원칙처럼 포장한 것, 실패 사례 없는 일반 조언, 나중에 문제될 수 있다는 추측도 모두 억제 대상입니다. 검토자 1명이 실패하면 4명으로 진행하고, 2명 이상 실패하면 중단하고 보고합니다.

검토는 언제 끝나는가 — 사람 느낌이 아니라 P0·P1 개수와 3라운드

검토자 5명의 결과를 모으면 판정은 셋 중 하나입니다. P0도 P1도 0이면 통과, P0는 0인데 P1이 1개 이상이면 수정 후 재검토, P0가 1개 이상이면 중단하고 근거 단계로 되돌아갑니다. 판정을 내리는 주체는 모델의 판단이 아니라 P0와 P1의 개수입니다. '이제 충분한 것 같다'는 식의 종료를 규칙이 금지합니다.

재검토 루프에도 상한이 있습니다. 최대 3라운드이고, 라운드마다 검토자는 완전히 새 세션입니다. 이전 라운드에서 무엇을 고쳤는지 모르고 현재 스펙만 봅니다. 재검토는 완전성과 일관성 검토자 2명만 다시 돌립니다. 나머지 셋은 구조가 바뀌지 않는 한 1회로 충분하다는 판단입니다. 라운드마다 스펙 변경은 커밋으로 남겨, 무엇을 고쳤는지의 증거를 대화 기억이 아니라 git 이력에 둡니다.

루프가 스스로 멈추는 신호도 정해 두었습니다. 지적 개수가 2→4→5처럼 늘면 가정이 틀렸거나 스펙 구조 자체에 문제가 있다는 뜻이라 라운드 수와 무관하게 즉시 중단합니다. 고쳤는데 지적이 하나도 바뀌지 않으면 그것도 중단 신호입니다. 라운드마다 변경률이 30%→15%→3%로 줄면 수렴이고, 40%→35%→40%처럼 제자리면 발산입니다.

한 라운드에서 기각된 지적은 새 증거 없이 다음 라운드에서 다시 막을 수 없습니다. 기각된 지적의 지문을 저장해 두고, 같은 지적이 다시 P0나 P1로 올라오면 자동으로 억제하고 로그만 남깁니다. 3라운드를 다 써도 P1이 남으면 그 항목은 논의 큐로 넘겨 대표 리뷰에서 결정하고, 통과 보고에는 몇 라운드를 돌았고 무엇이 남았는지를 적습니다.

아직 막지 못한 곳 — 구현 단계의 자기 완료 선언

7월 30일 진단은 이 규칙의 빈칸 다섯 개를 남겼습니다. 그중 둘째, 지적의 형식이 없다는 문제는 이번 개정에서 닫혔습니다. 나머지는 열려 있고, 그 가운데 가장 큰 것은 이 글의 주제와 같은 문장입니다.

1번이 남아 있다는 뜻은 이렇습니다. 스펙 단계에서는 만든 쪽이 끝났다고 말하지 못하게 했지만, 구현 단계에서는 여전히 구현한 세션이 테스트 결과를 보고 스스로 완료를 선언합니다. 외부 사례로 인용한 Convergo는 구현이 끝난 뒤 새 세션이 변경 내용을 처음 보는 눈으로 읽고 종료를 판정합니다. 우리 규칙은 그 판정을 아직 코드 단계에 넣지 않았고, 사소하지 않은 작업에만 선택적으로 넣는 처방만 적어 둔 상태입니다.

그래서 이 글의 결론은 '고쳤다'가 아니라 '한 자리를 고쳤고 같은 문장이 한 자리 더 남았다'입니다. 7월 25일에 배운 것은 설계서 품질을 올리는 법이 아니었습니다. 완료를 누가 선언하는지, 그 선언을 무엇으로 재는지를 규칙에 적지 않으면 성실한 세션도 죽은 인터페이스를 남긴다는 것이었습니다.