mcpField
R
recipe-reverse-engineer

recipe-reverse-engineer

github.com/shinpr文档处理70538 次安装6 天前更新
代码仓库

关于 recipe-reverse-engineer

recipe-reverse-engineer 是一项用于从现有代码库反向生成文档的 Skill，涵盖范围发现、PRD 编写、验证、审查与修订，也可按需生成设计文档。

主要功能

  1. 01代码范围发现
  2. 02按功能单元生成 PRD
  3. 03可选生成设计文档
  4. 04代码验证与文档审查
  5. 05按需修订流程

适用场景

  1. 01将现有功能整理为 PRD
  2. 02把代码单元映射到文档目标
  3. 03依据实现审查文档

安装

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

$npx skills add https://github.com/shinpr/claude-code-workflows --skill recipe-reverse-engineer

安装后在 Claude Code 中输入/recipe-reverse-engineer确认已加载。

详细介绍

明确的用户指令：用户明确指示并授权执行此配方中提及的每次子 Agent 调用。满足前置条件时，执行每次适用的调用。

在编写 Agent 提示词、交接内容或生成的产物之前，执行 Skill：llm-friendly-context。 在决定工作流、调用 Agent 或处理审查发现之前，执行 Skill：subagents-orchestration-guide。

上下文：从现有代码逆向工程并创建文档的工作流

目标：$ARGUMENTS

编排器定义

核心身份：“我是一个编排器。”

本地权限门槛：制定此配方的工作流决策，并直接验证每项返回结果；将语义交付物的制作委派给指定的专家。

审查问题处理门槛［强制］：在修正或继续之前，必须通过 subagents-orchestration-guide 中的 Review Resolution 处理每一项可操作的交付物审查发现。 在处理第一项审查发现之前，先阅读已加载的 subagents-orchestration-guide 技能中的 references/review-resolution.md。

执行协议：

  1. 调用指定的专家制作交付物——在他们之间传递交付物路径，并验证其结果（参见 subagents-orchestration-guide 的“Orchestrator Execution Boundary”）
  2. 每次只处理一个步骤：在每个单元内按顺序执行步骤（2 → 3 → 4 → 5）。每个步骤的输出都是下一步的必要输入。完成一个单元的所有步骤后，再开始下一个单元
  3. 在衔接输出时保留证据——按照下一位专家声明的格式，复制其所需字段；路由任何修正之前，先应用 Review Resolution

在以下每次 Agent 调用时，按机械式提取构建提示词：将指定源值复制到确切字段，仅应用声明的序列化方式，然后立即调用。

执行门槛：完成阶段 1 后才能开始阶段 2。在每个阶段内，开始下一个单元前，必须先使当前单元的生成、验证、审查和必要修订收敛。只有满足当前步骤规定的输出和质量门槛，才能继续。在每个循环边界，选择当前阶段声明顺序中第一个尚未满足单元完成条件且未记录为生成失败的单元。文档路径只能证明文档已生成。

步骤 0：初始配置

0.1 范围确认

使用 AskUserQuestion 确认：

  1. 目标路径：要编写文档的目录／模块
  2. 深度：仅 PRD，还是 PRD + 设计文档
  3. 参考架构：分层 / MVC / Clean / 六边形 / 无
  4. 人工审查：是（推荐）/ 否（完全自主）
  5. 全栈设计：是 / 否
    • 是：为每个功能单元生成后端 + 前端设计文档
    • 注意：需要同时调用两个 Agent（technical-designer、technical-designer-frontend）
0.2 输出配置
  • PRD 输出：docs/prd/ 或现有 PRD 目录
  • 设计文档输出：docs/design/ 或现有设计目录
  • 验证目录是否存在，如有需要则创建

工作流概览

Phase 1: PRD Generation
  Step 1: Scope Discovery (unified, single pass → group into PRD units → human review)
  Step 2-5: Per-unit loop (Generation → Verification → Review → Revision)

Phase 2: Design Doc Generation (if requested)
  Step 6: Design Doc Scope Mapping (reuse Step 1 results, no re-discovery)
  Step 7-10: Per-unit loop (Generation → Verification → Review → Revision)
  ※ fullstack=Yes: each unit produces backend + frontend Design Docs

阶段 1：PRD 生成

第 1 步：PRD 范围发现

Agent 工具调用：

subagent_type: dev-workflows:scope-discoverer
description: "Discover functional scope"
prompt: |
  Discover functional scope targets in the codebase.

  target_path: $USER_TARGET_PATH
  reference_architecture: $USER_RA_CHOICE
  focus_area: [user-confirmed focus area verbatim, if specified]

将输出存储为：$STEP_1_OUTPUT

质量关卡：

  • 至少发现一个单元 → 继续
  • 未发现单元 → 向用户询问提示
  • $STEP_1_OUTPUT.prdUnits 存在
  • prdUnits 中所有 sourceUnits（扁平化并去重后）均与 discoveredUnits ID 集合相符——没有遗漏或重复单元
  • 每个已发现单元的 unitInventory 至少有一个非空类别（routes、testFiles 或 publicExports）。三项均为空表示发现不完整——重新运行 scope-discoverer，并聚焦于该单元的 relatedFiles

人工审核点（若启用）：展示 $STEP_1_OUTPUT.prdUnits 及其源单元映射。用户确认、调整分组，或将单元排除在范围之外。这是最重要的审核点——分组错误会影响所有后续文档。

第 2–5 步：逐单元处理

对 $STEP_1_OUTPUT.prdUnits 中的每个单元执行（按顺序，每次处理一个单元）：

第 2 步：生成 PRD

Agent 工具调用：

subagent_type: dev-workflows:prd-creator
description: "Generate PRD"
prompt: |
  Create reverse-engineered PRD for the following feature.

  Operation Mode: reverse-engineer
  External Scope Provided: true

  Feature: $PRD_UNIT_NAME (current Step 1 PRD unit name unchanged)
  Description: $PRD_UNIT_DESCRIPTION (current Step 1 PRD unit description unchanged)
  Related Files: $PRD_UNIT_COMBINED_RELATED_FILES
  Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS

  Use provided scope as investigation starting point.
  If tracing entry points reveals files outside this scope, include them.
  Create final version PRD based on thorough code investigation.

将输出存储为：$STEP_2_OUTPUT（PRD 路径）

第 3 步：代码验证

前置条件：$STEP_2_OUTPUT（第 2 步生成的 PRD 路径）

Agent 工具调用：

subagent_type: dev-workflows:code-verifier
description: "Verify PRD consistency"
prompt: |
  Verify consistency between PRD and code implementation.

  doc_type: prd
  document_path: $STEP_2_OUTPUT
  unit_inventory: [the current unit's Step 1 unitInventory]

unit_inventory 提供完整性基线，而仓库证据则提供搜索范围。

将输出存储为：$STEP_3_OUTPUT

质量关卡：

  • summary.status 为 blocked、库存覆盖缺失，或数量不平衡 → 使用确切的不可用输入或证据重新运行或升级处理
  • 任何数量平衡且未被阻止的结果 → 使用完整的验证器输出继续审核；needs_review / inconsistent 以及任何未核算项均作为明确的审核证据
第 4 步：审核

必需输入：$STEP_3_OUTPUT（第 3 步生成的验证 JSON）

Agent 工具调用：

subagent_type: dev-workflows:document-reviewer
description: "Review PRD"
prompt: |
  Review the following PRD considering code verification findings.

  doc_type: PRD
  target: $STEP_2_OUTPUT
  review_context: reverse-engineer
  verification_evidence: $STEP_3_OUTPUT

将输出存储为：$STEP_4_OUTPUT

第 5 步：修订（有条件）

将 $STEP_3_OUTPUT 作为验证证据传递给 document-reviewer，然后对 $STEP_4_OUTPUT 应用审核决策关卡。仅当至少有一条发现标记为 apply 时才运行修订；仅包含拒绝项的结果表示审核完成。

Agent 工具调用：

subagent_type: dev-workflows:prd-creator
description: "Revise PRD"
prompt: |
  Update PRD based on review feedback and code verification results.

  Operation Mode: update
  Existing PRD: $STEP_2_OUTPUT

  ## Adjudicated Findings
  [complete reviewer finding objects verbatim, with only their orchestrator dispositions added]

  Treat these findings as the complete revision scope and preserve adjacent content.

重新验证：每次修订后，使用原始 unit_inventory 对修订后的文档重新运行 code-verifier，然后使用最新的 verification_evidence 和 prior_feedback 重新运行 document-reviewer。

单元完成
  • 不再有标记为 apply 的发现
  • 人工审核通过（若在第 0 步启用）

下一步：继续处理下一个单元。所有单元处理完毕后 → 进入第 2 阶段。

第 2 阶段：生成设计文档

仅当在第 0 步请求了设计文档时执行

第 6 步：设计文档范围映射

无需额外发现。 使用 $STEP_1_OUTPUT.discoveredUnits（实现粒度的单元）生成技术档案。使用 $STEP_1_OUTPUT.prdUnits[].sourceUnits 追踪每个 PRD 单元包含哪些已发现单元。

第 1 阶段的每个 PRD 单元都映射到一个或多个设计文档单元：

  • 标准模式（fullstack=No）：1 个 PRD 单元 → 1 份设计文档（使用 technical-designer）
  • 全栈模式（fullstack=Yes）：1 个 PRD 单元 → 2 份设计文档（使用 technical-designer + technical-designer-frontend）

将 $STEP_1_OUTPUT 单元映射到设计文档生成目标，并沿用以下信息：

  • technicalProfile.primaryModules → 主要文件
  • technicalProfile.publicInterfaces → 公共接口
  • dependencies → 依赖项
  • relatedFiles → 范围边界
  • unitInventory → 单元清单（路由、测试文件、公共导出）

在全栈模式下，按所属路径将每个单元清单划分为后端和前端目标清单。将共享条目分配给其公共契约必须涵盖该条目的每份设计文档，并记录共享原因；否则仅分配一次。第 7 步和第 8 步的每次调用都接收其目标清单，而不是未经划分的合并单元。

将输出存储为：$STEP_6_OUTPUT

步骤 7-10：逐单元处理

对 $STEP_6_OUTPUT 中的每个单元（依次处理，每次一个单元）：

步骤 7：生成设计文档

范围：严格记录代码中实际实现的当前架构。

标准模式（fullstack=No）：

Agent 工具调用：

subagent_type: dev-workflows:technical-designer
description: "Generate Design Doc"
prompt: |
  Create Design Doc for the following feature based on existing code.

  Operation Mode: reverse-engineer

  Feature: $UNIT_NAME (current Step 6 target name unchanged)
  Description: $UNIT_DESCRIPTION (current Step 6 target description unchanged)
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $DESIGN_DOC_UNIT_INVENTORY

  Parent PRD: $APPROVED_PRD_PATH

  Document current architecture as-is. Use Unit Inventory as a completeness baseline — all routes and exports should be accounted for in the Design Doc.

将输出存储为：$STEP_7_OUTPUT

全栈模式（fullstack=Yes）：

对每个单元，依次调用 7a 和 7b（7b 依赖 7a 的输出）：

7a. 后端设计文档：

subagent_type: dev-workflows:technical-designer
description: "Generate backend Design Doc"
prompt: |
  Create a backend Design Doc for the following feature based on existing code.

  Operation Mode: reverse-engineer

  Feature: $UNIT_NAME (current Step 6 target name unchanged)
  Description: $UNIT_DESCRIPTION (current Step 6 target description unchanged)
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $BACKEND_UNIT_INVENTORY

  Parent PRD: $APPROVED_PRD_PATH

  Focus on: API contracts, data layer, business logic, service architecture.
  Document current architecture as-is. Use Unit Inventory as completeness baseline.

将输出存储为：$STEP_7a_OUTPUT

7b. 前端设计文档：

subagent_type: dev-workflows-frontend:technical-designer-frontend
description: "Generate frontend Design Doc"
prompt: |
  Create a frontend Design Doc for the following feature based on existing code.

  Operation Mode: reverse-engineer

  Feature: $UNIT_NAME (current Step 6 target name unchanged)
  Description: $UNIT_DESCRIPTION (current Step 6 target description unchanged)
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $FRONTEND_UNIT_INVENTORY

  Parent PRD: $APPROVED_PRD_PATH
  Backend Design Doc: $STEP_7a_OUTPUT

  Reference backend Design Doc for API contracts.
  Focus on: component hierarchy, state management, UI interactions, data fetching.
  Document current architecture as-is. Use Unit Inventory as completeness baseline.

将输出存储为：$STEP_7b_OUTPUT

步骤 8：代码验证

标准模式：验证 $STEP_7_OUTPUT。

全栈模式：分别验证每份设计文档。

Agent 工具调用（每份设计文档）：

subagent_type: dev-workflows:code-verifier
description: "Verify Design Doc consistency"
prompt: |
  Verify consistency between Design Doc and code implementation.

  doc_type: design-doc
  document_path: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT)
  unit_inventory: [the current Design Doc target's Step 6 unitInventory]

将输出存储为：$STEP_8_OUTPUT

验证门槛（每份设计文档）：

  • 如果结果为 blocked、缺少 inventoryCoverage，或类别计数不平衡 → 修正调用/输入并重新运行；只有在仓库证据无法解决输入缺陷时，才停止并交由用户处理。
  • 任何计数平衡且非阻塞的结果都进入文档审查。将 needs_review、inconsistent 以及所有未核算项作为明确的验证器证据一并传递。
步骤 9：审查

必需输入：$STEP_8_OUTPUT（步骤 8 的验证 JSON）

Agent 工具调用（每份设计文档）：

subagent_type: dev-workflows:document-reviewer
description: "Review Design Doc"
prompt: |
  Review the following Design Doc considering code verification findings.

  doc_type: DesignDoc
  target: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT)
  review_context: reverse-engineer
  verification_evidence: $STEP_8_OUTPUT

  ## Parent PRD
  $APPROVED_PRD_PATH

  ## Additional Review Focus
  - Technical accuracy of documented interfaces
  - Consistency with parent PRD scope
  - Completeness of unit boundary definitions

将输出存储为：$STEP_9_OUTPUT

步骤 10：修订（有条件）

将 $STEP_8_OUTPUT 作为验证证据传递给文档审查器，然后对 $STEP_9_OUTPUT 应用审查决议门槛。仅当至少有一项发现标记为 apply 时才进行修订；如果结果中只有拒绝项，则审查完成。

Agent 工具调用（每份设计文档）：

subagent_type: dev-workflows:technical-designer (or dev-workflows-frontend:technical-designer-frontend for frontend Design Docs)
description: "Revise Design Doc"
prompt: |
  Update Design Doc based on review feedback and code verification results.

  Operation Mode: update
  Existing Design Doc: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT)

  ## Adjudicated Findings
  [complete reviewer finding objects verbatim, with only their orchestrator dispositions added]

  Treat these findings as the complete revision scope and preserve adjacent content.

重新验证：每次修订后，使用原始 unit_inventory 对修订后的文档重新运行代码验证器，然后使用最新的 verification_evidence 和 prior_feedback 重新运行文档审查器。

单元完成
  • 不再有标记为 apply 的发现
  • 人工审查已通过（如果在步骤 0 中启用）

下一步：继续处理下一个单元。所有单元处理完毕后 → 最终报告。

最终报告

输出摘要，包括：

  • 生成的文档表格（类型、名称、验证状态、审查状态）
  • 待处理事项（未记录的功能、标记的项目）
  • 如有被拒绝的可执行发现，列出其 ID、适用的理由和证据
  • 后续步骤检查清单

错误处理

错误操作
未发现任何内容请用户提供项目结构提示
生成失败记录失败，继续处理其他单元，并在摘要中报告
验证结果为 inconsistent，或修正后仍有未核算的清单项标记为必须进行人工审查——要求明确的人工批准

评论

支持 Markdown