AGENTS.md는 도구 전환에도 살아남아야 한다

이질감(마찰)은 에디터 자체가 아니다

최근 저는 Cursor, Cline, Claude Code 간을 오가며 작업했습니다. 각 도구의 학습 곡선 자체는 괜찮았습니다. 하지만 실제로 제 시간을 잡아먹은 것은 프로젝트를 각 도구에 다시 설명하는 과정이었습니다.

저장소(repo) 레이아웃도 같습니다. 테스트 명령어도 같습니다. "이 파일은 건드리지 마세요."라는 지시도 같습니다. "인증 흐름(auth flow)은 여기에 있고, 저기에 있는 게 아닙니다."와 같은 내용도 마찬가지입니다. 저는 이 내용을 Cursor에 붙여넣고 올바르게 작동하는 것을 확인한 다음, 다른 작업을 위해 Cline으로 전환하면 처음부터 다시 시작해야 했습니다. 도구는 프로젝트에 대한 아무것도 기억하지 못했습니다. 제가 클립보드 역할을 해야 했습니다.

이것이 바로 아무도 예산 책정(budget)을 하지 않는 비용입니다. 도구의 학습 곡선이 아니라, 도구마다 반복적으로 설명해야 하는 '재설명' 과정입니다.

각 도구는 자신만의 파일을 원한다

Cursor는 .cursorrules를 읽습니다. Claude Code는 CLAUDE.md를 읽습니다. Cline은 자체적인 지침을 읽습니다. 그리고 다른 많은 도구들은 누군가 만든 가장 근접한 교차 벤더(cross-vendor) 규칙인 AGENTS.md를 읽습니다.

만약 여러분이 거의 동일한 세 개의 파일을 유지한다면, 결국 이탈하게 됩니다. "pnpm 사용"이라고 적힌 파일은 저장소가 bun으로 이동하면 구식이 됩니다. 테스트 명령어를 나열한 파일은 Makefile의 타겟 이름이 바뀌면 오래된 정보가 됩니다. 6개월 후, 여러분의 Cursor 에이전트는 더 이상 존재하지 않는 명령을 실행하고 있고, Claude Code 에이전트는 사용 중단된 디렉토리를 읽고 있을 수 있습니다.

해결책은 세 개의 파일을 동기화하는 데 더 규율적(disciplined)이 되는 것이 아닙니다. 해결책은 이 모든 도구가 읽는 단 하나의 짧은 파일이 존재하게 하고, 각 도구별 래퍼(wrapper)를 그 파일로 연결되는 얇은 포인터로 만드는 것입니다.

실제로 공유 파일에 포함되어야 할 것들

본능적으로 모든 것을 쏟아내고 싶을 겁니다. 저항하세요. 이 파일은 여러분이 어떤 도구를 사용하든 관계없이 참인 내용, 그리고 에이전트가 이를 모른다고 가정할 때 잘못하게 될 내용을 위한 것입니다.

구체적으로는 다음과 같습니다:

• 테스트 실행 방법: 정확한 명령어(‘테스트 스위트’가 아님)를 명시해야 합니다. 환경 변수나 데이터베이스가 필요하다면 이를 언급하세요.
• 파일 위치: 에이전트(agent)가 가장 자주 접근할 가능성이 있는 12개 디렉토리와 절대 건드려서는 안 되는 12개 디렉토리를 명시합니다.
• 변경 사항 검증 방법: 성공적인 실행(green run)의 모습과 수정이 작동했음을 증명하는 명령어를 알려줍니다.
• 주의할 점 (Gotchas): "여기서는 lodash를 사용하지 않습니다," "마이그레이션 러너는 오프라인 전용입니다," "이 패키지는 ESM 전용입니다"와 같은, 당신에게는 명확하지만 에이전트에게는 보이지 않는 것들.
• 이 리포지토리(repo)에서 '완료됨(done)'의 의미: 조직 전체의 미션이 아닌 로컬 정의를 제시합니다. (예: 테스트 통과, 린트(lint) 통과, 빌드가 X를 생성함.)

속하지 않는 것들: 아키텍처 에세이, 제품 로드맵, 기여 가이드의 모든 규칙, 커밋 메시지 스타일에 대한 당신의 선호도 등. 에이전트는 필요할 때 그것들을 읽을 수 있습니다. 공유 파일은 매 세션마다 반복하는 것을 막아주는 50줄의 핵심 정보입니다.

문장(prose)으로 전혀 작성되어서는 안 되는 것들

이것에 대해 저의 생각을 바꾼 부분이 있습니다. 사람들이 지침 파일(instructions file)에 쓰려고 하는 것들 대부분은, 알려주는 것이 아니라 도구가 직접 읽을 수 있어야 할 사실들입니다.

빌드 파이프라인(build pipeline)이 존재한다면, 에이전트는 Makefile을 읽을 수 있습니다. 테스트 설정이 존재한다면, config를 읽을 수 있습니다. 디렉토리 구조가 존재한다면, ls 명령어를 실행할 수 있습니다. 당신은 그것을 서술할 필요가 없습니다. 리포지토리를 글로 많이 설명할수록 더 낡게 됩니다—왜냐하면 그 글(prose)이 진실의 원천이 아니라 파일들이기 때문입니다.

예외는 기계가 읽을 수 있는 곳 어디에도 표현되지 않은 것들입니다: "저 파일은 건드리지 마세요," "우리는 의도적으로 이 종속성(dependency)을 고정했습니다," "스테이징 배포(staging deploy)는 금요일에 수동으로 진행됩니다." 이것들은 공유 파일에 속해야 합니다. 왜냐하면 다른 어떤 것도 에이전트에게 알려주지 않을 것이기 때문입니다.

그리고 바로 이 지점에서 API 계약(API contract)이 어색하게 자리 잡고 있습니다. 사람들은 명령어 파일에 '인증 엔드포인트는 사용자 객체를 반환한다', '오류는 이런 형태로 모양지어지고 있다', '버전 관리는 헤더에 있다'와 같이 API가 어떻게 작동하는지에 대한 문단을 작성합니다. 하지만 레포지토리에는 이미 모든 것을 말해주고 있는 OpenAPI 사양(spec)이 있습니다. 더 정확하게는, 모든 도구가 파싱할 수 있는 형식으로요. 서술적인 버전은 변하지만, 이를 진실의 원천(source of truth)으로 취급한다면 사양은 그렇지 않을 것입니다.

결국 우리는 OpenAPI 사양을 유지하기로 했고, 이는 모든 AI 코딩 도구가 마크다운에서 재설명하는 대신 직접 읽는 기계 판독 가능한 아티팩트입니다. 에이전트가 엔드포인트가 무엇을 반환해야 하는지 알아야 할 때, 그것은 사양을 읽습니다. 사양이 변경되면, 에이전트는 자동으로 새로운 동작 방식을 얻게 됩니다. 동기화할 필요가 있는 명령어 파일이 없습니다. 이것은 공유되는 AGENTS.md와 같은 원칙입니다. 단지 레포지토리의 이미 정형화된 부분이 적용되었을 뿐입니다.

기준 테스트 (A litmus test)

명령어 파일에 한 줄을 추가하기 전에, 다음 질문을 던지세요: 내가 이 내용을 적지 않으면 에이전트가 이것을 잘못 이해할까?

만약 대답이 '아니다'라면 — 도구가 발견할 수 있거나, 파일이 존재하거나, 테스트 명령어가 Makefile에서 명확하다면 — 아무것도 쓰지 마세요. 당신은 그저 썩어버릴 노이즈를 추가하는 것일 뿐입니다.

만약 대답이 '그렇다'라면 — '에이전트가 생성된 파일을 계속 편집한다', '에이전트가 로컬에서 존재하지 않는 docker-compose를 시작하려고 계속 시도한다', '에이전트가 우리가 폐기한 프레임워크를 사용한다고 가정한다'와 같은 경우 — 그때 쓰세요. 단 한 번만, 공유 파일에요. 당신이 실제로 잘못되었을 때 업데이트할 만큼 충분히 짧게 유지하세요.

요점 (The point)

당신은 도구를 바꿀 것입니다. 아마 다음 분기에요. 오늘 선택한 도구가 6개월 후에 최고의 도구는 아닐 것이고, 당신은 이동하게 될 겁니다.

그때가 되면, 그 전환 비용(cost of that switch)은 당신이 도구별 프롬프트에 얼마나 많은 부족 지식(tribal knowledge)을 녹여 넣었는지에 비례합니다. 모든 도구가 읽는 50줄짜리 AGENTS.md는 몇 분의 설정 시간입니다. 하지만 1년 동안 Cursor에서 관리해 온 프롬프트 라이브러리는 다시 작성하는 작업이 됩니다.

지침 파일은 문서가 아닙니다. 그것은 당신의 머리와 다음에 사용할 도구 사이에서 가능한 가장 짧은 번역본입니다. 마치 한 번도 만난 적 없는 에이전트(agent)가 읽을 것처럼 작성하세요. 왜냐하면 그 에이전트가 바로 이것을 가장 먼저 열기 때문입니다.