자사 API 문서를 다시 쓰거나 노션 운영 매뉴얼을 정리하려다, 이걸 Claude Code 같은 AI 코딩 도구가 알아서 잘 참고하게 하려면 어떻게 써야 하나 하는 물음 앞에서 멈춘 적이 있으실 겁니다. 개발자 없이 서비스를 운영하는 1인 창업가나 기획자일수록 이 질문은 절박합니다. AI 에이전트에게 코드 작업을 맡기는 시간이 늘어날수록, 결국 내가 남긴 문서가 그 에이전트의 유일한 안내서가 되기 때문입니다.
그런데 정작 AI 코딩 에이전트가 어떤 문서를 언제 열어보고, 그 다음에 무엇을 하는지를 실제 행동 데이터로 들여다본 연구는 지금까지 없었습니다. Zhijun Gao와 Jing Chen이 발표한 논문은 이 빈틈을 메우려는 시도입니다. 문서를 잘 쓰는 법에 대한 조언은 이미 넘치지만, 그 조언들이 실제 에이전트의 행동과 얼마나 맞아떨어지는지는 검증된 적이 없었다는 것이 이 연구의 출발점입니다.
에이전트의 문서 소비 행태를 실측하다
연구진은 공개된 두 개 데이터셋을 뜯어봤습니다. 하나는 SWE-chat으로, 557건의 에이전틱 코딩 세션에서 나온 9만4,813건의 개발 이벤트를 담고 있고, 이 중 3,033건이 문서와 관련된 상호작용이었습니다. 다른 하나는 AIDev로, 3만3,097건의 에이전틱 풀 리퀘스트에서 나온 69만260건의 파일 단위 변경 기록입니다. 두 데이터셋 모두 AI 에이전트가 실제로 코드를 작성하는 과정을 그대로 기록한 것이어서, 에이전트의 행동을 추측이 아니라 관찰로 확인할 수 있습니다. 연구진은 에이전트가 어떤 종류의 문서를 열어보는지, 그 참고가 코드 편집이나 테스트로 이어지는지, 문서와 코드 중 무엇이 먼저 바뀌는지를 하나씩 짚었습니다.
코드가 문서보다 먼저 움직인다
가장 먼저 눈에 띄는 결과는 에이전트가 실제로 많이 여는 문서의 정체입니다. 지시 파일이나 작업 노트 성격의 문서가 전체 문서 상호작용의 60.5%를 차지한 반면, 사람이 흔히 떠올리는 전통적 기술 문서는 10.6%, API 레퍼런스는 1.3%에 그쳤습니다. 에이전트는 잘 정리된 가이드보다 지금 무엇을 해야 하는지 알려주는 짧은 지시문을 훨씬 자주 찾는다는 뜻입니다.
문서 참고와 코드 편집의 관계는 생각보다 단순하지 않았습니다. 바로 다음 행동으로 이어지는 확률은 0.002에 불과했고, 보정하지 않은 상태의 연관성도 약했습니다(3-event lift 1.05). 다만 단계를 보정한 모델에서는 참고 이후 편집 가능성이 유의하게 높아졌습니다(OR 1.33, 95% 구간 1.09~1.62). 반면 문서 참고가 즉각적인 테스트로 이어지는 경우는 오히려 줄었습니다(lift 0.23, 보정 후 OR 0.39). 문서를 읽는 행동이 검증을 대신하는 것처럼 보인다는 뜻입니다.
더 흥미로운 대목은 문서와 코드 중 무엇이 먼저 바뀌느냐입니다. 에이전트가 문서를 참고하는 계기는 실패에 부딪혀서가 아니라 스스로 필요하다고 판단해서인 경우가 70.2%로 압도적이었고, 실패 이후 찾아보는 경우는 7.5%에 그쳤습니다. 그리고 코드와 문서를 함께 바꾸는 여러 커밋짜리 풀 리퀘스트에서는, 코드를 먼저 손대는 경우가 문서를 먼저 손대는 경우보다 4.7배 많았습니다.
코드가 먼저, 문서는 나중에
이 결과를 토대로 연구진은 에이전트와 문서의 관계를 선형적인 여정이 아니라 두 개의 엽을 가진 순환 구조로 설명합니다. 문서를 먼저 읽고 코드를 짜는 일직선 흐름이 아니라, 코드 작업과 문서 작업이 서로 다른 리듬으로 오가며 얽힌다는 뜻입니다.
AI 에이전트 친화 문서, 이렇게 씁니다
1인 사업자나 기획자 입장에서 가장 먼저 손볼 곳은 API 레퍼런스나 장문의 가이드가 아니라, 지금 이 프로젝트에서 무엇을 해야 하고 무엇을 하면 안 되는지를 짧게 정리한 지시 파일입니다. 에이전트가 실제로 가장 자주 여는 문서 유형이 바로 이런 성격이기 때문입니다. 반대로 공들여 쓴 API 문서는 상대적으로 덜 참고된다는 점도 새겨둘 만합니다.
또 하나 유념할 부분은, 문서를 아무리 잘 써도 에이전트가 그것을 읽었다고 자동으로 테스트까지 챙기지는 않는다는 사실입니다. 검증이 꼭 필요한 작업이라면, 문서와는 별개로 이 작업 후 반드시 테스트를 실행하라는 지시를 명시적으로 남겨두는 편이 안전합니다. 문서와 코드가 저절로 함께 갱신되지도 않으므로, 코드가 바뀐 뒤에는 관련 문서를 손보라고 별도로 요청하는 습관이 필요합니다.
이 연구가 말하지 않는 것
이 연구는 두 개의 공개 데이터셋에 기록된 행동을 관찰한 것으로, 실험적으로 문서 형식을 바꿔가며 효과를 비교한 것은 아닙니다. 또한 문서가 실행 가능해야 한다거나 검증 가능해야 한다는, AI 에이전트 친화 문서 작성법에서 흔히 전제하는 두 속성이 실제 행동 데이터로는 일관되게 뒷받침되지 않았다고 연구진은 밝히고 있습니다. 즉 이번 결과를 이렇게 쓰면 무조건 더 잘 읽힌다는 공식으로 받아들이기보다는, 지금까지의 통념을 다시 점검해볼 근거로 삼는 편이 정직한 태도일 것입니다.
