你的 AI 不是不够聪明，它只是缺一套协作协议

我用 AI 写代码快一年了。最让我头疼的不是 AI 不够聪明，而是在"开新会话"和"继续旧会话"之间反复权衡的痛苦。

开一个新会话，上下文干净、响应快，但 AI 完全不记得你之前在做什么——它不知道当前需求是什么、做到第几步了、上次做了什么技术决策。你得从零开始重新描述一切。

继续一个旧会话呢？上下文确实还在，但已经塞满了十几轮对话的冗余信息，每次响应越来越慢，token 消耗越来越高。更糟的是，上下文太长之后 AI 开始"遗忘"早期讨论的关键约束，你不得不反复提醒它。

两种选择都不对。这不是 AI 模型的问题，是协作协议的问题——我们缺一套让 AI 知道"当前在做什么、做到哪了、下一步可以做什么"的系统。

PACE（Progressive Agentic Collaborative Engineering，渐进式 AI 协作工程）就是为这个设计的。它是一个 AI 工程化工具集，也是一个方法论。核心思路很简单：用一套结构化文件（Markdown + YAML）作为人-AI 之间的共享记忆，让 AI 知道你当前在做什么需求、做到第几步了、上次做了什么决策。

它不依赖数据库，不需要额外服务，只需要一个文件夹。我今天把它拆开，看看这套系统到底怎么搭的。

在往下看之前，先交代几个 PACE 里最基础的概念，后面会反复出现。你花一分钟扫一眼就行，不用记。

概念	一句话解释
Skill	PACE 里的"能力模块"。每个 Skill 是一份 Markdown 文件，写明"什么场景触发、按什么步骤执行"。比如 pace-plan 管需求规划，pace-check 管质量检查。AI 读了这个文件就知道怎么干活。
Agent	执行任务的独立上下文。PACE 把大任务拆成多个 Agent 并行跑，每个 Agent 只负责一件事，上下文干净、互不干扰。
Command	用户的显式入口，比如 /pace-plan。它本身不包含逻辑，只是一个"路标"——告诉 AI 该加载哪个 Skill。日常使用不需要记命令，直接用自然语言就行。
todo	待办任务项。PACE 用 Markdown checkbox（- [ ]）来追踪进度，勾选 [x] 就是完成。这是整个执行引擎的核心数据结构。
prj-wiki/	PACE 在项目根目录下的产物文件夹。所有需求的状态文件（plan、todo、进度日志）和知识沉淀都在这里面。

好了，概念交代完，开始拆系统。

三个断层：为什么你的 AI 助手总是"断片"

① 没有规划

② 没有状态

③ 没有沉淀

先说一个真实场景。你打开 IDE，对 AI 说："帮我做一个登录功能"。AI 二话不说开始写代码。它改了 user_model.go、新建了 auth_handler.go、动了数据库 schema。写到一半，你发现它根本没问你密码怎么加密、token 用什么方案、要不要支持 OAuth。

这是第一个断层——没有规划。AI 默认"你说的都对"，不追问、不确认、不评估复杂度。一句模糊指令就能让它埋头写 500 行代码，写完你才发现方向偏了。

然后是第二个断层——没有状态。上下文窗口太大了你想开个新窗口，AI 完全不知道你之前做了什么。它不会说"上次做到了 2.1 实现登录接口，还剩 5 个待办"。你必须重新描述上下文，让它重新读代码，重新猜你在哪。

最气人的是第三个断层——没有沉淀。你上周花了一下午踩的坑，它一个字都没记。同样的问题换个需求又来一遍。你的经验永远只存在于你的脑子里，不会变成 AI 下次能直接用的知识。

三个承诺：PACE 的设计哲学

① 对人：不需要学任何命令

② 对 AI：文件系统就是状态

③ 为明天：今天人写的东西，明天 AI 能直接接手

PACE 的设计者给自己定了两个硬约束。

第一，对人足够简单。 整个系统只有一个引导命令 /pace-help，日常使用不需要任何命令。你想做需求，说"帮我规划一个用户认证模块"。想继续，说"继续做"。想检查质量，说"检查一下"。自然语言就是参数，AI 自己判断意图、匹配对应的 Skill、执行流程。

第二，对 AI 足够结构化。 所有产物都是 Markdown 和 YAML。plan.md 记录背景和方案，todo.md 用 checkbox 追踪进度，meta.yaml 存状态和统计。人可以直接编辑，AI 解析也一样快。文件系统就是数据库，不需要额外维护。

这两个约束背后有一个更大的设计意图：为终局准备。PACE 的设计者相信 AI 自闭环开发是必然终局，问题不是要不要，而是怎么过渡。今天的每个 Skill 文件里已经写好了触发条件，未来 AI 能力足够时，直接读这些 Skill 就能自主运行——不再需要人输入命令。

核心引擎：一个四阶段闭环怎么跑起来

① Plan：动手前的一切思考

② Execute：跨会话的状态感知

③ Check：三级渐进的质量门禁

PACE 的核心是一个四阶段闭环。每个需求进来，走一圈：规划 → 执行 ⇄ 检查 → 归档。走完归档不是结束，归档时会从你的需求里提炼经验，写入知识库，下次规划新需求时自动检索。

规划阶段的关键是自适应。你说"加个字段"，它判断复杂度 small，生成简洁 plan 和 2-3 个待办。你说"实现用户认证模块"，它判断 medium，生成完整 plan 和 5-10 个待办。跨服务架构变更则触发 large 模式，多出一份 design.md 技术设计文档。

执行阶段不是"执行命令 → 返回结果"，而是一个状态感知系统。每次执行时：

1. 先读 meta.yaml——知道整体进度（3/7）
2. 读 todo.md——找到第一个 [ ] 未勾选项
3. 读 progress.log——恢复上次会话的上下文和决策
4. 执行当前待办，勾选 [x]，更新进度
5. 自动触发 quick check

这意味着你下班关电脑不需要做任何操作。明天打开说"继续"，它自己就知道该干什么。

检查阶段用了三级渐进设计。每个 todo 完成后自动跑 quick check（build + lint），30 秒搞定。你说"检查一下"触发 standard 模式，加跑测试。你说"全面审查"或全部 todo 完成时触发 deep 模式，三个审查 Agent 并行跑。

审查结果有固定格式：

CHECK: PASS          ← 结构化头部，Hook 自动解析
MODE: quick

Build:    ✅
Lint:     ✅ (0 issues)
Review:   ⚠️ (1 Major)

这套检查系统不只是一个"建议"——它是门禁。meta.yaml 里的 status 不是 checked 或 tested，你按 git push 会被 IDE Hook 直接拦截。Hook 不是 AI 说了算，是系统层面确定性阻断。

状态机：为什么没有 pause 和 resume

① 8 个状态 × 12 条转移路径

② 分支确认规则：AI 的"刹车机制"

③ "关掉 IDE 就是暂停，打开就是恢复"

分布式人-AI 协作的第一性问题是："当前到哪了？" 你和 AI 是两个独立执行单元，靠消息通信。如果没有一个共享的状态机，就像两个人拼乐高但看不到对方的手。

PACE 用一个8 状态、12 转移路径的有限状态机解决这个问题。

状态机里有一个很关键的安全设计：分支确认规则。当当前状态有多条出边，且用户的输入模糊时（比如只说"继续"），AI 禁止自行选择路径，必须列出选项让用户确认。比如进度 3/5、检查通过、还有剩余待办时，AI 不能直接继续执行，而要问清楚是继续还是提交还是看清单。

为什么没有 pause 和 resume？ 设计者的答案是："执行"是一个持续过程，不存在"暂停"的概念。你关上 IDE 就是自然中断，下次打开说"继续"就是自然恢复。显式的 pause/resume 是不必要的认知负担。

两层 Skill 架构：编排层和能力层为什么分开

① 6 个编排层 Skill：控制全流程

② 8 个能力层 Skill：提供专项能力

③ 一个为全自动化预留的后门

前面提到了 Skill 是 PACE 的"能力模块"，每个 Skill 文件定义了触发条件和执行步骤。PACE 把它分了两层，这又是一个关注点分离的设计。

编排层（6 个 Skill）管"做什么、怎么编排"：pace-plan 负责规划，pace-execute 负责执行，pace-save 同步人工变更。pace-check 做质量检查，pace-record 沉淀知识，pace-archive 做归档。

能力层（8 个 Skill）管"具体怎么做"。pace-task-engine 负责解析 todo.md 和 checkbox 状态，pace-session-state 管跨会话恢复。pace-verification-checks 跑 build/lint/test，pace-knowledge 管知识库读写。

编排层引用能力层，但两者独立维护。改一个能力不影响其他编排。

最有远见的设计是 Command 和 Skill 的分离。 前面说过，Command 只是"路标"——/pace-plan 之类的前缀命令本身不包含逻辑，它的唯一作用是告诉 AI 该加载哪个 Skill。真正的执行逻辑全在 Skill 文件里。Skill 的 description 字段写明了触发条件：

当用户描述新需求、提到项目管理系统、"帮我做 xxx"、"分析一下"→ 加载 pace-plan

这意味着，当 AI 能力足够时，它可以直接读 Skill 的 description 自动判断该加载哪个能力。Command 可以被淘汰，Skill 独立运行。架构上没有为此做任何妥协，今天的每行代码都在为明天准备。

Subagent 编排：Dispatcher 自己不做事

① 四个专职 Agent：各干各的，互不干扰

② 审查 Agent 并行跑：主 Agent 只汇总

③ 加了把锁：两个入口抢同一个需求怎么办

PACE 的主 Agent 叫 Dispatcher。一个纯调度员。它不写代码、不审查、不沉淀、不归档。它只做三件事：理解用户意图、管理状态机、创建和汇总子 Agent。

实际干活的 Agent 有四个：Planner（需求分析和产物创建）、Executor（代码实现和进度更新）、Checker（质量检查和审查协调）、Archiver（归档校验和知识提炼）。

Checker Agent 下面又挂了三个审查 Agent，并行跑：golang-reviewer 查 Go 代码规范，design-reviewer 查实现和设计文档是否一致，security-reviewer 查安全漏洞。三个 Agent 在独立上下文中运行，互不污染。跑完把结果汇总给 Checker，Checker 再发回 Dispatcher。

这种设计的最大好处是上下文隔离。如果把审查逻辑塞进主 Agent，几千行代码 diff 加上规范文件会把上下文撑爆。拆成独立 Agent 后，每个 Agent 的上下文干净、聚焦、可复用。

还有个细节：locked_by 并发锁。PACE 支持两个入口同时操作同一个需求：一个是 IDE 里的 AI 对话面板，另一个是 IM 消息（比如飞书或钉钉里的机器人）。如果 IDE 侧已经有 Executor 在跑，IM 侧想再启动一个，系统会提示冲突："当前 IDE 侧有 Executor 正在运行。等它完成，还是强制接管？" 这个锁机制用 meta.yaml 的 locked_by 字段实现，干净利落。

产物体系：三个文件管住所有状态

① meta.yaml = WHERE：到哪了

② todo.md = WHAT：做什么

③ progress.log = HISTORY：发生了什么

不需要数据库。PACE 把所有状态都存在项目根目录的 prj-wiki/ 文件夹下，用三个文件解决问题。

meta.yaml 是身份证。记录需求 ID、名称、复杂度评分、当前状态、进度统计。所有 Agent 读写状态都通过这个文件。

id: "20260621-user-auth"
name: "用户认证模块"
complexity: medium
status: in_progress
progress:
  total: 7
  done: 3
  current: "2.1 实现 POST /api/login"

todo.md 是待办清单。Markdown checkbox，人和 AI 都能直接读。

## 1. 数据层
- [x] 1.1 新增 password_hash 字段
- [x] 1.2 编写 migration 脚本

## 2. 接口层
- [ ] 2.1 实现 POST /api/login       ← Executor 自动定位到这里
- [ ] 2.2 实现 POST /api/logout

progress.log 是叙事桥梁。append-only，只追加不修改。新会话启动时读这个文件就能恢复完整上下文。

## 2026-06-21 14:30 [会话 abc123]

### 完成
- T001: 实现 POST /api/login，修改 handler.go (+45 -12)

### 决策
- 选择 JWT 而非 session，微服务无共享状态

### 下一步
- T002: 实现 POST /api/logout

三个文件的职责清楚分开：

文件	回答什么问题	谁读	谁写
meta.yaml	WHERE — 到哪了？	Executor 判断大局	各阶段 Agent
todo.md	WHAT — 做什么？	Executor 找下一个任务	Executor + Save
progress.log	HISTORY — 发生了什么？	新会话恢复上下文	Executor + Save

这个设计最妙的地方是不需要 save/load。传统系统里切换会话要先保存状态、恢复会话要重新加载。PACE 直接依赖文件系统——修改文件就是保存状态，读文件就是恢复上下文。零额外成本。

知识沉淀：让每次协作变成永久资产

① 四分类知识库：改哪里、能用什么、怎么做、为什么

② INDEX.md 是 AI 的"检索入口"

③ 冲突检测：知识不是你随便改的

归档不是简单的"把文件夹从 active 挪到 archive"。PACE 的归档流程多了一步关键的知识沉淀。

从完成的需求里，AI 自动提炼四类知识：

分类	回答	示例
service-map/	改哪里	"user-svc 提供 Login() 和 GetUser() 接口"
dependencies/	能用什么	"Redis 连接池配置最佳参数"
experiences/	怎么做	"JWT 在微服务里的最佳实践和踩坑记录"
business/	为什么	"为什么登录模块选择 JWT 而不是 session"

然后更新 INDEX.md——一个全量知识索引。规划新需求时，AI 先读 INDEX.md，通过标签匹配找到相关条目，定向读取后在 plan.md 里用 [[]] 引用。这个 [[]] 是 Obsidian 风格的维基链接语法，写成 [[service-map/user-svc.md]] 就能跳转到对应知识条目，同时支持反向追溯——你可以看到"哪些 plan 引用了这条知识"。

## service-map
| [[service-map/user-svc.md]] | 用户服务接口 | user, auth | active |

## experiences
| [[experiences/20260621-jwt-practice.md]] | JWT最佳实践 | jwt, go | active |

还有一个冲突检测机制。写入新知识时自动检查同标签条目，发现有矛盾就标注 [⚠️ 待审核] 并提示用户，不静默覆盖。这个设计说明了一件事：知识库不是日志，每条记录都必须有可复用结论，宁缺毋滥。

写在最后

到这，PACE 的设计全景基本就清楚了。最直观的感受不是"这个系统很复杂"，而是"它其实很简单"。

23 个触点——6 个编排层 Skill、8 个能力层 Skill、5 个 Agent、3 个审查 Agent、1 个 Hook、2 个辅助脚本。PACE 的设计团队此前尝试过多套 AI 工程化方法论的组合，加起来将近 200 个触点。PACE 把它们的核心价值浓缩到了 23 个，裁减率 89%。每个触点都有明确的单一职责，能独立替换。

几个最关键的设计决策值得再强调一遍：

• 文件系统即状态，不需要数据库。checkbox 勾选就是进度，文件写入就是保存
• 自适应替代多命令，用户永远不用想"该调哪个"。说"全面审查"就自动走 deep
• Dispatcher 不做事，上下文隔离，每个 Subagent 跑在干净的环境里
• Command 不定义参数，自然语言就是参数。这是为 AI 全自动化预留的接口
• 没有 pause/resume，关掉 IDE 就是自然中断，打开就是自然恢复