AI 에이전트의 기억력을 높이는 섀도우 문서 트리 전략

커뮤니티 반응

작성자의 접근 방식에 대해 긍정적인 반응이며, 특히 RAG의 한계를 지적하고 결정론적인 문서 매핑 구조를 제안한 점에 대해 공감하는 분위기이다.

주요 논점

01찬성다수

검색에 의존하는 대신 코드 구조를 그대로 따르는 문서 트리가 에이전트의 컨텍스트 유지에 훨씬 확실한 방법이다.

합의점 vs 논쟁점

합의점

AI 에이전트는 시간이 지나면 설계 의도를 잊어버리며, 이를 방지하기 위한 외부 저장소가 반드시 필요하다.
마크다운 형식은 인간과 AI 모두에게 가독성이 좋아 협업 도구로 적합하다.

논쟁점

수동으로 문서 트리를 관리하는 비용과 코드 변경 시 문서 업데이트를 강제하는 프로세스의 지속 가능성에 대한 의문이 있을 수 있다.

실용적 조언

복잡한 프로젝트라면 소스 코드와 동일한 디렉토리 구조를 가진 별도의 docs 폴더를 만들어 관리하라.
에이전트에게 코드를 수정하게 하기 전, 반드시 관련 문서를 먼저 읽고 현재 코드와 일치하는지 확인하는 단계를 프롬프트에 포함하라.

섹션별 상세

소스 파일과 마크다운 문서를 1:1로 매칭하는 섀도우 트리 구조를 도입했다. src/Backend/UserController.php 파일이 있다면 onboarding/src/Backend/UserController.md 파일을 생성하여 코드에 직접 나타나지 않는 설계 의도와 세부 규칙을 기록한다. 에이전트가 소스 파일을 읽을 때 검색이나 임베딩 없이도 즉시 대응하는 동반 문서를 함께 참조하게 하여 정확도를 높인다.

작업의 복잡도에 따라 세 가지 상호작용 모드를 운영한다. 단순 작업은 채팅으로, 중간 규모는 경량 작업 파일로, 대규모 마이그레이션은 단계별 워크플로우를 적용한다. 모든 모드에서 계획 수립 전 문서와 코드 간의 드리프트 체크, 코드 수정 전 승인, 수정 후 문서 업데이트라는 엄격한 규율을 적용하여 정보의 최신성을 유지한다.

마크다운 기반의 문서화는 인간 개발자의 온보딩과 협업에도 큰 이점을 제공한다. 에이전트만을 위한 블랙박스 시스템이 아니라 누구나 읽고 기여할 수 있는 마크다운 형식을 채택함으로써, 한 명의 개발자가 정리한 정보가 팀 전체와 그들이 사용하는 에이전트들에게 동시에 공유되는 효과를 얻었다.

용어 해설

컨텍스트 부패(Context Rot): — AI 에이전트와 대화가 길어지거나 시간이 지남에 따라 초기 의도와 맥락이 손실되어 모델의 성능과 정확도가 떨어지는 현상이다. 이를 방지하기 위해 중요한 의사결정이나 코드의 숨은 의도를 별도의 문서로 기록하여 모델의 주의력을 유지하는 것이 중요하다.
시맨틱 검색(Semantic Search): — 단순한 키워드 매칭을 넘어 단어의 의미와 문맥을 이해하여 관련 정보를 찾는 검색 방식이다. 본문에서는 사용자가 무엇을 모르는지조차 모르는 상황에서는 시맨틱 검색이나 RAG만으로 코드의 세부적인 의도를 파악하기 어렵다는 한계점이 지적되었다.
드리프트(Drift): — 실제 소스 코드의 상태와 이를 설명하는 문서 또는 계획 간에 차이가 발생하는 현상을 의미한다. 에이전트가 코드를 수정하기 전 반드시 드리프트 여부를 체크하여 문서와 코드의 동기화를 유지하는 것이 시스템의 신뢰성을 결정한다.

언급된 도구

agents-remember.md추천링크

코드와 문서를 1:1 매핑하여 에이전트의 기억을 보조하는 레포지토리 구조

언급된 리소스

GitHubagents-remember.md GitHub Repository