AI에게 학습 문서를 쓰게 할 때 사람이 하는 일

문서를 얻은 것이 아니라 이해를 복원한 날

2시간짜리 워크숍을 따라간 뒤에도 나는 무엇을 만들었는지 충분히 설명하지 못했다. 복사하고 붙여넣고 배포하고 테스트하는 흐름은 끝까지 따라갔지만, 이해는 손에 남지 않았다. 현장 평가는 10점 만점에 7점이었다. 짧은 시간 안에서 실습을 끝내는 방식은 최선이었지만, 이해 없이 따라간 부분이 분명했기 때문이다.

다음 날 나는 현장 기록과 녹음 스크립트, 안내 자료를 한 세션에 넣었다. 목표는 워크숍 후기를 쓰는 일이 아니었다. 회사에서 맡은 AI 챗봇 일을 더 잘 이해할 수 있도록, 따라 친 결과를 설명 가능한 지식으로 바꾸는 일이었다.

문서는 세 갈래로 나눴다.

현장기록: 그날 실제로 무엇을 했는지 남겼다.
지식정리: 왜 그렇게 연결되고 동작하는지를 풀었다.
회고: 이해가 비어 있던 지점과 검증 결과를 남겼다.

최종 문서는 1,231줄이 됐다. 현장기록 85줄, 지식정리 1,051줄, 회고 95줄이다. 하지만 이 숫자는 문서의 품질을 말해 주지 않는다. 중요한 것은 초안이 그럴듯하게 틀린 지점을 내가 어떻게 발견하고, 무엇을 요구해서 다시 쓰게 했는가였다.

AI가 문서를 쓰고 사람이 검수한다는 말에서 사람의 역할은 오탈자를 고치는 일이 아니다. 독자가 무엇을 모르고, 문맥이 어디서 끊기며, 설명의 기준이 어디서 흔들리는지 요구로 바꾸는 일이다.

초안은 네 번 다른 방식으로 틀렸다

세션 전문은 1,755줄이었고, 내가 남긴 발화는 111건이었다. 한 장을 읽고 문제를 불릿으로 적으면 문서는 고쳐졌고, 나는 그 사이 다음 장을 읽었다. 이 병렬 리뷰에서 반복해서 걸린 문제는 네 가지였다.

독자가 이미 안다고 가정했다

초안은 여러 서비스를 이름만으로 등장시켰다. 나는 그 이름을 안다고 전제하지 말라고 했다. 실제로 나는 Lambda가 무엇인지도 충분히 설명할 수 없는 상태였다.

그래서 지식정리 맨 앞에 사전 지식 장을 붙였다. 각 서비스마다 무엇을 하는 것인지와 오늘 실습에서 맡은 역할을 두 열로 나눴다. 개념을 먼저 놓고 실습을 뒤에 붙이자, 이후의 호출 관계를 읽을 발판이 생겼다.

학습 문서에서 독자 수준은 장식용 도입부가 아니라 설명의 시작점이다. 내가 모르는 상태를 숨기지 않은 것이 오히려 문서의 기준을 세웠다.

코드에서 맥락을 잘라냈다

초안은 에이전트를 만드는 부분만 여섯 줄로 잘라 보여줬다. 핵심처럼 보였지만, 그 조각만으로는 앞뒤에서 무엇을 준비하고 어디로 연결하는지 알 수 없었다.

나는 실제 코드가 훨씬 긴데 일부만 보면 전체 그림이 없다고 지적했다. 이후에는 모듈마다 전체 코드를 두고 ── [부분 N] ── 주석으로 구획을 나눠 설명했다. 테스트에 넣은 JSON도 함께 남겼다.

선택	얻는 것	잃는 것
핵심 몇 줄만 발췌	짧고 빠르게 읽힌다	앞뒤 맥락과 실행 조건이 사라진다
전체를 두고 구획별 해설	코드가 놓인 위치를 함께 본다	독자가 읽어야 할 양이 늘어난다

이번 문서에서는 후자를 골랐다. 처음 배우는 사람에게 필요한 것은 압축된 정답이 아니라, 그 정답이 놓인 자리였다. 즉, 코드 발췌는 짧을수록 좋은 것이 아니라 독자가 다음 행동을 판단할 수 있을 만큼 완결돼야 한다.

비유의 축이 중간에 바뀌었다

초안에는 서비스 관계를 몸·뼈대·뇌로 설명하다가 창고·관문·경비로 넘기는 비유가 있었다. 한 문장 안에서 신체와 건물이라는 두 축이 섞였다. 더 근본적으로는 모델이 맡는 일을 플랫폼 이름이 대신하고 있었다.

나는 이 비유를 고치기보다 걷어냈다. 서비스 간 호출 관계를 여섯 줄의 번호 목록으로 다시 썼다. 어려운 개념을 여는 비유는 도움이 되지만, 대응 관계가 흐려지는 순간 설명은 기억 장치가 아니라 오답이 된다.

비유는 개념 하나를 정확히 겨냥할 때만 쓴다. 관계를 더 정확하게 보여 주지 못하면 사실을 그대로 나열하는 편이 낫다.

이 판단은 문장 취향의 문제가 아니었다. 독자가 비유를 외운 뒤 실제 구성 요소를 잘못 연결하면, 읽기 쉬운 문서가 가장 위험한 문서가 된다.

설명을 그대로 옮기면 관점까지 따라간다

초안은 한 도구는 워크플로우용이고 다른 도구는 에이전트용이라고 대비했다. 하지만 한쪽으로도 에이전트를 만들 수 있고, 실제로 그렇게 만든 서비스가 많다. 소개 자리에서의 단순화를 문서가 그대로 받아 적은 셈이었다.

수정은 도구의 우열을 다시 정하는 일이 아니었다. 차이를 에이전트 여부가 아니라 기본 설계 철학으로 옮겼다. 그리고 비교표 앞에 오해 방지 문단을 넣었다.

발표의 설명: 전달 시간을 줄이기 위해 특정 관점을 강조할 수 있다.
문서의 설명: 강조된 관점과 함께 그 설명이 생략한 조건도 밝혀야 한다.
검수자의 질문: 이 문장이 사실인가가 아니라, 이 문장이 독자를 잘못된 이분법으로 몰아가는가를 묻는다.

이 차이가 없으면 문서는 출처를 인용한 것이 아니라 출처의 프레임을 무비판적으로 복제한 것이 된다.

검수는 답을 주는 일이 아니라 요구를 만드는 일이다

문서를 고치는 동안 나는 매번 정답을 알고 있지 않았다. docstring을 두고도 그냥 주석이 아닌지 의심했다. 확인 뒤에는 파이썬의 """..."""가 문법상 문자열 리터럴이며 __doc__으로 읽힐 수 있고, 에이전트 SDK가 이를 도구 설명에 넣는다는 점을 문서에 반영했다.

이 장면이 중요했다. 검수자는 모든 내용을 미리 아는 사람이 아니라, 불확실한 문장을 그냥 넘기지 않는 사람이어야 한다. 모르는 것을 모른다고 표시하고 확인을 요구하는 것도 검수다.

내가 이번에 실제로 한 요구는 다음처럼 정리할 수 있다.

독자 기준을 밝힌다: 용어를 쓰기 전에 무엇을 안다고 가정하는지 확인한다.
문맥을 보존한다: 코드·그림·표에서 앞뒤 조건이 잘려 나가지 않았는지 본다.
설명의 축을 지킨다: 비유와 분류가 같은 기준으로 끝까지 이어지는지 본다.
출처의 관점을 분리한다: 사실과 소개자의 프레임을 같은 문장으로 옮기지 않는다.
확신 없는 문장을 멈춘다: 의심이 들면 그 의심을 확인 작업으로 바꾼다.

⇒ 검수는 읽는 행위가 아니라, 빠진 조건과 틀린 전제를 다시 쓰게 하는 요구의 집합이다.

손으로 한 실습이 남긴 재료

워크숍 현장에서는 이해가 부족했다. 그럼에도 실습이 이론 수업보다 나았다고 느꼈다. 손으로 배포하고 테스트한 순서가 다음 날 문서를 읽을 때 붙잡을 수 있는 재료가 됐기 때문이다.

가장 크게 실패했던 RAG 실습도 마찬가지였다. 현장에서는 동기화를 놓쳤지만, 지식 테스트에서는 그 문항을 가장 정확하게 답했다. 완성된 문서를 바탕으로 만든 7문항에서 나는 6문항을 맞혔고, 1문항은 부분 정답이었다. 유일하게 흔들린 지점도 앞서 확인을 요구했던 docstring의 역할이었다.

처음 세운 기준을 다시 채점했다

내가 세운 기준은 결과를 길게 만드는 것이 아니라, 따라 한 작업을 설명 가능한 상태로 바꾸는 것이었다. 그 기준으로 보면 결과는 완전히 끝나지 않았다. 7문항 중 한 문항에서 흔들렸고, 문서가 곧 이해 자체는 아니기 때문이다.

그래도 현장에서 막연했던 부분을 질문할 수 있는 문장으로 바꿨고, 그 문장을 다시 검증할 수 있게 됐다. 그래서 이번 문서화는 10점 만점에 7점이었던 실습을 이해의 출발점으로 되돌린 작업이었다고 평가한다.

AI가 초안을 만드는 속도는 분명 유용하다. 그러나 그 초안이 독자의 수준을 넘겨짚고, 맥락을 자르고, 비유를 섞고, 출처의 시선을 그대로 옮기는 순간 속도는 품질이 아니다. 나는 다음에도 문장을 고치는 데서 멈추지 않고, 무엇이 빠졌고 왜 틀렸으며 어떤 형태로 다시 써야 하는지를 요구할 것이다.