在 Vue 2 大型 SPA 与 Cursor / Agent 长期协作中，把「会写 prompt」升级为可复用的工程体系：行为有契约、上下文有归属、变更有边界。

适用读者：前端 Tech Lead、与 AI 结对超过一个季度的开发者、正在给团队铺 Agent 工作流的同学。

Agent 能写代码，但缺少结构时会：跨层改文件、重复实现已有语义、把实现细节当产品规则、每次会话重读整仓。

工程化的目标不是限制 AI，而是把稳定约束写进仓库，让对话只处理本次差异。

• 行为契约与实现分离：Requirements 写「做什么」，design/tasks 写「怎么做」。
• 持久上下文 vs 一次性任务：Rules 长期生效；Chat 只解决当前变更。
• 模块 README 作局部 SSOT：目录、数据流、入口写清楚，Agent 不必扫全仓。
• 读写分离、状态单一归属：同一业务状态只有一个权威来源；UI 只发命令，不编排副作用链。
• 存量渐进、增量守边界：旧代码允许例外，新增必须走 composable / service / spec。
• 改行为走 change，不直接改真相：已归档 spec 是行为真相；回填也要留 archive 快照。
• 验证围绕 diff，不围绕焦虑：优先验证本次变更触达的文件、状态和场景，不默认跑全仓 lint/build。

部分工作流思路参考 Matt Pocock skills（如 grill、diagnose、tdd）；业务规则与 reviewer 协议为项目内沉淀。

不需要一开始就建设完整体系。对一个已有项目，我通常按这个顺序落地：

1. 写一份 AGENTS.md 或 .cursor/rules/architecture.mdc，先约束分层、import 方向和高风险命令。
2. 给最复杂的 1-2 个业务目录补 README.md，写清入口、状态来源、核心数据流和不要踩的坑。
3. 新功能先走 OpenSpec change：先写行为，再写设计和任务拆分。
4. 合并前跑专项 reviewer：至少覆盖架构边界、运行时稳定性和复杂度控制。
5. 改完只验证本次 diff 相关路径，优先做小而准的回归，不用全仓扫描制造噪声。

flowchart LR
  intent[需求与 Grill] --> change[OpenSpec change]
  change --> rules[Cursor Rules]
  rules --> impl[实现与单测]
  impl --> readme[模块 README]
  impl --> archive[Archive 合并 specs]
  skills[Skills] --> intent
  skills --> impl
  review[Reviewer] --> impl

典型节奏：Grill 定边界 → active change 写 delta → Rules 约束实现 → 模块 README 同步 → archive 合并进 specs → reviewer 过一遍再合入。

AI 协作里，验证不是“跑得越多越安全”，而是要让反馈足够短、足够准。

• 默认不跑全仓 build / lint / test，除非变更风险真的需要。
• 优先只验证本次 diff 触达的文件、状态 owner 和调用链。
• 对高风险改动至少覆盖三类场景：正常路径、空值/缺省、异常输入。
• 对画布、媒体、账号、登录态这类复杂链路，先确认状态来源和副作用边界，再设计回归。
• 验证失败时先缩小问题面，不把一次失败扩散成全仓排查。

Reviewer 不是泛泛地“让 AI 再看一遍代码”，而是按视角拆分问题。

常用 reviewer：

• AI 可维护性：结构是否容易被 Agent 理解、续写和避免误改。
• 架构 / DDD：领域边界、状态归属、依赖方向和演进成本。
• 运行时稳定性：Vue2 reactivity、生命周期释放、副作用扩散和线上 bug 风险。
• 复杂度控制：是否过度抽象、伪解耦、增加不必要心智负担。
• 领域一致性：同一业务语义是否重复实现，service / domain boundary 是否稳定。

统一输出协议：

• 只给 Top 风险，不做散点式风格点评。
• 每个风险必须有证据、触发条件、危害和最小修改建议。
• 优先收敛问题，不默认扩大重构范围。

让仓库适合 Agent 长期协作，本质是降低它每次理解系统的成本。

• Rules 写稳定约束，不写百科。
• Spec 写行为，不写文件名。
• README 写局部地图，不复制实现细节。
• Skill 写可重复流程，不写一次性结论。
• Reviewer 写 Top 风险，不写泛泛建议。
• 复杂模块先定义状态 owner、写入口、读入口和恢复优先级，再允许实现。

复杂 AI 产品里，最容易被 Agent 写坏的不是 UI，而是“谁拥有真相”。

• 问题：Agent 易在 view 直调 API、UI 反向依赖 store、同一权限多套判断并行存在。
• 手段：分层 rules 明确 import 方向；UI 组件禁止反向引用业务层；新模块走 composable + service。
• 教训：存量可以慢慢迁，但新增若不守边界，协作成本会指数上升。

• 问题：多个大功能已上线，却没有可机器读的「行为真相」，每次都要重读实现。
• 手段：对已上线域做 retroactive archive 回填；日常变更走 active change；spec 只写 GIVEN/WHEN/THEN，不写文件名。
• 教训：禁止为图省事直接改 specs/ 却不留 archive；过程稿不进 OpenSpec，结论必须先落 proposal/design。

• 问题：transient UI 包住旧表单、连线图与 local cache 多源恢复，易出现 prompt 被清空、连线误删。
• 手段：Wrapper 适配层 + resolver 中间结构；标量与附件 SSOT 分离（草稿/cache vs 连线）；恢复期限制流，禁止误触全量 echo。
• 教训：「打开面板」与「已打开时新增上游连线」是两条数据流，不能共用一套全量回显。

工程化不是把所有事情都流程化。

• 不为一次性需求写庞大 spec。
• 不为了 AI 协作把所有逻辑都抽成 service。
• 不让 rules 变成长篇知识库。
• 不把 reviewer 当成格式化意见收集器。
• 不用全仓扫描替代模块文档。
• 不用复杂抽象掩盖状态 owner 不清的问题。

• 把 spec 写成实现步骤清单 → Agent 会绑死错误抽象。
• Rules 过长且无分层 → 上下文被挤占，反而遵守率下降。
• 模块无 README → 每个新会话都从 grep 开始。
• HTTP 拦截器已弹错，业务 catch 再 Message.error → 重复提示。
• 让 Agent 跑全仓 lint/build「验证一下」→ 慢且噪声大；应只 lint 改动文件。
• 半登录 / 门控状态多处 decode → 权限判断不一致。
• 画布 / 媒体链路：跨域污染、生命周期未清理、seek 与首帧时序 → 需按媒体管线单独诊断，不能当普通 UI bug 修。

当前 v1 先保留轻量模板，后续可拆到独立 templates/ 目录。

change/
  proposal.md      # 为什么改，目标和非目标
  design.md        # 方案、状态 owner、边界和风险
  tasks.md         # 可执行任务拆分
  specs/*/spec.md  # GIVEN / WHEN / THEN 行为场景

# Module Name

## Responsibilities
这个模块负责什么，不负责什么。

## Entry Points
页面入口、组件入口、service 入口。

## Data Flow
核心数据从哪里来，经过哪里，写回哪里。

## State Ownership
哪些状态由 store / service / composable / local draft 拥有。

## Common Pitfalls
Agent 最容易误改的边界。

一句话结论

Top risks:
1. 等级 / 证据 / 危害 / 触发条件 / 最小修改建议
2. 等级 / 证据 / 危害 / 触发条件 / 最小修改建议
3. 等级 / 证据 / 危害 / 触发条件 / 最小修改建议

Next actions:
- 可直接执行的下一步

当 README 篇幅继续膨胀时，计划拆出独立文档站（VitePress + GitHub Pages）与脱敏 templates/：

• OpenSpec 骨架
• 通用 architecture rule
• module README 模板
• reviewer skill 模板
• JIT 验证脚本模板

当前 v1 先保留方法论正文与最小模板。