프로젝트 컨텍스트
bmad-project-context는 AI 에이전트가 저장소에서 제대로 작업할 수 있도록 환경을 정비합니다. 산출물은 저장소의 AGENTS.md 안에 들어가는 간결하고 검증된 규칙 블록입니다. 조직이 요구하는 사항, 실제로 실행해 확인한 명령, 일반적인 예상과 다른 규칙, 에이전트가 이 저장소에서 반복하는 실수를 기록합니다.
이 스킬은 생성기가 아니라 대화형 도구입니다. 에이전트가 지켜야 할 규칙, 즉 거버넌스와 보안, 코딩 표준을 알려주면 나머지는 스킬이 찾아 검증합니다. 무엇을 쓸 때든 사람이 확인하며 무인 실행 모드는 없습니다.
의도적으로 수집하지 않는 정보와 그 이유를 포함한 전체 근거는 프로젝트 컨텍스트의 이론을 참고하세요.
포함하는 정보와 제외하는 정보
섹션 제목: “포함하는 정보와 제외하는 정보”기준은 필요한 순간에 해당 사실을 찾아내는 데 드는 비용입니다. 에이전트는 코드를 설명한 글보다 코드 자체를 더 정확히 읽습니다. 적은 비용으로 찾을 수 있는 내용을 글로 복제하면 금세 낡고, 호출할 때마다 불필요한 비용도 듭니다. 따라서 저장소 개요, 디렉터리 구조, 기술 스택 목록은 넣지 않습니다. 대신 찾는 데 큰 비용이 들거나, 실수한 뒤에야 발견하기 쉬운 내용을 기록합니다.
코드만 읽어서는 필요한 순간에 찾기 어렵거나 알 수 없는 다음 정보는 기록할 가치가 있습니다.
- 조직 정책 — 변경 금지 경로, 생성된 파일, 브랜치 규칙, 보안 및 규정 준수 요구 사항
- 설정 파일만으로 알 수 없는 실행 조건 — 모든 스크립트를 옮겨 적는 대신 어떤 명령을 사용해야 하는지와 주의할 점을 기록합니다.
pnpm test는 이미package.json에 있지만, 테스트가 11분 걸리거나 먼저 서비스를 실행해야 한다는 사실은 그렇지 않습니다. - 생태계 기본값과 다른 규칙 — 별도 지침이 없으면 에이전트는 일반적인 방식을 따르기 때문입니다.
- 실제로 겪은 문제 — 기존 기록, 관리자의 기억, Git 이력에서 반복해 수정한 실수, 이번 작성 과정에서 발견하고 바로잡은 실수만 포함합니다. 스캔 중 위험해 보이는 사실을 찾더라도 곧바로 규칙으로 쓰지 않고 먼저 질문합니다.
- 컴포넌트 간 규칙과 필수 버전 — 지금 편집하는 파일만 봐서는 알 수 없지만 시스템 여러 부분에서 함께 지켜야 하는 규칙과, 프로젝트가 실제로 빌드할 때 사용하는 도구 버전을 기록합니다.
- 작업 결과가 저장되는 위치와 먼저 읽어야 할 파일을 가리키는 포인터
스킬이 적용하는 모든 규칙과 그 근거는 references/best-practices.md에 정리되어 있습니다. 스킬은 이 기준으로 저장소의 현재 상태를 평가하고, 작업을 마칠 때 판단 근거도 설명합니다.
지원하는 의도
섹션 제목: “지원하는 의도”| 의도 | 수행하는 작업 |
|---|---|
| Setup | 보존할 기존 지침이 없는 저장소에서 사용합니다. 사용자가 제공할 규칙을 물은 뒤 나머지를 찾아 검증하고, 전체 블록을 미리 보여준 다음 승인받아 작성합니다. |
| Adopt | 사용자가 이미 작성한 지침을 받아들입니다. 파일을 쓰기 전에 기존 지침이 각각 어떻게 처리되는지 보여주며, 사용자 승인 없이 삭제하지 않습니다. |
| Refresh | 기존 블록을 대상으로 같은 과정을 실행합니다. 명령을 다시 실행하고, 기록된 커밋 이후 삭제되거나 이름이 바뀐 항목을 비교해 이동한 내용을 갱신합니다. |
| Record | 에이전트가 실제로 저지른 실수 하나를 발생 시점에 기록합니다. 반복되거나 비용이 큰 실수라면 한 줄을 추가합니다. |
| Audit | 내용을 다시 검증하고 불필요한 항목을 덜어냅니다. 작업 후 블록은 이전보다 작거나 같은 크기를 유지합니다. |
에이전트가 불러오는 방식
섹션 제목: “에이전트가 불러오는 방식”주요 코딩 도구가 모두 읽는 저장소 루트의 AGENTS.md를 사용합니다. BMad는 <!-- bmad:context -->와 <!-- /bmad:context --> 사이만 관리합니다. 사용자가 마커 밖에 작성한 내용은 바이트 단위로 그대로 보존하며 Refresh도 건드리지 않습니다.
모노레포의 컴포넌트와 중첩된 저장소에는 같은 규칙으로 별도의 파일을 만들고, 상위 파일에서 포인터로 연결합니다. 특정 디렉터리에만 적용되는 규칙이 많다면 해당 디렉터리의 AGENTS.md로 옮길 수 있습니다. 다만 사용하는 도구가 그 위치의 파일을 실제로 읽는지 먼저 확인해야 합니다. 읽지 않는다면 규칙을 루트 파일에 두고, 각 규칙이 적용되는 디렉터리를 명시합니다.
저장소와 홈 디렉터리 중 어디에 둘까
섹션 제목: “저장소와 홈 디렉터리 중 어디에 둘까”이 스킬이 작성한 내용은 저장소에 커밋해야 합니다. 팀이 공유하고, 모든 컴퓨터에서 같은 규칙을 쓰며, 제약을 받는 코드와 함께 버전으로 관리하기 위해서입니다. 모든 프로젝트에서 같은 규칙이 반복되거나 팀 규칙이 아닌 개인 취향이라면 홈 디렉터리에 있는 에이전트 전역 설정에 두세요.
아키텍처와의 관계
섹션 제목: “아키텍처와의 관계”결정은 bmad-architecture에서 내립니다. 서로 다른 선택지에 실제 장단점이 있어 의견이 갈리는 설계 결정을 발견하면 이 스킬이 조용히 결론을 내리지 않고 bmad-architecture에서 다뤄야 한다고 안내합니다.