agentleFS
xsyubinxsyubin/clue-lens/.agents/skills/spec-clarification/SKILL.md

spec-clarification

Skill0 starsChanged 9 days agoMITView on GitHub

通过 Codex 与需求方进行轻量、多轮的业务需求澄清,识别目标、角色、范围、业务规则、核心流程、权限和异常边界,并在用户确认后生成 `clarification.md`。用于 OA、采购、审批、台账等业务系统的需求获取、原型口径确认、需求头脑风暴和范围澄清;输出作为后续技术需求细化与正式需求文档的输入。

The file

Files
SKILL.md

需求澄清

把零散想法、原型、会议记录或已有需求转化为经用户确认的轻量业务澄清文档。只澄清 WHAT、WHY、WHO 和业务边界,不展开页面字段、接口契约、表结构或代码设计。

执行流程

第 1 步:定位规格目录与输入

  • 按以下顺序确定目标规格目录:
    1. 若用户明确提供 spec/ 下的相对路径,将其作为目标路径。
    2. 若用户提供完整路径,确认其位于当前项目的 spec/ 目录下,并转换为相对路径。
    3. 若用户未提供路径,但当前请求明确指向 spec/ 下唯一的功能目录,可使用该目录,并向用户说明判断结果。
    4. 若存在多个候选目录或无法确定目标,不得猜测;在读取需求材料或写文件前先询问用户。
    5. $1 仅作为兼容写法,例如 $1=platform/audit,不假设调用环境一定提供位置参数。
  • 将最终确定的相对路径记为 <spec-path>;后续所有输入输出路径均使用 spec/<spec-path>/...。
  • 如果用户只调用 spec-clarification 而未提供功能、目录或需求材料,无法形成唯一候选时,先请用户提供目标功能或规格目录。
  • 目标目录为 spec/<spec-path>/,最终输出为 spec/<spec-path>/clarification.md。
  • 读取 spec/<spec-path>/raw-requirements.md 作为原始需求(若存在)。
  • 读取目标目录中用户提供的原始需求、会议记录、原型说明、图片说明和已有澄清文档;不要把 requirements.md、design.md 或 tasks.md 当作原始需求来源,除非用户明确要求基于它们反向澄清。
  • 仅按需读取与当前需求直接相关的项目规范,用于识别模块落位、项目边界和既有术语。
  • 若存在同类页面或模块,按需检查现有实现以发现可复用能力和潜在冲突,但不要把现有实现自动视为已确认需求。
  • 能在环境中查证的事实必须自己查,不要拿来占用提问轮次;只有决策才交给用户。现有实现、配置、既有术语和平台能力属于事实;是否沿用现状、是否纳入范围属于决策。
  • 若无法确定目标目录或没有任何可用的原始需求,先向用户索取必要信息,不生成空泛清单。

第 2 步:建立澄清底稿

读取 references/clarification-guide.md,从输入中提取:

  • 已明确事实:用户已经明确表达、无需再次开放式询问的内容。
  • 待确认假设:可以从上下文合理推断,但未经用户确认的内容。
  • 冲突与变更:不同材料之间口径不一致,或后续回答推翻前述结论的内容。
  • 关键缺口:会改变范围、用户行为、业务规则、验收口径或工作量级的问题。
  • 设计议题:技术栈、表结构、接口、组件、架构等应留到设计阶段的问题。

不要在此阶段写最终文件。先在对话中给出当前理解的精炼摘要,再进入提问。

第 3 步:分轮头脑风暴

  • 每轮聚焦一个主题,优先提出 1 至 3 个高影响问题,避免一次抛出整份问卷。
  • 同批提出的问题必须相互独立。若某个问题的答案会改变另一个问题是否还成立或该怎么回答,先问前者,拿到回答后再问后者。主题顺序先按依赖关系排布,依赖相同时再按影响度排序。
  • 问题必须说明“为什么需要确认”或不同选择的业务影响。
  • 有清晰且互斥的选择时给出 2 至 4 个选项,并允许用户补充其他答案;没有成熟选项时使用开放问题。
  • 每个问题都要附上你的推荐答案和理由,把用户的成本从开放作答降为确认或推翻。推荐必须标记为“建议”,经用户确认后才能成为结论。
  • 上下文不足以形成推荐时,说明还缺哪些信息,不要编造一个推荐。
  • 对用户回答进行回述,明确记录“已确认”“仍待确认”和“新出现的矛盾”。
  • 用户回答含糊时继续追问可观察的业务行为,不自行补齐关键规则。
  • 用户表示“不确定”时,补充说明推荐方案的取舍和风险帮助其判断,但不得替用户拍板。
  • 已确认的问题不重复询问,除非新信息造成冲突。

第 4 步:执行确认门

当关键缺口已关闭后,在对话中输出一份确认摘要,至少包含:

  • 目标与核心痛点
  • 用户角色与职责
  • 范围内与范围外
  • 核心业务规则和主要流程
  • 权限与数据边界
  • 异常、容量、性能或合规约束
  • 仍保留的开放问题或推迟项

明确询问用户是否确认按该口径生成需求澄清文档。只有用户明确表示“确认”“可以生成”“按此执行”等同意后,才进入下一步。

第 5 步:生成需求澄清文档

  • 读取 templates/clarification.md,根据实际需求裁剪章节,不机械保留无关问题。
  • 创建或更新 spec/<spec-path>/clarification.md。
  • 若更新已有文件,保留仍有效的历史结论;对被推翻的结论记录变更原因,不能静默覆盖造成口径丢失。
  • 文档必须区分已确认结论、范围边界、开放问题和变更记录。
  • 文档正文不得包含对话式占位语,如“请回答”“待用户填写”或空白的“回答:”;未决事项统一进入“开放问题与推迟项”。
  • 只记录需求口径。技术方案建议若对澄清有帮助,放入“设计阶段输入”,并明确标记为非需求结论。

第 6 步:自检并交付

写入后检查:

  • 每项结论都能追溯到原始材料或用户确认,不包含未经确认的关键假设。
  • 范围内、范围外和相邻系统职责清晰,不互相矛盾。
  • 角色、触发条件、业务行为、异常场景和约束足以支撑后续技术需求细化与正式需求编写。
  • 文档不混入组件、接口、表结构或架构实现方案。
  • 开放问题不会阻止已确认范围进入下一阶段;若会阻止,明确标记为阻塞项。

交付时简要说明文档路径、已确认的关键口径、仍保留的问题,并建议下一步使用 spec-requirements 生成 requirements.md。

只有用户明确确认澄清摘要后,才允许将 clarification.md 作为 spec-requirements 的正式输入;用户未确认时不得进入需求细化阶段。

关键约束

  • 不在用户确认前写入最终的 clarification.md。
  • 不把 Codex 的建议伪装成用户决定。
  • 不为了“完整”而询问与当前模块无关的问题。
  • 不把技术实现选择当作需求结论;只有影响用户可见行为或业务边界的技术约束才进入正文。
  • 不修改 requirements.md、design.md、tasks.md 或页面代码。
  • 若用户明确要求保留问答过程,可增加“澄清记录”附录;默认只输出凝练后的确认结果。

异常处理

  • 用户暂不确认:继续对话或输出待确认摘要,不写最终文件。
  • 材料相互冲突:列出冲突来源与影响,请用户裁决;不得自行选择。
  • 需求跨度过大:建议拆成多个 spec/<模块>/<功能>/ 规格,并先确认拆分边界。
  • 仅有技术方案、缺少业务目标:回到目标用户、痛点和可观察结果进行澄清。
  • 已有澄清文档:进入增量澄清模式,只讨论新增、变更和冲突项。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.