BMAD-METHOD/docs/zh-cn/how-to/project-context.md

title	description	sidebar
管理项目上下文	创建并维护 project-context.md 以指导 AI 智能体	order 8

使用 project-context.md，确保 AI 智能体在各类工作流中遵循项目的技术偏好与实现规则。 为了保证这份上下文始终可见，你也可以在工具上下文或 always-rules 文件（如 AGENTS.md） 中加入这句： Important project context and conventions are located in [path to project context]/project-context.md

:::note[前置条件]

• 已安装 BMad Method
• 了解项目的技术栈与团队约定 :::

何时使用

• 在开始架构（architecture）前，你已有明确的技术偏好
• 已完成架构设计，希望把关键决策沉淀到实施阶段
• 正在处理具有既定模式的既有代码库
• 发现智能体在不同用户故事（story）之间决策不一致

步骤 1：选择路径

手动创建 — 适合你已经明确知道要沉淀哪些规则

架构后生成 — 适合把 solutioning 阶段形成的架构决策沉淀下来

为既有项目生成 — 适合从现有代码库中自动发现团队约定与模式

步骤 2：创建文件

选项 A：手动创建

在 _bmad-output/project-context.md 创建文件：

mkdir -p _bmad-output
touch _bmad-output/project-context.md

然后补充技术栈与实现规则：

---
project_name: '我的项目'
user_name: '你的名字'
date: '2026-02-15'
sections_completed: ['technology_stack', 'critical_rules']
---

# AI 智能体项目上下文

## 技术栈与版本

- Node.js 20.x, TypeScript 5.3, React 18.2
- 状态管理：Zustand
- 测试：Vitest, Playwright
- 样式：Tailwind CSS

## 关键实现规则

**TypeScript：**
- 开启严格模式，禁止使用 `any` 类型
- 对外 API 使用 `interface`，联合类型使用 `type`

**代码组织：**
- 组件放在 `/src/components/`，并与测试文件同目录（co-located）
- API 调用统一使用 `apiClient` 单例，不要直接使用 `fetch`

**测试：**
- 单元测试聚焦业务逻辑
- 集成测试使用 MSW 模拟 API

选项 B：架构后生成

在新的会话中运行：

bmad-generate-project-context

该工作流会扫描架构文档和项目文件，生成能够反映已做决策的上下文文件。

选项 C：为既有项目生成

对于既有项目，运行：

bmad-generate-project-context

该工作流会分析代码库中的约定，然后生成可供你审阅和完善的上下文文件。

步骤 3：验证内容

审查生成文件，并确认它覆盖了：

• 正确的技术版本
• 你的真实约定（不是通用最佳实践）
• 能预防常见错误的规则
• 框架相关模式

如果有缺漏或误判，直接手动补充和修正。

你将获得

一个 project-context.md 文件，它可以：

• 确保所有智能体遵循相同约定
• 避免在不同用户故事（story）中出现不一致决策
• 为实施阶段保留架构决策
• 作为项目模式与规则的长期参考

提示

:::tip[最佳实践]

• 聚焦“不明显但重要”的规则：优先记录智能体容易漏掉的项目约束，而不是 “变量要有意义”这类通用建议。
• 保持精简：此文件会被多数实现工作流加载，过长会浪费上下文窗口。避免写入 只适用于单一 story 的细节。
• 按需更新：当团队约定变化时手动更新，或在架构发生较大变化后重新生成。
• 适用于 Quick Flow 与完整 BMad Method：两种模式都可共享同一份项目上下文。 :::

后续步骤

• 项目上下文说明 - 了解其工作原理
• 工作流程图 - 查看哪些工作流会加载项目上下文