地図があれば迷わず最短ルートで進める

이렇게 한다

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

지도에 넣을 내용 (예):

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

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

왜

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

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

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

운용의 팁

失敗のたびに地図が濃くなる

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

"어차피 낡게 된다"에 대한 답변: 신선도 유지를 작업(Job)으로 만들기

문서 정비에 대한 가장 큰 반론은 "만들어도 낡게 된다"는 것이다. 이것도 인간의 마음가짐이 아니라, 구조(Mechanism)로 해결한다.

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

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

공지

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

Discussion