115 lines
3.2 KiB
Markdown
Executable File
115 lines
3.2 KiB
Markdown
Executable File
# AI上下文体系 - 团队级AI Coding简明手册
|
||
|
||
> 来源：幻灯片分享，2026-06-20 归档
|
||
|
||
## 核心理念
|
||
|
||
使用完整的文档来描述上下文和约束体系，**区分过程方案和事实方案，减少维护成本**。
|
||
|
||
---
|
||
|
||
## 文档分层结构
|
||
|
||
| 目录 | 用途 | 维护者 | 性质 |
|
||
|------|------|--------|------|
|
||
| `docs/standards` | 标准规格（API、命名、安全规范） | Tech Lead | 事实方案 |
|
||
| `docs/features` | 需求规格 | 产品/BA | 事实方案 |
|
||
| `docs/plans` | 计划规格（每轮任务实现方案） | AI/开发 | **过程方案** |
|
||
| `docs/designs` | 设计规格（DB、表等 Source of Truth） | AI/开发 | 事实方案 |
|
||
| `docs/others` | 架构决策、Release、测试用例 | — | 按需 |
|
||
| `AGENTS.md` | 宪法级约束 | — | 事实方案 |
|
||
|
||
---
|
||
|
||
## 过程方案 vs 事实方案
|
||
|
||
### 过程方案（Plans）
|
||
|
||
**定义**：每次 Plan/Go 循环产生的**执行计划**，记录"我们打算怎么做"。
|
||
|
||
**特点**：
|
||
- 临时的、一次性的
|
||
- 每次创建**新文件**（如 `plan-2026-06-20-feature-x.md`）
|
||
- 细微修改**不再更新**旧文件，直接创建新版本
|
||
- 作为执行记录，不是长期参考
|
||
|
||
**示例**：
|
||
```
|
||
docs/plans/
|
||
├── plan-2026-06-01-user-auth.md
|
||
├── plan-2026-06-05-user-auth-v2.md
|
||
└── plan-2026-06-10-payment-flow.md
|
||
```
|
||
|
||
**为什么这样设计**：
|
||
- 避免反复修改同一文件导致的 Git 冲突
|
||
- 保留历史决策轨迹，方便复盘
|
||
- AI 每次执行完可以"丢弃"，不污染长期文档
|
||
|
||
---
|
||
|
||
### 事实方案（Designs / Standards / Features）
|
||
|
||
**定义**：反映系统**当前真实状态**的文档，是 Source of Truth。
|
||
|
||
**特点**：
|
||
- 长期有效的、稳定的
|
||
- 每次变更以**最终态更新**（覆盖式修改）
|
||
- 作为下一次 Plan 的**起点和依据**
|
||
- 必须与实际代码/系统保持一致
|
||
|
||
**示例**：
|
||
```
|
||
docs/designs/
|
||
├── database-schema.md # 当前数据库表结构
|
||
├── api-endpoints.md # 当前 API 定义
|
||
└── architecture.md # 当前架构图
|
||
|
||
docs/standards/
|
||
├── coding-style.md # 编码规范
|
||
└── security-guidelines.md # 安全规范
|
||
```
|
||
|
||
**为什么这样设计**：
|
||
- AI 每次 Plan 时读取这些文档，获得"当前真相"
|
||
- 避免 AI 基于过时的信息做决策
|
||
- 减少维护成本：只维护一份最终态
|
||
|
||
---
|
||
|
||
## Plan/Go 模式的规格流转
|
||
|
||
```
|
||
起点 Features
|
||
↓
|
||
Standards（约束）
|
||
↓
|
||
TDD 驱动测试 + 代码
|
||
↓
|
||
事实方案 Designs（更新最终态）
|
||
↓
|
||
过程方案 Plans（执行记录）
|
||
↓
|
||
回到起点 Features（验收）
|
||
```
|
||
|
||
**流转规则**：
|
||
- **追加**：创建新文件，细微修改不再更新 → 过程方案
|
||
- **变更**：以最终态更新，作为下一次 Plan 的事实依据 → 事实方案
|
||
|
||
---
|
||
|
||
## 实践建议
|
||
|
||
1. **AGENTS.md 作为宪法**：定义 AI 的行为边界和基本原则
|
||
2. **区分"打算做"和"已做完"**：Plans 是意图，Designs 是事实
|
||
3. **减少维护成本**：过程方案不维护，事实方案必须维护
|
||
4. **AI 友好**：每次 Plan 前读取事实方案，执行后更新事实方案
|
||
|
||
---
|
||
|
||
## 参考
|
||
|
||
- 幻灯片：如何让AI听话-构建AI上下文体系
|
||
- 归档日期：2026-06-20
|