개발 에이전트에게 코드베이스를 맡길 때 가장 먼저 필요한 것은 전체 파일 목록이 아니다.
필요한 것은 작업 기억이다.
무엇을 고치려는가. 어느 모듈이 책임지는가. 그 모듈은 누구에게 입력을 받고, 누구에게 영향을 주는가. 수정 후 어떤 검증을 해야 하는가.
아래 앱은 이 질문을 위해 만든 작은 모듈 지도다.
파일 트리는 충분하지 않다
에이전트에게 코드베이스를 보여줄 때 흔히 파일 트리부터 넘긴다.
1 | source/ |
나쁘지는 않다. 하지만 파일 트리는 에이전트에게 “무엇이 어디 있는가”만 알려준다. “어떤 작업에서 무엇을 먼저 봐야 하는가”는 알려주지 않는다.
예를 들어 블로그에 실행 가능한 앱을 붙이는 작업은 파일 하나의 문제가 아니다.
1 | source/files/<demo> 정적 앱 |
이걸 매번 파일 트리에서 추론하게 하면 에이전트는 불필요한 탐색을 반복한다. 좋은 개발 에이전트에게 필요한 것은 단순 컨텍스트가 아니라 작업 가능한 구조화된 컨텍스트다.
이번 앱이 지도화한 코드베이스
이번 데모는 실제 Reasonofmoon 블로그 저장소를 대상으로 만들었다.
단, public/**, .deploy_git/**, node_modules/**, 로그, db.json 같은 생성물과 큰 캐시는 제외했다.
분석한 모듈은 10개다.
1 | Content Posts source/_posts |
지도에는 파일 수와 라인 수도 들어 있다.
예를 들어 현재 source/_posts는 27개 Markdown 파일, 약 9,551라인이다.
tools는 16개 파일, 약 3,254라인이다.
scripts/knowledge-links.js는 하나의 파일이지만, 블로그의 포워드링크, 백링크, knowledge-graph.json을 생성하므로 영향력은 크다.
이 숫자 자체가 목적은 아니다. 숫자는 에이전트에게 대략적인 크기와 위험도를 알려주는 신호다.
모듈 지도는 작업 경로다
이 앱의 핵심은 오른쪽에 있는 모듈 설명보다 왼쪽의 Task Route다.
예를 들어 “작동하는 글 발행” 플로우를 선택하면 다음 경로가 강조된다.
1 | Static Demos |
이 경로는 실제로 우리가 최근 글을 만들 때 반복한 순서와 비슷하다.
먼저 앱을 만든다.
정적 경로를 skip_render에 추가한다.
해설 글에서 iframe으로 붙인다.
커버를 만든다.
위키 링크가 지식 그래프에 들어가는지 본다.
테마가 OG 이미지를 제대로 내보내는지 확인한다.
마지막으로 빌드, push, deploy, 공개 URL 200 확인을 한다.
이 플로우는 책 TXT 색인을 검색 앱으로 만들면 LLM Wiki의 최소 단위가 보인다와도 연결된다. 그 글에서는 책을 지식 객체로 만들었다. 이번 글에서는 코드베이스를 작업 객체로 만든다.
에이전트 메모 카드
앱에서 모듈을 클릭하면 YAML 형태의 메모가 나온다.
1 | type: agent_working_memory |
이것이 내가 말하는 개발 에이전트의 작업 기억이다.
에이전트는 매번 코드베이스 전체를 다시 읽을 필요가 없다. 현재 작업에 필요한 모듈, upstream/downstream, 위험 체크, 검증 명령을 먼저 들고 들어가면 된다.
Tool Calling은 함수 호출이 아니라 인터페이스 설계다에서 도구 호출을 행동의 인터페이스라고 했다. 같은 방식으로 모듈 지도는 코드베이스를 향한 에이전트의 인지 인터페이스다.
에이전트가 파일을 직접 열기 전에, 먼저 “이 작업은 어느 경로를 통과하는가”를 볼 수 있어야 한다.
LLM Wiki와 코드베이스 지도
LLM Wiki의 핵심은 벡터 DB가 아니라 지식 아키텍처다에서 말한 지식 아키텍처는 문서에만 적용되는 것이 아니다. 코드베이스에도 적용된다.
코드베이스의 모듈도 지식 노드다.
각 모듈에는 책임이 있다. 입력과 출력이 있다. 의존 관계가 있다. 위험이 있다. 검증 방법이 있다.
이 정보를 문서화하지 않으면 에이전트는 파일을 많이 읽어도 작업의 경계를 놓치기 쉽다. 반대로 이 정보를 구조화하면 에이전트는 더 적은 컨텍스트로도 더 안전하게 움직인다.
그래서 모듈 지도는 RAG나 코드 검색보다 앞에 있어야 한다.
코드 검색은 “어디에 있는가”를 찾는다. 모듈 지도는 “어디부터 봐야 하는가”를 알려준다.
실제 작업에서 어떻게 쓰나
예를 들어 링크 썸네일이 깨졌다고 해보자.
파일 검색만 하면 cover, og:image, head.ejs, theme.og_image 같은 후보가 나온다.
하지만 작업 경로를 알면 더 빠르다.
1 | Content Posts |
이 경로는 문제의 원인을 좁힌다.
글의 cover가 SVG인지, 테마가 page.cover를 OG 이미지로 먼저 쓰는지, 기본 브랜드 PNG가 설정되어 있는지 확인하면 된다.
실제로 우리는 이 문제를 그렇게 고쳤다.
글 목록 커버와 링크 미리보기 이미지를 분리했다.
그 뒤부터는 달의 이성 브랜드 PNG가 social preview에 다시 붙었다.
이런 경험이 모듈 지도에 축적되면 다음 에이전트는 같은 문제를 처음부터 다시 겪지 않아도 된다.
작동하는 글의 세 번째 패턴
최근 만든 글들은 같은 형식을 따른다.
단어 암기 카드를 인터랙티브 HTML로 만들면 무엇이 달라질까에서는 단어 데이터가 학습 카드 앱이 되었다. 책 TXT 색인을 검색 앱으로 만들면 LLM Wiki의 최소 단위가 보인다에서는 책 색인이 LLM Wiki 지식 객체가 되었다. 이번 글에서는 코드베이스가 개발 에이전트의 작업 기억이 되었다.
셋은 서로 다른 앱처럼 보이지만 같은 패턴이다.
1 | 데이터 |
블로그 글은 이 패턴을 설명한다. 앱은 그 패턴이 실제로 돌아간다는 증거가 된다.
다음 버전
지금 데모는 수동으로 정리한 모듈 지도다. 다음 버전은 코드베이스에서 자동 생성할 수 있다.
1 | 1. rg로 파일 목록 수집 |
여기서 중요한 것은 자동화 자체가 아니다. 중요한 것은 에이전트가 코드베이스를 “파일 더미”가 아니라 “작업 가능한 지도”로 보게 만드는 것이다.
개발 에이전트의 성능은 모델 크기만으로 결정되지 않는다. 무엇을 기억하고, 무엇을 잊고, 어느 경로로 움직일지 알려주는 작업 기억이 필요하다.
코드베이스 모듈 지도는 그 작업 기억의 최소 단위다.
댓글
GitHub 계정으로 의견을 남길 수 있습니다. 댓글은 GitHub Discussions에 저장됩니다.