모두가 추가하지만 두 번 읽지 않는 파일

AGENTS.md는 코딩 에이전트에게 저장소 안에서 어떻게 일할지 알려주는 표준으로 조용히 자리 잡았다. Codex가 읽고, Cursor와 Cline은 각자의 변형을 읽으며, agents.md 관례는 빠르게 퍼지고 있다. 그래서 팀들은 하나 추가한다 — 그리고 에이전트가 그 절반을 무시하는 걸 지켜본다.

문제는 에이전트가 지시를 못 따라서인 경우는 드물다. 대부분의 AGENTS.md가 새로 온 사람의 온보딩 문서처럼 쓰이기 때문이다: 프로젝트 소개, 배경 설명 문단들, 지향하는 가치. 이건 다음 턴에 모델이 하는 행동을 바꾸는 게 유일한 임무인 파일에는 정확히 잘못된 형태다.

행동을 실제로 바꾸는 파일을 쓰는 법에 대해, 연구 — 그리고 프론티어 랩들 자신의 가이드 — 가 실제로 뭐라 하는지 정리했다.

1. 소개가 아니라 함정부터

실제 컨텍스트 파일을 분석한 실증 연구는, 이 파일들이 기능적 세부(빌드 명령·구현 노트·아키텍처)에 크게 치우쳐 있고, 정작 나쁜 출력을 막는 것들 — 보안·성능 가드레일 — 은 일곱 파일 중 한 개 꼴로만 등장함을 발견했다. 에이전트는 보통 당신이 프로젝트를 설명해 줄 필요가 없다; 코드를 읽으면 된다. 필요한 건 코드로는 알 수 없는 소수의 함정이다: 먼저 돌려야 하는 마이그레이션, 안전해 보이지만 아닌 엔드포인트, 코드베이스가 의도적으로 피하는 패턴.

그것들로 시작하라. 코드를 읽어서 알 수 있는 줄이라면, 그 자리를 차지할 자격이 없을 가능성이 크다.

2. 서술보다 지시

“이 서비스는 인증을 처리한다” 와 "Authorization 헤더를 절대 로깅하지 마라" 사이에는 진짜 차이가 있다. 앞은 서술이고, 뒤는 운영 규칙이다. 지시가 수동적 산문으로 남으면 컨텍스트 포화 속에서 희석되어 조용히 위반된다. 제약처럼 읽히는 규칙 — 이걸 해라, 저건 절대 하지 마라, 항상 X부터 확인해라 — 은 긴 컨텍스트 창을 훨씬 잘 견딘다.

주석이 아니라 명령을 써라.

3. 생각보다 짧게

Anthropic이 최신 모델에 맞춰 Claude Code를 튜닝했을 때, 시스템 프롬프트를 약 80% 줄였는데 코딩 성능에 측정 가능한 하락이 없었다. 교훈은 “프롬프트는 중요하지 않다"가 아니다 — 유능한 모델은 포화가 아니라 방향이 필요하다는 것이다. 당신이 더하는 모든 문단은, 정작 중요한 문단과 주의를 두고 경쟁한다.

핵심만 팽팽하게 담아라. AGENTS.md가 화면 한두 개를 넘겼다면, 아마 모델이 이미 아는 걸 설명하고 있는 것이다.

4. 자기모순을 피하라

지시 파일에서 가장 비싼 줄은 서로 싸우는 줄이다. 한 섹션은 “적절히 문서를 남겨라"라 하고, 다른 섹션은 “주석을 달지 마라"라 하면, 모델은 파일을 건드리기도 전에 어느 쪽이 이기는지 정하느라 추론을 소모한다. 프론티어 랩 엔지니어들은 이제 길고 자기모순적인 정책보다, 명확한 규칙 한 줄을 덧붙이라고(echo "Avoid code comments unless asked" >> CLAUDE.md) 말 그대로 권한다. 일관성은 기능이다.

5. 역할 기반 조회를 위한 구조

파일에 명확한 섹션을 줘라 — 설정, 컨벤션, 가드레일, 함정 — 그래야 모델(그리고 동료)이 전부 다시 읽지 않고 관련 규칙을 찾는다. 이건 의미적 구조다: Markdown으로 포맷만 하는 게 아니라 기능별로 조직하는 것. 값싸고, 복리로 쌓인다.

어디에 들어맞나: 정체성 vs 운영

AGENTS.md는 운영 레이어다 — 이 저장소에서 에이전트가 어떻게 일하나. 이는 에이전트의 정체성 — 누구인가, 목소리, 지켜야 할 원칙 — 과 별개다. 이 둘을 하나의 거대한 파일에 섞는 것이 AGENTS.md가 비대해지는 흔한 이유다.

그 분리가 Soul Spec의 핵심 아이디어다: 정체성은 SOUL.md / IDENTITY.md에, 운영은 AGENTS.md에 살고, 각자 초점을 유지한다. ClawSouls CLI로는 큐레이션된 페르소나를 당신 도구가 기대하는 관례에 바로 설치할 수 있다:

npx clawsouls install clawsouls/surgical-coder --use codex

페르소나는 clawsouls 마커 안에서 당신의 AGENTS.md에 병합되므로, 기존 규칙은 보존된다. 그리고 배포 전에 SoulScan이 이 글이 다룬 자기모순과 빠진 가드레일을 파일에서 점검해 줄 수 있다.

한 줄 요약

좋은 AGENTS.md는 짧고, 지시적이고, 자기모순이 없고, 모델이 코드에서 추론할 수 없는 함정을 앞에 배치한다. 아주 유능하지만 바쁜 동료를 위한 체크리스트처럼 써라 — 그게 정확히 그것을 읽는 대상이니까.