AI가 코드를 작성하는 것이 당연해지면서, 개발 문서에도 새로운 역할이 늘어났습니다. 인간이 읽기 위해서뿐만 아니라, AI에게 읽히기 위한 문서가 필요합니다. 저희 팀도 그렇게 생각하여 AI를 위한 「만드는 법 문서(作り方ドキュメント)」를 약 3,500행까지 키워왔습니다.

그것을, 전부 버렸습니다. 대신 AI에게 전달하기로 한 것은 코드 그 자체입니다.

자사 WordPress 플러그인 개발 중에 일어난, 조금 이상한 이야기입니다 (지난번에는 유명 플러그인에 수정 제안을 7건 던진 이야기를 썼습니다).

일어난 변화를 먼저 한 장으로 보여드립니다.

渡すものを変えた図。いままで＝AIが写した説明書3,455行を別のAIが読む（ズレたらどちらが正か人には判定できない）。これから＝AIが製品のコードを直接読み、人は2ページだけ書き、検証器が機械採点する

사람이 유지하는 설명서는 3,455행 → 약 100행 (36분의 1). 복사본은 제로로

AI에게 설명서를 쓰게 해도, 따라잡지 못했다 (1일차·아침)

저희 플러그인에는 「어시스턴트(Assistant)」라는 확장 기구가 있어서, JSON 정의 파일을 작성하면 그 안에서 작은 앱이 동작합니다. 그 「만드는 법 문서」가 여러 리포지토리를 합쳐 약 3,455행 있었습니다.

여기서 고백하자면, 이 설명서를 작성한 것은 AI 자신입니다. 인간이 쓰는 것은 힘들기 때문에 AI에게 쓰게 했습니다. 합리적인 판단이었을 것입니다.

하지만 본체 코드는 매주 바뀝니다. AI가 작성한 설명서라도, 유지(다시 쓰기)에는 그때마다 시간과 토큰이 소모됩니다. 많을 때는 보름 동안 「어긋난 설명을 코드에 맞춰 다시 수정하는」 작업만으로 PR 5건 분량이 나옵니다. 수정한 주의 다음 주에는 벌써 다음 어긋남이 자라나고 있습니다. AI에게 쓰게 해도 여전히 따라잡지 못한다는 아이러니한 상태였습니다.

그리고 가장 무서웠던 것은 이것입니다.

설명서와 코드가 어긋났을 때,

어느 쪽이 틀렸는지 인간의 눈으로는 더 이상 판단할 수 없다.

설명서 3,455행에 대해 대조해야 할 상대 코드는 쿼리 실행기만 2,559행, 데이터 정의 2,683행, 저장층 2,817행……. 수천 행 vs 만 행급의 대조 작업은 인간의 업무 범위를 넘어섰습니다.

범인은 「복사본」이라는 구조 (1일차·아침)

1일차 아침, 이 불안을 AI (Claude)와 함께 분해해 보니 모든 것이 같은 곳에서 오고 있었습니다.

설명서란 본체 코드의 「복사본(写し)」이다. 복사본은 원본이 움직이는 순간부터 거짓말을 하기 시작한다.

「유지가 힘들다」, 「미래의 비용을 예측할 수 없다」, 「어느 쪽이 옳은지 모르겠다」——이 세 가지 불안은 전부 복사본을 가지고 있음으로써 발생하는 이자였습니다. 동기화를 자동화하면 이자는 저렴해집니다. 하지만 원본(복사본 그 자체)이 있는 한, 이자는 제로가 되지 않습니다.

질문을 뒤집다 (1일차·낮)

낮 전, 질문이 바뀌었습니다. 「어떻게 하면 설명서를 최신으로 유지할 수 있을까?」가 아니라——

애초에, 항상 최신 자료가 처음부터 있는 것 아닌가?

있습니다. 코드입니다. 스키마(Schema)도, 검증 프로그램도, 실행 코드도, 개발한 순간부터 항상 최신이며 거짓말을 할 수 없습니다. 그리고 AI는 지금 그것을 직접 읽을 수 있습니다. 그렇다면 복사본을 전달하는 것을 그만두고 실물을 전달하면 됩니다.

결정한 형태는 다음과 같습니다.

• 만드는 사람인 AI에게는
  제품 그 자체(스키마·검증기·실행 코드·실례)를 전달한다
• 인간이 유지하는 문서는
  단 2페이지뿐. 「어기면 망가지는 규칙만을 적은 지시서 1장(92행)」과 「인간용 사용법 1장」
• 3,455행 → 약 100행.
  36분의 1. 게다가 규칙은 좀처럼 바뀌지 않으므로, 이 100행은 거의 다시 쓸 일이 발생하지 않는다.

가장 효과적이었던 발명은 기술이 아니라 선언이었습니다. 그 가장 무서운 문제——어긋났을 때 어느 쪽이 옳은가——는 이렇게 종이에 써서 고정하니 사라졌습니다.

코드가 항상 옳다. 복사본은 항상 패배한다. 어긋나면 내용을 읽지 않고 코드로부터 덮어쓴다.

읽어서 비교하며 중재한다는 업무 그 자체가 사라집니다. 두려움의 핵심은 판정을 잘하는 것이 아니라, 판정을 불필요하게 함으로써 사라졌습니다.

비유하자면, 두꺼운 운전 매뉴얼을 계속 유지하는 것을 그만두고, 차체 그 자체를 만지게 하며, 교통 규칙(어기면 사고가 나는 규칙)만을 종이로 전달하는 것과 같습니다. 차가 신형이 되어도 만져보면 알 수 있습니다. 종이를 다시 쓸 필요가 없습니다.

실험 ① — 무작정 부딪히기, 힌트 없음 (1일차·오후)

이론은 깔끔합니다. 하지만 「AI가 코드를 올바르게 해석해 줄지는 AI 하기 나름이겠지」라는 불안도 아침 시점에 입 밖으로 나왔었습니다. 그래서 오후, 가장 까다로운 조건으로 시험해 보았습니다.

아무것도 모르는 AI 한 대를 준비합니다. 오늘의 논의 기억은 제로. 전달하는 것은 코드 일체와 92행의 지시서뿐. 의뢰는 한 줄——「가장 많이 조회된 페이지 상위 10개를 표로 보여주는 어시스턴트를. 기간은 지난달」. 힌트 추가는 금지. 막히더라도 도와주지 않습니다.

약 5분 후, 결과가 돌아왔습니다. 정의 파일, 번역 2개 언어, 플러그인 헤더, 아이콘까지 한 세트가 모두 갖춰져 있었고, 검증 프로그램(Verification Program)을 단번에 통과했습니다. 지시서의 규칙인 「검증을 통과하지 않으면 완성이라고 말하지 않는다」도 지켰습니다. 그뿐만 아니라, 이 AI는 검증기(Verifier)가 고장 나지 않았는지 의심하며, 일부러 잘못된 정의를 입력해 「제대로 불합격되는지」까지 스스로 확인했습니다. 의심이 많군요. 합격의 무게가 더해졌습니다.

実験の作法。渡したのはコード一式と92行の指示書だけ。初見のAIに、ヒント追加禁止・詰まっても助けない条件で依頼し、約5分で検証に一発合格。おまけに見本の誤りの発見・幽霊機能の報告・検証器の自己確認まで

실험 조건과 결과. 이후의 실험 ②~⑤도 모두 이와 동일한 방식

예상치 못한 수확 — 코드는 설명서보다 정직했다 (1일 차·오후)

실험에는 대본에 없던 볼거리가 두 가지 있었습니다. 개인적으로는 방침 그 자체보다 더 설득력이 있습니다.

① 샘플의 거짓말을 처음 보는 AI가 간파했다. 제품에 동봉된 샘플 어시스턴트에는 사실 숫자가 실제보다 크게 나오는 오류가 숨어 있었습니다. 실험 중이던 AI는 샘플을 흉내 내려다가, 문득 발을 멈췄습니다. 샘플의 방식이 코드에 적힌 주석(Note)과 일치하지 않는다는 것을 깨닫고, 올바른 방식으로 전환한 뒤 「샘플과 주석이 일치하지 않습니다」라고 보고해 왔습니다.

이 구멍은 수기로 작성된 문서를 몇 번이나 전수 조사(Inventory)해도 나오지 않았던 것입니다. 설명서는 「작성자의 이해」를 투영하기 때문에, 작성자가 깨닫지 못한 실수는 그냥 지나치게 됩니다. 코드를 읽게 하는 방식은 읽는 사람이 매번 제로 베이스에서 대조하기 때문에, 실수가 「발견되는 쪽」에 서게 됩니다. 5분의 실험이 인간의 전수 조사 수 회분만큼의 검품이 되었습니다 (샘플의 오류는 당일 수정했습니다).

② 유령 기능의 발견. 구현 코드에는 사용 예시와 함께 존재하지만, 설정 문법이 그것을 허용하지 않는 —— 즉, 어떤 설정에서도 영원히 호출할 수 없는 기능이 있다는 사실도 동일한 실험에서 발견되었습니다. 여기서 중요한 것은 AI의 행동입니다. 지시서의 규칙인 「불일치를 발견하면 수정하지 말고 보고한다」에 따라, 손을 대지 않고 보고만 해왔습니다. 작성한 규칙이 처음 보는 AI를 상대로 첫 시도부터 기능한 순간이었습니다.

읽지 못한다면? — 안전장치는 문장이 아니라 기계

그럼에도 AI는 언젠가 규칙을 읽지 못할 수도 있습니다. 이 방식이 그것을 허용할 수 있는 이유는, 방어 기제를 문장에서 기계로 옮겼기 때문입니다.

다시 한번 뒤집히다 (1일 차·저녁)

방침이 확정되고 실험에서도 승리한 저녁. 마무리 잡담으로 던진 한마디가 마지막 군더더기를 깎아냈습니다.

「AI에게 전달하는 그 34개 파일은 복사본이야? 그러면 이중 관리나 한쪽이 구형이 되는 문제가 또 발생하지 않을까?」

정곡을 찔렸습니다. 낮 시점의 구현은 본체에서 기계적으로 복사한 「키트(Kit)」 34개 파일이었습니다. md5로 동일성을 기계 검증할 수 있으니 안전한 복사본이라고 설계했습니다. 그럼에도 불구하고 —— 복사본은 복사본입니다. 릴리스할 때마다 다시 구워야 하는 의무가 남고, 잊어버리면 오래된 키트가 배포됩니다. 아침에 죽였다고 생각했던 문제의 작은 생존자가 주머니 속에 남아 있었습니다.

「그럼, 배포하는 제품 ZIP 그 자체를 읽게 하면 되지 않을까」. 소스를 열어 확인해보니, 제품은 스키마(Schema)도 검증 엔진(Verification Engine)도 처음부터 자신 안에 가지고 있었습니다. 어시스턴트를 불러올 때마다 런타임 검증(Runtime Verification)을 수행하는 방어선이 코드에 실재하며, 이를 위한 스키마 정의와 검증 클래스도 배포 ZIP에 동봉되어 있었습니다. 즉 제품 ZIP은, 스스로를 검증할 수 있는 완전한 교재였던 것입니다.

최종 형태 = 최신 제품 ZIP + 종이 2장 + 수십 줄의 검증 래퍼(Wrapper) (ZIP 내부의 엔진을 호출하기만 하는 접착제 역할). 키트는 폐지되었습니다. 하루의 추이를 한 줄로 요약하면 다음과 같습니다.

설명서 3,455행 → 키트 34개 파일 → 제로 (실물 그 자체)

후일담 — 정말로 지웠다 (2~3일 차)

여기까지가 1일 차입니다. 결정만 하고 끝내고 싶지 않았기에, 이어지는 며칠 동안:

• 2일 차: 실제 상황과 동일한 구성(제품 ZIP + 종이 2장 + 래퍼)으로 실험 ② 진행. 결과는 솔직히 말하자면 "방식은 성립하지만, 한계도 보였다"였습니다. AI는 길을 잃지 않았고, 검증도 기능했습니다. 반면, 제품 측에 경로가 마련되어 있지 않은 기능(기간 비교)은, 지시서를 어떻게 작성하더라도 AI가 추측으로 채우려 합니다. 즉, "지시서의 빈틈"과 "제품의 빈틈"이 실험을 통해 구분되었습니다. 이 또한 수확으로서 프로덕트 측의 과제가 되었습니다. -
  3일 차: 수기 미러(handwritten mirror) 문서 3,492행을 삭제하는 PR을 머지(merge). 리포지토리에서 "복사본"이 사라졌습니다.

사람이 유지하는 문서는 정말로 2페이지가 되었습니다.

4일간의 움직임을 다시 한 장으로 정리하면 다음과 같습니다.

説明書を捨てた4日間の全体地図。上段が出来事のタイムライン、下段は人が維持する説明書の量が3,455行から約100行（36分の1）へ潰れていく様子

위=사건 타임라인 / 아래=사람이 유지하는 설명서의 양 (실제 스케일). ✓는 검증 프로그램에 첫 시도에 바로 합격

텍스트 버전 (표)

어디까지 확인했고, 무엇이 남아있는가 (솔직한 각주)

확인된 사항:

• 실험은 여기까지 총 5건입니다. 4일 차에는 "복잡한 과제" 3연전—비율 계산 열 + 설정 저장 / 설명서에 한 줄도 없는 목표 분석 / 16개 화면의 연출물—까지 진행했지만, 3건 모두 12~17분 만에 첫 시도에 바로 합격했습니다. - 실험을 할 때마다 제품 측의 빈틈도 발견되고 있습니다 (예를 들어 "검증도 에러도 통과하는데, 결과만 조용히 비어버리는" 결합 키(結合 key)의 함정. 발견한 당일에 과제로 등록하고 있습니다). 방식이 빈틈을 숨기는 것이 아니라, 빈틈을 찾는 장치로서 기능하고 있는 것은 기분 좋은 오판이었습니다. - 설명서가 침묵하는 곳에서는, 코드 측에 둔 "이 숫자는 세어서는 안 된다"라는 한 줄의 선언만을 근거로 AI가 위험한 집계를 피했습니다. 설명을 늘려 쓰는 것보다 선언을 코드에 두는 것이 더 효과적이다—현재로서는 그렇게 보입니다.

아직 남아있는 한계:

• 과제는 모두 "한 명의 AI가 하나를 만드는" 형태입니다. 다수 인원의 운용이나, 더 큰 어시스턴트는 미검증 상태입니다. - 이 방식은 코드를 읽고 검증기를 실행할 수 있는 에이전트형 AI (Agentic AI) (Claude Code 등)를 전제로 합니다. 채팅형 AI만 사용할 수 있는 사람을 위한 대책은 미해결 상태입니다. - "코드가 항상 정답이다"라는 것은, 코드가 읽을 수 있는 품질임과 기계 검증의 망(network)이 있음을 전제로 합니다. 망을 만들기 전에 설명서부터 버리면 아마 사고가 날 것입니다 (저희도 순서가 반대였다면 선택하지 못했을 것입니다).

요약

1일 차 아침, "문서 유지 비용의 미래가 보이지 않는다"며 고민했습니다. 그날 저녁에는 "유지하는 것은 종이 2장. 오류는 검증망이 막는다. 증거는 5분의 실험"이 되어 있었습니다.

문서는 "쓰는 양"이 아니라 "복사본을 가질 것인가"에 따라 수명이 결정된다—라는 것이 이번의 배움입니다. AI가 코드를 직접 읽을 수 있게 된 지금, "AI를 위해 친절한 문서를 작성하는 것(쓰게 하는 것)"은 사실 이제 최적해(optimal solution)가 아닐지도 모릅니다.

여러분의 프로젝트에서는 AI를 위한 문서를 어디까지 작성하고 계신가요? "우리는 이것 때문에 고생했다"와 같은 이야기가 있다면 꼭 댓글로 들려주세요.

Discussion