기업 실습에서 참가자들의 CLAUDE.md를 열어보면 대부분 비슷하다.
프로젝트 개요, 디렉토리 구조, 기술 스택, 네이밍 컨벤션, API 명세, 환경 변수 목록, 브랜치 전략. 성실하게 작성된 300줄짜리 문서가 나온다. 어떤 팀은 온보딩 위키를 그대로 복사해 넣기도 한다.
그런데 이 파일을 넣기 전과 후의 결과물이 크게 다르지 않다. 작성에 들인 시간을 생각하면 납득하기 어려운 결과다. 참가자들이 가장 많이 하는 질문도 여기서 나온다. "이렇게 자세히 썼는데 왜 그대로 안 따라오죠?"
원인은 내용의 정확성이 아니라 내용의 성격에 있다.
어떤 개발자가 남긴 8줄
지난주 Marcos Hernanz라는 개발자가 자신의 AGENTS.md 전문을 공개했다. 본인 설명에 따르면 에이전트 코딩으로 600억 토큰 정도를 쓰고 남은 결과물이다.
AGENTS.md는 코딩 에이전트가 작업 시작 시 읽는 프로젝트 지침 파일이다. Claude Code의 CLAUDE.md와 같은 역할을 한다.
600억 토큰이면 상당한 양이다. 중형 프로젝트 수십 개를 에이전트와 함께 완주할 수 있는 분량이고, 그 과정에서 에이전트가 저지르는 실수의 거의 모든 유형을 목격하게 되는 규모다.
그렇게 축적한 지침이 8줄이었다. 빌드 명령어도, 디렉토리 트리도, 기술 스택 설명도 없었다.
내용은 이렇다.
- 해결책을 설계하기 전에, 이미 자리 잡은 제품들이 같은 문제를 어떻게 푸는지 먼저 살펴볼 것. 접근 방식을 처음부터 발명하지 말고 검증된 패턴과 관례를 채택할 것
- 하위 호환을 유지하지 말 것. 호환 레이어·폴백·마이그레이션을 덧붙이는 대신 쓰이지 않는 경로를 삭제할 것
- 현재 요구사항을 완전히 충족하는 가장 단순한 구현을 선택할 것. 추측에 근거한 추상화, 설정값, 간접 계층을 만들지 말 것
- 시스템은 레이어로 키울 것. 엔드투엔드로 동작하는 최소 버전에서 시작해 이미 동작하는 결과물 위에 기능을 하나씩 얹을 것. 동작하는 코드를 미완성 복잡도와 맞바꾸지 말 것
- 컴포넌트는 모듈로 분리하고 관심사를 명확히 나눌 것
- 검증되고 유지보수되는 라이브러리가 전체 복잡도를 낮추거나 안정성을 높인다면 그것을 쓸 것. 흔한 기능을 명확한 이유 없이 재구현하지 말 것
- 직접 구현하거나 패키지를 추가하기 전에 이미 설치된 의존성부터 확인할 것. 문서와 타입을 확인하지 않은 채 "이 라이브러리엔 그 기능이 없다"고 단정하지 말 것
- 아키텍처 결정은 장기 관점으로 할 것. 지금만 넘기고 나중에 교체할 임시방편을 받아들이지 말 것
8줄의 공통점
한 줄씩 뜯어보면 규칙성이 보인다.
전부 LLM이 시키지 않으면 반드시 저지르는 실수를 겨냥하고 있다.
| 지침 | 막으려는 기본 동작 |
|---|---|
| 기존 제품 먼저 조사 | 요구사항을 듣자마자 자기 방식으로 설계에 착수 |
| 하위 호환 유지 금지 | 기존 코드를 안 건드리려고 _v2 함수와 폴백을 누적 |
| 가장 단순한 구현 | 쓰이지 않을 설정 레이어와 추상화를 미리 구축 |
| 레이어로 성장 | 대규모 리팩터링 중간에 전체를 깨뜨림 |
| 모듈·관심사 분리 | 한 파일에 로직을 계속 덧붙임 |
| 재구현 금지 | 표준 라이브러리 기능을 직접 작성 |
| 기존 의존성 확인 | 문서 확인 없이 "그 기능은 없다"고 단정 |
| 임시방편 거부 | # TODO: 나중에 교체 주석을 달고 통과 |
여덟 줄 중 어느 것도 프로젝트에 관한 정보가 아니다. 전부 모델의 성향에 관한 교정 지시다.
왜 프로젝트 정보는 적을 필요가 없나
에이전트는 파일 시스템에 접근할 수 있다.
디렉토리 구조가 궁금하면 탐색하면 된다. 네이밍 컨벤션이 궁금하면 기존 파일 몇 개를 읽으면 된다. 사용 중인 라이브러리가 궁금하면 package.json이나 pyproject.toml을 열면 된다. 테스트 실행 방법은 Makefile이나 scripts 항목에 이미 있다.
에이전트가 스스로 알아낼 수 있는 정보를 컨텍스트 파일에 적는 것은 토큰 낭비일 뿐 아니라, 정말 중요한 지시의 밀도를 떨어뜨린다.
300줄 안에 핵심 지시 3줄이 섞여 있으면, 그 3줄은 나머지 297줄에 묻힌다. 사람이 읽는 문서라면 목차와 강조 표시로 해결되지만, 컨텍스트 창 안에서는 그런 장치가 작동하지 않는다.
반대로 에이전트가 알면서도 하지 않는 것은 명시하지 않으면 절대 실행되지 않는다.
"덧붙이지 말고 지워라"가 대표적이다. 학습 데이터에 존재하는 코드 대부분은 무언가를 추가하는 커밋이다. 과감하게 삭제하는 패턴은 상대적으로 희소하다. 그래서 지시하지 않으면 에이전트는 항상 추가하는 쪽을 택한다. 코드베이스는 매 세션마다 조금씩 부풀어 오른다.
맨 앞줄이 가장 비싸다
여덟 줄 중 하나만 남겨야 한다면 첫 번째 줄이다.
해결책을 설계하기 전에, 이미 자리 잡은 제품들이 같은 문제를 어떻게 푸는지 먼저 살펴보세요.
LLM은 요청을 받으면 곧바로 만들기 시작한다. 인증 흐름도, 페이지네이션도, 상태 관리도, 에러 처리도 자기 방식으로 새로 설계한다. 이미 수십만 개의 제품이 합의해둔 방식이 있는데도 그렇다.
결과물은 대개 틀리지 않는다. 돌아가고, 테스트도 통과한다. 문제는 팀의 어떤 관례와도 닮지 않았다는 점이다. 리뷰어는 코드를 읽을 때마다 처음 보는 구조를 새로 이해해야 한다. 이런 코드가 쌓이면 코드베이스는 일관성을 잃는다.
이 한 줄은 순서를 바꾼다. 설계 → 구현이 아니라, 조사 → 설계 → 구현이다.
컨텍스트 파일에 한 줄로 넣어두면 상시 적용되고, 특히 중요한 작업이라면 그 세션의 프롬프트에서 한 번 더 강제하면 된다.
이 기능을 구현하기 전에, 먼저 조사만 해줘.
1) 같은 문제를 이미 푼 제품·라이브러리 3개를 찾아서 각각 어떤 구조로 푸는지 요약
2) 우리 코드베이스에 이미 있는 유사 패턴 위치
3) 그중 우리에게 맞는 방식 하나를 고르고 이유를 세 줄로
여기까지만 하고 멈춰. 코드는 내가 승인한 뒤에 작성해.
나머지 일곱 줄이 구현 품질을 지키는 규칙이라면, 첫 줄은 방향 자체를 잡는 규칙이다.
세 가지 분류 기준
컨텍스트 파일에 무엇을 넣을지 판단하는 기준은 단순하다.
1️⃣ 에이전트가 스스로 알아낼 수 있는 것 → 적지 않는다. 디렉토리 구조, 파일 목록, 설치된 패키지, 기존 코드 스타일. 탐색으로 확인 가능한 정보다.
2️⃣ 에이전트가 알면서도 하지 않는 것 → 반드시 적는다. 삭제, 단순화, 기존 방식 조사, 문서 확인, 임시방편 거부. 능력의 문제가 아니라 성향의 문제이므로 명시적 지시가 필요하다.
3️⃣ 판단이 갈리는 지점 → 어느 쪽인지 명시한다. "하위 호환을 유지할 것인가"는 팀마다 답이 다르다. 라이브러리를 제공하는 팀이라면 Marcos의 두 번째 줄을 그대로 쓰면 안 된다. 내부 도구를 만드는 팀이라면 그대로 써도 된다. 이런 항목은 정답이 없으므로 우리 팀의 선택을 적어야 한다.
여기에 프로젝트 고유의 예외 사항 — 건드리면 안 되는 디렉토리, 반드시 실행해야 하는 검증 명령, 규제 요건 — 을 짧게 덧붙이면 실무용 컨텍스트 파일이 완성된다.
바로 복사해서 쓰는 프롬프트
한국어 환경에서 그대로 쓸 수 있도록 명령형으로 다듬은 버전이다. CLAUDE.md 또는 AGENTS.md 최상단에 넣으면 된다.
# 작업 원칙
- 해결책을 설계하기 전에, 이미 자리 잡은 제품들이 같은 문제를 어떻게 푸는지
먼저 살펴보세요. 접근 방식을 처음부터 발명하지 말고
검증된 패턴과 관례를 채택하세요.
- 하위 호환을 유지하지 마세요. 호환 레이어·폴백·마이그레이션을 덧붙이는 대신
쓰이지 않는 경로를 삭제하세요.
- 현재 요구사항을 완전히 충족하는 가장 단순한 구현을 선택하세요.
추측에 근거한 추상화, 설정값, 간접 계층을 만들지 마세요.
- 시스템은 레이어로 키우세요. 엔드투엔드로 동작하는 최소 버전에서 시작하고,
이미 동작하는 결과물 위에 기능을 하나씩 얹으세요.
동작하는 코드를 미완성 복잡도와 맞바꾸지 마세요.
- 컴포넌트는 모듈로 분리하고 관심사를 명확히 나누세요.
- 검증되고 유지보수되는 라이브러리가 전체 복잡도를 낮추거나 안정성을 높인다면
그것을 쓰세요. 흔한 기능을 명확한 이유 없이 재구현하지 마세요.
- 직접 구현하거나 패키지를 추가하기 전에 이미 설치된 의존성부터 확인하세요.
문서와 타입을 확인하지 않은 채 "이 라이브러리엔 그 기능이 없다"고 단정하지 마세요.
- 아키텍처 결정은 장기 관점으로 하세요. 지금만 넘기고 나중에 교체할
임시방편을 받아들이지 마세요.
# 프로젝트 예외
- (건드리면 안 되는 경로)
- (작업 완료 전 반드시 실행할 검증 명령)
- (규제·보안상 반드시 지켜야 할 사항)
우리 팀에 맞게 고쳐야 하는 줄
두 번째 줄(하위 호환)은 팀 상황에 따라 반드시 검토해야 한다. 외부에 공개된 API나 라이브러리를 유지보수하는 팀이라면 정반대로 적어야 한다.
외부 API·SDK를 제공하는 팀 — 2번 줄 교체
- 공개 API의 하위 호환을 깨지 마세요. 시그니처·응답 스키마·에러 코드를 바꿔야 한다면
새 경로를 추가하고 기존 경로는 deprecated 표시 후 유지하세요.
제거는 별도 작업으로 분리하고, 임의로 삭제하지 마세요.
규제 산업(금융·의료·공공) — 8번 줄 뒤에 추가
- 개인정보·인증정보가 흐르는 코드를 수정할 때는 먼저 어떤 데이터가
어디로 흐르는지 요약해서 보여주고 승인을 받으세요.
로그·에러 메시지·외부 전송에 원본 값을 담지 마세요.
레거시 마이그레이션 중인 팀 — 4번 줄 보강
- 신규 코드는 새 방식으로 쓰되, 기존 코드를 지나가는 김에 함께 바꾸지 마세요.
마이그레이션은 별도 작업으로 제안만 하고, 이번 변경의 범위 밖은 그대로 두세요.
컨텍스트 파일도 운영 대상이다
이 8줄이 처음부터 8줄이었던 것은 아니다.
Marcos가 며칠 전 올린 초기 버전은 3줄이었다. 이후 며칠 사이에 항목이 하나씩 늘었다. 사용하면서 반복적으로 관찰된 실패 패턴이 새 줄로 승격된 것이다.
컨텍스트 파일은 한 번 작성하고 끝나는 문서가 아니라, 실패 로그를 관찰하며 갱신하는 운영 자산이다.
권장하는 루틴은 단순하다.
- 세션이 끝날 때, 결과물을 손으로 고쳐야 했던 지점을 기록한다
- 같은 유형의 수정이 세 번 반복되면 컨텍스트 파일에 한 줄을 추가한다
- 분기마다 전체를 다시 읽고, 더 이상 발동되지 않는 줄을 삭제한다
이 세 가지를 손으로 하지 않아도 된다. 에이전트에게 시키면 된다.
세션 끝에 — 규칙 후보 뽑기
이번 세션에서 네가 처음 내놓은 결과물을 내가 어떤 식으로 고쳤는지 되짚어줘.
- 내가 수정한 지점을 유형별로 묶어줘 (예: 불필요한 추상화, 삭제 대신 추가, 문서 미확인)
- 각 유형에 대해, 컨텍스트 파일에 한 줄로 넣으면 다음부터 막을 수 있는 지시를 써줘
- 이미 CLAUDE.md에 있는 내용과 겹치는 건 빼줘
- 이번 작업에만 해당하는 일회성 요구는 규칙 후보에서 제외해줘
분기마다 — 안 쓰이는 줄 걷어내기
CLAUDE.md를 읽고, 각 줄을 다음 세 가지로 분류해줘.
A) 네가 파일을 뒤져 스스로 알아낼 수 있는 정보 → 삭제 후보
B) 지시가 없으면 네 기본 동작이 반대로 갈 항목 → 유지
C) 팀의 선택을 적어둔 항목 → 유지하되 최신인지 나에게 질문
분류 결과를 표로 주고, A로 분류한 줄은 왜 스스로 알 수 있는지 근거를 한 줄씩 적어줘.
세 번째가 특히 중요하다. 모델이 세대를 거듭하면서 예전에는 필요했던 지시가 불필요해진다. 그 줄을 남겨두면 다시 밀도가 떨어진다. 컨텍스트 파일에도 첫 번째 원칙 — 쓰이지 않는 경로는 삭제한다 — 이 적용된다.
정리하며
컨텍스트 파일의 품질은 길이가 아니라 밀도로 결정된다.
600억 토큰을 태운 사람이 8줄만 남긴 이유는 문서를 짧게 쓰는 취향 때문이 아니다. 효과가 확인되지 않은 줄을 전부 걷어냈기 때문이다.
에이전트에게 무엇을 알려줄지 고민하는 대신, 에이전트가 무엇을 알면서도 하지 않는지를 관찰하자. 그 목록이 곧 여러분의 컨텍스트 파일이다.
AX LABS는 국내 대기업을 대상으로 AX 컨설팅과 AI 에이전트 개발 실무 교육을 수행하고 있습니다. 팀의 컨텍스트 파일과 에이전트 운영 체계를 함께 설계하고 싶다면 문의하기 →
참고
- Marcos Hernanz의 AGENTS.md 원문 게시물: https://x.com/MarcosHernanz/status/2083011475346510240
- AGENTS.md 규격: https://agents.md/
- Claude Code 메모리(CLAUDE.md) 문서: https://docs.claude.com/en/docs/claude-code/memory
