reverse-engineer

逆向工程（路由感知）

逆向工程到规范驱动开发流程的第 2 步，共 6 步。 6 步流程：1. 分析，2. 逆向工程（此技能），3. 创建规范，4. 差距分析，5. 实施规划，6. 实施。

**预计时间：**30-45 分钟 **前置条件：**已完成第 1 步（analysis-report.md 和 .stackshift-state.json 中的路由选择） 输出：docs/reverse-engineering/ 中的 11 个文档文件

因路由而异的行为：

• **Greenfield：**仅提取业务逻辑（与框架无关）
• **Brownfield：**提取业务逻辑 + 技术实现细节

无论使用哪种实现框架（Spec Kit、BMAD 还是 BMAD Auto-Pilot），输出都相同。框架选择只会影响第 2 步之后的内容。

---

配置检查

守卫：继续之前，验证状态文件是否存在。

if [ ! -f .stackshift-state.json ]; then
  echo "ERROR: .stackshift-state.json not found."
  echo "Step 1 (Initial Analysis) must be completed first. Run /stackshift.analyze to begin."
  exit 1
fi

DETECTION_TYPE=$(cat .stackshift-state.json | jq -r '.detection_type')
ROUTE=$(cat .stackshift-state.json | jq -r '.route')

if [ "$DETECTION_TYPE" = "null" ] || [ -z "$DETECTION_TYPE" ]; then
  echo "ERROR: detection_type missing from state file. Re-run /stackshift.analyze."
  exit 1
fi
if [ "$ROUTE" = "null" ] || [ -z "$ROUTE" ]; then
  echo "ERROR: route missing from state file. Re-run /stackshift.analyze."
  exit 1
fi

echo "Detection: $DETECTION_TYPE"
echo "Route: $ROUTE"

SPEC_OUTPUT=$(cat .stackshift-state.json | jq -r '.config.spec_output_location // "."')
echo "Writing specs to: $SPEC_OUTPUT"

if [ "$SPEC_OUTPUT" != "." ]; then
  mkdir -p "$SPEC_OUTPUT/docs/reverse-engineering"
  mkdir -p "$SPEC_OUTPUT/.specify/memory/specifications"
fi

状态文件结构：

{
  "detection_type": "monorepo-service",
  "route": "greenfield",
  "implementation_framework": "speckit",
  "config": {
    "spec_output_location": "~/git/my-new-app",
    "build_location": "~/git/my-new-app",
    "target_stack": "Next.js 15..."
  }
}

捕获提交哈希以进行增量更新：

COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
COMMIT_DATE=$(git log -1 --format=%ci 2>/dev/null || date -u +"%Y-%m-%d %H:%M:%S")
echo "Pinning docs to commit: $COMMIT_HASH"

根据检测结果 + 路由选择提取方式：

检测类型	+ Greenfield	+ Brownfield
Monorepo 服务	仅业务逻辑（与技术无关）	完整实现 + 共享包（技术规范性）
Nx 应用	仅业务逻辑（与框架无关）	完整的 Nx/Angular 实现细节
通用应用	仅业务逻辑	完整实现

• detection_type 决定要查找哪些模式（共享包、Nx 项目配置、monorepo 结构等）
• route 决定如何记录这些内容（与技术无关或技术规范性）

---

阶段 1：深入分析代码库

使用 subagent_type=stackshift:stackshift-code-analyzer:AGENT 的 Task 工具执行分析。如果该 Agent 不可用，则改用 Explore Agent。

**错误恢复：**如果子 Agent 失败，或某个子阶段返回空结果，则使用 Explore Agent 重试一次。如果重试仍失败，则使用 [ANALYSIS INCOMPLETE] 标记记录该缺漏，并继续执行剩余子阶段。

**缺少的组件：**如果某个子阶段未发现相关代码（例如，纯后端服务中没有前端），则在对应的输出文件中记录该组件不存在，而不是跳过该子阶段。

使用单独的子 Agent 调用并行启动子阶段 1.1 至 1.6。收集所有结果后再进入阶段 2。

1.1 后端分析

• 查找所有 API 端点，并记录其方法、路由、身份验证要求、参数和用途。
• 编目所有数据模型，包括架构、类型、接口和字段定义。
• 清点所有配置来源：环境变量、配置文件和设置。
• 梳理所有外部集成：API、服务和数据库。
• 从服务、工具函数和算法中提取业务逻辑。

1.2 前端分析

• 列出所有页面和路由，并说明其用途和身份验证要求。
• 按类别编目所有组件：布局、表单和 UI 组件。
• 记录状态管理：存储结构和全局状态模式。
• 梳理 API 客户端层：前端如何调用后端。
• 提取样式模式：设计系统、主题和组件样式。

1.3 基础设施分析

• 记录部署配置：IaC 工具、云服务提供商和服务。
• 梳理 CI/CD 流水线和工作流。
• 编目数据库设置：类型、架构和迁移。
• 识别存储系统：对象存储、文件系统和缓存。

1.4 测试分析

• 定位所有测试文件，并识别所使用的测试框架。
• 按类型分类测试：单元测试、集成测试和 E2E 测试。
• 按模块估算覆盖率百分比。
• 编目测试数据：模拟对象、测试固件和种子数据。

1.5 业务背景分析

• 阅读 README、CONTRIBUTING 以及任何营销页面或落地页。
• 提取软件包描述和仓库元数据。
• 识别表明面向用户功能的注释模式。
• 收集错误消息和面向用户的字符串，以推断用户画像。
• 分析命名惯例，揭示领域概念。
• 检查 git 历史，追溯决策缘由。

1.6 决策溯源

• 检查依赖清单（package.json、go.mod、requirements.txt），了解技术选型。
• 分析配置文件（tsconfig、eslint、prettier），了解设计理念。
• 查看 CI/CD 配置，了解部署决策。
• 对关键架构文件运行 git blame，找出决策节点。
• 收集包含“why”解释的注释（TODO、HACK、FIXME、NOTE）。
• 查找 git 历史或注释中体现的被否决方案。

进度信号： 所有子阶段完成后，记录：“Phase 1 complete: Analysis gathered for [list which sub-phases produced results].”

---

第 2 阶段：生成文档

创建 docs/reverse-engineering/ 目录并生成全部 11 个文档文件。每个文件都按照 operations/output-file-specs.md 中的说明，采用绿地或棕地项目对应的变体。现在阅读该文件，了解每个文件的详细规范。

如果 .stackshift-docs-meta.json 已存在，请用新的元数据将其完整覆盖。

步骤 2.1：首先写入元数据文件

COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
COMMIT_DATE=$(git log -1 --format=%ci 2>/dev/null || date -u +"%Y-%m-%d %H:%M:%S")
GENERATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

写入 docs/reverse-engineering/.stackshift-docs-meta.json：

{
  "commit_hash": "<COMMIT_HASH>",
  "commit_date": "<COMMIT_DATE>",
  "generated_at": "<GENERATED_AT>",
  "doc_count": 11,
  "route": "<greenfield|brownfield>",
  "docs": {
    "functional-specification.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "integration-points.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "configuration-reference.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "data-architecture.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "operations-guide.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "technical-debt-analysis.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "observability-requirements.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "visual-design-system.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "test-documentation.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "business-context.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "decision-rationale.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" }
  }
}

步骤 2.2：为每个文档添加元数据头

每个生成的文档都要在标题后添加以下头部：

# [Document Title]

> **Generated by StackShift** | Commit: `<short-hash>` | Date: `<GENERATED_AT>`
> Run `/stackshift.refresh-docs` to update with latest changes.

步骤 2.3：分批生成文件并设置检查点

按以下顺序生成文件，每生成一个文件后记录进度：

第 1 批（核心架构）：

1. functional-specification.md
2. data-architecture.md
3. integration-points.md
4. configuration-reference.md

写完文件 1-4 后，记录：“Generated 4/11 files (core architecture complete).” 继续之前，请确认输出目录中有 4 个文件。

第 2 批（运维与质量）： 5. operations-guide.md 6. technical-debt-analysis.md 7. observability-requirements.md 8. visual-design-system.md 9. test-documentation.md

写完文件 5-9 后，记录：“Generated 9/11 files (operations and quality complete).” 继续之前，请确认输出目录中有 9 个文件。

第 3 批（背景与决策）： 10. business-context.md 11. decision-rationale.md

写完文件 10-11 后，记录：“Generated 11/11 files. Phase 2 complete.”

输出结构：

docs/reverse-engineering/
├── .stackshift-docs-meta.json
├── functional-specification.md
├── integration-points.md
├── configuration-reference.md
├── data-architecture.md
├── operations-guide.md
├── technical-debt-analysis.md
├── observability-requirements.md
├── visual-design-system.md
├── test-documentation.md
├── business-context.md
└── decision-rationale.md

---

成功标准

• 在 docs/reverse-engineering/ 中生成全部 11 个文档文件
• 全面覆盖应用程序的各个方面
• 与框架无关的功能规范（适用于绿地项目）
• 完整的数据模型文档
• 清晰记录业务背景，并使用 [INFERRED] / [NEEDS USER INPUT] 标记
• 使用 ADR 格式记录决策理由
• 通过数据流图完整映射集成点
• 创建 .stackshift-docs-meta.json，其中包含用于增量更新的提交哈希
• 每个文档都包含元数据头，其中有提交哈希和生成日期

---

后续步骤

生成所有文档后：

对于 GitHub Spec Kit（implementation_framework: speckit）： 继续执行第 3 步——使用 /stackshift.create-specs 将文档转换为 .specify/ 规范。

对于 BMAD Method（implementation_framework: bmad）： 继续执行第 6 步——移交给 BMAD 的 *workflow-init。BMAD 的 PM 和 Architect Agent 会将逆向工程文档用作上下文。

对于 BMAD Auto-Pilot（implementation_framework: bmad-autopilot）： 继续执行 /stackshift.bmad-synthesize，自动生成 BMAD 构件。11 份逆向工程文档涵盖了 BMAD 所需内容的约 90%。

---

应做 / 不应做

应做：

• 描述系统做什么，而不是如何实现（尤其是从零开始的项目）
• 利用所有可用线索进行推断：README、注释、命名、配置、Git 历史
• 标明置信度：不加标记 = 有把握，[INFERRED] = 合理推断，[NEEDS USER INPUT] = 确实未知
• 在文档之间交叉引用（例如，技术债务会影响权衡取舍）
• 为每项推断引用具体证据

不应做：

• 在功能规格中硬编码框架名称（从零开始的项目）
• 将业务逻辑与技术实现混为一谈（从零开始的项目）
• 在没有证据支持的情况下编造业务目标
• 不加标记就将推断说成事实
• 因某个章节需要推断就跳过它——应尝试撰写并标明置信度

---

完整性检查清单

确认分析已涵盖：

• 所有 API 端点（不只是显而易见的端点）
• 所有数据模型（包括 DTO、类型、接口）
• 所有配置选项（检查多个文件）
• 所有外部集成
• 所有面向用户的字符串和错误消息（用于推断角色和上下文）
• 所有配置文件（用于推断决策依据）

每份文档都必须全面、准确、条理清晰、可执行，并如实说明哪些信息是推断得出的，哪些已得到验证。