AI 코딩의 진짜 병목은 코드가 아니라 연속성이다

AI에게 "이런 앱 만들어줘"라고 하면 이제 정말 잘 만든다. 코드 생성은 더 이상 어려운 일이 아니다. 그런데 비개발자가 AI로 무언가를 만들어 본 적이 있다면, 진짜 막히는 자리는 코드가 나오는 순간이 아니라는 걸 안다. 며칠 뒤 같은 프로젝트를 이어서 손보려고 새 대화를 열면, AI는 자기가 만든 프로젝트인데도 처음 보는 코드처럼 군다. "왜 이렇게 만들었더라"는 어디에도 남아 있지 않다.

원인은 모델이 약해서가 아니다. 프로젝트의 맥락이 대화 안에만 살아 있었기 때문이다. 세션이 리셋되거나, 도구를 바꾸거나, 그냥 며칠 지나면, 그 맥락은 같이 증발한다. 이 글은 그 문제 — 코드가 아니라 연속성이 병목이라는 것 — 을 정리하고, 다음 AI 에이전트가 코드베이스를 빠르고 안전하게 이해하도록 문서를 설계하는 한 가지 방법을 다룬 노트다. 앞 글에서 다룬 "파일시스템을 에이전트의 기억으로 쓴다"는 패턴을, 이번엔 AI로 만든 프로젝트라는 구체적 상황에 적용해 본다.

진짜 병목은 코드 생성이 아니라 프로젝트 연속성이다

코드 한 덩어리를 새로 짜는 일은 AI가 한 세션 안에서 끝낼 수 있다. 그래서 눈에 잘 띈다. 반면 연속성 문제는 조용하다 — 처음엔 멀쩡히 돌아가다가, 두 번째 세션, 세 번째 도구에서 슬그머니 무너진다.

비개발자에게 이게 특히 아픈 이유는 단순하다. 코드를 직접 읽고 보정할 수 없기 때문이다. 개발자라면 AI가 맥락을 잊어도 자기가 코드를 훑어 "아, 이건 이래서 이렇게 했지"를 복원할 수 있다. 비개발자는 그 복원을 다시 AI에게 맡길 수밖에 없는데, 그 AI도 맥락이 없으면 추측으로 메운다. 추측은 틀리고, 틀린 추측 위에 또 작업이 쌓인다.

그래서 던질 질문은 "AI가 코드를 잘 짜는가"가 아니다. "다음 세션의 AI가, 또는 도구를 바꾼 뒤의 AI가, 이 프로젝트를 빠르고 안전하게 이해하고 이어받을 수 있는가" 다. 이 질문에 "그렇다"라고 답하려면 프로젝트의 맥락이 대화 밖, 저장소 안에 남아 있어야 한다.

코드 검색만으로는 부족하다

여기서 흔한 반론이 나온다. 요즘 도구는 코드베이스 전체를 인덱싱(색인 — 어떤 내용이 어느 파일에 있는지 미리 정리해 두는 것)해서 검색해 주지 않나. 그러면 AI가 알아서 파악하지 않나.

코드 인덱스는 파일이 어디 있는지는 잘 알려준다. 그러나 거기서 멈춘다. 인덱스가 놓치는 것들을 늘어놓으면 이렇다.

• 왜 이렇게 설계됐는지 — 코드는 "무엇"을 보여주지만 "왜 이 구조로 갔는지"는 담지 않는다.
• 어떻게 실행하고 디버그하는지 — 어떤 명령으로 띄우는지, 막혔을 때 어디를 보는지는 파일을 읽는다고 나오지 않는다.
• 어느 파일이 수정하면 위험한지 — 건드리면 연쇄로 깨지는 자리는 파일명에 적혀 있지 않다.
• 이미 정해진 결정이 무엇인지 — "이건 이렇게 하기로 했다"가 안 남아 있으면, 다음 AI가 그 결정을 모르고 뒤엎는다.
• 파일명만 봐선 모르는 동작 — 이름과 실제 동작이 다른 함수, 숨은 부수효과 같은 것.
• 지난 문서화 이후 무엇이 바뀌었는지 — 변경 이력이 없으면 어디까지가 최신인지 알 수 없다.

이 여섯 가지는 코드 어디에도 명시적으로 적혀 있지 않다. 사람 개발자라면 시간을 들여 코드를 읽고 머릿속에서 복원하지만, 그건 세션마다 처음부터 다시 하는 일이다. 연속성의 핵심은 검색 가능한 코드가 아니라, 검색만으로는 안 나오는 이 여섯 가지를 미리 적어 두는 것에 있다.

해법: 다음 AI 에이전트를 독자로 삼는 문서 세트

그래서 떠올릴 수 있는 해법은 문서다. 단, 평소 우리가 떠올리는 README와는 독자가 다르다. 이 문서의 독자는 사람 관리자가 아니라, 이 프로젝트를 빠르고 안전하게 이해해야 하는 다음 AI 에이전트다. 그 차이가 형식을 바꾼다 — 줄글 설명보다 표·목록·코드블록을 쓰고, 토큰(AI가 한 번에 읽는 글의 단위)을 아끼고, 모호함을 남기지 않는다.

구체적으로는 ai-docs/라는 폴더 하나에 정해진 12개 문서를 둔다. 각 문서는 앞의 여섯 가지 빈칸을 하나씩 메운다.

문서	담는 것
00_INDEX	가장 먼저 읽는 진입점. 나머지로 가는 지도.
01_ENVIRONMENT	실행 환경, 명령어, 환경변수 이름(값은 빼고)
02_DEPENDENCIES	패키지 매니저, 의존성, 외부 서비스
03_ARCHITECTURE	시스템 구조와 데이터 흐름
04_STRUCTURE	디렉터리 지도와 진입점
05_DATA_MODELS	DB 스키마, 타입, 저장 방식
06_API	엔드포인트, 인증, 외부 연동
07_BUSINESS_LOGIC	핵심 동작과 워크플로우
08_DEBUG	로그, 테스트, 흔한 실패와 대처
09_STANDARDS	이 프로젝트만의 규칙과 안티패턴
10_WARNINGS	위험한 자리, 부수효과, 건드리면 안 되는 구역
11_TODO	알려진 버그, 미완성 기능, 앞으로 할 일

10_WARNINGS(위험 구역)와 11_TODO(남은 일), 09_STANDARDS(이미 정한 규칙)가 바로 코드 검색이 못 채우던 빈칸이다. 파일이 어디 있는지가 아니라, 어디를 조심하고 무엇이 이미 결정됐는지를 다음 에이전트에게 넘긴다.

사람이 아니라 에이전트들이 이 문서를 만든다

문서 12개를 사람이 일일이 쓰는 건 비현실적이고, AI 하나에게 "전부 써줘"라고 던지면 컨텍스트 창(한 번에 들고 있을 수 있는 작업 기억)이 넘쳐 흐트러진다. 그래서 만드는 과정 자체를 여러 에이전트로 쪼갠다. 흐름은 이렇다.

1. 정찰(scout) — 한 에이전트가 프로젝트를 훑어 .skeleton.md(스켈레톤 — 뼈대 파일)를 남긴다. 여기엔 공유 사실, 런타임·프레임워크 버전, 진입점, "어느 소스 파일이 어느 문서로 가는지"의 대응표, 교차참조 대상, 알려진 위험이 들어간다.
2. 병렬 작성 — 여러 작성자 에이전트가 각자 맡은 문서를 동시에 쓴다. 이들은 스펙(SPEC.md), 스켈레톤, 그리고 자기 문서에 관련된 소스 파일만 읽는다 — 프로젝트 전체를 다 읽지 않는다.
3. 병렬 리뷰 — 리뷰어 에이전트들이 소스를 다시 읽으며 빠진 곳을 메운다.
4. 교차검증(cross-checker) — 마지막 검사자가 모든 문서가 실제로 있는지, Evidence 섹션이 있는지, 교차참조가 실제로 연결되는지, 공유 사실이 문서끼리 일치하는지, 실행 명령이 그럴듯한지, 경고와 할 일이 서로 모순되지 않는지 확인한다.
5. INDEX 마지막 — 나머지가 다 정리된 뒤에야 00_INDEX를 쓴다. 지도는 길이 다 난 다음에 그려야 정확하기 때문이다.

여기엔 앞 글의 패턴이 그대로 깔려 있다. 한 에이전트가 전체를 끌어안지 않고, 일을 독립적인 조각으로 나눠 병렬로 돌리고, 결과를 파일로 남긴다. 문서 생성이라는 작업 자체가 "파일시스템을 공유 상태로 쓰는" 그 패턴의 한 사례다.

그리고 한 번 만들고 끝이 아니다. 코드는 계속 바뀐다. 그렇다고 매번 12개를 통째로 다시 만들면 낭비고 위험하다. 기본 업데이트 방식은 마지막으로 문서화한 커밋부터 지금까지의 git diff(변경 내역)를 떠서, 바뀐 파일이 어느 문서에 영향을 주는지 추려, 그 문서만 골라 고치는 것이다. 전체 재생성은 큰 변경이 있을 때만 쓰는 예외이지 기본값이 아니다. 그래서 00_INDEX에는 "어느 커밋 시점까지 반영했는지"를 기록해 둔다 — 다음 업데이트의 출발점이 된다.

환각을 막는 것은 멋진 문장이 아니라 작성 규칙이다

AI가 쓴 문서에서 가장 무서운 건 틀린 정보가 아니라 그럴듯하게 틀린 정보다. 코드를 못 읽는 비개발자는 그걸 걸러낼 수 없다. 그래서 이 문서 세트는 문장의 품질보다 작성 규칙에 무게를 둔다. 규칙은 짧고 강하다.

• 저장소 증거에서만 쓴다. 모델의 일반 지식이나 추측으로 채우지 않는다.
• 확인 못 하면 UNKNOWN. 빈칸을 그럴듯한 말로 메우는 대신, 모른다고 적는다. 이 한 줄이 환각(그럴듯하지만 근거 없는 생성)을 막는 마지막 방어선이다.
• 비밀값은 절대 기록하지 않는다. 환경변수는 이름만 적고 값은 비운다. API 키·비밀번호가 문서로 새어 나가지 않게.
• 모든 문서는 ## Evidence로 끝난다. 그 문서의 근거가 된 실제 파일 경로를 마지막에 나열한다. 그래서 어느 주장이 어느 파일에서 나왔는지 되짚을 수 있다.
• 산문보다 표·목록·코드블록. 줄글은 모호하고 토큰을 잡아먹는다. 구조화된 형식은 다음 에이전트가 빠르게 정확히 읽는다.

핵심은 UNKNOWN과 ## Evidence의 짝이다. 모르면 모른다고 적고, 안다면 근거 파일을 댄다. 이 둘이 있으면 문서는 검사 가능(inspectable) 해진다 — 사람이든 다른 AI든 "이 주장 어디서 나왔냐"를 따져 검증할 수 있다. 검증할 수 없는 매끄러운 문서보다, 검증할 수 있는 거친 문서가 연속성에는 훨씬 안전하다.

왜 비개발자에게 특히 절실한가

이 패턴은 개발자에게도 쓸모 있지만, 비개발자에게는 단순한 편의가 아니라 안전장치에 가깝다.

개발자는 문서가 없어도 코드를 직접 읽어 맥락을 복원할 수 있고, AI의 환각도 자기 눈으로 거른다. 비개발자에게는 그 두 안전망이 없다. AI가 맥락을 잃으면 복원해 줄 사람이 없고, AI가 그럴듯하게 틀려도 잡아낼 사람이 없다. AI 의존도가 높을수록 연속성의 빈자리는 더 치명적이다.

그래서 비개발자가 AI로 만든 프로젝트일수록, 맥락을 대화에 맡겨 두면 안 된다. 맥락을 세션 리셋과 도구 교체를 견디는 내구성 있고 검사 가능한 계층으로 따로 빼두어야 한다. UNKNOWN이 적힌 문서는 "여긴 아직 확인 못 했으니 다음 세션에서 확인하라"는 정직한 표지판이 되고, ## Evidence는 "이 말 믿어도 되는지 직접 확인할 길"을 남긴다. 코드를 못 읽는 사람에게 이건 프로젝트를 잃지 않을 유일한 방법에 가깝다.

이 문서 세트와 생성 흐름은 앞 글에서 소개한 파일 기반 프로토콜 모음에 "AI용 프로젝트 문서"라는 이름으로 함께 들어 있다. 설치할 런타임 없이, 정해진 파일 규칙일 뿐이다.

저장소: github.com/aminpiano/agentic-workflows

정리

AI 코딩의 병목은 점점 코드 생성에서 멀어지고 있다. 모델은 코드를 잘 짠다. 무너지는 자리는 그 코드가 세션을 넘고 도구를 바꿔 살아남느냐 — 즉 연속성이다. 코드 검색은 파일 위치만 알려줄 뿐, 설계 이유·실행 방법·위험한 자리·이미 정한 결정은 놓친다. 그 빈칸을, 다음 AI 에이전트를 독자로 삼은 문서 세트로 메운다. 저장소 증거에서만 쓰고, 모르면 UNKNOWN이라 적고, 모든 문서를 근거 파일로 닫는다. 그러면 프로젝트의 맥락은 휘발성 대화가 아니라, 세션 리셋과 도구 교체를 견디는 검사 가능한 계층 위에 놓인다. 코드를 직접 못 읽는 사람일수록, 이 계층 하나가 프로젝트의 생사를 가른다.