AGENTS.md는 조용히 부패한다

Claude Code / Cursor / Codex 등의 에이전트(Agent)에게 전달하는 AGENTS.md

(또는 llms.txt / CLAUDE.md). "셋업은 npm run build", "엔트리는 src/index.ts"라고 적혀 있음에도 불구하고, 리네임(Rename)이나 삭제로 인해 그 지시 사항이 어느샌가 거짓말이 되어간다. 에이전트는 그것을 믿고 사고를 친다.

표기 불일치나 문체가 아니라, "거짓 지시" 그 자체를 CI에서 걸러내는 린터(Linter), agents-lint를 만들었다.

무엇을 검출하는가

일부러 불일치를 넣은 샘플을 통과시키면 다음과 같이 나타난다.

✗ agents-lint: AGENTS.sample.md — 3건의 참조 에러
:8 `npm run build` — package.json에 script "build"가 없습니다
:14 참조 `src/parser.ts`가 존재하지 않습니다
...

npm run <script>가 package.json에 없으면 에러 (유사한 이름 제안)

• 백틱(Backtick)으로 작성된 참조 경로가 디스크에 없으면 에러
• 문제가 있으면 종료 코드(Exit code) 1 반환

CI에서 사용하기 (정착의 핵심)

name: agents-lint
on: [push, pull_request]
jobs:
...

지적 사항은 PR(Pull Request)에 인라인 주석(Inline annotation)으로 나타나며, 작업(Job)이 실패하므로 오래된 설정은 머지(Merge)할 수 없다. 사람이 의식하지 않아도 매 PR마다 실행된다는 것, 이것이 정착의 핵심이다.

언어 독립적

체크하는 것은 "사실"(명령어나 경로가 실제로 존재하는지)이므로, 일본어든 영어든 효과가 있다. 영어권일수록 AGENTS.md의 밀도가 높으므로, 그대로 해외에서도 통할 수 있는 설계이다.

리포지토리 (Repository)

Discussion