133 lines
3.7 KiB
Markdown
133 lines
3.7 KiB
Markdown
---
|
||
title: "管理项目上下文"
|
||
description: 创建并维护 project-context.md 以指导 AI 智能体
|
||
sidebar:
|
||
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` 创建文件：
|
||
|
||
```bash
|
||
mkdir -p _bmad-output
|
||
touch _bmad-output/project-context.md
|
||
```
|
||
|
||
然后补充技术栈与实现规则：
|
||
|
||
```markdown
|
||
---
|
||
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：架构后生成
|
||
|
||
在新的会话中运行：
|
||
|
||
```bash
|
||
bmad-generate-project-context
|
||
```
|
||
|
||
该工作流会扫描架构文档和项目文件，生成能够反映已做决策的上下文文件。
|
||
|
||
### 选项 C：为既有项目生成
|
||
|
||
对于既有项目，运行：
|
||
|
||
```bash
|
||
bmad-generate-project-context
|
||
```
|
||
|
||
该工作流会分析代码库中的约定，然后生成可供你审阅和完善的上下文文件。
|
||
|
||
## 步骤 3：验证内容
|
||
|
||
审查生成文件，并确认它覆盖了：
|
||
|
||
- 正确的技术版本
|
||
- 你的真实约定（不是通用最佳实践）
|
||
- 能预防常见错误的规则
|
||
- 框架相关模式
|
||
|
||
如果有缺漏或误判，直接手动补充和修正。
|
||
|
||
## 你将获得
|
||
|
||
一个 `project-context.md` 文件，它可以：
|
||
|
||
- 确保所有智能体遵循相同约定
|
||
- 避免在不同用户故事（story）中出现不一致决策
|
||
- 为实施阶段保留架构决策
|
||
- 作为项目模式与规则的长期参考
|
||
|
||
## 提示
|
||
|
||
:::tip[最佳实践]
|
||
- **聚焦“不明显但重要”的规则**：优先记录智能体容易漏掉的项目约束，而不是
|
||
“变量要有意义”这类通用建议。
|
||
- **保持精简**：此文件会被多数实现工作流加载，过长会浪费上下文窗口。避免写入
|
||
只适用于单一 story 的细节。
|
||
- **按需更新**：当团队约定变化时手动更新，或在架构发生较大变化后重新生成。
|
||
- **适用于 Quick Flow 与完整 BMad Method**：两种模式都可共享同一份项目上下文。
|
||
:::
|
||
|
||
## 后续步骤
|
||
|
||
- [**项目上下文说明**](../explanation/project-context.md) - 了解其工作原理
|
||
- [**工作流程图**](../reference/workflow-map.md) - 查看哪些工作流会加载项目上下文
|