6.8 KiB
| title | description | sidebar | ||
|---|---|---|---|---|
| 프로젝트 컨텍스트 | project-context.md가 프로젝트 규칙과 선호도로 AI 에이전트를 안내하는 방법 |
|
project-context.md 파일은 AI 에이전트를 위한 프로젝트 구현 가이드입니다. 다른 개발 체계의 "헌장"처럼 모든 워크플로에서 일관된 코드 생성을 보장하는 규칙, 패턴, 선호 사항을 포착합니다.
하는 일
AI 에이전트는 구현 중 계속 결정을 내립니다. 어떤 패턴을 따를지, 코드를 어떻게 구조화할지, 어떤 관례를 사용할지 등입니다. 명확한 안내가 없으면 다음이 일어날 수 있습니다.
- 코드베이스와 맞지 않는 범용 모범 사례를 따릅니다
- 스토리마다 일관되지 않은 결정을 내립니다
- 프로젝트별 요구사항이나 제약을 놓칩니다
project-context.md 파일은 에이전트가 알아야 할 것을 간결하고 LLM에 최적화된 형식으로 문서화해 이 문제를 해결합니다.
작동 방식
모든 구현 워크플로는 project-context.md가 있으면 자동으로 로드합니다. 아키텍트 워크플로도 아키텍처를 설계할 때 기술 선호 사항을 존중하기 위해 이 파일을 로드합니다.
이 워크플로들이 로드합니다:
bmad-create-architecture- 솔루션 설계 중 기술 선호 사항을 존중합니다bmad-create-story- 프로젝트 패턴으로 스토리 작성을 안내합니다bmad-dev-story- 구현 결정을 안내합니다bmad-code-review- 프로젝트 표준과 비교해 검증합니다bmad-quick-dev- 사양을 구현할 때 패턴을 적용합니다bmad-sprint-planning,bmad-retrospective,bmad-correct-course- 프로젝트 전반의 컨텍스트를 제공합니다
언제 만들까요?
project-context.md 파일은 프로젝트 어느 단계에서든 유용합니다.
| 시나리오 | 만들 시점 | 목적 |
|---|---|---|
| 새 프로젝트, 아키텍처 전 | bmad-create-architecture 전에 수동 작성 |
아키텍트가 기술 선호 사항을 존중하도록 문서화 |
| 새 프로젝트, 아키텍처 후 | bmad-generate-project-context 또는 수동 작성 |
구현 에이전트를 위해 아키텍처 결정 포착 |
| 기존 프로젝트 | bmad-generate-project-context로 생성 |
기존 패턴을 발견해 에이전트가 기존 관례를 따르게 함 |
| 빠른 흐름 프로젝트 | bmad-quick-dev 전 또는 중 |
빠른 구현이 패턴을 존중하도록 보장 |
:::tip[권장] 새 프로젝트에서 강한 기술 선호 사항이 있다면 아키텍처 전에 수동으로 만드세요. 그렇지 않다면 아키텍처 후 생성해 그 결정을 포착하세요. :::
무엇이 들어가나요?
파일에는 두 주요 섹션이 있습니다.
기술 스택과 버전
프로젝트가 사용하는 프레임워크, 언어, 도구를 구체적 버전과 함께 문서화합니다.
## 기술 스택과 버전
- Node.js 20.x, TypeScript 5.3, React 18.2
- 상태 관리: Zustand(Redux 아님)
- 테스트: Vitest, Playwright, MSW
- 스타일링: 커스텀 디자인 토큰을 사용하는 Tailwind CSS
중요한 구현 규칙
에이전트가 놓칠 수 있는 패턴과 관례를 문서화합니다.
## 중요한 구현 규칙
**TypeScript 설정:**
- 엄격 모드 사용 - 명시적 승인 없이 `any` 타입 금지
- 공개 API에는 `interface`, 유니언/인터섹션에는 `type` 사용
**코드 구성:**
- 컴포넌트는 `/src/components/`에 두고 `.test.tsx`를 함께 배치
- 재사용 가능한 순수 함수는 `/src/lib/` 유틸리티에 배치
- API 호출은 `apiClient` 싱글턴 사용 - 직접 fetch 금지
**테스트 패턴:**
- 단위 테스트는 구현 세부사항이 아니라 비즈니스 로직에 집중
- 통합 테스트는 MSW로 API 응답을 모킹
- E2E 테스트는 중요한 사용자 여정만 다룸
**프레임워크별 규칙:**
- 모든 비동기 작업은 일관된 오류 처리를 위해 `handleError` 래퍼 사용
- 기능 플래그는 `@/lib/flags`의 `featureFlag()`로 접근
- 새 라우트는 `/src/app/`의 파일 기반 라우팅 패턴을 따름
코드 스니펫을 읽고 에이전트가 추론하지 못할 겉으로 잘 드러나지 않는 것에 집중하세요. 보편적으로 적용되는 표준 관행은 문서화하지 마세요.
파일 만들기
세 가지 선택지가 있습니다.
수동 작성
_bmad-output/project-context.md에 파일을 만들고 규칙을 추가합니다.
# 프로젝트 루트에서
mkdir -p _bmad-output
touch _bmad-output/project-context.md
기술 스택과 구현 규칙을 편집하세요. 아키텍트와 구현 워크플로가 자동으로 찾아 로드합니다.
아키텍처 후 생성
아키텍처를 완료한 뒤 bmad-generate-project-context 워크플로를 실행합니다.
bmad-generate-project-context
이 워크플로는 아키텍처 문서와 프로젝트 파일을 스캔해 내려진 결정을 담은 컨텍스트 파일을 생성합니다.
기존 프로젝트용 생성
기존 프로젝트에서는 bmad-generate-project-context를 실행해 기존 패턴을 발견합니다.
bmad-generate-project-context
워크플로가 코드베이스를 분석해 관례를 식별한 뒤 검토하고 다듬을 수 있는 컨텍스트 파일을 생성합니다.
왜 중요한가
project-context.md가 없으면 에이전트는 프로젝트에 맞지 않는 가정을 할 수 있습니다.
| 컨텍스트 없음 | 컨텍스트 있음 |
|---|---|
| 일반 패턴 사용 | 기존 관례 따름 |
| 스토리마다 일관되지 않은 스타일 | 일관된 구현 |
| 프로젝트별 제약을 놓칠 수 있음 | 모든 기술 요구사항 존중 |
| 각 에이전트가 독립적으로 결정 | 모든 에이전트가 같은 규칙에 맞춰 동작 |
특히 다음에 중요합니다.
- 빠른 흐름 - PRD와 아키텍처를 건너뛰므로 컨텍스트 파일이 공백을 채웁니다
- 팀 프로젝트 - 모든 에이전트가 같은 표준을 따르게 합니다
- 기존 프로젝트 - 기존 패턴을 깨뜨리지 않게 합니다
편집과 업데이트
project-context.md 파일은 살아 있는 문서입니다. 다음 때 업데이트하세요.
- 아키텍처 결정이 바뀝니다
- 새 관례가 확립됩니다
- 구현 중 패턴이 진화합니다
- 에이전트 동작에서 공백을 발견합니다
언제든 수동으로 편집하거나, 큰 변경 후 bmad-generate-project-context를 다시 실행해 업데이트할 수 있습니다.
:::note[파일 위치]
기본 위치는 _bmad-output/project-context.md입니다. 워크플로는 그곳을 검색하고, 프로젝트 어디에 있든 **/project-context.md도 확인합니다.
:::