requirements-clarity

requirements-clarity 技能概览

requirements-clarity 是一套结构化的需求澄清流程，专门用来在真正开始写代码之前，把模糊的功能想法整理成可落地、可实施的需求。它尤其适合产品经理、技术负责人、创业者，以及经常借助 AI 开发的人：你们常常会从“加个登录”“做个 dashboard”“接入支付”这类请求起步，但此时的信息还不足以做估时、设计方案，或安全地推进上线。

requirements-clarity 主要解决什么问题

它真正要解决的，不是“把 prompt 写得更漂亮”。核心价值在于通过结构化追问，把遗漏的决策点逼出来，减少返工：包括范围边界、技术上下文、验收标准、边界场景、约束条件，以及成功指标。requirements-clarity 不是给你一次泛泛的头脑风暴回复，而是通过聚焦提问和 PRD 风格的输出路径，帮助你把需求补完整。

最适合的使用场景

requirements-clarity 最适合在以下情况下使用：

• 需求表述本身有歧义
• 这个功能大概率不只是一个小修小补
• 会涉及多个团队或多个利益相关方
• 技术栈、集成方式或非功能约束还没有说清楚
• 你需要的不是松散讨论，而是更接近可用 spec 的结果

它和普通 prompt 的区别在哪里

真正的差异在于流程。这个技能会明确识别模糊需求，执行结构化的缺口分析，分轮次提问，而不是一次性把所有问题全丢出来；同时还会用一个评分模型来判断需求的完整度。如果你的主要问题是“信息缺失”，而不是“文案润色不够”，那它会比一句式的“帮我完善这个功能需求”更值得采用。

什么情况下不该用 requirements-clarity

如果任务已经非常接近代码、而且足够具体，就不该优先使用 requirements-clarity，比如：

• 一个带有明确复现步骤的 bug
• 一个已经指向具体文件或行号的改动请求
• 请求里已经附带了代码片段
• 工作重点围绕现有的某个函数或类展开

这类场景通常直接走实现、调试或代码评审流程会更快。

如何使用 requirements-clarity 技能

requirements-clarity 的安装与仓库位置

在 softaworks/agent-toolkit 仓库里，这个技能位于 skills/requirements-clarity。如果你的环境支持从 GitHub 安装 Skills，比较实用的安装方式是：

npx skills add softaworks/agent-toolkit --skill requirements-clarity

如果你的 agent runtime 不使用这个安装器，也可以直接查看技能内容：
https://github.com/softaworks/agent-toolkit/tree/main/skills/requirements-clarity

建议先读 SKILL.md，再看 README.md 了解更高层的说明。

第一次使用前应该先读哪些文件

按这个顺序看：

1. skills/requirements-clarity/SKILL.md
2. skills/requirements-clarity/README.md

SKILL.md 是最关键的文件，关系到调用行为：什么情况下应该触发这个技能、什么情况下不该触发，以及提问流程是怎么设计的。README.md 更适合用来理解评分逻辑和预期产出。

requirements-clarity 应该在什么情况下被触发

requirements-clarity 是为模糊请求设计的，不是给已经写得很细的工程 ticket 用的。只要输入信息还不足以让团队有把握地开工，它就应该介入。典型触发示例包括：

• “Add login to the app”
• “Implement payment support”
• “Create an admin dashboard”
• “We need user management”

这类表述足够宽泛，技能才能通过澄清过程真正创造价值。

什么样的输入最容易得到高质量输出

最好的起始 prompt，不是把所有事情都讲完，而是提供足够的背景，让技能能提出更聪明的追问。建议至少包含：

• 业务目标
• 目标用户
• 当前产品或系统
• 已知约束
• 粗略的时间要求或交付阶段
• 必须接入的集成
• 已知不做的范围

一个较弱的输入是：

• “Build notifications.”

一个更强的输入是：

• “We need in-app notifications for team admins in our SaaS dashboard. Stack is React + Node. MVP should cover system alerts and mention alerts, but not email yet. We need something small enough for this sprint and clear enough to estimate.”

第二种写法能让 requirements-clarity 少问很多泛泛的问题，更快进入可用 spec 的状态。

如何把一个粗略目标写成好的调用 prompt

可以按这个结构组织：

• 这个功能是什么
• 为什么重要
• 服务谁
• 在哪里使用
• 技术环境
• 约束条件
• 你已经知道什么
• 还有什么没定

示例：

“I need help using requirements-clarity for Requirements Planning. We want to add SSO to our B2B web app for enterprise customers. Current stack is Next.js, Node, and Postgres. We already support email/password login. We need a first-pass PRD covering MVP scope, admin setup flow, acceptance criteria, edge cases, and non-goals. Unknowns include which providers to support first and how provisioning should work.”

这种 prompt 的好处是：它给了技能足够具体的分析基础，但又不会假装需求已经完整定稿。

requirements-clarity 的实际工作流通常是什么样

一个实用的 requirements-clarity usage 流程通常如下：

1. 先给出粗略的功能请求。
2. 让技能识别缺失的需求维度。
3. 分小批次回答追问。
4. 回看澄清后的范围，以及明确写出的非目标。
5. 再要求生成最终的 PRD 风格输出。
6. 用这份结果做估时、设计或交接。

质量高低往往取决于你是否完成了整段对话，而不是只看第一轮回复。

这个评分系统真正有用的地方是什么

仓库里描述了一个 100 分的清晰度模型。真正有价值的不是分数本身，而是它带来的 checklist 效果。它能帮你暴露出请求是否缺少以下内容：

• 技术上下文
• 验收标准
• 成功指标
• 边界场景
• 错误处理
• 范围边界

把这个分数当成“还有哪些问题没回答”的信号，而不是拿来做表面上的好看指标。

一次应该回答多少问题

这个技能本身的方法更倾向于一次只处理一个类别，通常每轮回答 2–3 个聚焦问题。这样做很重要，因为如果把所有未知项一次性全塞进一条回复里，通常只会得到浅层回答，还容易把矛盾藏起来。短轮次互动更有利于提升需求质量，也更方便利益相关方审核。

使用 requirements-clarity 时通常能得到什么输出

一次跑得比较好的 requirements-clarity 流程，最终通常会留下这些成果：

• 更清晰的功能定义
• 明确写出的假设
• MVP 与后续阶段的边界
• 验收标准
• 关键边界场景
• 约束与依赖
• 一份还能继续迭代的 PRD 风格产物

如果最后只得到一些泛泛建议，通常说明起始上下文太薄，或者对话过早结束了。

能显著提升 requirements-clarity 使用效果的实用技巧

• 直接点明产品区域，比如：“admin dashboard”“checkout”“mobile onboarding”。
• 尽早说清楚已知不做的内容，比如：“No mobile app in MVP”“No SAML in phase 1.”
• 补充现有系统事实：当前登录方式、当前支付服务商、当前角色体系。
• 如果同时有业务诉求和实现偏好，把两者分开表达。
• 如果团队还处在探索阶段，先让技能列出未知项，再进入方案建议。

这些小改动，通常比一句“请更详细一点”更能提升结果的具体性。

requirements-clarity 技能 FAQ

requirements-clarity 适合新手吗？

适合，尤其适合那些已经知道想做什么功能，但还不会把需求写扎实的新手。它的结构化流程能帮助他们避免一些典型遗漏，比如漏掉边界场景、范围说不清、没有验收标准等。对有经验的团队也有价值，因为它能提供一套可重复使用的需求 intake 流程。

它和直接让 AI 写 PRD 有什么不同？

直接让 AI 生成 PRD，往往会为了补空白而“自动脑补”很多细节。requirements-clarity 更适合那些希望模型先识别模糊点、提出有针对性的问题，然后再进入 PRD 输出的人。这样可以减少虚假的确定感，通常也更容易产出值得信赖的规划文档。

我能只把 requirements-clarity 用在 Requirements Planning 上吗？

可以，而且这正是它最适合的场景之一。这个技能尤其适合用在实现前规划、backlog 梳理、产品探索，以及跨职能对齐阶段。它不只是最终文档产出工具；在需求还不稳定、尚未定型的早期阶段，它反而更有价值。

什么情况下应该跳过 requirements-clarity，直接用 coding skill？

当工作项已经具备清晰的实现上下文时，就应该跳过它，例如：

• 有明确的文件引用
• 正在讨论现有代码
• bug 步骤清晰
• 改动范围很窄、歧义很低

如果你的核心未知是“这段代码该怎么写”，而不是“我们到底要做什么”，那就该改用偏 coding 或 review 的技能。

这个技能是否要求特定技术栈？

不要求。这个流程本身是 stack-agnostic 的，但只要你提供技术栈，产出通常会更好。技术上下文本来就是这个技能要主动识别的缺口之一，所以越早说清楚你的环境，它就越能提出更相关的问题。

requirements-clarity 适合小任务吗？

有时适合，但并不总是。对于非常小的改动，做完整澄清流程的成本可能并不划算。这个技能最有价值的场景，还是那些需求有歧义、存在风险，或者规模大到返工代价较高的功能。

如何改进 requirements-clarity 技能的使用效果

给 requirements-clarity 更好的原始输入

提升效果最快的方法，就是把起始输入写得更扎实。建议补上：

• 用户类型
• 业务目标
• 当前流程
• 技术栈与集成背景
• 交付约束
• 哪些内容不在范围内

这样能减少泛泛追问，让技能把精力放在真正不确定的部分。

常见失败模式：过早要求给方案

很多团队在问题定义和成功标准还没说清时，就急着讨论 UI、数据库或者 vendor 选择。使用 requirements-clarity 时，更好的顺序是：先让它识别需求缺口、假设和范围边界，再进入方案选项。这个顺序会让结果更耐用，也更不容易推翻重来。

常见失败模式：名词太空泛

像 “dashboard”“management”“notifications”“enterprise support” 这类词，背后可能隐藏着非常大的范围差异。要提升结果质量，最有效的方法之一就是把这些泛词改写成具体能力清单。

不要只说：

• “Need user management”

更推荐写成：

• “Need admin-only controls for inviting users, assigning roles, deactivating access, and viewing audit history”

只改这一点，requirements-clarity 的澄清基础就会好很多。

主动要求列出明确的非目标和边界场景

想提升 requirements-clarity 输出质量，一个很有效的做法是每次都要求它输出两个部分：

• “What is explicitly out of scope?”
• “Which edge cases still need decisions?”

这能有效避免那种“看起来很完整、实际一开发就反复返工”的 PRD。

先完成第一版，再迭代，不要在开始前就反复打磨

更高效的做法是先完整跑完一轮澄清，再做 refinement。一个比较顺手的迭代循环通常是：

1. 提出初始请求
2. 回答追问
3. 审阅生成的需求草稿
4. 纠正错误假设
5. 要求收紧验收标准和范围表述

这通常比一开始就想把初始 prompt 写到“完美”更有效。

把最终输出当成交接材料，而不是真理终稿

即使是质量很高的 requirements-clarity 输出，也依然应该经过产品、工程以及相关依赖团队的审核。最好的定位是：把它当作需求加速器和质量闸口，而不是替代利益相关方确认的工具。最稳妥的采用方式通常是：先澄清，后评审，再实施。