Plate spec-flow-analyzer 技能详解：四阶段规格流程分析法与缺口识别方法

Plate spec-flow-analyzer 技能详解四阶段规格流程分析法与缺口识别方法【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/platePlate 仓库Rich-text editor with AI and shadcn/ui中集成了一个名为spec-flow-analyzer的 Agent 技能定义于 .agents/skills/spec-flow-analyzer/SKILL.md。它的方法论是在实现开始之前从最终用户视角对规格说明spec、计划plan或功能描述做流程走查把缺失的用户流程、模糊需求和未定义的边界情况尽早暴露出来——因为此时修复成本最低。读完本文你可以完整掌握这套四阶段分析法的操作细节如何锚定代码库、如何映射用户流程、如何识别四类缺口、如何提出高质量问题、标准的四段式输出格式以及在 Plate 仓库中它被挂载到哪条工作流major-task重任务通道上用于 RFC、提案和验收标准的完整性压测。技能定位与元数据技能的 frontmatter 元数据声明了它的基本身份与来源name: spec-flow-analyzer description: Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation. model: inherit metadata: skiller: source: plugins/compound-engineering/agents/workflow/spec-flow-analyzer.md几个值得注意的事实触发时机description字段当一份规格、计划或功能描述需要做流程分析、边界情况发现或需求校验时使用。model: inherit该技能不绑定特定模型继承调用方 Agent 的模型配置。来源追踪metadata.skiller.source指向plugins/compound-engineering/agents/workflow/spec-flow-analyzer.md。这一点与仓库根目录的 skiller-lock.json 相互印证——其中记录了spec-flow-analyzer的source为EveryInc/compound-engineering-pluginsourceType为github并带有computedHash用于校验内容一致性。也就是说这份技能是从 Compound Engineering 插件安装到 Plate 仓库的一份本地化产物由 skiller 工具链管理相关全局配置见 .agents/skiller.toml。在 Plate 工作流中的位置根据 docs/analysis/compound-engineering-tree.md 中的 Compound Engineering Agent 树spec-flow-analyzer是 Workflow 分类下唯一安装的 agent挂在major-task lane上用途是RFC、proposal、acceptance-criteria、rollout 和完整性压测。它不属于默认的task轻量通道——只有当任务升级为架构、比较、基准测试或提案类重活时才会加载。这也与 .agents/rules/major-task.mdc 中把它列为 major-task 的 CE 引用之一相一致。三个典型使用场景SKILL.md 内联了三个example界定该技能最典型的触发语境。三者有一个共同点输入都是一份尚未实现的、待评审的规格输出都是对用户流程与缺口的系统化分析。OAuth 集成规格用户刚起草完 OAuth 实现规格Heres the OAuth spec for our new integration: [OAuth spec details]助手启动 spec-flow-analyzer识别所有用户流程、边界情况和缺失的澄清点。社交分享功能构想用户还在口头描述阶段Users can share to Twitter, Facebook, and LinkedIn助手判断这是一个值得做流程分析的功能规格从用户视角梳理全部流程变体permutations并抛出关于缺失部分的追问。Onboarding 流程计划评审用户明确要求 reviewmake sure we havent missed anything助手从用户视角彻底分析该 onboarding 计划找出所有用户流程、边界情况和规格缺口。从这三个示例可以推断出技能的适用边界它面向的是实现前的需求/规格评审而不是代码评审或事后 bug 分析。Phase 1先锚定代码库Ground in the Codebase方法论的第一步不是读规格而是搜代码。原文给出的理由非常明确这能防止给出泛泛的反馈并暴露真实的约束条件。具体三步用原生内容搜索工具例如 Claude Code 中的 Grep查找与功能域相关的代码——models、controllers、services、routes、已有测试用原生文件搜索工具例如 Glob查找可能共享模式或与之集成的相关功能记录既有模式代码库今天是如何处理类似流程的错误处理、认证、校验方面存在什么约定SKILL.md 用一句话总结了这一步的哲学Gaps are only gaps if the codebase doesnt already handle them.只有代码库没有处理的问题才算真正的缺口。这一步的输出会塑造后续所有阶段的判断——它把通用检查清单式的评审变成基于本项目现状的评审。Phase 2映射用户流程Map User Flows这一步要求像用户一样走一遍规格Walk through the spec as a user把每一条从入口到结果的独立旅程映射出来。对每条流程flow需要识别四个要素Entry point入口点——用户如何到达这里直接导航、链接、重定向、通知Decision points决策点——流程基于用户动作或系统状态在哪里分叉Happy path快乐路径——一切正常时的预期旅程Terminal states终态——流程在哪里结束成功、错误、取消、超时。这里有一条重要的克制性约束Focus on flows that are actually described or implied by the spec. Dont invent flows the feature wouldnt have.聚焦于规格中实际描述或隐含的流程不要发明该功能本来不会有的流程。这与后文 Principles 中Derive, dont checklist的原则一脉相承。Phase 3找出缺失的部分Find Whats Missing将 Phase 2 映射出的流程与规格实际规定的内容做对比。SKILL.md 指出最有价值的缺口是规格作者大概没想到的并给出四个高频缺口维度Unhappy paths不快乐路径——用户输入错误、失去网络连接、撞到限流时会发生什么错误状态是最多缺口藏匿的地方State transitions状态迁移——用户能否进入规格没有考虑过的状态部分完成、并发会话、过期数据Permission boundaries权限边界——规格是否考虑了不同用户角色与该功能的交互Integration seams集成接缝——本功能触碰既有功能的地方交接handoffs是否被明确指定这一步必须回用 Phase 1 的成果做校准如果代码库已经处理了某个关切例如已有全局错误处理中间件就不要把它标记为缺口。这条规则是避免检查清单噪音的关键机制。Phase 4把缺口转化为问题Formulate Questions对每个缺口SKILL.md 要求形成一个具体的问题并明确区分了好问题与坏问题好当 OAuth provider 返回 429 限流时UI 应该显示带倒计时的重试按钮还是在后台静默重试坏限流怎么办原文的批评标准是模糊的问题what about errors?浪费规格作者的时间好的问题要点名场景、把模糊性具体化。并且每个问题必须附带三个组成部分问题本身Why it matters——如果不加规定什么会坏掉或退化Default assumption——如果问题始终得不到回答时的默认假设。这个问题 利害关系 默认值的三元组结构使得输出可以直接转化为规格文档的待办事项而不是停留在提了个醒的层面。标准输出格式SKILL.md 规定了四段式输出结构每段都有明确的组织原则1. User Flows用户流程逐条编号列出。分支复杂到值得可视化时用 mermaid 图简单则用纯文字描述——不强制配图。2. Gaps缺口按严重程度组织而不是按类别组织Critical——阻塞实现或带来安全/数据风险Important——显著影响 UX或产生开发者会各自不一致地解决的歧义Minor——存在合理默认值但值得确认。每个缺口需说明缺的是什么、为什么重要、既有代码库模式如果有暗示了什么默认值。3. Questions问题编号列表按优先级排序。每条包含问题、利害关系stakes、默认假设。4. Recommended Next Steps建议的下一步Concrete actions to resolve the gaps -- not generic advice.解决缺口的具体行动而非泛泛建议。必须引用那些在实现推进之前应当被回答的具体问题编号。设计原则PrinciplesSKILL.md 末尾给出四条原则它们是整套方法论的灵魂也是对AI 评审容易输出清单式噪音这一通病的直接回应Derive, dont checklist推导而非打勾清单——分析这份特定规格真正需要什么而不是套一份通用关切清单。原文举了两个反例一个 CLI 工具的规格不需要屏幕阅读器的可访问性考量一个内部后台页面不需要离线支持。Ground in the codebase锚定代码库——引用既有模式。代码库对类似流程用 X 处理但这份规格没提它远比考虑一下 X有用。Be specific具体——点名场景、用户、数据状态。具体示例让模糊性无处遁形。Prioritize ruthlessly无情地排序——区分阻塞项与锦上添花。标出 30 个等权重条目的规格评审不如标出 5 个关键缺口的评审有用。在 Plate 仓库中的实际应用位置结合 docs/analysis/compound-engineering-tree.md 可以看到 Plate 对这套 CE 工具链做了刻意瘦身task轻量通道默认不加载任何文档评审人格而major-task通道才在条件触发下挂载研究脊柱与文档评审人格spec-flow-analyzer正是其中的流程完整性一环。该文档给出的取舍逻辑是keep a small serious research spine——保持一条小而严肃的研究脊柱拒绝把每个任务都变成research circus研究马戏团。从 skiller-lock.json 的元数据还可以看到完整的安装清单spec-flow-analyzer与scope-guardian-reviewer等 agent 一样带有computedHash说明仓库用哈希锁来保证从上游 Compound Engineering 插件同步下来的技能内容未被本地篡改。配合 .agents/AGENTS.md 中.agents/AGENTS.md与.agents/rules/*.mdc才是 source of truth编辑后运行pnpm install同步切勿直接编辑 SKILL.md的约定可以推断出 Plate 仓库的 Agent 技能治理模式是规则源文件.agents/rules/*.mdc为真相 → 由 skiller 工具链生成/同步 SKILL.md 产物 → 用 lock 文件哈希固化。这也解释了为什么阅读仓库内 Agent 行为约定时应优先看.agents/rules/目录。小结spec-flow-analyzer提供的是一套可迁移的规格评审方法论其核心贡献有四顺序反转——先读代码库再读规格Phase 1 前置让缺口的定义由项目现状而非通用清单决定用户旅程四要素模型——入口点、决策点、快乐路径、终态配合不发明流程的克制约束四维度缺口扫描 严重度分级——不快乐路径、状态迁移、权限边界、集成接缝输出按 Critical/Important/Minor 分级而非按类别罗列三元组问题结构——每个问题自带利害关系与默认假设使评审结论可直接落成规格修订项。这套方法对任何在实现前需要压力测试 RFC、提案或验收标准的项目都有参考价值在 Plate 仓库中它被明确限定在major-task重任务通道内按需加载体现了小工具集、按证据增补的工程治理取向。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考