정교한 버전이 더 정확했지만, 아무 프로젝트에나 쓸 순 없었다

앞 글에서 ai-docs라는 12개 문서 세트를 소개했다. AI로 만든 프로젝트가 세션을 넘어 살아남게 하려고, 다음 AI 에이전트를 독자로 삼아 프로젝트의 맥락을 저장소 안에 적어 두는 문서 묶음이다. 중요한 전제가 하나 있다 — 이건 한 프로젝트만을 위한 맞춤 시스템이 아니라, 어떤 프로젝트에나 꽂아서 쓰는 범용 도구다. 그래서 잘 만들었는지를 따지는 기준도 한 프로젝트가 아니라 "아무 프로젝트에서나 작동하는가"가 된다.

그 글 끝에서 업데이트 방식을 이렇게 약속했다 — 매번 12개를 통째로 다시 만들지 않고, git diff(변경 내역)를 떠서 바뀐 파일이 영향을 주는 문서만 골라 고친다고. 그 "골라 고치기"를 더 똑똑하게 만들고 싶었다. 그래서 ai-docs를 다시 만들기 시작했다. 두 번, 세 번, 네 번. 그리고 결국 거의 처음 버전으로 돌아왔다.

먼저 오해를 하나 걷어내고 싶다. 이건 "정교한 버전과 단순한 버전 중 단순한 쪽을 골랐다"는 이야기가 아니다. 정교한 버전이 실제로 더 정확했는데도 처음 버전으로 돌아왔다. 정교한 쪽이 못 만들어서가 아니라, 범용 도구로 쓰기엔 신경 쓸 게 너무 많고 다양한 프로젝트에 두루 적용하기 어려웠기 때문이다. 이 글은 그 차이 — 정확함과 범용 도구로서의 적합성이 서로 다른 축이라는 것 — 에 관한 노트다.

무엇을 더 똑똑하게 만들려 했나

처음 버전의 업데이트에는 사람의 판단이 한 번 낀다. git diff를 보고 "이 변경은 어느 문서를 낡게 만들지?"를 누군가 — 사람이든 AI든 — 판단해야 한다. 큰 변경이 오면 결국 통째로 다시 만든다. 자동이 아니라 반자동이다.

그래서 욕심이 생겼다. 코드와 문서 사이에 자동 연결을 깔면 어떨까. 코드가 바뀌면 어느 문서의 어느 주장이 낡았는지 시스템이 스스로 감지하고(이걸 drift, 표류 — 문서가 코드에서 미끄러진 정도라고 부른다), 그 부분만 다시 쓰게. 문서를 한 번 만들고 끝이 아니라, 코드를 따라 계속 살아 있게.

이 목표를 향해 세 번을 더 다시 설계했다. 비개발자 언어로 옮기면 이렇다.

버전	핵심 시도	한 줄로
1판	12개 문서 + 만드는 에이전트들	앞 글에서 소개한 그것. 단순하고 검증됨.
2판	문장마다 증거 꼬리표	"이 문장은 이 파일에서 나왔다"를 달아 두고, 그 파일이 바뀌면 표시
3판	구조화된 중간 모델	프로젝트를 먼저 지도(부품과 연결의 데이터)로 뽑고, 글은 그 지도에서 자동으로 그려냄. 코드↔지도↔글 3겹으로 표류 감지
4판	경량 라우터	3판이 너무 무거워서, 가볍게 "바뀐 것만 해당 작업으로 보내는" 형태로

공통된 목표는 하나였다. 문서가 코드를 따라 자동으로 갱신되게 만드는 것. 사람이 "이거 낡았나?"를 챙기지 않아도 되게.

정교한 버전이 실제로 더 정확했다

여기서 흔히 기대하는 전개는 "정교하게 만들었더니 오히려 망가졌다, 그래서 단순한 걸로 돌아갔다"일 것이다. 그런데 그렇지 않았다.

같은 실서비스 코드베이스 — 실제로 운영 중인 수천 개 파일 규모의 프로젝트 — 로 처음 버전과 3판을 나란히 돌려 비교했다. 처음엔 3판이 졌다. 원인을 파고드니 한 가지 근본 결함이었다. 여러 줄에 걸쳐 쓰인 코드(예: 한 줄이 아니라 여러 줄로 선언된 함수나 설정)를 한 줄씩만 보다가 통째로 놓치고 있었다. 그 결함 하나를 고치자 3판은 처음 버전을 넘어섰다 — 더 정확했고, 빠뜨리는 항목도 더 적었다.

그러니까 정교한 버전이 못 만든 게 아니다. 한 프로젝트를 놓고 "얼마나 정확하게 문서를 만드느냐"만 보면, 정교한 쪽이 이겼다. 그런데도 도구로는 채택하지 않았다. 정확도 점수와 도구로 쓸 수 있느냐는 별개의 문제였기 때문이다.

그런데 왜 범용 도구로는 쓸 수 없었나

다시 전제를 떠올려야 한다. ai-docs는 내 프로젝트 하나를 잘 문서화하려고 만든 게 아니다. 언어도 구조도 규모도 제각각인 아무 프로젝트에나 꽂아서, 손 안 대고 돌아가야 하는 도구다. 이 기준으로 보면 정교한 버전들은 세 곳에서 걸렸다.

첫째, 단계가 많을수록 프로젝트마다 신경 쓸 게 늘어난다.

3판은 일곱 단계짜리 파이프라인에 중간 데이터 계층까지 얹은 물건이었다. 잘 돌 땐 좋다. 문제는 한 군데서 어긋났을 때다. 어디서 틀렸는지 추적해야 하는데, 단계가 많을수록 그 추적이 길어지고, 프로젝트마다 손봐 줘야 할 구석이 생긴다. 범용 도구는 "꽂으면 된다"가 생명인데, 매번 손이 가면 그건 더 이상 도구가 아니라 프로젝트다. 코드를 직접 못 읽는 사람에게는 그 한 번의 손길도 벽이 된다.

둘째, 특정 조건에 맞춰 정교해질수록 적용 범위가 좁아진다.

정교한 설계는 보통 "이런 모양의 프로젝트"를 머릿속에 두고 만들어진다. 그래서 그 모양에서 벗어나면 흔들린다. 무게를 덜겠다고 가볍게 다시 만든 버전조차, 정작 크고 복잡한 프로젝트에서는 항목을 빠뜨리기 시작했다 — 작은 프로젝트에선 멀쩡했는데. 범용 도구가 가장 도움이 필요한 순간은 프로젝트가 크고 복잡할 때인데, 하필 거기서 깨지면 도구의 의미가 없다. 정교함이 올라갈수록 "아무 프로젝트"라는 범위가 조용히 줄어들고 있었다.

셋째, 정교함이 노린 그 기능 자체가 아직 아무도 못 푼 미완성 기술이었다.

자동 표류 감지 + 바뀐 부분만 다시 만들기 — 이걸 하겠다고 나선 도구는, 내가 둘러본 범위만 해도 이미 여럿이었다. 상용도 있고 오픈소스도 있어 시장은 붐볐다. 그리고 더 중요한 사실이 있었다. "코드가 바뀌면 문서를 진짜로 자동 재생성해 준다"는 그 핵심을, 내가 들여다본 것들 중 어느 것도 끝까지 가지 못했다. 다들 "초안은 만들어 줄게, 맞는지는 사람이 확인해"에서 멈춰 있었다. 내가 매 버전마다 버그와 재검증에 시간을 쏟은 부분이 정확히 그 "아무도 제대로 못 푼 곳"이었다. 아직 무르익지 않은 기술을 범용 도구의 기둥으로 삼으려 했던 셈이다.

세 가지를 한 줄로 모으면 이렇다. 정확함은 한 프로젝트 안에서 재는 척도이고, 범용성은 도구를 재는 척도다. 정교한 버전은 앞에서 이기고 뒤에서 졌다. 그리고 도구를 고를 때는 뒤의 척도가 이긴다.

곁다리로 배운 것: AI에게 "어느 게 더 나아?"를 묻지 마라

판단 과정에서 하마터면 길을 잘못 들 뻔한 대목이 있어 같이 적어 둔다.

두 버전 중 어느 쪽이 나은지, 처음엔 AI 심사위원에게 블라인드로 평가시켰다(어느 게 어느 버전인지 모르게 하고 점수만 매기게). 결과는 처음 버전의 압승이었다. 하마터면 그 점수만 믿고 끝낼 뻔했다.

그런데 점수를 믿지 않고 직접 코드와 한 줄씩 대조해 보니, 정반대였다. AI 심사위원은 처음 버전의 틀린 주장을 칭찬하고, 정교한 버전의 맞는 주장을 깎고 있었다. 사실을 거꾸로 읽은 것이다. AI는 그럴듯한 문장에 점수를 주지, 그 문장이 코드와 맞는지는 채점하지 못한다.

교훈은 앞 글의 철학과 같은 뿌리다. AI가 만든 결과물의 품질을, 또 다른 AI에게 채점시키면 그럴듯한 오답이 나온다. 진실은 코드와 직접 대조해야만 나왔다. 정교한 버전이 더 정확하다는 사실도, 그 대조를 거치고서야 제대로 보였다.

정리

네 번 다시 만들고, 결국 도구로 남긴 것은 처음 버전에 프롬프트만 조금 손본 판이었다. 거의 출발점으로 돌아온 셈이다. 다시 강조하면, 단순한 게 더 좋아서가 아니다. 범용 도구라는 시험을 끝까지 통과한 게 단순한 버전이었을 뿐이다 — 어떤 프로젝트에 꽂아도 손이 덜 가고, 크고 복잡한 데서도 덜 흔들렸기 때문이다.

헛수고였을까. 아니다. "정교한 버전이 실제로 더 정확하다"는 것도, "그런데도 범용 도구로는 쓸 수 없다"는 것도, 직접 네 번 만들어 보지 않았으면 몰랐다. 버린 세 판이 처음 버전을 고를 근거가 됐다.

비개발자에게 특히 새겨 둘 만한 대목이다. AI로 무언가를 만들다 보면 더 똑똑한 구조를 쌓고 싶은 유혹이 늘 따라온다. 더 자동화하고, 더 영리하게, 더 손 안 가게. 하지만 한 프로젝트에서 멋지게 작동하는 정교한 시스템과, 아무 프로젝트에나 꽂아 쓸 수 있는 도구는 같은 것이 아니다. 도구를 만들 때 던질 질문은 "이 프로젝트에서 얼마나 잘 되나"가 아니라 "아무 프로젝트에서나, 손 안 가고 되나" 다. 그 질문 앞에서는, 더 정확한 버전도 탈락할 수 있다.

저장소: github.com/aminpiano/ai-docs — 이 글에서 다룬 ai-docs 저장소다. 앞 글에서 소개한 네 가지 파일 기반 프로토콜 묶음(ai-docs 포함)은 agentic-workflows에 함께 있다.