최근 AI 코딩 에이전트를 사용하는 팀들은 각 작업 세션 후에 에이전트가 모든 정보를 잊어버리는 문제에 직면하고 있습니다. 복잡한 "메모리" 솔루션을 찾는 대신, 이 글은 리포지토리의 문서를 사용하여 이 문제를 해결할 것을 제안합니다. 전통적인 메모리는 검증할 수 없고, 검토할 수 없으며, 공유할 수 없다는 세 가지 약점이 있습니다. 반대로, 리포지토리의 문서는 Git으로 제어되고, 풀 리퀘스트를 통해 검토되며, 모든 에이전트와 모든 사람이 단일 정보 소스를 사용합니다. 이는 일관성을 보장하고 오류를 쉽게 수정하는 데 도움이 됩니다.문서 구조는 세 가지 계층으로 나뉩니다: AGENTS.md (150줄 미만)는 규칙과 명령을 포함하고, docs/agents/*.md는 각 모듈에 대한 자세한 문서를 포함하며, docs/adr/는 아키텍처 결정 기록을 포함합니다. 샘플 AGENTS.md는 필수 명령, 하드 규칙, 모듈 맵 및 불확실할 때의 지침을 포함합니다. 문서를 작성할 때 중요한 원칙은 다음과 같습니다: 정확한 명령을 작성하고, 하드 규칙에 대한 간략한 이유를 포함하며, 에이전트가 실수할 때마다 문서에 한 줄을 추가하는 것입니다.문서가 오래되는 것을 방지하기 위해, 저자는 리포지토리 맵을 자동으로 생성하는 스크립트(repo-map.sh)와 CI에서 코드와의 문서 지연을 확인하는 파이썬 스크립트(check_doc_drift.py)를 사용합니다. 이 스크립트는 관련 문서가 업데이트되지 않은 채 코드가 14일 이상 변경된 경우 오류를 보고합니다. 완전한 워크플로우는 에이전트가 문서를 읽고, 코드를 수정하고, PR을 열고, CI가 문서를 확인하고, 검토/병합하는 것을 포함합니다.결론적으로, 문서를 버전 관리되고, 검토되며, 공유되는 메모리로 취급하면 에이전트가 더 효율적으로 작업하는 데 도움이 될 것입니다. 구체적인 조치에는 다음이 포함됩니다: 간결한 AGENTS.md 생성, 에이전트가 실수할 때마다 문서에 추가, 쉽게 오래되는 문서 부분 자동 생성, CI에 문서 지연 확인 포함, ADR을 사용하여 아키텍처 결정 기록. 이 방법은 에이전트뿐만 아니라 신규 동료가 프로젝트에 쉽게 접근하는 데도 도움이 됩니다.