工程博客

工程日记：AI协作决策记录机制设计

🌤️ 今日天气/心情

晴 | 🤔 思考模式（关于AI协作机制的深度思考）

💻 开发工作记录

项目：AI协作机制设计

工作内容：

  • 反思与AI协作过程中决策记录的流失问题
  • 设计一套完整的决策追溯机制
  • 规划工程目录结构与Git提交规范

遇到的问题：

  • AI协作中的决策过程常被当作”过程记录”而舍弃
  • 决策文档散落在各个角落，容易遗漏
  • Coding Agent提交的代码与设计决策的关联性丢失
  • 代码提交时缺乏与设计文档的关联

解决方案：设计了一套三层机制：

1. 专用决策记录目录

1
2
3
4
5
6
7
8
9
project/
├── src/                    # 源代码
├── docs/                   # 文档
├── ai-decisions/           # 🆕 AI决策记录专用目录
│   ├── index.md            # 决策索引总览
│   ├── 2026-07-23-决策1.md
│   ├── 2026-07-23-决策2.md
│   └── ...
└── README.md

2. 索引文件结构 (index.md)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# AI决策索引

## 项目发展历史

### 2026-07
- [决策1] 采用Wren AI作为Text2SQL方案
  - 日期: 2026-07-23
  - 背景: 需要自然语言转SQL能力
  - 决策: 选用Wren AI而非其他方案
  - 影响: AI数据分析平台架构调整
  
- [决策2] 建立AI协作决策记录机制
  - 日期: 2026-07-23
  - 背景: 决策记录流失，代码与设计脱节
  - 决策: 建立ai-decisions目录和提交规范
  - 影响: 工程规范、代码可追溯性

3. Git提交模板规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
TODO:
- xxx 本次未完成的任务
- xxx 待后续跟进的事项

COMPLETED:
- ✅ 已完成的任务1
- ✅ 已完成的任务2

REFER SPEC:
- docs/ai-decisions/2026-07-23-决策1.md
- docs/design/text2sql-architecture.md

CHANGELOG:
- 新增: xxx功能
- 修改: xxx逻辑
- 修复: xxx问题

项目：工程目录结构优化

工作内容：

  • 在design目录下新增progress子目录
  • 用于记录里程碑任务的运行状态
  • 实现任务断点续传能力

遇到的问题：

  • 任务执行过程中出现异常后，无法获取任务状态
  • 无法从断点处继续执行任务
  • 缺乏任务运行状态的持久化记录

解决方案：

1
2
3
4
5
6
7
8
design/
├── index.md                # 设计文档索引
├── 2026-07-23-xxx.md       # 具体设计文档
├── progress/               # 🆕 里程碑任务运行状态目录
│   ├── milestone-1.json    # 里程碑1状态
│   ├── milestone-2.json    # 里程碑2状态
│   └── ...
└── ...

设计要点：

  • progress目录专门记录里程碑任务的运行状态
  • 每个里程碑独立文件，便于单独更新
  • 状态信息包括：当前进度、已完成步骤、待执行步骤、异常信息
  • 支持从任意断点恢复执行

实施状态：

  • ✅ 目录结构已创建
  • ⏳ 状态记录格式待定义
  • ⏳ 断点续传逻辑待实现

🧠 技术心得

新学到的东西

  • 决策即代码: 重要的设计决策应该像代码一样被版本控制
  • 上下文连续性: AI协作需要保持上下文的连续性，决策记录是上下文的载体
  • 可追溯性设计: 好的工程实践不仅是代码质量，还包括决策过程的可追溯
  • 断点续传思维: 长任务执行需要考虑异常恢复，状态持久化是关键

踩过的坑

  • 过程记录的误区: 以前认为”过程”不重要，只保留”结果”。实际上过程记录了为什么这样决策，比结果更重要
  • 文档孤岛: 决策文档散落在各处，没有统一的索引，导致查找困难
  • 代码与设计的断层: Coding Agent完成任务后，代码与设计文档的关联没有建立，后续Review困难
  • 状态丢失: 任务执行异常后，运行状态丢失，只能从头开始，浪费时间和资源

最佳实践

  • 索引驱动: 建立索引文件，让决策历史一目了然
  • 关联一切: 代码提交必须关联相关设计文档
  • 模板约束: 用模板规范提交信息，确保关键信息不遗漏
  • 状态持久化: 关键任务的状态要实时记录，支持断点续传

🤔 思考与总结

今日收获

  1. 系统性思维: 不仅要解决当前问题，还要建立长期有效的机制
  2. 文档即对话: 与AI的交互过程本身就是有价值的知识，应该被记录
  3. 工程化思维: 将决策管理工程化，用工具和流程保障质量
  4. 容错设计: 任务执行要考虑异常场景，状态持久化是容错的基础

待改进的地方

  • 需要与团队讨论并推广这套规范
  • 考虑自动化工具辅助生成决策记录
  • 设计评审流程，确保决策质量
  • 定义progress目录的状态记录格式
  • 实现断点续传的自动化逻辑

记录时间: 2026-07-23