점진적 공개(Progressive Disclosure): 무엇을, 어디서, 언제 불러올 것인가
AGENTS.md 한 파일에 모든 규칙을 밀어 넣는 방식이 왜 실패하는지, 그리고 규칙을 '무엇·어디서·언제'라는 세 축으로 나눠 필요한 순간에만 로드하는 점진적 공개 전략을 정리했다.
Progressive Disclosure: What, Where, When, and Why
Do you remember when we first started using AGENTS.md files? You would have a project root file...
개요 #
코딩 에이전트에게 규칙을 주는 가장 흔한 방법은 프로젝트 루트에 AGENTS.md나 CLAUDE.md를 두고 거기에 모든 내용을 적는 것이다. Reporails의 Gábor Mészáros는 이 방식이 오히려 에이전트의 주의력을 갉아먹는다고 지적한다.
핵심 근거는 숫자로 나온다. 실제 저장소 28,721개를 분석했더니 지시 파일 하나에 담긴 항목은 중앙값 기준 약 50개였고, 그중 실제 지시문은 12개 정도에 불과했다. 나머지는 매 턴마다 모델이 읽고 지나가는 껍데기였다.
대안으로 제시한 개념이 점진적 공개(progressive disclosure) 다. 규칙을 항상 켜두는 대신, 그 규칙이 필요한 순간에만 꺼내 쓰는 방식이다. 저자는 이를 '무엇이 로드되는가', '어디서 로드되는가', '언제 로드되는가' 세 갈래로 쪼갠다.
폴더별 지시 파일에서 출발한 이야기 #
AGENTS.md가 처음 쓰이기 시작했을 때의 구조는 단순했다. 루트에 프로젝트 전체를 설명하는 파일 하나, 그리고 하위 폴더마다 그 폴더의 내용을 설명하는 작은 파일들. 규칙을 작업이 벌어지는 자리에 놓고, 그 자리에서만 등장하길 기대하는 구조였다. 저자도 한때 프로젝트 전체를 이 방식으로 굴렸다고 한다. 코드베이스 각 계층마다 작은 지시 파일 하나씩.
문제는 경계가 깔끔하게 나뉘지 않을 때 드러난다. 백엔드를 고치는 중에 프론트엔드도 함께 손봐야 하는 상황이 대표적이다. 두 영역의 지시가 동시에 올라오면 서로 주의를 두고 경쟁하고, 에이전트는 양쪽으로 집중을 쪼개야 한다. 저자가 "mayhem"이라고 표현한 상태다.
Cursor와 Claude가 내놓은 다음 단계는 더 촘촘한 스코핑이었다. 하위 폴더마다 파일을 뿌리는 대신, 어디서 로드할지를 경로 설정으로 지정하는 방식. 폴더 단위가 아니라 파일 단위까지 내려간다. 진전은 맞지만 끝은 아니다.
Photo by RDNE Stock project on Pexels
왜 "전부 로드"가 답이 아닌가 #
가장 거친 선택지를 다시 떠올려 보자. 그냥 전부 컨텍스트에 밀어 넣고 나머지는 LLM이 알아서 판단하게 두면 안 되나?
대부분이 처음에 시도한 방법이고, 당신의 CLAUDE.md가 300줄이 된 이유이기도 하다. 지금은 아예 지워버리라는 주장까지 나오는 그 파일 말이다(Opus 5: Delete your CLAUDE.md?). 지금까지 쓴 모든 규칙이 매 턴 컨텍스트 창에 들어와 항상 손 닿는 곳에 있다. 안전한 선택처럼 보이지만 실제로는 비싼 선택이고, 토큰 비용은 청구서의 가장 작은 항목일 뿐이다.
모델은 사람이 체크리스트를 훑듯 지시문을 한 줄씩 차례로 읽고 각각에 시간을 주지 않는다. 눈앞에 놓인 전체에 정해진 양의 주의를 흩뿌린다. 한 줄을 더할 때마다 같은 예산을 당기는 항목이 하나 늘어난다. 규칙이 열 개면 각각이 실질적인 몫을 가져간다. 백 개가 되면, 이번 턴에 정말 필요한 그 한 줄은 무관한 아흔아홉 개 사이에서 소리치는 목소리 하나가 된다. 앞서 나온 프론트·백엔드 동시 작업 문제와 같은 구조인데, 이번엔 매 턴 영구적으로 겪는다.
저자가 정리한 저장소 분석 결과(The State of AI Instruction Quality)로 돌아가면, 항상 켜져 있는 파일의 대부분이 에이전트에게 무언가를 시키는 내용조차 아니다. 그런데도 같은 주의 예산을 두고 경쟁한다.
경로 설정이 겨냥한 지점이 바로 여기다. 결제 코드에서 작업할 때만 결제 규칙을 로드하는 것. 각 규칙을 그것이 속한 턴이 올 때까지 무대 밖에 두는 방식이다. 진짜 진전이지만, 여전히 답의 일부에 그친다. 규칙이 어디에 사는지는 레버 하나일 뿐이고 다른 레버도 있기 때문이다.
규칙은 잘못된 위치에 로드되는 것만이 아니라, 애초에 로드할 필요가 없는 것일 수도 있다. 폴더가 아니라 특정 순간에 필요한 규칙도 있다. 결국 원하는 건 모든 규칙에 대해 무엇을, 어디서, 언제 로드할지 정하는 방법이다.
세 개의 손잡이 #
점진적 공개는 관련 지시와 컨텍스트를 코딩 에이전트에게 단계적으로 건네는 절차다. 항상 켜져 있는 파일 하나 대신, 각 규칙이 필요해지기 직전에 건네고 나머지 시간에는 치워둔다. 이 아이디어가 실제로 써먹을 만해지는 건 세 개의 손잡이로 쪼갤 수 있기 때문이다. 셋을 따로 볼 수 있게 되면 반사적으로 루트 파일에 손이 가는 습관이 사라진다.
Anthropic도 Claude 5 세대 가이드에서 같은 처방을 명시한다. Thariq Shihipar는 지시 파일이 비대해지는 원인으로 "모든 알려진 관행을 담는 중앙 저장소로 만들고 싶어 하는 통념"을 지목하고, 해법으로 "점진적 공개를 적극적으로 사용"하고 나머지는 파일이 가리키는 스킬에서 로드하라고 말한다(the new rules of context engineering).
무엇이 로드되는가 #
규칙이 반드시 에이전트가 위에서 아래로 읽는 파일의 한 줄일 필요는 없다. 스킬(skill)로 포장하면 된다. 작업이 요구할 때 에이전트가 직접 끌어오고, 그 외에는 아예 보지 않는 독립된 지시 단위다. 레이아웃 버그를 쫓는 중에 커밋 컨벤션이 컨텍스트 창에 있을 이유는 없다. 스킬은 git에 손을 뻗는 순간까지 그 규칙을 밖에 둔다.
어디서 로드되는가 #
이미 나온 이야기다. 결제 코드만 관장하는 규칙은 결제 코드 옆에 둔다. 하위 폴더에 파일을 두는 폴더 단위 방식이거나, Cursor와 Claude가 추가한 경로 설정을 쓰는 파일 단위 방식이거나. 에이전트가 그 자리에서 일하는 턴에만 등장하고 나머지 시간엔 방에 없다. 규칙이 약해진 게 아니라 조준된 것이다.
언제 로드되는가 #
어떤 규칙은 장소가 아니라 순간에만 의미가 있다. 그럴 땐 순간에 묶는다. 세션이 시작될 때, 혹은 특정 종류의 작업이 시작될 때 규칙을 끌어오고 그전까지는 꺼둔다. 같은 규칙, 다른 등장 시점이다. 다시 쓰는 게 아니라 언제 무대에 오를지를 정하는 것이다.
왜 #
셋 중 어느 것도 규칙의 내용을 바꾸지 않는다. 바뀌는 건 에이전트가 그 규칙을 짊어져야 하는 시점이다. 그리고 부족한 자원은 디스크 공간도, 심지어 토큰도 아니다. 정작 중요한 턴에 에이전트가 쏟을 수 있는 주의력이다.
세 축을 제대로 맞추면 300줄짜리 상시 로드 파일은 가벼운 루트 하나와 신호에 맞춰 등장하는 규칙 세트로 분해된다. 붐비던 방이 비고, 이번 턴에 필요한 규칙은 백 개 중 하나가 아니라 세 개 중 하나가 된다.
Photo by 파일은 애초에 단위가 아니었다 #
파일을 쪼개는 사이에 바뀐 게 하나 있다. 문서를 정리한 게 아니라 시스템을 만든 것이다. 가벼운 루트 하나에, 각자 신호를 받아 로드되는 규칙들. 어떤 건 경로에 묶이고 어떤 건 순간에 묶인다.
시스템에는 파일 하나를 스크롤해서는 파악할 수 없는 형태가 생긴다. 이 규칙은 아직 내가 생각하는 자리에서 로드되고 있나? 저 규칙은 너무 좁게 스코핑해서 이제 아무 데도 닿지 않는 건 아닌가? 둘이 같은 턴에 로드되도록 설정돼서 다시 주의를 두고 경쟁하고 있진 않나? 더 나쁘게는, 둘이 조용히 정반대를 지시하고 있진 않나(Opus 5: Cost of Instruction Conflicts에서 그 비용을 다룬다)?
"파일에 들어 있나"는 파일이 하나일 때 유효한 질문이었다. 이제 그 하나의 파일은 없다. 질문은 실제로 무엇이, 어디서, 언제 로드되는가, 그리고 그게 여전히 의도와 맞는가로 바뀐다.
저자는 이 글을 시리즈의 출발점으로 두고, 이후 각 편에서 손잡이 하나씩을 코드와 함께 파고들겠다고 예고했다. 무엇이 로드되고 그걸 어떻게 확인하는지, 규칙을 어디까지 좁혀야 무관한 턴을 희석하지 않는지, 언제 규칙을 페이지에서 이벤트로 옮기는지. 덧붙여 "규칙이 완벽하게 로드돼도 에이전트가 무시할 수 있다"는 별개 문제도 따로 다룰 예정이라고 밝혔다.
자신이 만든 구조를 눈으로 확인하고 싶다면 — 어떤 규칙이 아직 로드되는지, 어디서 둘이 충돌하는지 — Reporails가 제공하는 CLI 도구를 쓸 수 있다. 무료이고 로컬에서 돌아가며, 작성한 파일만 읽고 실행 중 에이전트를 건드리지 않는다.
이 글은 위 출처를 바탕으로 한국 독자를 위해 재작성한 기사입니다. 원문의 사실과 수치에 근거하며, 별도의 견해를 포함하지 않습니다.