reverse-engineer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reverse Engineer (Path-Aware)

逆向工程（路径感知型）

Step 2 of 6 in the Reverse Engineering to Spec-Driven Development process.

Estimated Time: 30-45 minutes Prerequisites: Step 1 completed (

analysis-report.md

and path selection) Output: 9 comprehensive documentation files in

docs/reverse-engineering/

Path-Dependent Behavior:

Greenfield: Extract business logic only (framework-agnostic)
Brownfield: Extract business logic + technical implementation details

逆向工程到规范驱动开发流程中的第2步（共6步）

预计耗时： 30-45分钟 前置条件： 已完成第1步（生成

analysis-report.md

并选择路径） 输出结果： 在

docs/reverse-engineering/

目录下生成9份全面的文档文件

路径相关行为：

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

When to Use This Skill

何时使用此技能

Use this skill when:

You've completed Step 1 (Initial Analysis) with path selection
Ready to extract comprehensive documentation from code
Path has been chosen (greenfield or brownfield)
Preparing to create formal specifications

Trigger Phrases:

"Reverse engineer the codebase"
"Generate comprehensive documentation"
"Extract business logic" (greenfield)
"Document the full implementation" (brownfield)

在以下场景使用此技能：

已完成第1步（初始分析）并选择了路径
准备从代码中提取全面的文档
已选择路径（greenfield或brownfield）
准备创建正式规范

触发短语：

"对代码库进行逆向工程"
"生成全面的文档"
"提取业务逻辑"（greenfield路径）
"记录完整实现细节"（brownfield路径）

What This Skill Does

此技能的作用

This skill performs deep codebase analysis and generates 9 comprehensive documentation files.

Content adapts based on your path:

该技能执行深度代码库分析，并生成9份全面的文档文件。

内容会根据你选择的路径进行适配：

Path A: Greenfield (Business Logic Only)

路径A：Greenfield（仅业务逻辑）

Focus on WHAT the system does
Avoid framework/technology specifics
Extract user stories, business rules, workflows
Framework-agnostic functional requirements
Can be implemented in any tech stack

聚焦于系统的功能（WHAT）
避免框架/技术细节
提取用户故事、业务规则、工作流
与框架无关的功能需求
可在任何技术栈中实现

Path B: Brownfield (Business Logic + Technical)

路径B：Brownfield（业务逻辑+技术实现）

Focus on WHAT and HOW
Document exact frameworks, libraries, versions
Extract file paths, configurations, schemas
Prescriptive technical requirements
Enables
```
/speckit.analyze
```
validation

9 Documentation Files Generated:

functional-specification.md - Business logic, requirements, user stories (+ tech details for brownfield)
integration-points.md - External services, APIs, dependencies, data flows (single source of truth)
configuration-reference.md - Config options (business-level for greenfield, all details for brownfield)
data-architecture.md - Data models, API contracts (abstract for greenfield, schemas for brownfield)
operations-guide.md - Operational needs (requirements for greenfield, current setup for brownfield)
technical-debt-analysis.md - Issues and improvements
observability-requirements.md - Monitoring needs (goals for greenfield, current state for brownfield)
visual-design-system.md - UI/UX patterns (requirements for greenfield, implementation for brownfield)
test-documentation.md - Testing requirements (targets for greenfield, current state for brownfield)

聚焦于系统的功能与实现方式（WHAT和HOW）
记录确切的框架、库、版本
提取文件路径、配置、模式
指定技术要求
支持
```
/speckit.analyze
```
验证

生成的9份文档文件：

functional-specification.md - 业务逻辑、需求、用户故事（Brownfield路径包含技术细节）
integration-points.md - 外部服务、API、依赖项、数据流（唯一可信来源）
configuration-reference.md - 配置选项（Greenfield路径为业务层面，Brownfield路径为全部细节）
data-architecture.md - 数据模型、API契约（Greenfield路径为抽象内容，Brownfield路径为具体模式）
operations-guide.md - 运维需求（Greenfield路径为需求，Brownfield路径为当前设置）
technical-debt-analysis.md - 问题与改进方向
observability-requirements.md - 监控需求（Greenfield路径为目标，Brownfield路径为当前状态）
visual-design-system.md - UI/UX模式（Greenfield路径为需求，Brownfield路径为实现细节）
test-documentation.md - 测试需求（Greenfield路径为目标，Brownfield路径为当前状态）

Configuration Check (FIRST STEP!)

配置检查（第一步！）

Load state file to check detection type and route:

bash

undefined

加载状态文件以检查检测类型和路径：

bash

undefined

Check what kind of application we're analyzing

DETECTION_TYPE=$(cat .stackshift-state.json | jq -r '.detection_type // .path') echo "Detection: $DETECTION_TYPE"

Check extraction approach

ROUTE=$(cat .stackshift-state.json | jq -r '.route // .path') echo "Route: $ROUTE"

Check spec output location (Greenfield only)

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

Create output directories if needed

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


**State file structure (new):**
```json
{
  "detection_type": "monorepo-service",  // What kind of app
  "route": "greenfield",                  // How to spec it
  "config": {
    "spec_output_location": "~/git/my-new-app",
    "build_location": "~/git/my-new-app",
    "target_stack": "Next.js 15..."
  }
}

File write locations:

Route	Spec Output	Where Files Go
Greenfield	Custom location	`{spec_output_location}/docs/` , `{spec_output_location}/.specify/`
Greenfield	Not set (default)	`./docs/reverse-engineering/` , `./.specify/` (current repo)
Brownfield	Always current repo	`./docs/reverse-engineering/` , `./.specify/`

Extraction approach based on detection + route:

Detection Type	+ Greenfield	+ Brownfield
Monorepo Service	Business logic only (tech-agnostic)	Full implementation + shared packages (tech-prescriptive)
Nx App	Business logic only (framework-agnostic)	Full Nx/Angular implementation details
Generic App	Business logic only	Full implementation

How it works:

```
detection_type
```
determines WHAT patterns to look for (shared packages, Nx project config, monorepo structure, etc.)
```
route
```
determines HOW to document them (tech-agnostic vs tech-prescriptive)

Examples:

Monorepo Service + Greenfield → Extract what the service does (not React/Express specifics)
Monorepo Service + Brownfield → Extract full Express routes, React components, shared utilities
Nx App + Greenfield → Extract business logic (not Angular specifics)
Nx App + Brownfield → Extract full Nx configuration, Angular components, project graph

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


**新状态文件结构：**
```json
{
  "detection_type": "monorepo-service",  // What kind of app
  "route": "greenfield",                  // How to spec it
  "config": {
    "spec_output_location": "~/git/my-new-app",
    "build_location": "~/git/my-new-app",
    "target_stack": "Next.js 15..."
  }
}

文件写入位置：

路径	规范输出位置	文件存放位置
Greenfield	自定义位置	`{spec_output_location}/docs/` , `{spec_output_location}/.specify/`
Greenfield	未设置（默认）	`./docs/reverse-engineering/` , `./.specify/` （当前仓库）
Brownfield	始终为当前仓库	`./docs/reverse-engineering/` , `./.specify/`

基于检测类型+路径的提取方式：

检测类型	+ Greenfield	+ Brownfield
Monorepo Service	仅业务逻辑（与技术无关）	完整实现+共享包（指定技术）
Nx App	仅业务逻辑（与框架无关）	完整Nx/Angular实现细节
Generic App	仅业务逻辑	完整实现

工作原理：

```
detection_type
```
决定需要查找哪些模式（共享包、Nx项目配置、单体仓库结构等）
```
route
```
决定如何记录这些内容（与技术无关 vs 指定技术）

示例：

Monorepo Service + Greenfield → 提取服务的功能（不包含React/Express细节）
Monorepo Service + Brownfield → 提取完整的Express路由、React组件、共享工具
Nx App + Greenfield → 提取业务逻辑（不包含Angular细节）
Nx App + Brownfield → 提取完整的Nx配置、Angular组件、项目图

Process Overview

流程概述

Phase 1: Deep Codebase Analysis

阶段1：深度代码库分析

Approach depends on path:

Use the Task tool with

subagent_type=stackshift:code-analyzer

(or

Explore

as fallback) to analyze:

方式取决于所选路径：

使用Task工具，设置

subagent_type=stackshift:code-analyzer

（如果不可用则使用

Explore

作为备选）进行分析：

1.1 Backend Analysis

1.1 后端分析

All API endpoints (method, path, auth, params, purpose)
Data models (schemas, types, interfaces, fields)
Configuration (env vars, config files, settings)
External integrations (APIs, services, databases)
Business logic (services, utilities, algorithms)

See operations/backend-analysis.md

所有API端点（方法、路径、认证、参数、用途）
数据模型（模式、类型、接口、字段）
配置（环境变量、配置文件、设置）
外部集成（API、服务、数据库）
业务逻辑（服务、工具、算法）

查看 operations/backend-analysis.md

1.2 Frontend Analysis

1.2 前端分析

All pages/routes (path, purpose, auth requirement)
Components catalog (layout, form, UI components)
State management (store structure, global state)
API client (how frontend calls backend)
Styling (design system, themes, component styles)

See operations/frontend-analysis.md

所有页面/路由（路径、用途、认证要求）
组件目录（布局、表单、UI组件）
状态管理（存储结构、全局状态）
API客户端（前端调用后端的方式）
样式（设计系统、主题、组件样式）

查看 operations/frontend-analysis.md

1.3 Infrastructure Analysis

1.3 基础设施分析

Deployment (IaC tools, configuration)
CI/CD (pipelines, workflows)
Hosting (cloud provider, services)
Database (type, schema, migrations)
Storage (object storage, file systems)

See operations/infrastructure-analysis.md

部署（IaC工具、配置）
CI/CD（流水线、工作流）
托管（云服务商、服务）
数据库（类型、模式、迁移）
存储（对象存储、文件系统）

查看 operations/infrastructure-analysis.md

1.4 Testing Analysis

1.4 测试分析

Test files (location, framework, coverage)
Test types (unit, integration, E2E)
Coverage estimates (% covered)
Test data (mocks, fixtures, seeds)

See operations/testing-analysis.md

测试文件（位置、框架、覆盖率）
测试类型（单元测试、集成测试、E2E测试）
覆盖率估算（覆盖百分比）
测试数据（模拟数据、固定数据、种子数据）

查看 operations/testing-analysis.md

Phase 2: Generate Documentation

阶段2：生成文档

Create

docs/reverse-engineering/

directory and generate all 8 documentation files.

See operations/generate-docs.md for templates and guidelines.

创建

docs/reverse-engineering/

目录并生成所有8份文档文件。

查看 operations/generate-docs.md 获取模板和指南。

Output Files

输出文件

1. functional-specification.md

Focus: Business logic, WHAT the system does (not HOW)

Sections:

Executive Summary (purpose, users, value)
Functional Requirements (FR-001, FR-002, ...)
User Stories (P0/P1/P2/P3 priorities)
Non-Functional Requirements (NFR-001, ...)
Business Rules (validation, authorization, workflows)
System Boundaries (scope, integrations)
Success Criteria (measurable outcomes)

Critical: Framework-agnostic, testable, measurable

重点： 业务逻辑，系统的功能（而非实现方式）

章节：

执行摘要（用途、用户、价值）
功能需求（FR-001、FR-002……）
用户故事（优先级P0/P1/P2/P3）
非功能需求（NFR-001……）
业务规则（验证、授权、工作流）
系统边界（范围、集成）
成功标准（可衡量的结果）

关键要求： 与框架无关、可测试、可衡量

2. configuration-reference.md

Complete inventory of all configuration:

Environment variables
Config file options
Feature flags
Secrets and credentials (how managed)
Default values

所有配置的完整清单：

环境变量
配置文件选项
功能标志
密钥和凭证（管理方式）
默认值

3. data-architecture.md

All data models and API contracts:

Data models (with field types, constraints, relationships)
API endpoints (request/response formats)
JSON Schemas
GraphQL schemas (if applicable)
Database ER diagram (textual)

所有数据模型和API契约：

数据模型（包含字段类型、约束、关系）
API端点（请求/响应格式）
JSON模式
GraphQL模式（如适用）
数据库ER图（文本形式）

4. operations-guide.md

How to deploy and maintain:

Deployment procedures
Infrastructure overview
Monitoring and alerting
Backup and recovery
Troubleshooting runbooks

部署与维护方式：

部署流程
基础设施概述
监控与告警
备份与恢复
故障排查手册

5. technical-debt-analysis.md

Issues and improvements:

Code quality issues
Missing tests
Security vulnerabilities
Performance bottlenecks
Refactoring opportunities

问题与改进方向：

代码质量问题
缺失的测试
安全漏洞
性能瓶颈
重构机会

6. observability-requirements.md

Logging, monitoring, alerting:

What to log (events, errors, metrics)
Monitoring requirements (uptime, latency, errors)
Alerting rules and thresholds
Debugging capabilities

日志、监控、告警：

需要记录的内容（事件、错误、指标）
监控需求（可用性、延迟、错误）
告警规则与阈值
调试能力

7. visual-design-system.md

UI/UX patterns:

Component library
Design tokens (colors, typography, spacing)
Responsive breakpoints
Accessibility standards
User flows

UI/UX模式：

组件库
设计令牌（颜色、排版、间距）
响应式断点
无障碍标准
用户流程

8. test-documentation.md

Testing requirements:

Test strategy
Coverage requirements
Test patterns and conventions
E2E scenarios
Performance testing

测试需求：

测试策略
覆盖率要求
测试模式与约定
E2E场景
性能测试

Success Criteria

成功标准

After running this skill, you should have:

✅
```
docs/reverse-engineering/
```
directory created
✅ All 8 documentation files generated
✅ Comprehensive coverage of all application aspects
✅ Framework-agnostic functional specification
✅ Complete data model documentation
✅ Ready to proceed to Step 3 (Create Specifications)

运行此技能后，你应具备以下成果：

✅ 创建了
```
docs/reverse-engineering/
```
目录
✅ 生成了所有8份文档文件
✅ 全面覆盖应用的所有方面
✅ 与框架无关的功能规范
✅ 完整的数据模型文档
✅ 准备好进入第3步（创建规范）

Next Step

下一步

Once all documentation is generated and reviewed, proceed to:

Step 3: Create Specifications - Use the create-specs skill to transform docs into formal specifications.

生成并审核所有文档后，进入：

第3步：创建规范 - 使用create-specs技能将文档转换为正式规范。

Important Guidelines

重要指南

Framework-Agnostic Documentation

与框架无关的文档

DO:

Describe WHAT, not HOW
Focus on business logic and requirements
Use generic terms (e.g., "HTTP API" not "Express routes")

DON'T:

Hard-code framework names in functional specs
Describe implementation details in requirements
Mix business logic with technical implementation

需要做：

描述功能（WHAT），而非实现方式（HOW）
聚焦于业务逻辑和需求
使用通用术语（例如："HTTP API"而非"Express路由"）

不要做：

在功能规范中硬编码框架名称
在需求中描述实现细节
将业务逻辑与技术实现混合

Completeness

完整性

Use the Explore agent to ensure you find:

ALL API endpoints (not just the obvious ones)
ALL data models (including DTOs, types, interfaces)
ALL configuration options (check multiple files)
ALL external integrations

使用Explore工具确保你找到：

所有API端点（不仅仅是明显的那些）
所有数据模型（包括DTO、类型、接口）
所有配置选项（检查多个文件）
所有外部集成

Quality Standards

质量标准

Each document must be:

Comprehensive - Nothing important missing
Accurate - Reflects actual code, not assumptions
Organized - Clear sections, easy to navigate
Actionable - Can be used to rebuild the system

每份文档必须：

全面 - 不遗漏重要内容
准确 - 反映实际代码，而非假设
有条理 - 清晰的章节，易于导航
可操作 - 可用于重建系统

Technical Notes

技术说明

Use Task tool with
```
subagent_type=stackshift:code-analyzer
```
for path-aware extraction
Fallback to
```
subagent_type=Explore
```
if StackShift agent not available
Parallel analysis: Run backend, frontend, infrastructure analysis concurrently
Use multiple rounds of exploration for complex codebases
Cross-reference findings across different parts of the codebase
The
```
stackshift:code-analyzer
```
agent understands greenfield vs brownfield routes automatically

Remember: This is Step 2 of 6. The documentation you generate here will be transformed into formal specifications in Step 3.

使用Task工具并设置
```
subagent_type=stackshift:code-analyzer
```
进行路径感知型提取
如果StackShift代理不可用， fallback到
```
subagent_type=Explore
```
并行分析：同时运行后端、前端、基础设施分析
对于复杂代码库，使用多轮探索
跨代码库不同部分交叉验证发现的内容
```
stackshift:code-analyzer
```
代理会自动理解greenfield与brownfield路径

注意： 这是6个步骤中的第2步。你在此处生成的文档将在第3步转换为正式规范。