AI 协作实操：经验沉淀、任务看板与脚手架搭建的技术细节

AI 协作实操：经验沉淀、任务看板与脚手架搭建的技术细节

前情提要：本文是"AI 协作之从可用到可控"的续篇。前文聊了 Prompt → Memory → Rules → Skills 四个约束维度，这篇在此基础上展开技术实操——经验怎么沉淀、任务看板怎么搭、脚手架怎么组织，以及搭的过程中踩了什么坑。

项目地址：GitCode - AI-Tasks-Dashboard

---

目录

1. 经验沉淀：踩坑记录和决策记录

2. AI-Tasks-Dashboard：三层架构的技术实现

3. 规则分级：三种触发模式

4. 任务看板：最小可行的实现

5. 防止系统比项目还重

6. 按项目分级选用治理强度

7. 总结

---

一、经验沉淀：踩坑记录和决策记录

前文提过，Rules 是从反复验证的经验里提炼出来的。但实际执行中，"提炼"这个动作很容易被跳过——问题解决了，就过去了。

1.1 踩坑记录：五分钟循环

有一次遇到端口冲突：两个服务占了同一个端口，AI 在不同对话里分别选了 8000。改个端口号就解决了，五分钟的事。但多做了一步，按四个步骤把这次经历沉淀下来：

第一步，记录问题——端口冲突，原因是 AI 临时分配端口，没有全局分配表。

第二步，提炼原则——每个服务的基础配置（端口、数据目录、日志路径）应该有明确的分配表，不应由 AI 在每次对话中临时决定。

第三步，写入规则——在 g-development-environment.md 中加了一段端口分配表：

## 服务端口分配表

| 服务 | 端口 | 数据目录 | 日志路径 |
|------|------|---------|---------|
| 后端 API | 8000 | ./data/api | ./logs/api |
| 前端 Dev | 3000 | - | ./logs/frontend |
| MQTT Broker | 1883 | ./data/mqtt | ./logs/mqtt |

## 规则
- 新服务必须在分配表中注册端口后才能使用
- 禁止 AI 在对话中临时指定端口号

第四步，关联经验——把这个原则关联到数据存储和 MQTT 的决策上，它们也涉及"避免资源冲突"。

整个过程花了大概五分钟。后来类似的问题再也没出现过。

慢慢养成了习惯：遇到问题，先解决；解决之后，花几分钟提炼出一句话的原则；写进文件里；再看看和之前记录的经验有没有关联。投入产出比可能是这段时间做过的最高的事。

1.2 决策记录：最有价值的是"没选的那个"

做技术选型——用 SQLite 还是 MySQL，用 JWT 还是 Session——以前做完选择就过了。后来开始在记录里多写一部分：没选什么、为什么没选。

下面是一个实际的决策记录模板：

# 决策记录：数据存储方案选择

## 基本信息
- 编号：D002
- 日期：2026-04-15

## 问题描述
项目需要本地数据存储，用于存储任务状态和配置信息。

## 可选方案
| 方案 | 优点 | 缺点 |
|------|------|------|
| SQLite | 零运维、单文件 | 并发写入受限 |
| MySQL | 高并发、成熟 | 需要额外运维 |

## 决策结果
选择 SQLite。部署环境为单机，零运维是最高优先级。

## 被否决方案及原因
- MySQL：运维成本高，本项目不需要高并发
- JSON 文件：并发不安全，数据丢失风险

## 依赖关系
- 影响 D005（缓存策略需要考虑 SQLite 的 WAL 模式）

决策记录最有价值的部分不是"选了什么"，而是**“被否决的方案和否决原因”**。有一次项目需求变了，需要考虑多节点部署。翻出这条记录，立刻就知道了当初否决 MySQL 的前提条件，可以快速重新评估，省了一轮完整的调研。

实操要点：不需要每个决策都写完整记录。一般只在"选了之后可能后悔"的决策上花这个时间——比如技术选型、架构选择、协议选择。端口号这种事不值得写决策记录。

---

二、AI-Tasks-Dashboard：三层架构的技术实现

踩坑记录、决策文件、规则文件、任务清单——这些东西积累了一段时间之后，散落在项目各处。每次开新对话，AI 要读的文件东一个西一个。后来把这些东西整理到一起，搭了一个叫 AI-Tasks-Dashboard 的脚手架。

2.1 核心设计

用三层 Markdown 文件把 AI 协作所需的信息归好类：

层	职责	文件位置	核心文件
约束层	管"什么不能做"	.cursor/rules/	g-core.md、g-testing.md
任务层	管"现在做什么"	tasks/	task_registry.md、active/task_*.md
设计层	管"项目长什么样"	design/	modules/*/README.md、decisions/*.md

AI 每次开工先读这些文件，就能带着上下文进入工作，不用每次从头交代。

2.2 目录结构

project-root/
├── .cursor/
│   └── rules/              # 约束层：规则文件
│       ├── g-core.md       # 全局核心规则（always_on）
│       ├── g-testing.md    # 测试规范（always_on）
│       └── l-frontend.md   # 前端规范（manual）
├── tasks/
│   ├── task_registry.md    # 任务层：全局任务看板
│   ├── active/             # 进行中的任务
│   │   └── task_001-auth.md
│   └── archive/            # 已归档的任务
├── design/
│   └── modules/
│       └── auth/README.md  # 设计层：模块文档
└── README.md

所有文件放在项目根目录下，不需要数据库，不需要后端服务。AI 按目录结构就能定位到需要的信息。

---

三、规则分级：三种触发模式

约束层最基础的用法是 always_on——一次写入，永久生效。但实际用了一段时间后发现，如果所有规则都是 always_on，AI 每次对话都要加载一大堆信息，其中可能有一半跟当前任务无关。

3.1 三种触发模式

触发模式	配置方式	加载时机	数量建议
always_on	alwaysApply: true	每次对话自动加载	≤ 7 个
manual	alwaysApply: false	手动指定时加载	≤ 10 个
model_decision	globs: "*.py"	匹配到特定文件类型时自动加载	不限

always_on 只放真正的"红线"——不自动提交代码、不修改生产数据这类硬约束。manual 放特定领域的规则，比如前端开发规范只在写界面时手动加载。model_decision 用文件路径匹配，比如 AI 编辑 .py 文件时自动加载 Python 相关的编码规范。

3.2 实操配置

在 Cursor 中，规则文件的头部用 alwaysApply 和 globs 字段控制触发模式：

---
description: 项目核心约束规则
globs:
alwaysApply: true
---

# 核心规则

## 硬约束（P0，必须遵守）
- 不自动执行 git commit 或 git push
- 不修改 production 环境配置

## 软指导（P1，推荐但允许灵活调整）
- 函数长度建议不超过 50 行
- 公共函数建议添加 docstring

---
description: 前端开发规范
globs: "**/*.vue,**/*.tsx"
alwaysApply: false
---

# 前端规范

## 组件命名
- 使用 PascalCase
- 文件名与组件名一致
...

这个分级让 AI 每次只看到与当前任务相关的信息，输出质量明显提升。

实操要点：先从 always_on 开始，只放最重要的 3-5 条规则。随着项目推进，再把领域规则拆到 manual 和 model_decision 中。不要一开始就搞很多规则文件。

---

四、任务看板：最小可行的实现

约束层（Rules）本质上都是在管"AI 怎么做事"。但实际项目中还有一个维度是它覆盖不到的——“现在该做什么”。

4.1 问题场景

AI 完全清楚项目规范，也了解项目背景，编码能力也没问题。但如果不给它一个清晰的任务指令，它会在一堆"可能要做的事"里打转——一会儿建议优化性能，一会儿建议补文档，一会儿又想重构某个模块。

AI 擅长执行，但不擅长排优先级。这件事需要人来做。

4.2 全局任务看板

在项目根目录放一个 tasks/task_registry.md，格式很简单：

# 任务看板

> 最后更新：2026-06-01

## 进行中
- [ ] task_001: 实现用户认证模块 | 优先级: P0 | 依赖: -

## 待办
- [ ] task_002: 性能优化 | 优先级: P1 | 依赖: task_001
- [ ] task_003: 单元测试补充 | 优先级: P2 | 依赖: task_001

## 已完成
- [x] task_000: 项目初始化 | 完成: 2026-05-20

每次开新对话，AI 先读这个文件，就知道当前的工作重心是什么。

4.3 单任务文件

对于进行中的任务，创建一个独立的文件 tasks/active/task_001-auth.md：

# Task 001: 用户认证模块

## 目标
实现完整的用户登录、注册、Token 刷新流程

## 验收标准
- [ ] 登录接口响应时间 < 200ms
- [ ] Token 刷新不中断当前会话
- [ ] 所有接口有对应的单元测试

## 工作分解
1. [x] 设计数据库 Schema
2. [x] 实现 JWT 工具类
3. [ ] 实现登录接口
4. [ ] 实现注册接口
5. [ ] 编写单元测试

## 技术决策
- D001: JWT 过期时间选 24h（安全与体验平衡）
- D003: 密码加密使用 bcrypt（部署环境限制）

## 关键发现
- bcrypt 在当前负载下性能足够（< 50ms/次）
- 需要注意并发登录时的 Token 竞态问题

任务完成后移入 tasks/archive/ 目录，保留历史记录。

4.4 为什么"技术决策"和"关键发现"很重要

这两个字段是最有价值的部分。它们告诉 AI 的不只是"做了什么"，还有"为什么这样做"和"过程中发现了什么"。

比如"为什么选 bcrypt 而不是 argon2"——这个决策原因在下次对话时 AI 是看不到的，除非写下来。写下来了，AI 在做后续修改时就不会自作主张地把 bcrypt 换成 argon2。

实操要点：任务文件不需要写得多漂亮，关键是"够用"。目标、验收标准、工作分解、技术决策这四个字段，覆盖了 90% 的场景。

---

五、防止系统比项目还重

整理脚手架的过程中，掉进了一个自己没预料到的坑。

5.1 隐蔽的陷阱

有一段时间特别享受"优化协作系统"这件事——规则文件越写越详细，有一个达到了 600 多行，详细规定了 AI 如何拆分并行任务、如何协调子代理。文件本身的质量不差，但后来算了一下：审核、更新、同步关联引用、检查跨文件一致性——这些"维护系统"的工作，花的时间可能比它帮我省下的还多。

这个坑挺隐蔽的，因为它看起来像是在做"正确的事"。但当维护系统的成本超过了系统带来的收益，就该停下来精简了。

5.2 规则复杂度预算

后来给自己定了几个粗略的预算指标：

指标	预算	检查频率
always_on 规则数量	≤ 7 个	每月
always_on 合计行数	≤ 500 行	每月
超过 3 个月未审核的规则	0	每季度
元工作占比（维护系统 / 总工作）	< 20%	自观察

一旦超出预算，就做一轮"规则瘦身"：合并功能重叠的、删掉从未被违反的、把 always_on 降级为 manual。

5.3 规则打架的问题

规则多了之后，规则之间可能自相矛盾。比如一个规则文件写着"终端输出禁止使用表情符号"（PowerShell 编码问题的教训），另一个写着"菜单设计必须包含表情符号"（UI 设计需求）。每条规则各有各的道理，但从来没被放在一起审查过。

这类矛盾单看每条规则都发现不了——因为每条都是在特定踩坑场景下写的。只有摊在一起对比时才暴露。

应对方式是一个小习惯：每次新建或修改规则时，花两分钟看一下它和现有关联规则有没有冲突。具体做法是列出新规则涉及的关键词，在现有规则文件中搜索这些关键词，检查有没有矛盾或重复。

5.4 硬约束与软指导的区分

这是最有效的一个调整。把规则分成两个级别：

硬约束（P0）——必须遵守的底线，违反后果严重。比如：不自动 git commit、不删除生产数据、不吞异常。

软指导（P1/P2）——推荐做法，允许 AI 灵活调整。比如：函数长度建议不超过 50 行、变量命名建议用 camelCase。

在规则文件中用不同的标题区分：

## 硬约束（P0，必须遵守）
- 不自动执行 git commit 或 git push
- 代码变更必须同步更新相关文档

## 软指导（P1，推荐但允许灵活调整）
- 函数长度不超过 50 行
- 优先使用标准库而非第三方依赖

调整之后 AI 的输出质量明显提升——它不再为了"不违反规则"而绕远路，而是在守住底线的前提下选择更自然的实现方式。

实操要点：规则治理的核心思路跟代码治理一样——控制复杂度、定期审查、及时清理。如果花在"维护规则"上的时间比"用规则干活"的时间还多，说明规则太重了。

---

六、按项目分级选用治理强度

这些方案是从工业项目（IEC 标准、电缆算法）里提炼出来的，天然偏"严格"。后来也用类似方式做过一些轻量级项目——内部工具、脚本、小原型。

把同一套体系原封不动搬到小项目上，反而拖慢了速度。一个周末写的小工具，非要维护一套完整的规则文件、任务看板、设计文档，有点杀鸡用牛刀。

所以后来按项目性质分了三档：

模式	适用场景	规则数	任务管理	设计文档
轻量	原型/脚本/工具	2-3 条 always_on	TODO 清单	不需要
标准	产品/API 服务	5-7 条 always_on + manual	task_registry + 单任务文件	模块级 README
严格	工业/医疗/金融	7+ 条 + 完整分级	完整任务体系 + 归档流	决策记录 + 模块文档

关键是诚实地判断项目在哪一档。不是所有项目都需要"严格模式"，够用就好。

---

七、总结

这篇是"从可用到可控"的续集。前者解决的是"怎么让 AI 守规矩"，这篇聊的是"守规矩之后，怎么把经验留下来、怎么让协作更顺畅"。

回顾整条线索：积累（踩坑记录 + 决策记录）→ 整理（搭三层架构的脚手架）→ 细化（规则分级 + 任务看板的具体实现）→ 克制（防止系统过重 + 按场景选力度）。

几个核心要点：

经验沉淀五分钟循环——遇到问题 → 记录 → 提炼原则 → 写入规则 → 关联经验。每次多花五分钟，省下未来几十分钟的重复排查。

决策记录重在"没选的"——记录被否决的方案和否决原因，未来环境变化时可以快速重新评估。

三层架构——规则管"什么不能做"，任务管"现在做什么"，设计文档管"项目长什么样"。三层信息用纯 Markdown 文件管理，零成本、零依赖。

规则分级加载——always_on、manual、model_decision 三种触发模式，让 AI 每次只看到与当前任务相关的约束。

规则本身要治理——控制数量预算、区分硬约束和软指导、定期检查一致性。

按项目选用强度——轻量项目用轻量模式，复杂项目才用完整体系。

做到后面，慢慢有了一点不太一样的感受。AI 在不少方面的能力已经超过了大多数初中级工程师——代码生成、重构、跨语言翻译，它做起来都很利落。但它也会在一些"理所当然"的地方犯低级错误。这种反差让人觉得，我们和 AI 的关系，可能更接近于和一个成长很快的搭档协作——它在某些维度上已经比你强，但在另一些维度上还需要你的判断力来补位。

做着做着慢慢发现，真正有价值的部分可能不在于"控制"AI，而在于在这个过程中，把脑子里那些模糊的经验、直觉、判断，一点一点地变成了清晰可复用的东西。我们沉淀领域知识，AI 执行和反馈，两边都在往前走。与其说是"管 AI"，不如说是"一起共建"。

配套的 Markdown 脚手架已开源在 GitCode - AI-Tasks-Dashboard，包含规则模板、任务模板和示例配置，可以直接拿去用或按需裁剪。有问题欢迎在评论区交流。

---

参考来源

• 前文：“AI 协作之从可用到可控”

• Anthropic: Effective Context Engineering for AI Agents

• JetBrains Research: Efficient Context Management for LLM Agents