项目上下文

project-context.md 文件是您的项目面向 AI 智能体的实施指南。类似于其他开发系统中的”宪法”，它记录了确保所有工作流中代码生成一致的规则、模式和偏好。

它的作用

AI 智能体不断做出实施决策——遵循哪些模式、如何组织代码、使用哪些约定。如果没有明确指导，它们可能会：

遵循与您的代码库不匹配的通用最佳实践
在不同的用户故事中做出不一致的决策
错过项目特定的需求或约束

project-context.md 文件通过以简洁、针对 LLM 优化的格式记录智能体需要了解的内容来解决这个问题。

它的工作原理

每个实施工作流都会自动加载 project-context.md（如果存在）。架构师工作流也会加载它，以便在设计架构时尊重您的技术偏好。

由以下工作流加载：

create-architecture — 在解决方案设计期间尊重技术偏好
create-story — 使用项目模式指导用户故事创建
dev-story — 指导实施决策
code-review — 根据项目标准进行验证
quick-dev — 在实施技术规范时应用模式
sprint-planning、retrospective、correct-course — 提供项目范围的上下文

何时创建

project-context.md 文件在项目的任何阶段都很有用：

场景	何时创建	目的
新项目，架构之前	手动，在 `create-architecture` 之前	记录您的技术偏好，以便架构师尊重它们
新项目，架构之后	通过 `generate-project-context` 或手动	捕获架构决策，供实施智能体使用
现有项目	通过 `generate-project-context`	发现现有模式，以便智能体遵循既定约定
快速流程项目	在 `quick-dev` 之前或期间	确保快速实施尊重您的模式

文件内容

该文件有两个主要部分：

技术栈与版本

记录项目使用的框架、语言和工具及其具体版本：

## Technology Stack & Versions

- Node.js 20.x, TypeScript 5.3, React 18.2
- State: Zustand (not Redux)
- Testing: Vitest, Playwright, MSW
- Styling: Tailwind CSS with custom design tokens

关键实施规则

记录智能体可能忽略的模式和约定：

## Critical Implementation Rules

**TypeScript Configuration:**
- Strict mode enabled — no `any` types without explicit approval
- Use `interface` for public APIs, `type` for unions/intersections

**Code Organization:**
- Components in `/src/components/` with co-located `.test.tsx`
- Utilities in `/src/lib/` for reusable pure functions
- API calls use the `apiClient` singleton — never fetch directly

**Testing Patterns:**
- Unit tests focus on business logic, not implementation details
- Integration tests use MSW to mock API responses
- E2E tests cover critical user journeys only

**Framework-Specific:**
- All async operations use the `handleError` wrapper for consistent error handling
- Feature flags accessed via `featureFlag()` from `@/lib/flags`
- New routes follow the file-based routing pattern in `/src/app/`

专注于那些不明显的内容——智能体可能无法从阅读代码片段中推断出来的内容。不要记录普遍适用的标准实践。

创建文件

您有三个选择：

手动创建

在 _bmad-output/project-context.md 创建文件并添加您的规则：

# In your project root
mkdir -p _bmad-output
touch _bmad-output/project-context.md

使用您的技术栈和实施规则编辑它。架构师和实施工作流将自动查找并加载它。

架构后生成

在完成架构后运行 generate-project-context 工作流：

/bmad-bmm-generate-project-context

这将扫描您的架构文档和项目文件，生成一个捕获所做决策的上下文文件。

为现有项目生成

对于现有项目，运行 generate-project-context 以发现现有模式：

/bmad-bmm-generate-project-context

该工作流分析您的代码库以识别约定，然后生成一个您可以审查和优化的上下文文件。

为什么重要

没有 project-context.md，智能体会做出可能与您的项目不匹配的假设：

没有上下文	有上下文
使用通用模式	遵循您的既定约定
用户故事之间风格不一致	实施一致
可能错过项目特定的约束	尊重所有技术需求
每个智能体独立决策	所有智能体遵循相同规则

这对于以下情况尤其重要：

快速流程 — 跳过 PRD 和架构，因此上下文文件填补了空白
团队项目 — 确保所有智能体遵循相同的标准
现有项目 — 防止破坏既定模式

编辑和更新

project-context.md 文件是一个动态文档。在以下情况下更新它：

架构决策发生变化
建立了新的约定
模式在实施过程中演变
您从智能体行为中发现差距

您可以随时手动编辑它，或者在重大更改后重新运行 generate-project-context 来更新它。

术语说明

agent：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
workflow：工作流。指一系列自动化或半自动化的任务流程。
PRD：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。
LLM：大语言模型（Large Language Model）。指基于深度学习的自然语言处理模型。
singleton：单例。一种设计模式，确保一个类只有一个实例。
E2E：端到端（End-to-End）。指从用户角度出发的完整测试流程。
MSW：Mock Service Worker。用于模拟 API 响应的库。
Vitest：基于 Vite 的单元测试框架。
Playwright：端到端测试框架。
Zustand：轻量级状态管理库。
Redux：JavaScript 应用状态管理库。
Tailwind CSS：实用优先的 CSS 框架。
TypeScript：JavaScript 的超集，添加了静态类型。
React：用于构建用户界面的 JavaScript 库。
Node.js：基于 Chrome V8 引擎的 JavaScript 运行时。