3부 · 두 장의 문서 — 스킬 문서와 요구사항 명세

본 장의 질문. AI가 생성한 코드를 사람이 검수해야 한다. 그런데 사람은 코드를 읽는 속도가 AI의 생성 속도를 따라잡지 못한다. 이 비대칭을 해결하는 방법은 단 하나뿐이다. 코드를 검수하지 말고, 코드를 재현할 수 있는 문서를 검수할 것. 그 문서가 두 장이다. 대응 규약: AICBOK P.1(자연어 우선), P.2(재현 가능성), P.3(이중 문서), D.2(범위 영역) · 참조: PMBOK 8판 2.2 Scope Performance Domain

3.1 사람이 읽지 못하는 것을 사람이 승인할 수 없다

AI가 생성한 코드를 사람이 읽어 검수한다는 발상은, 작은 규모에서는 가능하지만 일정 임계를 넘는 순간 물리적으로 불가능해진다. 에이전트 하나가 몇 분 안에 수백 줄의 코드를 쏟아내고, 수십 개의 에이전트가 동시에 돌아가는 환경에서는 하루에 생성되는 코드의 양이 사람이 일주일 동안 읽어도 다 읽을 수 없는 수준에 도달한다. 이 조건에서 "사람이 코드를 검수한다"라는 전통적 원칙은 형식적 서명으로 전락하거나 아예 버려진다. 어느 쪽이든 결과는 같다. 누가 어떤 코드에 책임을 지는지가 불분명해지고, 문제가 생겼을 때 추적이 불가능해진다.

이 문제의 해결책으로 자주 제안되는 것은 AI가 코드를 검수하게 하자는 방안이다. 표면적으로 합리적으로 보이지만, 본질에 닿지 않는다. AI가 AI의 코드를 검수하는 구조는 두 가지 이유로 실패한다. 첫째, 검수하는 AI가 생성하는 AI와 동일한 모델을 쓰는 경우, 양쪽이 같은 오류 패턴을 공유하므로 오류가 걸러지지 않는다. 이 현상은 7부에서 자세히 다룰 MAD의 한 형태다. 둘째, 검수하는 AI가 다른 모델을 쓰더라도, 검수의 결과를 최종 승인하는 주체가 AI라면 책임의 소재가 여전히 불분명하다. 책임은 법적·사회적 개념이고, 현 시점의 AI는 법적 주체가 될 수 없다.

남는 선택지는 하나뿐이다. 사람이 검수할 수 있는 층위에 사람이 읽을 수 있는 문서를 두는 것. 그 문서가 코드 자체를 대체할 수는 없지만, 코드의 의도와 절차와 경계를 대체할 수는 있다. 사람은 코드를 읽지 못해도, 이 코드가 무엇을 달성하려는가, 어떤 절차로 만들어졌는가, 어떤 범위 안에서 작동하는가는 읽을 수 있다. 이 세 가지를 자연어와 마크다운으로 담아낸 문서가 본 장의 주제인 두 장의 문서다.

두 장이라는 숫자는 우연이 아니다. 한 장으로는 부족하고, 세 장은 과잉이다. 한 장으로는 작업의 절차와 작업의 요구사항이라는 두 방향의 정보를 동시에 담을 수 없다. 절차는 "이렇게 만들었다"를 기술하고, 요구사항은 "이것을 만들기 위해 무엇이 필요한가"를 기술한다. 두 방향은 서로의 검증 도구가 된다. 절차만 있으면 요구가 누락된 것을 알 수 없고, 요구만 있으면 실제로 그것이 어떻게 구현됐는지를 알 수 없다. 세 장으로 늘리면 문서 사이의 일관성을 유지하는 비용이 기하급수적으로 늘어나고, 결국 두 장과 본질적으로 같은 내용이 중복된다. 두 장이 최소 충분 조건이다.

이 두 장은 다음과 같이 불린다. 스킬 문서(Skill.md) 와 요구사항 명세(역기획서). 각각이 무엇인지를 이하에서 차례로 정의한다.

3.2 스킬 문서(Skill.md) — 재현 가능성의 결정체

스킬 문서는 특정 작업을 재현 가능한 형태로 기술한 마크다운 문서다¹. 작업을 완료한 AI 에이전트가 자신의 작업 과정을 역산해서 작성하며, 이 문서를 다른 AI 에이전트에게 전달하면 동일하거나 거의 유사한 결과물이 다시 생성될 수 있어야 한다. 이 재현성이 스킬 문서의 본질이다. 재현되지 않는 스킬 문서는 스킬 문서가 아니다.

구체적 구조를 두 가지 예시로 설명한다.

첫째는 창작 프로젝트: “세계관 단편소설 100편의 각 단편을 마크다운으로 작성하고 글로서리를 자동 추출해 옵시디안에 저장하라.”

둘째는 프로그래밍 프로젝트: “레거시 REST API v1의 전 엔드포인트를 OpenAPI 3.1 스펙으로 변환하고, 각 엔드포인트의 요청/응답 스키마를 TypeScript 인터페이스로 생성하라.”

두 작업은 규모와 분야가 다르지만 스킬 문서의 구조는 동일하다. 이 작업이 완료된 뒤, AI에게 다음과 같이 요청한다.

“지금까지 우리가 작업한 전 과정을 역산해, 동일한 결과가 다른 AI에게도 재현될 수 있도록 스킬 문서로 정리해라. 시행착오와 중간에 폐기된 접근은 명시적으로 제외하되, 왜 제외되었는지는 기록하라. 최종 절차는 단계별로 명시해, 1단계부터 N단계까지 순서가 명확하게 드러나야 한다.”

이 요청을 받은 AI는 수십 분에 걸쳐 스킬 문서를 생성한다. 분량은 작업의 복잡도에 따라 다르지만, 일반적으로 수만 자 수준이다. 세계관 창작 프로젝트에서 축적된 스킬 문서는 1.5메가바이트에 달한다². 이 용량은 결코 작지 않지만, 이 문서가 존재하는 순간 같은 작업을 다른 팀이 다시 수행할 때 시행착오의 대부분이 제거된다 (실무 관찰 기반 추정).

스킬 문서는 다음 여섯 가지 구성 요소를 포함한다.

① 작업 개요와 목적 이 스킬이 해결하려는 문제가 무엇인지, 어떤 상황에서 적용되는지, 어떤 결과를 만들어야 하는지를 명시한다. 이 섹션이 없으면 다른 AI가 스킬 문서를 읽어도 "이 문서가 내 상황에 맞는가"를 판단하지 못한다.

② 전제 조건(Prerequisites) 이 스킬을 적용하기 위해 필요한 입력물, 도구, 외부 자원을 열거한다. 예를 들어 “옵시디안 볼트가 기본 구조로 설정되어 있을 것”, “마크다운 변환 도구 Markitdown이 설치되어 있을 것”, “모델은 100K 토큰 이상의 컨텍스트를 지원할 것” 같은 조건이다. 전제 조건이 명시되지 않으면 스킬을 적용해도 재현되지 않는 경우가 발생한다.

③ 단계별 절차(Steps) 작업의 핵심이다. 1단계부터 N단계까지, 각 단계에서 무엇을 수행하고 어떤 결과물을 만들며 다음 단계로 어떻게 넘어가는지를 순서대로 기술한다. 각 단계는 독립적으로 실행 가능해야 하고, 이전 단계의 출력이 다음 단계의 입력이 되는 명시적 연결이 있어야 한다. 이 연결이 끊어진 스킬 문서는 중간에 멈춘다.

④ 시행착오와 금지 사항(What Not to Do) 과거에 시도했지만 실패한 접근과 그 실패 이유를 기록한다. 이 섹션은 다른 AI가 같은 시행착오를 반복하는 것을 막는 데 필수적이다. 단지 "이렇게 하라"가 아니라 "이렇게 하지 말라"를 함께 명시한다. 이 부정의 기록이 없는 스킬 문서는 긍정 지시의 목록일 뿐이고, 그것은 원 작업의 지식 중 절반만 담고 있는 것이다.

⑤ 판정 기준(Acceptance Criteria) 스킬이 성공적으로 수행되었는지를 판정하는 기준이다. 몇 개의 출력 파일이 생성되어야 하고, 각 파일이 어떤 구조를 가져야 하며, 어떤 품질 지표(예: 글로서리 추출 정확도, 링크 무결성, 포맷 일관성)를 충족해야 하는지를 명시한다. 이 기준 없이 수행된 스킬은 완료 여부가 주관적 판단에 맡겨진다.

⑥ 변경 이력(Changelog) 스킬 문서 자체의 버전 이력. 이 스킬이 언제 누구에 의해 어떻게 갱신됐는지를 기록한다. AI 환경이 매주 바뀐다는 전제(AICBOK P.6)를 받아들이면, 스킬 문서도 매주 갱신된다. 변경 이력이 없는 스킬 문서는 어느 시점의 AI 환경을 전제했는지 알 수 없는, 역사 없는 문서가 된다.

이 여섯 구성 요소를 모두 갖춘 스킬 문서는 프로그래밍 라이브러리의 README.md와 같은 역할을 한다. 다만 대상이 사람이 아니라 AI라는 점이 다르다. AI는 README를 읽고 해당 라이브러리의 사용법을 학습하듯이, 스킬 문서를 읽고 해당 작업의 수행법을 학습한다.

[배경] 스킬 문서와 클로드 코드 슬래시 명령의 구분 클로드 코드나 유사 CLI 환경에서 "스킬"이라는 이름으로 저장된 프롬프트 묶음이 존재한다³. 슬래시 명령(/skill-name)으로 호출되는 이 파일들은 작업 지시의 단편을 재사용 가능한 형태로 모아둔 것이다. 본서에서 말하는 "스킬 문서(Skill.md)"는 이것과 개념적으로 비슷하지만 목적이 다르다. CLI의 슬래시 스킬은 "무엇을 시킬 것인가"의 템플릿이고, 본서의 스킬 문서는 "어떤 작업이 어떻게 수행되었는가"의 역산 기록이다. 전자는 실행을 위한 도구이고, 후자는 재현과 검수를 위한 문서다. 두 개념을 혼동하면 스킬 문서를 단순 프롬프트 파일로 오해하게 된다.

3.3 역산 작성 — 시행착오를 걷어내는 기술

스킬 문서가 재현 가능해야 한다는 조건은 한 가지 실무적 함의를 낳는다. 문서는 작업이 완료된 뒤에 작성되어야 한다. 작업을 시작할 때부터 스킬 문서를 쓰는 것이 아니라, 작업이 끝난 뒤에 그 결과를 역산해서 문서를 만드는 것이다. 이 순서가 중요하다. 시작 시점에 쓴 문서는 실제 작업 과정에서 일어날 시행착오를 예측하지 못하고, 시행착오를 포함한 문서는 재현성을 망친다.

역산 작성의 원리는 다음과 같다. 작업이 완료된 시점에 AI에게 묻는다. “이 결과물을 만들기 위해 실제로 어떤 절차가 필요했는가?” AI는 자신의 작업 이력을 되짚으며 절차를 정리한다. 그 과정에서 무의미했던 시도, 잘못된 접근, 되돌린 수정은 최종 절차에서 제외된다. 최종 절차에는 직접적으로 결과에 기여한 단계만 남는다. 이 걸러내기가 역산 작성의 첫 단계다.

두 번째 단계는 단계 간의 의존 관계 명시화다. 작업을 실제로 수행할 때 인간은 여러 작업을 동시에 진행하거나 순서를 자주 바꾼다. 이 유연성이 작업 자체에는 도움이 되지만, 문서로 기록될 때는 혼란을 만든다. 재현하려는 사람은 유연성을 따라 할 수 없기 때문이다. 역산 작성은 실제 작업 순서가 아니라 논리적 의존 순서로 단계를 재배열한다. A단계가 B단계의 출력에 의존한다면 A는 반드시 B 뒤에 온다. 실제로 두 단계를 병렬로 진행했더라도, 문서 상에서는 직렬로 기록한다.

세 번째 단계는 제외 사항의 명시화다. "이 작업에서 이런 건 하지 말라"의 목록이다. 예를 들어 “글로서리 추출 시 고유명사와 일반명사를 구분하지 않으면 안 된다”, “마크다운 헤더 레벨을 2단계 이상 건너뛰면 옵시디안 링크가 깨진다”, “세션당 30만 자 이상을 한 번에 입력하면 모델이 첫 페이지를 잊는다”. 이런 경고는 한 번 시행착오를 겪어본 사람만이 쓸 수 있는 내용이다. 그리고 이 내용이 있어야 같은 실수를 다시 겪지 않는다.

역산 작성으로 만들어진 스킬 문서는 사용 지침서가 아니라 역사서에 가깝다. "이 작업은 이렇게 하면 된다"가 아니라 "이 작업을 위해 우리는 이런 절차를 거쳤고, 이런 함정을 만났고, 이렇게 탈출했다"이다. 이 차이가 스킬 문서의 품질을 결정한다. 단순한 지침서는 환경이 바뀌면 무용지물이 되지만, 역사서는 독자가 비슷한 상황을 만났을 때 판단의 근거를 제공한다.

위의 스켈레톤은 실제 사용 가능한 최소 템플릿이다. 이 템플릿을 확장해서 각 팀·각 프로젝트에 맞게 재단(tailoring)하면 된다. 재단의 원리는 AICBOK II의 재단 영역(11부)에서 별도로 다룬다.

3.4 요구사항 명세(역기획서) — 결과에서 요구를 뽑아낸다

두 번째 문서는 요구사항 명세(Requirements Specification)⁴다. 본서에서는 이 문서를 역기획서라고 부른다. “역”(逆)이라는 접두어는 통상의 요구사항 명세와 반대 방향으로 작성된다는 의미다. 통상의 요구사항 명세는 작업을 시작하기 전에 "무엇을 만들 것인가"를 정리해서 쓰는 문서다. 역기획서는 이미 만들어진 결과물을 역산해서 "이것을 만들기 위해 원래 어떤 요구가 있었어야 하는가"를 도출한다.