점진적 공개(Progressive Disclosure): 무엇을, 어디에, 언제, 왜 적용할까요?

AI 요약

코딩 에이전트에 프로젝트 규칙을 전달하는 방식은 단순히 지침을 많이 작성하는 문제가 아니라, 어떤 지침을 어떤 작업에서 언제 보여줄 것인지 설계하는 문제입니다. 이 글은 AGENTS.md에서 시작해 Cursor와 Claude의 경로 기반 설정, skills, 이벤트 기반 로딩으로 이어지는 흐름을 통해 점진적 공개(Progressive Disclosure)의 의미와 필요성을 설명합니다. 핵심은 모든 규칙을 항상 컨텍스트에 넣는 것이 아니라, 현재 작업에 실제로 필요한 규칙만 필요한 시점에 노출하는 것입니다. ■ AGENTS.md가 보여준 초기 형태 프로젝트 루트에 전체 프로젝트를 설명하는 AGENTS.md를 두고, 하위 폴더에는 해당 폴더의 내용에만 적용되는 지침 파일을 둘 수 있습니다. 이렇게 하면 규칙을 작업이 일어나는 위치 가까이에 배치하고, 코딩 에이전트가 해당 폴더에서 작업할 때만 그 규칙을 읽도록 만들 수 있습니다. 글쓴이는 코드베이스의 각 계층에 작은 지침 파일을 하나씩 두는 방식으로 프로젝트 전체를 운영한 경험을 소개합니다. 이 방식은 규칙이 적용되는 위치를 분명하게 만든다는 점에서 점진적 공개의 초기 형태입니다. 다만 폴더 단위 로딩에는 한계가 있습니다. 에이전트가 현재 작업 중인 폴더의 지침만 읽기 때문입니다. 예를 들어 백엔드 작업을 하면서 프론트엔드 일부도 함께 수정해야 한다면, 프론트엔드에 필요한 규칙이 자동으로 포함되지 않을 수 있습니다. 반대로 프론트엔드와 백엔드 영역을 동시에 크게 다루도록 하면 두 영역의 지침이 한 컨텍스트에서 경쟁하면서 에이전트가 양쪽에 주의를 나눠야 합니다. 글에서는 이를 컨텍스트 로트(context rot)와 연결해 설명합니다. ■ 파일 수준 경로 설정과 ‘모두 로드하기’의 문제 Cursor와 Claude는 여러 하위 폴더에 AGENTS.md나 CLAUDE.md를 흩어 놓는 대신, 어느 경로의 지침을 불러올지 지정하는 하네스 아티팩트(harness artifact)를 제공하는 방향으로 나아갔습니다. 이 설정은 폴더 수준을 넘어 파일 수준까지 범위를 좁힐 수 있습니다. 하지만 글은 이것만으로 문제가 끝나지 않는다고 말합니다. 가장 단순한 대안은 모든 지침을 한 번에 컨텍스트에 넣고 LLM이 알아서 필요한 부분을 고르게 하는 방식입니다. 많은 개발자가 처음에는 이 방법을 선택했고, 그 결과 CLAUDE.md가 300줄에 이르는 사례가 생겼습니다. 글은 이러한 항상 로드되는 파일이 신중한 선택처럼 보이지만 실제로는 비용이 크다고 지적합니다. 비용은 토큰 수에만 있지 않습니다. 모델은 사람처럼 체크리스트를 한 줄씩 검토하면서 각 규칙에 충분한 주의를 배분하지 않습니다. 입력에 있는 모든 항목이 고정된 주의(attention) 예산을 나눠 가지므로, 규칙이 10개일 때는 각 규칙이 의미 있는 비중을 차지하지만 100개가 되면 현재 작업과 무관한 99개의 규칙 사이에서 중요한 규칙 하나가 묻힐 수 있습니다. 글에서 소개한 28,721개 실제 저장소 분석에서는 지침 파일의 중앙값이 약 50개 항목을 포함했지만, 실제 지시문(directive)은 그중 약 12개에 불과했습니다. 나머지는 모델이 매번 읽어야 하는 구조적 내용(scaffolding)이었고, 이 내용도 동일한 주의 예산을 차지합니다. 따라서 ‘모든 것을 로드하기’는 문제를 피하는 방법이 아니라 문제를 가장 크게 만든 상태라고 설명합니다. 이 분석은 The State of AI Instruction Quality라는 글로 정리됐다고 합니다. ■ 점진적 공개의 세 가지 손잡이: 무엇을, 어디에, 언제 점진적 공개는 관련 지침과 컨텍스트를 코딩 에이전트에 점진적으로 소개하는 절차입니다. 하나의 항상 활성화된 파일에 모든 규칙을 담는 대신, 각 규칙이 실제로 중요해지기 직전에 불러오고 나머지 시간에는 컨텍스트에서 제외합니다. 글은 이를 세 가지 기준으로 나눕니다. 첫째는 ‘무엇을(what)’ 로드할지입니다. 모든 규칙을 일반 지침 파일의 한 줄로 작성하는 대신, 특정 작업에 필요한 규칙을 독립적인 skill로 패키징할 수 있습니다. skill은 작업이 요구될 때 에이전트가 불러오는 자기완결형 지침이며, 해당 작업과 무관한 동안에는 보이지 않습니다. 예를 들어 커밋 규칙은 레이아웃 버그를 수정하는 동안 항상 컨텍스트에 있을 필요가 없고, Git 작업을 수행할 때만 로드되도록 만들 수 있습니다. 둘째는 ‘어디에(where)’ 적용할지입니다. 결제 코드에만 필요한 규칙이라면 결제 코드 가까이에 둘 수 있습니다. 폴더 수준의 중첩 파일을 사용하거나, Cursor와 Claude가 제공하는 경로 설정으로 특정 파일 수준까지 범위를 지정할 수 있습니다. 이 규칙은 에이전트가 해당 영역에서 작업하는 턴에는 나타나지만, 다른 영역을 작업할 때는 컨텍스트를 차지하지 않습니다. 규칙의 내용 자체를 약화하는 것이 아니라 적용 대상을 정확히 겨냥하는 방식입니다. 셋째는 ‘언제(when)’ 로드할지입니다. 어떤 규칙은 특정 폴더보다 특정 순간에만 필요합니다. 세션 시작 시, 또는 특정 유형의 작업이 시작될 때 해당 규칙을 불러오도록 연결할 수 있습니다. 이 경우 규칙의 내용을 다시 작성하는 것이 아니라, 규칙이 컨텍스트에 들어오는 시점을 조정합니다. 따라서 위치에 묶이지 않는 작업 흐름의 규칙도 필요할 때만 활성화할 수 있습니다. ■ Anthropic의 컨텍스트 엔지니어링 지침 글은 Anthropic의 Claude 5 세대 관련 지침에서도 같은 방향을 확인할 수 있다고 설명합니다. Anthropic의 Thariq Shihipar는 CLAUDE.md를 알려진 모든 관행을 담는 중앙 저장소로 만들고 싶어 하는 태도를 하나의 통념(myth)으로 지적하고, 그 해결책으로 “progressive disclosure를 많이 사용하라”는 방향을 제시합니다. 루트 파일에는 필요한 skill을 가리키는 최소한의 내용만 두고, 나머지 규칙은 해당 skill에서 로드하도록 하는 방식입니다. 이 접근을 적용하면 300줄짜리 항상 활성화된 파일은 얇은 루트 파일과 작업별 규칙 묶음으로 분해됩니다. 규칙은 매번 모두 등장하는 대신, 현재 턴에 적용되는 소수의 규칙만 컨텍스트에 들어옵니다. 글은 이렇게 주의가 필요한 규칙에 집중할 수 있는 상태를 점진적 공개가 해결하려는 로딩 문제의 핵심으로 제시합니다. ■ 파일 하나를 시스템으로 분해할 때 생기는 새로운 문제 지침을 나누면 단순히 문서를 정리하는 데서 끝나지 않습니다. 어떤 규칙이 어느 경로에서 여전히 로드되는지, 특정 규칙의 범위를 너무 좁혀 아무 작업에도 도달하지 않게 만들지는 않았는지, 두 규칙이 같은 턴에 함께 로드되어 다시 주의 경쟁을 일으키지는 않는지를 확인해야 합니다. 서로 반대되는 지침이 조용히 동시에 적용되는 충돌도 생길 수 있습니다. 글은 이를 Opus 5: Cost of Instruction Conflicts에서 다룬 지침 충돌 비용과 연결합니다. 규칙이 하나의 파일에 있을 때는 “그 내용이 파일에 들어 있나요?”라고 물으면 됐지만, 규칙이 여러 경로와 시점으로 분리된 뒤에는 질문이 달라집니다. 실제로 무엇이 로드되고, 어디에서 로드되며, 언제 로드되는지, 그리고 그 결과가 작성자가 의도한 구조와 일치하는지를 확인해야 합니다. 또한 규칙이 정상적으로 로드됐더라도 에이전트가 이를 따르지 않을 수 있으며, 글은 이 문제를 로딩 문제와 다른 별도의 문제로 구분합니다. ■ Reporails가 제시하는 확인 방식 글은 이처럼 분산된 규칙 시스템의 형태와 충돌 지점을 확인하기 위해 Reporails를 소개합니다. Reporails는 개발자가 작성한 파일을 자신의 컴퓨터에서 읽고, 어떤 규칙이 로드되는지와 어디에서 서로 충돌할 수 있는지를 보여주는 도구로 설명됩니다. 에이전트가 실행되는 동안 에이전트 자체에 개입하는 것이 아니라, 작성된 규칙 구조를 읽어 점검하는 방식입니다. 이 글은 이후 시리즈에서 무엇이 로드되는지 확인하는 방법, 규칙의 범위를 어떻게 지정할지, 이벤트에 맞춰 언제 로드할지 각각을 코드와 함께 더 깊게 다루겠다고 예고합니다. 원문: dev.to / 번역·요약: Trawling