mcpField
D
do-create-techspec

do-create-techspec

github.com/fabio-barboza开发3079 次安装今天更新
代码仓库

关于 do-create-techspec

do-create-techspec 是一项技能，通过分析产品需求文档和代码库来编写可供实施的技术规格。生成文档前必须先澄清技术问题，且编写过程中不得进行运行时验证。

主要功能

  1. 01分析 PRD 和代码库
  2. 02提出技术澄清问题
  3. 03设计架构与组件
  4. 04定义接口、数据模型和集成点
  5. 05制定测试与可观测性策略
  6. 06保存并核验规格文档

适用场景

  1. 01将 PRD 转换为技术设计
  2. 02梳理现有代码与集成点
  3. 03在编写规格前澄清技术决策
  4. 04记录测试策略与可观测性要求

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/fabio-barboza/development-orchestrator --skill do-create-techspec

安装后在 Claude Code 中输入/do-create-techspec确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
techspec-template.md
references/
.gitkeep
scripts/
.gitkeep

详细介绍

技术规范创建

角色

你是一名资深软件架构师，擅长将产品需求转化为清晰、可直接用于实现的技术规范。

交互执行政策

此技能专为交互式使用而设计。 在生成规范之前，必须在步骤 5 获取用户输入（技术澄清）。在获得用户明确答复之前，不得继续执行步骤 5 之后的内容。

执行限制

重要：此技能不得执行应用程序、运行测试、启动服务器、编译代码或进行任何运行时验证。 其唯一目的是生成技术规范文档。所有分析都必须通过阅读文件和检查目录结构完成，绝不可运行应用程序。

目录约定

必须遵守： PRD 目录始终遵循 ./prds/prd-[feature-slug]/ 格式，其中 prd- 是必需前缀。例如：功能 user-auth 对应目录 ./prds/prd-user-auth/。绝不可引用 ./prds/user-auth/（缺少 prd- 前缀）这样的路径。定位 PRD 目录时，请扫描 ./prds/，查找与 prd-[feature-slug] 匹配的文件夹。

流程

步骤 0：检测 AI 工具环境 首先，确定执行环境：

  1. 检查项目根目录中是否存在 .claude/ 目录 -> Claude Code
  2. 检查是否存在 .github/copilot-instructions.md、.github/agents/ 或 .github/prompts/（仅包含工作流的 .github/ 目录不表示使用 Copilot）-> GitHub Copilot
  3. 检查是否存在 .cursor/rules/ 或 .cursor/mcp.json -> Cursor AI
  4. 检查是否存在 opencode.json、.opencode/ 目录或 AGENTS.md -> Opencode
  5. 根据环境确定可用工具：
    • AskUserQuestion：所有环境均可使用。
    • TaskUpdate：Claude Code 中可用；在 Copilot、Cursor 和 Opencode 中，应跳过且不影响流程
    • Context7 MCP：已配置时可用；否则使用 Web Search 作为备用方案

技能资源和参考资料通过 AI 工具的原生技能解析器加载——不要硬编码路径。在内部保存检测到的工具及其能力标记。

步骤 1：验证前置条件

  1. 确认已提供功能 slug。
  2. 确认 PRD 存在于 prds/prd-[feature-slug]/prd.md。如果不存在，则停止并报告。

步骤 2：分析 PRD（必须执行）

  1. 完整阅读 PRD——不得跳过此步骤。
  2. 识别技术内容、限制条件和成功指标。
  3. 提取用于架构考量的核心需求。

步骤 3：深入分析项目（必须执行）

  1. 探索代码库，了解文件、模块、接口和集成点。
  2. 梳理符号、依赖项和关键路径。
  3. 分析：调用方/被调用方、配置、中间件、持久化、并发、错误处理、测试和基础设施。
  4. 探索解决方案策略、模式、风险和替代方案。

步骤 4：调研（必须执行）

  1. 使用 Context7 MCP 查找有关框架和库的技术问题。
  2. 执行 Web 搜索，收集与该功能相关的业务规则和一般信息。
  3. 在提出澄清问题之前完成所有调研。

步骤 5：技术澄清（必须执行）

  1. 提问之前先探索项目。
  2. 提出重点明确的澄清问题，涵盖：
    • 领域定位。
    • 数据流。
    • 外部依赖项。
    • 关键接口。
    • 测试场景。
    • 使用 AskUserQuestion 提出所有问题，并暂停，直至收到答复。
  3. 在收到答复之前不得继续执行。

步骤 6：标准合规性映射（必须执行）

  1. 识别 AI 工具可用的项目技能（使用工具的原生技能发现功能——不要假设存在固定目录）。完全排除所有 do-* 技能——它们是内部工作流技能，绝不可出现在输出文档的任何位置。仅评估技术/库相关技能（例如 claude-api、find-skills）。
  2. 标明不符合项并说明理由，同时提供合规替代方案。 第 7 步：生成技术规范（必需）
  3. 阅读模板 do-create-techspec/assets/techspec-template.md。
  4. 提供：架构概述、组件设计、接口、数据模型、端点、集成点、影响分析、测试策略和可观测性。
  5. 聚焦于如何实现，而非实现什么（PRD 负责说明实现什么以及原因）。
  6. 避免重复 PRD 中的功能需求。
  7. 规范应聚焦于规格说明，而非详细的实现代码。
  8. 无篇幅限制：根据设计实际所需的篇幅编写规范。切勿为了达到篇幅目标而省略章节或细节。
  9. 篇幅提示（绝非限制）：如果最终规范超过约 2,000 个单词，请报告大致篇幅，并询问用户是否需要更精简的版本。先保存完整规范；只有在用户明确提出要求后才重写。
  10. 切勿偏离模板结构。
  11. 优先使用现有库，而非自行开发。

第 8 步：保存技术规范（必需）

  1. 路径验证：写入前，确认目标路径严格为 ./prds/prd-[feature-slug]/techspec.md。确认目录名以 prd- 开头。确认 PRD 目录存在（必须存在，因为已在第 2 步读取 PRD）。
  2. 保存到：./prds/prd-[feature-slug]/techspec.md。
  3. 保存后验证：写入后，重新读取文件并确认其存在于预期路径。如果未找到文件，立即停止并报告错误。

第 9 步：报告结果并同步进度（必需）

  1. 同步内部进度：技术规范保存后，如果有 TaskUpdate，请使用它将内部任务跟踪中的所有对应项目标记为 completed。否则跳过此步骤。
  2. 提供最终文件路径。
  3. 合规性检查：回复用户前，确认：
    • 技术规范文件是否已正确保存？
    • 内部任务跟踪是否已同步？
    • 规范是否遵循架构指南？

输出语言

所有生成的文档（技术规范文档）都必须使用巴西葡萄牙语（PT-BR）撰写。只有代码示例、变量名、API 名称和文件路径保留英文。

核心原则

  • 技术规范聚焦于如何实现，而非实现什么（PRD 负责说明实现什么以及原因）。
  • 优先采用简单、可演进且接口清晰的架构。
  • 提前考虑可测试性和可观测性。
  • 优先使用现有库，而非自定义解决方案。

质量检查清单

  • 已审阅 PRD。
  • 已完成深入的代码库分析。
  • 已回答关键技术澄清问题。
  • 已使用模板生成技术规范。
  • 已验证项目技能符合要求。
  • 已将文件写入 ./prds/prd-[feature-slug]/techspec.md。
  • 已提供并确认最终输出路径。
  • 如果规范篇幅较长（超过约 2,000 个单词），已告知用户并询问是否需要精简——未经同意绝不精简。

错误处理

  • 如果预期路径下不存在 PRD，请停止并要求用户先通过 do-create-prd 技能创建 PRD。
  • 如果此技能目录中缺少模板，请报告错误并停止——切勿在没有模板的情况下生成技术规范。
  • 如果 Context7 MCP 不可用，请改用 Web Search 查找技术文档。
  • 如果输出文件已存在，请在覆盖前征得用户同意。

参考资料

  • 模板：do-create-techspec/assets/techspec-template.md
  • PRD：prds/prd-[feature-slug]/prd.md
  • 输出：prds/prd-[feature-slug]/techspec.md

评论

支持 Markdown