---
title: "프로젝트 컨텍스트"
description: project-context.md가 프로젝트 규칙과 선호도로 AI 에이전트를 안내하는 방법
sidebar:
  order: 12
---

`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[권장]
새 프로젝트에서 강한 기술 선호 사항이 있다면 아키텍처 전에 수동으로 만드세요. 그렇지 않다면 아키텍처 후 생성해 그 결정을 포착하세요.
:::

## 무엇이 들어가나요?

파일에는 두 주요 섹션이 있습니다.

### 기술 스택과 버전

프로젝트가 사용하는 프레임워크, 언어, 도구를 구체적 버전과 함께 문서화합니다.

```markdown
## 기술 스택과 버전

- Node.js 20.x, TypeScript 5.3, React 18.2
- 상태 관리: Zustand(Redux 아님)
- 테스트: Vitest, Playwright, MSW
- 스타일링: 커스텀 디자인 토큰을 사용하는 Tailwind CSS
```

### 중요한 구현 규칙

에이전트가 놓칠 수 있는 패턴과 관례를 문서화합니다.

```markdown
## 중요한 구현 규칙

**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`에 파일을 만들고 규칙을 추가합니다.

```bash
# 프로젝트 루트에서
mkdir -p _bmad-output
touch _bmad-output/project-context.md
```

기술 스택과 구현 규칙을 편집하세요. 아키텍트와 구현 워크플로가 자동으로 찾아 로드합니다.

### 아키텍처 후 생성

아키텍처를 완료한 뒤 `bmad-generate-project-context` 워크플로를 실행합니다.

```bash
bmad-generate-project-context
```

이 워크플로는 아키텍처 문서와 프로젝트 파일을 스캔해 내려진 결정을 담은 컨텍스트 파일을 생성합니다.

### 기존 프로젝트용 생성

기존 프로젝트에서는 `bmad-generate-project-context`를 실행해 기존 패턴을 발견합니다.

```bash
bmad-generate-project-context
```

워크플로가 코드베이스를 분석해 관례를 식별한 뒤 검토하고 다듬을 수 있는 컨텍스트 파일을 생성합니다.

## 왜 중요한가

`project-context.md`가 없으면 에이전트는 프로젝트에 맞지 않는 가정을 할 수 있습니다.

| 컨텍스트 없음 | 컨텍스트 있음 |
| --- | --- |
| 일반 패턴 사용 | 기존 관례 따름 |
| 스토리마다 일관되지 않은 스타일 | 일관된 구현 |
| 프로젝트별 제약을 놓칠 수 있음 | 모든 기술 요구사항 존중 |
| 각 에이전트가 독립적으로 결정 | 모든 에이전트가 같은 규칙에 맞춰 동작 |

특히 다음에 중요합니다.

- **빠른 흐름** - PRD와 아키텍처를 건너뛰므로 컨텍스트 파일이 공백을 채웁니다
- **팀 프로젝트** - 모든 에이전트가 같은 표준을 따르게 합니다
- **기존 프로젝트** - 기존 패턴을 깨뜨리지 않게 합니다

## 편집과 업데이트

`project-context.md` 파일은 살아 있는 문서입니다. 다음 때 업데이트하세요.

- 아키텍처 결정이 바뀝니다
- 새 관례가 확립됩니다
- 구현 중 패턴이 진화합니다
- 에이전트 동작에서 공백을 발견합니다

언제든 수동으로 편집하거나, 큰 변경 후 `bmad-generate-project-context`를 다시 실행해 업데이트할 수 있습니다.

:::note[파일 위치]
기본 위치는 `_bmad-output/project-context.md`입니다. 워크플로는 그곳을 검색하고, 프로젝트 어디에 있든 `**/project-context.md`도 확인합니다.
:::