AI 에이전트 코드베이스 문서화 전략
한 줄 요약: 에이전트가 코드를 고치기 시작하면 문서는 안내문이 아니라 작업 입력값이 된다. AGENTS.md와 repo-local documentation은 필요하지만, 리뷰·검증·자동화 규칙 없이 늘리면 오래된 지식을 더 그럴듯하게 반복할 수 있다. 왜 지금 AI 에이전트 문서화가 이슈인가 AI 에이전트, AGENTS.md, repo-local documentation을 둘러싼 논쟁은 문서를 어디에 두느냐의 문제가 아니다. 코드 변경을 맡긴 자동화가 어떤 맥락을 믿고 움직이게 할 것인가의 문제다. 선정 글감은 AGENTS.md를 상세 설명서가 아니라 라우팅 계층으로 두고, 실제 시스템 설명은 docs/ 아래에 두자고 제안한다. docs/systems/, docs/flows/, docs/architecture/, docs/glossary.md, ADR(Architecture Decision Record)을 나눠 사람과 에이전트가 같은 지식 기반을 읽게 만드는 방식이다. ...