用途 该技能用于处理这样一种工作区:其中已有真实源代码,但没有任何规格(specs)文档。目标是反向推导出项目本应拥有的规格图。它通常经由 setting-up-a-project 流程进入。
主要能力
- 先读后问:按大致顺序阅读代理文件(AGENTS.md、CLAUDE.md、.cursor/rules/*、.cursorrules、.github/copilot-instructions.md、GEMINI.md、.windsurfrules)、文档(README、docs/、CONTRIBUTING、ADR)、清单与布局(package.json、pyproject.toml、go.mod、Cargo.toml、工作区 globs、目录结构、入口点、构建/测试脚本)以及代码(入口点和候选模块顶部),以了解职责和模块间依赖关系。
- 识别可采纳文档候选:持久的、声明式的、陈述现状的文档,例如架构/设计文档、ADR/决策记录、领域词汇表、协议/契约文档;README、CONTRIBUTING、变更日志、路线图、TODO、实现计划、生成的 API 文档仅作输入,不作为候选。
- 用 spec_grep / spec_graph 确认尚无规格图;若已存在规格,则停止并交回 setting-up-a-project 调度流程。
- 构建工作模型:用一句话描述目的,说明领域、技术栈、真实模块边界与依赖边、代码已强制的约束(分层、“X 从不导入 Y”、公共界面)以及代码中可见的非显而易见的决策。该模型仅保存在对话中,不写入文件。
- 仅就缺口进行访谈:只问文件无法回答且会改变规格的问题,例如主要用途/目标用户、明确的非目标、非显而易见决策的原因;以推断出具体答案让用户纠正的方式提问,而非开放式提问。还会通过多选确认已知限制,并询问哪些采纳候选应成为规格图节点。若文件已回答所有实质内容则跳过访谈。
- 自上而下草拟规格图:先创建 goal-and-requirements.md(类型 goal-and-requirements,作为图根),再创建 architecture.md(类型 architecture-design,父级为 goal id),然后为每个真实模块创建简短的 SPEC.md(类型 module-design,包内目录级模块用 submodule-design),说明职责与边界(允许的依赖/禁止的引用)。采纳的文档就地转为节点:为文件添加规格 frontmatter(id、type、title、status: draft、parent、必要时 depends-on/references),内容不动;若采纳文档不清晰或与代码漂移,则一并更正并说明。parent 关系镜像代码层级,depends-on 仅用于代码实际显示的边。
- 校验与交接:运行 spec_validate 修复悬挂链接、重复 id、父级循环;告知用户规格已草拟在工作区分支上,需在 Changes 中审阅,未经批准不会合并,并总结推断与确认的内容、采纳与仅作输入的文档以及所做的漂移更正。
使用方式 该流程由代理技能触发,按上述步骤执行;它不声明工作文件,工作模型保留在对话中。后续功能、行为变更和缺陷修复进入 brainstorming 流程;不改变行为的工作直接进行。此工作流到此结束。
适用场景 已有源代码但缺少规格文档的代码库,希望在开始新功能或修改前补建规格图的项目;包含真实规格类文档的仓库也可围绕这些文档构建,而非另起一套。
限制 资料未提供该技能的具体实现方式、依赖工具版本、收费信息或平台限制。该流程仅适用于尚无规格图的仓库;若已存在规格,应停止并交由 setting-up-a-project 处理。所有内容均为推断而非确认,草稿需用户审阅,未确认项在规格中内联标记。