프로젝트 컨텍스트의 이론

bmad-project-context는 다소 불편한 발견에서 출발했습니다. AI 에이전트를 위해 작성한 문서 대부분이 오히려 에이전트의 성능을 떨어뜨린다는 사실입니다. 이 문서에서는 이 스킬이 무엇을 왜 수집하는지, 더 중요하게는 무엇을 의도적으로 수집하지 않는지 설명합니다. bmad-document-project 또는 bmad-generate-project-context에서 넘어왔다면 마지막 절에서 무엇이 바뀌었는지 정확히 확인할 수 있습니다.

스킬의 기능과 실행 방법은 프로젝트 컨텍스트와 사용 가이드를 참고하세요.

기준선: 정보를 찾는 데 드는 비용

작성된 컨텍스트는 담고 있는 사실을 저장소에서 찾아내는 데 큰 비용이 들 때만 그만한 가치가 있습니다. 에이전트가 알아낼 수 있는지보다, 그 사실을 매번 직접 찾아야 할 때 치르는 비용이 기준입니다. 탐색에 드는 노력, 제때 올바른 곳을 찾을 가능성, 실수하기 전에 발견하는지 아니면 실수한 뒤에야 알게 되는지를 따집니다.

서로 다른 두 연구 분야의 결과가 같은 결론을 뒷받침합니다. 저장소 단위 작업에서 코드 추론과 문서 암기를 분리해 비교하면, 문서를 읽는 것보다 코드를 직접 볼 때 성능이 훨씬 크게 향상됩니다. 시스템의 작동 방식을 설명한 문서는 원본 소스보다 못합니다. 반대로 코드에서 요구 사항을 생성하게 하는 실험에서는 모델이 아직 구현되지 않은 내용을 안정적으로 만들어 내지 못했습니다. 현재 구현된 동작은 소스에서 복원할 수 있지만, 의도와 근거, 일부러 선택하지 않은 대안은 복원할 수 없습니다. 코드가 말하는 내용을 직접 확인하는 일은 비용이 적고 신뢰할 수 있으므로, 같은 내용을 따로 저장해 둘 가치가 없습니다.

따라서 에이전트가 원본에서 적은 비용으로 확실하게 읽을 수 있는 내용은 그때그때 확인하고 따로 저장하지 않습니다. 복사본은 금세 낡을 뿐 아니라 호출할 때마다 비용도 듭니다. 다만 같은 사실을 세션마다 힘들게 다시 찾아야 한다면, 저장소에서 유추할 수 있더라도 기록할 가치가 있습니다.

대부분의 AGENTS.md가 효과를 내지 못한 이유

저장소 지침 파일은 2026년에 가장 많이 연구된 산출물입니다. 그러나 파일이 있을 때와 없을 때를 비교한 결과는 좋지 않았습니다. 작업 성공률은 나아지지 않았고 추론 비용은 20% 늘었습니다. 실제 저장소를 대상으로 한 반복 실험에서도 같은 결과가 나왔으며, 실패 원인은 저장소 지식의 부족보다 구현 능력의 한계였습니다. 대규모 연구 하나에서는 무작위로 생성한 규칙이 전문가가 엄선한 규칙과 같은 성과를 냈습니다.

이 결과만 보면 저장소 지침 파일은 쓸모없어 보입니다. 하지만 해당 파일에 무엇이 들어 있었는지 살펴보면 이유가 드러납니다. 대부분 저장소 구조, 기술 스택, 아키텍처 요약처럼 저장소에 이미 있는 내용을 반복했습니다. 연구가 측정한 것은 작성된 컨텍스트 전체가 아니라, 저장소에서 유추할 수 있는 내용을 글로 복제했을 때의 효과였습니다.

항상 불러오는 파일의 짧은 인덱스가 정반대 결과를 낸 이유

한 대조 실험은 모델 학습 데이터에 없던 프레임워크 API를 대상으로 네 가지 설정을 비교했습니다.

설정	통과율
문서 없음	53%
재사용 가능한 스킬만 제공	53%
같은 스킬을 명시적으로 호출하도록 지시	79%
AGENTS.md에 압축된 문서 인덱스 제공	100%

효과가 없었던 앞선 연구와 파일 형식은 같았지만 내용이 달랐습니다. 저장소를 다시 설명하지 않고 모델이 모르는 지식을 담았습니다. 40KB 문서를 8KB로 압축한 인덱스였지만 성능은 떨어지지 않았습니다.

이 결과에서 놓치면 안 될 점이 있습니다. 별도 지시 없이 제공한 스킬은 56%의 사례에서 한 번도 호출되지 않았습니다. 호출하라는 명시적 지침을 추가하면 호출률이 95%를 넘었지만 통과율은 여전히 79%에 그쳤고, 문구가 조금만 달라져도 결과가 크게 흔들렸습니다.

필요할 때 알아서 찾아오도록 맡기는 방식은 신뢰하기 어렵습니다. 다른 측정도 같은 결론을 냈습니다. 709페이지짜리 위키에서 일부 구성을 제거해 비교한 실험에서 에이전트는 인덱스를 건너뛰고, 질문만 보고 페이지 경로를 추측했습니다.

이 결과를 설명하는 원칙은 하나입니다. 에이전트가 불러올지 스스로 판단해야 하는 인덱스는 건너뛰지만 이미 컨텍스트에 들어 있는 인덱스는 건너뛰지 않습니다. 반드시 필요한 정보는 항상 불러오는 파일에 둬야 합니다. 다른 파일을 가리키는 포인터에는 에이전트가 직접 확인할 수 있는 조건을 붙여야 합니다. 경로, 파일 형식, 구체적인 작업은 괜찮지만 에이전트가 스스로 판단하거나 자기 행동을 감시해야 알 수 있는 조건은 피해야 합니다.

포함할 가치가 있는 정보

모든 줄에는 가지치기 테스트를 적용합니다. 이 줄을 삭제하면 에이전트의 행동이 달라지는가? 사람이 작성한 줄이 이 테스트를 통과하지 못하더라도 곧바로 삭제하지는 않습니다. 먼저 삭제해도 되는 근거가 있는지 규칙을 없앨 때는 반대로 판단합니다의 기준에 따라 확인합니다.

• 설정 파일만으로 알 수 없는 프로젝트 실행 조건. 쉽게 짐작할 수 있는 명령은 package.json, Makefile, CI 설정에서 직접 확인하고, 여러 명령이 그럴듯해 보일 때 무엇을 사용해야 하는지와 그 파일에 없는 예외만 기록합니다. 루트 테스트 스크립트가 이 워크스페이스에서는 아무 일도 하지 않거나, 통합 테스트 전에 서비스를 실행해야 하거나, 전체 테스트가 너무 느려 개별 파일로 반복해야 하거나, CI가 테스트 스크립트에 없는 검사를 수행하는 경우입니다.
• 코드로 표현할 수 없는 정책. 변경 금지 경로, 생성된 파일, 브랜치 규칙, 보안 및 규정 준수 요구 사항입니다. 탐색으로 추측하지 않고 권한 있는 사람이 알려준 내용만 받습니다.
• 생태계 기본값과 다른 규칙. 차이가 있는 부분만 기록합니다. 별도 지침이 없으면 에이전트는 일반적인 방식을 따르므로 기본 방식으로도 틀리지 않을 사실은 한 줄을 쓸 가치가 없습니다.
• 실제로 관찰한 실패에서 나온 위험 요소. 저장소를 훑으면 위험해 보이는 사실을 수백 개 찾을 수 있지만 그중 실제 실수를 일으키는 몇 개를 사실의 성질만으로 가려낼 수는 없습니다. 그 신호는 실제 행동에서만 나옵니다. 스캔 중 뜻밖의 사실을 발견하면 곧바로 규칙으로 쓰지 않고 질문합니다.
• 컴포넌트 간 규칙과 필수 버전. 에이전트가 지금 편집하는 파일만 봐서는 알 수 없지만 시스템 여러 부분에서 함께 지켜야 하는 규칙과, 프로젝트가 실제로 빌드할 때 사용하는 도구 버전을 기록합니다. 빠짐없이 나열하기 위한 목록은 만들지 않습니다.
• 긍정형 지침보다 부정형 제약. 측정 결과 부정형이 더 효과적이었습니다. 그래서 금지 사항을 적을 때는 항상 허용되는 대안도 함께 밝힙니다.

의도적으로 수집하지 않는 정보

무엇을 비워 두는지가 이 설계의 핵심입니다.

수집하지 않는 정보	이유
코드가 이미 말해 주는 내용	에이전트는 소스 요약보다 소스 자체를 더 잘 읽습니다. 바꿔 쓴 설명을 추가하면 원본은 정확한데 복사본만 낡아 가는 문제가 생깁니다.
저장소 구조와 파일 맵	구조는 커밋마다 달라져 저장된 맵이 가장 빨리 낡습니다. 에이전트는 몇 초 안에 최신 구조를 직접 파악할 수 있습니다.
개요와 둘러보기 문서	대표적인 생성 산출물이자 측정된 성능 저하의 원인입니다. 블록은 독자를 안내하는 대신 에이전트의 행동을 바꿔야 합니다.
생태계 기본값	LLM은 일반적인 Node, Python, Go 프로젝트의 작동 방식을 이미 압니다. 기본값을 다시 설명하면 에이전트가 처음부터 알고 있던 내용을 가르치는 데 비용을 씁니다.
흥미롭다는 이유만으로 넣은 내용	흥미롭다는 사실은 필요하다는 증거가 아닙니다. 이 스킬은 바로 이런 정보가 쌓이는 문제를 막기 위해 존재합니다.
에이전트가 스스로 지켜야 하는 스타일 규칙	이런 규칙은 포매터, 린터, 훅, CI 검사가 맡아야 합니다. 스킬은 대신 검사를 제안하며, 검사가 도입되면 해당 줄은 삭제합니다.
이력과 편집 과정 설명	”X를 제거한 이유는…” 같은 서술은 금지합니다. 이력은 Git이 관리하고 블록에는 현재의 사실만 적습니다.
지향하는 미래 상태	시스템이 앞으로 어떤 모습이어야 하는지는 사양에 속합니다. 에이전트가 미래 목표를 현재 사실로 오인하면 존재하지 않는 동작을 구현합니다.

결과가 작은 것은 의도된 설계입니다. 근거가 열 줄만 뒷받침한다면 산출물도 열 줄이면 됩니다.

규칙을 없앨 때는 반대로 판단합니다

규칙을 없앨 때만큼은 가지치기 원칙을 반대로 적용해야 합니다. 이를 잘못 적용하면 파일에서 가장 가치 있는 내용이 조용히 사라집니다.

정책이나 위험 요소는 세 가지 경우에만 삭제합니다. 지키던 대상이 사라지거나 해당 제약이 자동으로 강제되는 경우, 또는 사람이 직접 폐기한 경우입니다. 최근에 같은 실패가 없었다는 이유로는 삭제하지 않습니다. 효과가 있는 규칙은 실패의 흔적을 스스로 없애기 때문입니다. 이 블록에서는 더는 발생하지 않는 실수를 막아 주는 규칙이 특히 중요합니다.

이 보호 원칙은 정책이나 위험 요소뿐 아니라 사람이 작성한 모든 지침에 적용됩니다. 내용이 오래됐거나 틀렸을 때, 훅이나 검사로 이미 강제될 때, 해롭거나 다른 지침과 충돌할 때, 또는 사용자가 항목별 삭제를 승인했을 때만 없앱니다. 저장소에서 유추하거나 다른 위치에서 찾을 수 있다는 이유만으로는 삭제하지 않습니다.

서로 다른 두 범위와 두 산출물

하나의 산출물로 코딩 작업과 계획 작업을 모두 지원할 수는 없습니다. 두 작업에 필요한 정보는 거의 겹치지 않습니다.

구현 컨텍스트는 제약, 명령, 규칙, 위험 요소를 담으며 코드 저장소에 속합니다. 코드와 대조하고 직접 실행해 검증할 수 있지만 커밋할 때마다 낡습니다. 모든 세션에서 불러오므로 아주 작아야 합니다. 이 스킬이 관리하는 대상입니다.

계획 컨텍스트는 결정 근거, 선택하지 않은 대안, 책임 주체, 도메인 의미, 조직 표준을 담으며 프로젝트나 이니셔티브에 속합니다. 출처 문서로만 추적할 수 있습니다. 저장소가 아니라 조직의 변화 주기에 따라 보통 수개월 단위로 낡습니다. 항상 불러오지 않고 필요할 때 집중적으로 살펴봅니다. 이는 별도의 기능이며 추후 제공될 예정입니다.

서로 다른 두 범위를 파일 하나로 해결하려 한 결과가 이 스킬이 대체한 두 스킬이었습니다.

컨텍스트는 계속 가치를 입증해야 합니다

이전 모델은 문서를 자산으로 다뤘습니다. 범위가 넓을수록 가치가 크다고 봤습니다. 이 스킬은 컨텍스트를 유지할 가치가 있는지 계속 입증해야 하는 부담으로 봅니다. Refresh는 모든 주의 사항을 다시 확인합니다. 삭제되거나 이름이 바뀐 항목도 각 줄과 대조합니다. Audit은 가지치기 테스트를 적용하되, 사람이 작성한 내용에는 앞에서 설명한 삭제 기준을 함께 적용합니다. 작업 후 블록은 이전보다 작거나 같은 크기를 유지합니다. 주장의 출처가 사라지면 새로운 사실에 맞춰 주장을 고치거나 제거합니다. 같은 내용을 언급한다는 이유만으로 다른 문서를 새 출처로 바꿔 끼우지 않습니다.

첫 버전은 쉽게 만들 수 있습니다. 진짜 가치는 계속 정확하게 유지하는 데 있습니다. Refresh와 Audit이 설명서의 참고 사항이 아니라 독립된 의도로 제공되는 이유입니다.

대체된 두 스킬과의 차이

bmad-document-project는 기존 저장소를 스캔해 개요, 소스 트리, 영역별 심층 설명으로 구성된 문서 트리를 생성했습니다. 문서를 자산으로 보는 모델이었지만 증거는 반대였습니다. 결과물은 크고 검증되지 않았으며 만들어지는 순간부터 낡았습니다. 에이전트의 성능을 떨어뜨리는 종류의 컨텍스트였습니다. 그래도 작업 전에 저장소를 이해해야 한다는 발상은 탐색 단계에 남았습니다. 이제 탐색 결과는 설명문을 만드는 대신 검증에 사용합니다.

bmad-generate-project-context에는 눈에 띄지 않는 프로젝트별 사실을 작은 규칙 파일 하나에 담는다는 올바른 생각이 있었습니다. 이제 그 생각이 전체 구조의 중심입니다. 이전 방식에는 검증 절차나 유지보수 주기가 없었고, 추론과 확인된 사실을 구분할 방법도 없었습니다.

이전 스킬은 더 많은 문서를 작성했고 새 스킬은 더 적은 사실을 관리합니다. 정보는 많기보다 적고 검증된 편이 낫습니다.