코딩 에이전트가 더 이상 사실이 아닌 규칙을 따르는 경우: 해결 방법

가장 위험한 에이전트 버그는 API를 발명하는 모델 자체가 아닙니다. 신뢰할 만큼 충분히 진실하지만, 틀렸을 만큼 오래된(stale) 지침 파일입니다.

AGENTS.md에는 테스트가 npm test로 실행된다고 명시되어 있습니다. 지난달 한 팀원이 이 테스트를 빌드 단계 뒤로 옮겼습니다. 에이전트는 그 규칙을 읽고, 그것을 신뢰하며, 오래된 명령어를 실행하고, 실제로는 실행되지 않은 클린 패스를 보고합니다. 오류는 발생하지 않습니다. 이 오래된 규칙은 설계상 침묵합니다.

이는 아예 규칙이 없는 것보다 더 나쁩니다. 규칙이 없으면 에이전트는 보수적으로 행동하지만, 오래된 규칙은 그것을 자신감 있게 만듭니다.

실패 모드(Failure mode), 구체적으로

지침 파일은 오류를 내지 않고도 오래될 수 있습니다. 이동한 경로를 참조하거나, 변경된 명령어를 사용하거나, 팀이 포기한 관습을 언급할 수 있습니다. 이 규칙이 여전히 사실인지 확인하는 것은 아무것도 없습니다. 왜냐하면 그 규칙은 소유자나 일정이 없는 단순한 산문이기 때문입니다.

그 결과는 신뢰 비대칭성(trust asymmetry)입니다. 파일 자체가 권위 있어 보이므로, 에이전트는 그것을 충실히 따르고 잘못된 일을 자신감 있게 수행합니다. 유지보수자는 그 지침이 벗어났다는 신호를 받을 수 없습니다. 왜냐하면 이 파일은 코드가 불일치할 때처럼 오류를 발생시키지 않기 때문입니다.

지침 파일을 코드처럼 다루기

해결책은 범주 변경에서 시작됩니다. AGENTS.md는 한 번 작성하고 잊어버리는 문서가 아닙니다. 그것은 실행될 때마다 소비되는 시스템에 대한 살아있는 입력값입니다. 이를 README나 API 문서를 유지보수하는 주기와 동일하게 취급해야 합니다. 즉, 검토 트리거(review trigger)가 필요합니다.

이것을 정직하게 유지하는 두 가지 메커니즘이 있습니다. 하나는 사후에 드리프트(drift)를 포착하고, 다른 하나는 규칙이 실제로 동작 변화를 일으키는지 확인한 후에 신뢰하는 것입니다.

메커니즘 1: CI에서의 문서 드리프트 검사

각 에이전트가 볼 수 있는 파일에 해당 파일이 설명하는 경로 목록을 나열하는 covers: 라인을 추가합니다. 그런 다음 각 문서를 커버하는 경로의 마지막 커밋 시간과 비교하는 CI 작업을 추가합니다.

# scripts/check_doc_drift.sh
# doc이 그 주제보다 MAX_LAG_DAYS보다 오래된 경우 실패함
MAX_LAG_DAYS=14
...

당신을 괴롭힐 수 있는 함정: CI 환경의 git checkout은 반드시 fetch-depth: 0를 사용해야 합니다. 그렇지 않으면 git log가 얕은 클론(shallow clone) 이후 단일 커밋만 보게 되어, 모든 문서가 새로 업데이트된 것처럼 보이고 작업이 항상 통과하지만 실제로는 문서는 조용히 노후화됩니다.

메커니즘 두 가지: 폐기하고 재시도하여 규칙 검증하기

doc-drift 체크는 뒤처진 파일을 포착합니다. 하지만 새로운 규칙이 어떤 역할을 하는지 알려주지는 않습니다. 이를 알 수 있는 유일한 방법은 해당 규칙을 격리하여 테스트하는 것입니다.

1. 규칙 추가 또는 수정
2. 현재 아티팩트를 폐기하거나 (브랜치에) 임시 저장(stash)합니다.
3. 업데이트된 규칙으로 새 세션을 시작합니다.
...

만약 기존 아티팩트를 유지하고 계속 진행한다면, 여전히 이전 시스템의 맥락에 오염되어 작업하게 됩니다. 모델은 새로운 규칙을 깔끔하게 적용하기보다는 오래된 작업과 조정하려고 시도할 수 있습니다. 규칙이 작동하는지, 아니면 단순히 증상만을 수동으로 해결했는지 알 수 없습니다. 폐기 후 재시도(Discard-and-retry)만이 유일하게 깨끗한 측정 방법입니다.

파일에 무엇을 포함해야 하는가

규칙을 추가하기 전에, 그 문제가 산문(prose)의 한 줄로 가장 잘 해결될 수 있는지 질문하십시오. 만약 규칙이 테스트, 훅(hook), 또는 권한 경계로 표현될 수 있다면, 대신 거기에 작성하세요. 그러한 요소들은 노후화될 때 크게 실패합니다. 산문은 오직 산문만이 담을 수 있는 것에만 남겨두세요:

• 에이전트가 실수로 절대로 실행해서는 안 되는 비용이 많이 드는 작업
• 에이전트가 건드려서는 안 되는 코드
• 프로젝트 수준의 보안 경계
• 팀원들의 머릿속에만 존재하고 코드에는 보이지 않는 규칙(convention)

그 외 모든 것은 에이전트가 코드 자체에서 읽을 수 있는 맥락입니다. 코드를 재진술하는 규칙은 신호는 추가하지 않으면서 토큰만 추가합니다.

파일에 검증 체크리스트 추가하기

지침 파일(instruction file)은 풀 리퀘스트(pull request)가 끝나는 방식처럼 끝나야 합니다. 짧은 체크리스트는 에이전트에게 완료를 보고하기 전에 반드시 검증하도록 강제하며, 인간이 diff에서 구체적으로 검토할 무언가를 제공합니다.

완료하기 전에

• 4단계의 명령어는 CI에 있는 것과 일치하는가
• 2단계의 경로는 여전히 main 브랜치에 존재하는가
  ...

파일이 검사 기능을 가지고 배포될 때, 오래된 규칙은 더 이상 침묵하지 않습니다. 이는 아무도 솔직하게 체크할 수 없는 확인란(checkbox)이 되며, 이것이야말로 유지보수자가 필요한 정확한 신호입니다.

실제 환경에서의 오래된 규칙

여기에 실패의 형태가 있습니다. 이 실패 때문에 저는 제 자체 명령어 파일에 대한 신뢰를 잃었습니다. 해당 저장소에는 '완료하기 전에 make check를 실행하라'는 규칙이 있었습니다. 한 팀원이 Makefile을 재구성하고 대상(target) 이름을 make ci-check로 변경했습니다. 아무것도 이전 이름(make check)을 참조하지 않았기 때문에 아무 문제도 발생하지 않았습니다. 에이전트는 이 규칙을 읽고, make check를 실행했으며, 대상 없음 오류(target-not-found error)를 받았습니다. 그리고 그 규칙에 '완료하기 전에'라고 쓰여 있었기 때문에, 이 오류가 사전에 존재하는 환경 문제라고 판단하고 어쨌든 완료했다고 보고했습니다. 에이전트는 규칙을 업데이트하지 않았는데, 이는 규칙 자체가 그렇게 하도록 허용하지 않았기 때문입니다.

그것이 한 루프 내에서의 침묵 드리프트(silent-drift) 실패입니다. 규칙은 여전히 페이지에 있었고, 여전히 신뢰받았지만, 틀렸습니다. 아무도 이를 포착할 테스트나 린터(linter), 또는 인간의 개입 경로가 없었습니다. 이는 누구의 규율 부족이 아니었습니다. 시스템에는 오래된 상태를 감지해야 할 장소가 없었던 것입니다.

정직하게 만드는 유지보수 주기

드리프트 검사(drift check)는 실행될 때만 유용합니다. 이를 의존성 업데이트나 라이선스 스캔과 같은 주기에 맞추어 배치하고, 기억날 때 하는 일회성 정리 작업으로 삼지 마십시오.

- 문서를 다루는 경로를 건드리는 모든 PR → 드리프트 검사 재실행
- 모델 버전 업그레이드 시마다 → AGENTS.md를 다시 읽고 이전 모델을 위해 작성된 규칙 삭제
- 매월 → 기억나지 않는 트리거가 된 규칙은 삭제해야 할 규칙입니다

마지막 것이 가장 어렵습니다. 대부분의 규칙은 버그 발생 후에 반응적으로 추가됩니다. 버그가 멈추면, 그 규칙은 남아있고, 1년 후에는 모든 세션에 대한 작은 세금처럼 작용합니다. 문서화된 근거도 없고 최근 트리거 기록도 없는 규칙은 보험이 아니라 임대료입니다. 그것을 삭제하고, 다음 실제 버그가 자리를 되찾도록 하십시오.

이것이 규율의 문제가 아닌 설계의 문제인 이유

본능적으로는 팀을 탓하게 됩니다: 누군가 파일을 업데이트했어야 했다고 생각합니다. 하지만 실제 문제는 그 파일 자체에 자신의 구식화(staleness)를 알리는 메커니즘이 없었다는 것입니다. 소유자도 없고, covers: 라인도 없고, 체크리스트도 없는 문서는 구조적으로 자신이 언제 틀렸는지 알려줄 수 없습니다. 누락된 피드백 루프만으로는 규율로 해결할 수 없습니다.

제가 확신하지 못하는 부분

저는 대규모 코퍼스에서 구식 규칙의 실패율을 측정해 본 적이 없습니다. covers: 라인 드리프트 검사(drift check)와 폐기 후 재시도 루프는 제가 소규모 팀에서 작동하는 것을 본 관행일 뿐, 인용할 수 있는 수치는 아닙니다. 이 메커니즘 자체를 논거로 삼고, 구체적인 임계값은 리포지토리(repo)에 맞게 조정하여 시작점으로 사용하십시오.

제가 확신하는 것은 구조입니다: 신뢰하지만 검증되지 않은 지침 파일은 옛 세상의 방향으로 실패할 것입니다. 해결책은 그 파일에 코드에 부여하는 것과 동일한 검증 규율을 부여하는 것입니다—검토 트리거(review trigger)와 규칙이 여전히 작동함을 증명하는 방법입니다.

출처

• dev.to, "AGENTS.md Pitfalls: 7 Mistakes That Make Coding Agents Less Reliable" (2026)
• dev.to, "How to write an AGENTS.md your AI agent actually follows" (2026)
• dev.to, "Agents Don't Need Memory, They Need Documentation: A Practical AGENTS.md Playbook" (2026)
• dev.to, "Stop Putting Everything in AGENTS.md" (2026)

본 게시물은 AI의 도움을 받아 작성되었습니다. 저자가 내용에 대한 책임을 집니다.