AGENTS.md 한 줄이 21시간 동안 에이전트를 속였습니다

포스트호그 레포에서 PR 하나가 10시간 동안 멈춰 있었습니다. 원인 추적에 45분이 걸렸어요. 범인은 AGENTS.md에 적힌 merge queue 설정 한 줄이었습니다.

그 줄은 코드 밖 상태와 어긋난 채 21시간 동안 살아 있었습니다. 에이전트는 그 줄을 믿었고, 믿은 대로 일했고, 그래서 틀렸어요.

포스트호그가 이 사고를 공개하며 아티클을 올렸습니다. 제목이 도발적입니다. "Your AGENTS.md is holding you back." 당신의 AGENTS.md가 발목을 잡고 있다는 겁니다. 공유 트윗은 조회 26,246에 북마크 671을 모았어요.

넣을수록 좋아지던 시대는 왜 끝났나?

AGENTS.md는 원래 필수품이었습니다. 초기 모델은 레포 구조도, 팀 컨벤션도, 빌드 명령도 몰랐어요. 사람이 한 줄 한 줄 적어줘야 에이전트가 굴러갔습니다.

지금은 사정이 다릅니다. 모델이 레포를 스스로 추론합니다. 구조를 읽고, 컨벤션을 파악하고, 명령을 찾아내요.

포스트호그 진단이 여기서 나옵니다. "에이전트가 그것 없이는 못 굴던 바로 그 컨텍스트가 이제 성능을 깎는다."

쌓아둔 파일은 매 세션 고정 비용이 됩니다. 맞는 줄도 토큰을 먹고, 틀린 줄은 토큰을 먹으면서 일까지 망쳐요. 모델이 이미 아는 내용을 덮고, 낡은 명령을 강제합니다. 넣는 만큼 좋아지던 시대가 끝나고, 지울 수 없는 줄이 성능을 깎는 시대가 온 겁니다.

방향 전환을 이 문장이 요약합니다. "컨텍스트 엔지니어링의 목표는 이제 최대한 빼서 모델의 길을 비켜주는 것으로 옮겨갔다."

큰 회사들도 같은 방향으로 움직였습니다. 앤트로픽은 클로드 코드 시스템 프롬프트를 80% 삭제했어요. 클로드 코드를 만든 보리스 처니는 6개월마다 CLAUDE.md를 지우라고 말합니다. 제품을 제일 잘 아는 사람들이 정기 삭제를 기본기로 못 박은 겁니다. 지시가 자산이던 시절엔 상상하기 어려운 결정이에요.

한 줄이 어떻게 21시간을 잡아먹었나?

사고 구조를 뜯어보면 무섭습니다. 누가 잘못 적은 게 아니라, 적을 때는 맞았던 줄이 틀려졌거든요.

merge queue 설정 한 줄이 코드 밖 상태와 어긋났습니다. 파일은 그대로인데 바깥 세계가 바뀐 거예요. 그 줄은 21시간 동안 에이전트에게 잘못된 지시를 내렸습니다.

에이전트는 지시를 의심하지 않았습니다. AGENTS.md는 사람이 준 명령이니까요. 결과는 PR 10시간 정체, 원인 추적 45분입니다.

포스트호그 온보딩 위저드도 비슷한 함정에 걸렸습니다. 루트 기본값 지시 때문에 모노레포에서 잘못된 프로젝트를 골랐어요. 고친 방법이 상징적입니다. 지시를 다듬은 게 아니라, 지시를 지우고 모델 추천을 쓰게 바꿨습니다.

여기서 이 파일의 구조적 약점이 드러납니다. 문서화된 지시는 코드와 같은 레포에 살지만, 코드와 달리 테스트가 없어요. 낡아도 경고가 안 뜨고, 빌드도 안 깨집니다. 낡은 코드는 컴파일러가 잡지만, 낡은 지시는 에이전트가 그대로 따릅니다. 성실한 에이전트일수록 더 정확하게 틀리는 구조예요.

그러면 지우는 기준은 무엇인가?

포스트호그가 내놓은 기준은 한 줄입니다.

"한 줄 한 줄, 그 줄이 막는 실패를 말할 수 없으면 지워라."

줄마다 존재 이유를 심문하는 겁니다. 이 줄이 없으면 어떤 실패가 나는가. "지난달 에이전트가 마이그레이션 명령을 잘못 짚어서 적었다"처럼 답이 나오면 남깁니다. "왠지 있어야 할 것 같아서"면 그 줄은 습관이거나 미신이에요. 답을 못 하는 줄은 성능을 깎는 후보고요.

실행 순서도 구체적입니다. 먼저 /doctor를 돌려 기계가 후보를 좁힙니다. 포스트호그에서는 /doctor가 안 쓰는 플러그인 3개와 스킬 3개 끄기를 제안했고, 그것만으로 세션당 평균 6K 토큰이 빠졌습니다. 그다음 사람이 남은 줄을 하나씩 검수해요. 기계가 후보를 좁히고, 삭제 판단은 사람이 내리는 순서입니다.

주목할 점은 6K라는 숫자가 극단적인 사례가 아니라는 겁니다. 매일 수백 세션을 돌리는 팀이라면, 안 쓰는 설정 몇 개를 끄는 것만으로 매일 수백만 토큰이 깨끗해집니다. 진짜 회복은 성능이고, 토큰 절감은 그 과정에서 따라오는 덤이에요.

지운 다음에는 무엇으로 채우나?

지운 자리는 실패가 다시 채웁니다.

실패한 프롬프트를 failures.md로 쌓아 회귀 테스트로 돌립니다. 지운 줄 때문에 옛 실수가 재발하면 기계가 먼저 알게 만드는 거예요. 지우기가 무서운 이유는 뭐가 깨질지 몰라서인데, 회귀 테스트가 그 안전망이 됩니다.

에이전트에게 직접 묻는 방법도 있습니다. 어떤 컨텍스트가 있었으면 이 실패를 막았겠느냐고요. 답이 모이면 묶어서 검증하고, 검증을 통과한 줄만 파일에 넣습니다.

넣는 관문이 이렇게 높아진 겁니다. 예전엔 생각나는 대로 적었다면, 이제는 실패가 증명한 줄만 들어갑니다. 파일이 사양서에서 실패 기록으로 바뀌는 순간이에요.

남는 생각

저는 이 글이 문서 정리 팁이 아니라 신뢰 이동 선언이라고 읽습니다.

지시를 쌓는 건 모델을 못 믿던 시절 습관입니다. 이제 모델이 레포를 스스로 읽으니, 오래된 지시가 모델보다 낡습니다. 믿음이 내 문서에서 모델로 옮겨간 거예요. 모델은 매 세션 레포를 새로 읽지만, 내 문서는 적은 날에 멈춰 있으니까요.

이 계정에서 다룬 286개 스킬 팩 경고와 같은 축입니다. 286개를 모은 사람이 한 번에 다 깔면 최악이라고 썼죠. 다 깔아도 최악, 다 적어도 최악. 쌓는 실력이 아니라 덜어내는 실력이 에이전트 시대 실력입니다.

오늘 밤 제 파일도 같은 심문을 거칠 예정입니다. 줄마다 묻습니다. 네가 막는 실패가 뭐냐. 답 못 하는 줄이 절반은 넘을 겁니다.

AGENTS.md는 사양서가 아니라 실패 기록이어야 합니다. 막은 실패를 말할 수 있는 줄만 남기면, 파일은 저절로 짧아져요. 짧은 파일이 부끄러운 게 아니라, 긴 파일이 빚입니다.

---

원문·소스

• 포스트호그 아티클 공유 트윗 (@posthog): https://x.com/posthog/status/2094485724171223409