프로젝트 컨텍스트 관리하기

bmad-project-context는 AI 에이전트가 저장소에서 제대로 작업할 수 있는 환경을 마련합니다. 새 프로젝트와 기존 코드베이스에서 모두 쓸 수 있고 BMad 설치 여부도 상관없습니다. 결과는 AGENTS.md에 들어가는 간결하고 검증된 규칙 블록입니다.

사용 시점

기존 코드베이스에서 AI 지원 작업을 시작하면서 거버넌스, 보안, 스타일 같은 조직 표준을 적용할 때
직접 작성한 AGENTS.md나 CLAUDE.md를 교체하지 않고 받아들여 개선하고 싶을 때
새 프로젝트의 첫 커밋부터 정해 둔 표준을 따르게 하고 싶을 때
에이전트가 같은 실수를 반복해 이를 기록하고 싶을 때
지침이 오래됐거나 불필요하게 커졌다고 느낄 때(Audit 실행)

1단계: 실행하기

bmad-project-context

“AGENTS.md를 설정해 줘”, “기존 AGENTS.md를 받아들여 줘”, “컨텍스트를 새로 고쳐 줘”, “컨텍스트를 감사해 줘”, “에이전트가 계속 잘못된 테스트 러너를 사용해”처럼 원하는 작업을 일반 문장으로 말하면 스킬이 알맞은 의도를 선택합니다. 스킬이 작성하지 않은 기존 지침이 있으면 Adopt를 사용하고, 이전에 스킬이 작성한 지침이 있으면 해당 내용을 갱신합니다. Setup은 보존할 지침이 없는 저장소에서만 사용합니다.

저장소 밖에서 실행했다면 작업할 저장소를 지정하세요. 경로가 둘 이상의 작업 트리로 연결되면 스킬은 파일을 쓰기 전에 어느 쪽인지 확인합니다.

2단계: 직접 알고 있는 규칙 알려주기

스킬은 먼저 AGENTS.md, CLAUDE.md, 편집기 규칙 파일, 문서 등 기존 자료를 읽습니다. 잘 구성된 부분과 오래된 것으로 보이는 부분, 바꾸기를 제안하는 내용을 나눠 알려줍니다. 사람이 작성한 기존 파일은 버리지 않고 개선합니다. 파일을 쓰기 전에 기존 지침이 각각 어떻게 처리되는지 보여주며, 사용자 승인 없이 삭제하지 않습니다.

그다음 저장소의 현재 상태와 무관하게 지켜야 할 규칙을 묻습니다. 거버넌스, 보안 및 규정 준수 요구 사항, 코딩 표준, 스타일 가이드, 변경 금지 영역 등이 해당합니다. 조직 핸드북, 위키 내보내기, MCP 지식 베이스처럼 저장소 밖의 문서도 함께 제공할 수 있습니다.

새 프로젝트라면 이 대화에서 필요한 내용이 모두 나옵니다. 기존 코드베이스에서는 스캔으로 알 수 없는 나머지 절반을 이 대화로 채웁니다.

3단계: 나머지 정보 검증하기

스킬은 기록할 모든 경로를 확인하고 package.json, Makefile, CI 설정을 읽습니다. 스크립트는 에이전트가 이 파일에서 직접 읽을 수 있으므로 그대로 옮겨 적지 않습니다. 대신 기존 설정이 무엇을 설명하는지 파악한 뒤, 사용해야 할 명령과 잘못된 추측을 바로잡는 내용, 주의 사항만 블록에 담습니다.

이후 스캔만으로 답할 수 없는 내용을 묻습니다. 에이전트가 이 저장소에서 반복하는 실수, 변경하면 안 되는 부분, 도메인 용어의 의미, 실행할 때 주의해야 하는 명령이 여기에 해당합니다.

4단계: 블록 승인하기

파일을 쓰기 전에 전체 블록을 먼저 보여줍니다. 사용자가 승인해야만 와  사이에 내용을 넣습니다. 마커 밖에 사용자가 작성한 내용은 바이트 단위로 그대로 보존합니다.

스킬은 커밋하지 않습니다. 사용자가 검토할 수 있도록 변경 사항을 작업 트리에 남겨 둡니다.

작업을 마치면 어떤 내용을 넣고 뺐는지, 왜 그렇게 판단했는지 설명합니다.

정확하게 유지하기

Refresh — 실제 변경이 생긴 뒤 실행합니다. 주의 사항이 여전히 맞는지 확인한 뒤 기록된 커밋 이후 삭제되거나 이름이 바뀐 항목을 비교해 이동한 내용을 갱신합니다. 이미 정한 내용은 다시 묻지 않습니다.
Record — 에이전트가 무언가 잘못한 순간 실행합니다. 실제로 관찰한 실수만 위험 요소로 기록할 수 있습니다.
Audit — 모든 내용을 다시 검증하고 불필요한 항목을 덜어냅니다. 작업 후 블록은 이전보다 작거나 같은 크기를 유지합니다.

규칙이 지키는 대상이 사라지거나 사용자가 직접 폐기할 때까지는 해당 규칙을 유지합니다. 최근에 같은 문제가 없었다는 이유만으로 삭제하면 안 됩니다. 효과가 있는 규칙은 실패의 흔적을 스스로 없애기 때문입니다.

저장소와 홈 디렉터리 중 어디에 둘까

이 스킬이 작성한 내용은 팀과 공유할 수 있도록 저장소에 커밋합니다. 모든 프로젝트에서 같은 규칙이 반복되거나 팀 규칙이 아닌 개인 취향이라면 홈 디렉터리에 있는 에이전트 전역 설정에 두세요.

폐기된 이전 스킬

다음 단계

프로젝트 컨텍스트 설명 — 설계와 그 근거
워크플로 맵 — 전체 방법론에서 컨텍스트가 들어가는 위치