흔히 있는 상태: 문서가 없거나(혹은 오래된) 코드베이스에서, 매번 AI에게 구두로 배경을 설명하며 사용하고 있다.

한 번 시간을 내어 AI에게 코드베이스를 해석하게 하고, "코드의 지도"로서 리포지토리(Repository)에 두는 것.

지도에 넣을 것(예):

• 전체상: 어떤 시스템이며, 주요 구성 요소는 무엇인가
• 아키텍처 (Architecture): 계층 구성, 데이터 흐름, 명명(Naming) 및 배치 규칙
• 함정: 이 코드베이스 특유의 전제 조건·역사적 경위·건드리면 위험한 곳
• 입구 색인: 목적별로 "이것을 알고 싶다면 이 파일"

만드는 것은 AI 자신입니다. "이 코드베이스를 해석해서, 새로 참여하는 엔지니어를 위한 지도를 작성해줘"라고 시작하면 됩니다. 인간은 나온 결과물을 리뷰하고, 틀린 부분과 빠진 부분을 수정합니다.

AI는 기억을 가지고 있지 않기 때문입니다. 아무리 우수해도, 매 세션은 "프로젝트에 당일 합류한 아주 우수한 엔지니어" 상태에서 시작됩니다. 고용된 외주 업체와 마찬가지로, 지난번에 무엇을 했는지 기억하지 못합니다.

그래서 무언가를 부탁하면, 우선 코드베이스 탐색부터 시작합니다. 이것이 매번 발생하는 낭비입니다.

지도가 있다면, AI는 처음에 그것을 읽고 감을 잡을 수 있습니다. 변하는 것은 속도뿐만이 아닙니다:

지도는 키워 나간다. 실패했을 때 스스로 하지 않는 루프에서 "정보 부족으로 인한 실패"가 발생할 때마다, 그 정보를 지도에 추가한다. AI가 지도가 오래되었다는 것을 깨달으면 수정하게 한다 -
리포지토리(Repository)에 둔다. Wiki나 개인 메모가 아니라 코드 본체와 같은 장소에. AI가 자연스럽게 읽을 수 있는 장소인 것이 중요하다 -
형식보다 신선도. 깔끔한 문서를 목표로 멈춰 있기보다, 거칠더라도 현상에 맞는 것이 가치가 높다

문서 정비에 대한 가장 큰 반론은 "만들어도 오래된다"입니다. 이것도 인간의 마음가짐이 아니라, 시스템으로 해결합니다.

주 1회 또는 격주 스케줄로, AI에게 "git의 이력과 지도를 비교하여 차이를 수정하는" 작업을 정의해 둔다. 최근의 변경 이력과 지도의 기술 내용을 대조하여, 오래된 부분의 수정안을 내게 한다——자동으로 PR(Pull Request)까지 내게 하면, 인간의 작업은 차이점을 리뷰하고 머지(Merge)하는 것뿐입니다.

"오래되는" 이유는, 업데이트가 인간의 기억과 선의에 의존하고 있기 때문입니다. 스케줄링된 작업으로 전환하면, 지도의 신선도는 운영의 일부가 됩니다. 이것은 개선의 정례화의 실례 그 자체입니다.

이 기사는 이데아라이브(Idealive) 사내의 "AI 주도 개발의 사고방식" 문서(전 12편)를 시리즈로 공개하고 있는 것입니다.