v2.0 复盘：两个视角的审视与改进路线

背景：框架已走过 v1.x → v2.0.0-20260422 的完整演进周期，形成了 7 Agent + 3 工作流 + 双向同步工具链 + VitePress 文档站的完整体系。本文档是停下来审视"这套框架到底好不好"的深度复盘。

---

一、框架设计者视角（架构 & 机制质量）

1.1 做得好的

两层分离 + Stub Marker 机制 — 最大的架构亮点

• core/（编排层）与下游项目 .claude/（执行层）的分离，解决了"一套规范多项目复用"的核心问题
• Marker 机制优雅地解决了"框架管理内容 vs 项目自定义内容"的边界问题，比 git submodule 或 npm 包更轻量
• 双向同步（upgrade/harvest）形成了"集中分发 → 分散验证 → 收割沉淀"的闭环，这在 AI 协作框架中很少见

framework core/  ──upgrade.sh──>  下游项目 .claude/
      ↑                              │
      └────harvest.sh───  验证过的改进 ←┘

Spec-Driven 工作流的完整性

从 Intake 三问 → 路由 → PM → (Prototype) → Arch → Dev/FE → QA → 验证 → 合并，每个环节都有明确的输入/输出门控：

门控点	类型	效果
Intake 三问	流程门控	防止需求模糊直接进入开发
01 用户审批	人类门控	需求偏差在写代码前发现
02 用户审批	人类门控	技术方案偏差在实现前发现
Dev/FE 自查	自检门控	合规性 + 质量两阶段自查
QA 四轴审查	独立审查	Spec 达成 + 一致性 + 质量 + 反过度设计

四轴审查覆盖了代码审查的核心维度，"反过度设计"作为独立审查轴是一个实用的创新。

工具链的工程化水平

• upgrade.sh：SHA-256 冲突检测 + 三种冲突策略（默认覆盖备份/preserve跳过/fail退出），设计精巧
• harvest.sh：版本逆序检查、内容缩减风险警告，数据安全意识强
• doctor.sh：分层检测（框架基础 → 项目工具 → 可选集成 → E2E），实用性强
• 整体工具链的错误处理、日志输出、边界覆盖达到企业级水准

知识复用的 Skill 体系

• frontend-conventions 作为 Arch/FE/Prototype 三个角色的单一真相源，消除了知识重复
• spec-templates 让 PM/Arch/Dev/FE 都引用同一套模板，保证产出物格式统一
• sdd-riper-one-light 作为轻量流程协议，与正式工作流形成"快/慢"双轨

可选集成的非阻塞设计

Jira/Confluence MCP 集成标记为"可选、非阻塞"，E2E 测试也是可选的。这种"渐进增强"的设计让框架对不同成熟度的项目都友好。

1.2 做得不好的

规则膨胀 — 最大隐患

单次对话加载的规则量：
├── CLAUDE.md                ~300 行
├── project_rule.md          ~323 行
├── Agent 定义（PM/Arch/...）各 100-200 行
├── Skill 加载               各 50-150 行
└── 总计                     1000+ 行纯规则

根本矛盾：规则越详细，AI 遵循度越高，但 token 成本也越高，且长 context 下规则可能被"稀释"。

很多规则是"给 AI 看的 SOP"而非"AI 能精确执行的指令"：

• "深入调研现有架构" — AI 什么叫"深入"？执行到什么程度算够？
• "需求精度决定下游质量" — 这是设计理念，不是可执行指令
• "保持沟通" — 过于模糊，无法验证是否执行

Agent 定义的"伪角色"问题

7 个 Agent 本质上是对同一个大模型的不同 prompt 注入，没有真正的隔离：

维度	当前设计	理想设计
工具隔离	PM 有 Write/Edit 但靠 prompt "禁止写代码"	PM 不应该有 Write/Edit 权限
状态隔离	无，各 Agent 看到同一对话历史	Agent 间应有明确的上下文边界
行为约束	靠 prompt 中的"绝对禁止事项"	应通过工具权限强制执行

工作流调度的脆弱性

• 整个调度逻辑写在 project_rule.md 里，靠主对话的 prompt 遵循能力来执行
• 没有状态机、没有持久化的流程状态——对话中断 = 流程丢失
• 路由决策树虽然逻辑清晰，但 Q0 的"轻量改动"判断标准（"不超过 3 个文件"）在需求初期很难准确判断

Spec 产出的"形式主义"风险

• 01 → 02 → 03 → 04 四个文档 + evidences/ 目录，对小需求来说产出物过重
• 这些 Spec 文档的实际质量完全依赖 AI 的写作能力，框架定义了格式但没有验证内容质量的机制
• PM 前端模式要求"字段级精度"，但实际产出是否达标？谁来校验？

跨项目假设

框架中很多 Skill 深度绑定了特定技术栈：

Skill	绑定
frontend-conventions	Vue 2 + Element UI
frontend-prototype	Nuxt 2
frontend-create-component	Vue 2
backend-rules	Java + MyBatis-Plus
e2e-testing	Playwright + qiankun

要适配其他技术栈（React、Go、Python）需要大量重写 Skill。

---

二、使用者视角（AI 遵从度 & 团队落地效果）

2.1 做得好的

"三铁律"的可记忆性

No Spec No Code      — 没文档，不准写代码
No Approval No Execute — 没批准，不准执行
Spec is Truth        — 文档是真相源

三个短语简洁有力，AI 容易记住和遵循。这种"口号式约束"比长篇规则更有效，是一个好的设计直觉。

审批门控的实际效果

01 和 02 的用户审批环节，在实际使用中确实起到了"纠偏"作用。人类在审批时发现 AI 理解偏差的频率不低，说明这个门控是有价值的。

证据落盘机制

evidences/ 目录要求所有关键操作留下记录。QA 的审查报告格式规范，PASS/FAIL 结论明确，对事后复盘和问题追溯很有帮助。

Dev Agent 的两阶段自查

第一阶段：Compliance（合规性）— 我做的和 Spec 一致吗？
第二阶段：Quality（质量）    — 代码本身过关吗？

合规性 + 质量的分离设计很实用，对标 02 的逐一核对有效减少了"实现偏离设计"的情况。

2.2 做得不好的

学习曲线陡峭 — 团队落地的最大障碍

新成员需要理解的概念清单：

两层分离、Marker 机制、7 个 Agent、3 种工作流、
Intake 三问、路由决策树、Spec 产出物定义、
Skill 体系、双向同步、冲突检测...

实际问题：团队成员不太可能通读这些文档，最终只有框架作者真正理解全貌。框架的"知识密度"太高，缺乏渐进式的学习路径。

AI 实际遵从度的不确定性

规则写得再好，AI 不遵循就是白写。实测中常见的违规行为：

违规行为	典型场景
跳过 Intake 直接开始	"看起来简单"的需求
Dev 自行修改 Spec	执行中发现设计问题，不报告直接改
QA 审查流于形式	输出 PASS 但实际没仔细看代码
路由判断走错	把前后端联动误判为纯前端

框架定义了很多硬约束，但无法在技术层面强制执行。

对话轮次的隐性成本

完整的工作流 A（纯后端）对话轮次估算：

Intake(2-3轮) → PM(2-3轮) → 审批(1轮) → Arch(2-3轮) → 审批(1轮)
→ Dev(3-5轮) → QA(2-3轮) → 验证(1-2轮) → 合并(1轮)
≈ 15-20 轮对话，30-45 分钟

团队成员的耐心是有限的，过长的流程会导致"直接让 AI 改代码"的冲动。

反馈回路的缺失

• 框架没有结构化的反馈机制
• harvest.sh 收割的是内容变更，不是流程改进建议
• 框架的演进完全依赖框架作者的个人判断，缺少来自使用数据的驱动

Demo 与真实项目的差距

Demo 是一个 4 实体的 CRUD 应用，验证的是"文件同步是否正常"。真实项目的复杂度（多模块、微前端、权限矩阵、国际化、跨团队协作）远超 Demo。

---

三、改进路线图

P0 — 立即可做（降低复杂度）

1. 精简规则体量

审视每条规则的"遵从 ROI"——AI 实际能遵循的规则 vs 只是"写了个安心"的规则。

具体方案：将 project_rule.md 拆分为两层：

core/rules/project_rule.md       ← 核心约束（~80行，常驻加载）
core/rules/workflow-reference.md ← 详细参考（按需加载）

核心约束只保留：

• Intake 三问（硬约束）
• 路由决策树（简化版）
• 三铁律
• 产出物定义表
• 绝对禁止事项

详细参考包含：

• 工作流 A/B/C 的完整阶段描述
• E2E 触发规则
• Deploy 阶段
• Jira 集成详细规则

2. 增加规则遵从度自检

在关键节点增加"checkpoint prompt"，让 AI 输出决策理由：

路由决策后必须输出：
  路由判断：工作流 X
  理由：...
  已排除的选项：...（为什么排除）

Spec 审批呈现后必须包含：
  需求要点摘要（3-5 条）
  边界和不做的项
  待确认的疑问（如有）

3. 收集使用数据

在下游项目中增加简单的使用日志，记录工作流触发类型、对话轮次、中断情况。数据驱动的改进比直觉判断更可靠。

P1 — 短期改进（提升落地效果）

4. 渐进式入门路径

设计"最小可用框架"配置：

Level 0: 无框架（直接用 Claude Code）
Level 1: Intake 三问 + 轻量流程（sdd-riper-one-light）
Level 2: + PM + Arch 角色分离
Level 3: + Dev/FE 两阶段自查 + QA 独立审查
Level 4: + Prototype + E2E + Jira 集成

对应到工具链：init-project.sh 增加 --level N 选项。

5. 强化 Agent 安全边界

• PM Agent：审视是否真的需要 Write 和 Edit tool（只写 .md 文件场景）
• 在 Agent prompt 末尾增加"操作审计"段，列出本次会话中创建/修改的所有文件
• QA Agent 已经没有 Edit tool，这是好的

6. 框架自测能力

设计标准化测试用例——给定特定的需求描述，验证：

• 路由是否正确（A/B/C/轻量）
• Spec 产出物是否包含所有必需字段
• QA 审查是否真正逐项核对

P2 — 中长期演进

7. 工作流状态持久化

引入轻量级状态文件 .claude/workflow-state.json：

{
  "feature": "user-manage",
  "stage": "arch-design",
  "artifacts": {
    "01": ".claude/specs/feature-user-manage/01_requirement.md",
    "02": null
  },
  "approvals": {
    "01": { "status": "approved", "timestamp": "..." },
    "02": { "status": "pending" }
  }
}

对话中断后通过读取状态文件恢复。

8. 技术栈解耦

将 Vue 2 / Java 特定的 Skill 从 core/ 中分离：

core/                         ← 技术栈无关的规则
  rules/project_rule.md
  agents/pm-agent.md
  skills/spec-templates/
  skills/sdd-riper-one-light/

plugins/vue2-element/         ← Vue 2 技术栈插件
  skills/frontend-conventions/
  skills/frontend-prototype/
  skills/frontend-create-component/

plugins/java-mybatis/         ← Java 技术栈插件
  skills/backend-rules/
  skills/sql-checker/

9. 可观测性

建立框架使用 Dashboard：工作流类型分布、平均轮次、审批通过率、QA 打回率。用数据回答"框架到底有没有用"。

---

四、总结矩阵

维度	好的	不好的	改进优先级
架构设计	两层分离 + Marker + 双向同步	规则膨胀、跨项目假设	P0 精简、P2 解耦
Agent 体系	角色分工清晰、三铁律好记	伪角色、安全边界靠 prompt	P1 强化边界
工作流	门控有效、四轴审查全面	调度脆弱、状态不持久	P0 自检、P2 状态化
产出物	格式统一、证据可追溯	形式主义风险、质量无验证	P1 自测能力
团队落地	Demo 先行、doctor 诊断	学习曲线陡、无反馈回路	P0 精简、P1 渐进入门
AI 遵从度	审批门控有效	违规常见、无法强制执行	P0 自检、P1 安全边界

一句话总结：框架的"骨架"设计优秀（两层分离、双向同步、门控流程），但"肌肉"过度发达（规则太多、Agent 太重、产出物太多），需要做减法。下一步的重点不是加功能，而是精简、验证、数据驱动。

---

五、Meta-review：改进工作本身的复盘

以下内容写于 P0/P1 改进实现之后，是对"改进工作本身"的诚实回顾。

5.1 实际完成情况

P0（立即可做）— 完成 2.5 / 3

#	改进项	状态	说明
1	精简规则体量	部分完成	project_rule.md 从 323→187 行（-42%），但原本设想的"拆分为两层文件"方案未实施——发现 .claude/rules/ 下所有文件会被 Claude Code 自动加载，拆分无法减少 token 消耗，只能靠删除冗余内容实现。方向正确，但"精简多少才够"还没有数据支撑
2	规则遵从度自检	已完成	路由自检 checkpoint + PM/Arch/QA 三个 Agent 的结构化自检。但自检的有效性尚未在实际任务中验证——AI 输出 ✅ 并不等于真的做了
3	收集使用数据	未完成	没有设计实现方案，这是最大的缺口。没有数据，所有规则的价值判断都是主观猜测

P1（短期改进）— 完成 3 / 3

#	改进项	状态	说明
4	渐进式入门路径	已完成	init-project.sh 支持 level1-4，各级别有明确的 Agent/Skill/Command 组合。Level 1 只有 Intake + 轻量流程，对新团队友好
5	强化 Agent 安全边界	基本完成	审查了所有 Agent 的 tools 字段，确认 PM 需要 Write（写 .md 文件）、QA 没有 Edit（好）。增加了结构化自检作为 prompt 层面的安全网。但本质问题（靠 prompt 约束而非工具隔离）未解决
6	框架自测能力	已完成	创建了 16 个标准化遵从度测试用例（compliance-tests.md），覆盖路由、Intake、Agent 行为、门控、异常处理

P2（中长期）— 未启动（符合预期）

状态持久化、技术栈解耦、可观测性均为中长期项，未在本轮启动。

5.2 诚实评价：哪些问题真正被改善了？

原始复盘识别了 10 个问题（设计者 5 个 + 使用者 5 个），逐条对照：

问题	是否改善	说明
规则膨胀	部分	减了 42%，但核心矛盾（规则量 vs token 成本）仍在
伪角色问题	否	本质未变，仍是 prompt 约束而非工具隔离
工作流调度脆弱	轻微	自检机制增加了一层保护，但状态不持久的核心问题仍在
Spec 形式主义	否	产出物数量未变，质量验证机制未建立
跨项目假设	否	未做技术栈解耦
学习曲线陡峭	是	Level 1-4 渐进式入门有效降低了起始门槛
AI 遵从度不确定	轻微	自检机制增加了一层约束，但无法验证自检本身的质量
对话轮次成本	否	流程未简化，轮次未减少
反馈回路缺失	否	使用数据收集未实现
Demo 差距	轻微	新增了遵从度测试用例，但尚未在真实项目中执行

结论：10 个问题中，只有 1 个（学习曲线）被有效改善，2-3 个有轻微改善，其余未动。

5.3 关键发现

发现一：我们做的是"让现有规则体系更精密"，而不是"验证现有规则体系是否值得这么精密"。

增加自检机制、精简规则、渐进式入门——这些都是在假设规则体系有价值的前提下做的优化。我们还没有回答一个更根本的问题：

这些规则里，有多少是 AI 没有规则也会自然遵循的？有多少是写了也白写的？

发现二：没有使用数据，所有判断都是猜测。

精简了 42% 的规则——这是好是坏？不知道。因为不知道精简前 AI 的遵从度是多少，精简后的遵从度是多少。自检机制——AI 输出的 ✅ 有多大可信度？不知道，因为没有对照实验。

发现三：最大的盲区是"验证"而非"设计"。

框架团队（其实就是一个人）擅长设计规则和工作流，但不擅长验证这些设计在真实场景中的效果。Demo 验证的是文件同步，遵从度测试用例还没有被跑过，真实项目的使用数据为零。

5.4 下一步方向

基于 meta-review，下一阶段的重心应从"设计规则"转向"验证规则"：

方向一：规则 ROI 审计

将 ~1400 行规则（rules + agents，不含 skills 知识库）逐条分类：

• 天然行为：AI 没有这条规则也会这样做 → 删除，节省 token
• 有效约束：有规则时 AI 行为明显不同 → 保留，核心价值
• 愿望性指导：写了但 AI 无法可靠执行 → 改写为具体动作或删除
• 死规则：从未被实际场景触发 → 移除或归档

方向二：遵从度实测

用 compliance-tests.md 的 16 个测试用例，在真实项目（如 your-project）中跑一轮。记录实际结果，形成"框架遵从度基线"。

方向三：使用数据收集

在 project_rule.md 中增加轻量的 session-log 机制，由主会话在工作流结束时自动追加记录（工作流类型、轮次、中断点、完成状态）。积累 5-10 条数据后，就能用数据而非直觉判断规则的价值。

5.5 经验教训

1. "精简"的悖论：精简规则需要知道哪些规则有效，但判断有效性需要数据，收集数据需要先有框架在用。这是一个鸡生蛋问题——先用直觉精简，再用数据验证。

2. "自检"的信任链：让 AI 自检是否遵循了规则，存在信任链问题——如果 AI 本身就不可靠，它的自检也不可靠。但这仍然比不自检好，因为自检格式（✅/❌）至少让违规变得可见。

3. 复盘的节奏：应该在每个版本发版后都做一次简短复盘（不是这种深度复盘），持续积累而非一次性大复盘。