4.0 KiB
4.0 KiB
| title | description | sidebar | ||
|---|---|---|---|---|
| 项目上下文 | project-context.md 如何使用项目规则和偏好指导 AI 智能体 |
|
project-context.md 是面向 AI 智能体的项目级上下文文件。它的定位不是教程步骤，而是“实现约束说明”：把你的技术偏好、架构边界和工程约定沉淀成可复用规则，让不同工作流、不同智能体在多个 story 中做出一致决策。
project context 解决什么问题
没有统一上下文时，智能体往往会：
- 套用通用最佳实践，而不是你的项目约定
- 在不同
story中做出不一致实现 - 漏掉代码里不易推断的隐性约束
有 project-context.md 时，这些高频偏差会明显减少，因为关键规则在进入实现前已经被显式声明。
它如何被工作流使用
多数实现相关工作流会自动加载 project-context.md（若存在），并把它作为共享上下文参与决策。
常见加载方包括：
bmad-create-architecture：在 solutioning 时纳入你的技术偏好bmad-create-story：按项目约定拆分和描述 storybmad-dev-story：约束实现路径和代码风格bmad-code-review：按项目标准做一致性校验bmad-quick-dev：在快速实现中避免偏离既有模式bmad-sprint-planning、bmad-retrospective、bmad-correct-course：读取项目级背景
什么时候建立或更新
| 场景 | 建议时机 | 目标 |
|---|---|---|
| 新项目（架构前） | 在 bmad-create-architecture 前手动创建 |
先声明技术偏好，避免架构偏航 |
| 新项目（架构后） | 通过 bmad-generate-project-context 生成并补充 |
把架构决策转成可执行规则 |
| 既有项目 | 先生成，再人工校对 | 让智能体学习现有约定而非重造体系 |
| Quick Flow 场景 | 在 bmad-quick-dev 前或过程中维护 |
弥补跳过完整规划带来的上下文缺口 |
:::tip[推荐做法] 如果你有强技术偏好（例如数据库、状态管理、目录规范），尽量在架构前写入。否则可在架构后生成，再按项目现实补齐。 :::
应该写哪些内容
建议聚焦两类信息：技术栈与版本、关键实现规则。原则是记录“智能体不容易从代码片段直接推断”的内容。
1. 技术栈与版本
## 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
2. 关键实现规则
## 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`
- API calls use the `apiClient` singleton — never fetch directly
**Testing Patterns:**
- Integration tests use MSW to mock API responses
- E2E tests cover critical user journeys only
常见误解
- 误解 1：它是操作手册。
不是。操作步骤请看 how-to；这里强调的是规则与边界。 - 误解 2：写得越全越好。
不对。冗长且泛化的“最佳实践”会稀释有效约束。 - 误解 3：写一次就结束。
这是动态文件。架构变化、约定变化后要同步更新。
文件位置
默认位置是 _bmad-output/project-context.md。工作流优先在该位置查找，也会扫描项目内的 **/project-context.md。
继续阅读
如需可执行步骤说明，请阅读 How-to：项目上下文；如果你在既有项目落地这套机制，可参考 既有项目常见问题。整体流程定位见 工作流地图。