chill_notes/AI工程/AI上下文体系_团队级AICoding.md

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