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

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

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

AGENTS.md가 길면 에이전트는 매 세션 고정 비용을 치릅니다. 에이전트는 맞는 줄에도 토큰을 쓰고, 틀린 줄 때문에 일까지 망쳐요. 이미 아는 내용을 제쳐 두고 파일에 적힌 낡은 명령까지 따르게 되죠.

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

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

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

사고 구조를 뜯어보면 무섭습니다. 적을 때는 맞던 줄이라서 더 그래요.

코드 밖 merge queue 상태는 바뀌었는데, AGENTS.md의 그 줄은 아무도 고치지 않았어요. 에이전트는 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