完整源码逆向工程技能 · codebase-reverse

把存量源码逆向成完整、可追溯、可继续钻取、能从源码反查遗漏项的项目元模型。

本技能是一套面向 AI 编程助手的提示词方法论，可将一个已有源代码项目逆向为功能、实现、架构、接口、对象、组件、配置、物理数据库等维度的完整元模型，并产出逐功能深挖文档（需求 + 实现穿透链 + 数据库追踪）。

⚠️ 适用对象说明（务必先读）

本技能主要针对 [Java Web 项目] 与 [Java 微服务（Spring Boot / Spring Cloud）项目] 做了深度定制。 它在以下方面与 Java 生态强绑定：

虽然校验脚本与若干概念（DAO、Service、Controller、DTO）源自 Java 习惯，但技能同样可推广到 C# / TypeScript / Python / Go / PHP / Ruby 等语言项目——只需按 references/exhaustive-discovery.md 的口径自行校准入口与对象命名约定即可。

一、技能能产出什么

在「全量架构与功能基线模式」下，技能会输出（详见 references/output-contract.md）：

• source-asset-inventory.md — 源码资产台账与归属
• business-function-requirements.md — 每个业务功能的需求功能面板
• function-chain-index.md — 每个功能的完整主实现穿透链
• database-inventory.md / database-schema.md / database-relations.md / database-access-matrix.md — 逐物理表、逐字段数据库逆向与 R/C/U/D 矩阵
• source-coverage-report.md — 从源码反查文档覆盖是否完整
• consistency-report.md — 独立语义与关系一致性检查
• function-drilldowns/FUNC-xxx.md — F-FULL 模式：业务 + 技术实现全集细粒度逆向（含 ASCII 页面原型）
• function-requirements/FUNC-xxx.md — F-REQ 模式：技术实现无关需求规格 + ASCII Demo + 数据库对象模型

两种细粒度模式

二、在主流 AI 工具上的安装与使用

本技能不依赖任何特定平台私有 API（无 WorkBuddy / MCP / Hook 专有调用），可完整运行在 Claude Code、Codex、Cursor、Cline、Aider 等支持加载提示词/技能文件的工具上。

1. WorkBuddy

cp -r codebase-reverse ~/.workbuddy/skills/codebase-reverse

对话中直接说：「帮我逆向这个项目」「对 xxx 模块做 F-FULL 深挖」「生成一份技术实现无关需求规格（F-REQ）」即可触发。

2. Claude Code

Claude Code 的 Skills 格式（前置 name + description 元数据 + SKILL.md + 附属文件）与本技能完全兼容，直接复制即可：

# 用户级
cp -r codebase-reverse ~/.claude/skills/codebase-reverse
# 或项目级
mkdir -p .claude/skills && cp -r codebase-reverse .claude/skills/

Claude Code 会自动发现技能，按 references/workflow.md 的三阶段 + 人工确认门禁执行。

3. Codex

Codex 没有原生 skill 注册表，但可把整个技能目录放进仓库，并用 codex.md / AGENTS.md 引用：

mkdir -p .codex/skills && cp -r codebase-reverse .codex/skills/

在 codex.md / AGENTS.md 加一句：

做源码逆向时，加载 .codex/skills/codebase-reverse/SKILL.md，先读 references/output-language.md 等 5 个「Read First」文件，再按 references/workflow.md 执行；每完成一个阶段暂停等人确认。

注意：校验脚本 validate_meta_model.ps1 需在 PowerShell 环境运行（Windows 原生；macOS/Linux 可用 PowerShell 7 pwsh）。Codex 沙箱若无 PowerShell，可跳过自动校验、仅做人工 Pass A-O 检查。

4. Cursor / Cline / Aider 等

把 SKILL.md 当作「方法论指令文件」注入项目上下文即可（如放入 .cursorrules、.clinerules，或对话开头粘贴 references/prompt-pack.md 的提示词）。

三、快速使用流程

步骤 0：语言门禁

技能会先确认输出语言（中文 zh-CN / 英文 en-US）。未指定时它会让你先选，选定后整套文档保持一致；类名、方法名、路径、表字段等源码标识保持原文不翻译。

步骤 1：全量基线（默认）

直接对目标源码项目说：

请对本项目执行「全量架构与功能基线逆向」，覆盖全部业务功能、入口、接口、任务、事件、对象、DAO、物理表与组件能力。

技能会依次执行 B0–B9 阶段：范围界定 → 源码资产台账 → 技术架构 → 业务架构与需求面板 → 接口与对象 → 数据库设计 → 功能穿透链 → 公共能力 → 覆盖对账 → 独立校验。

步骤 2：单功能深挖（可选）

• F-FULL：请对 FUNC-xxx 做 F-FULL 全集逆向 —— 输出业务 + 技术实现全集。
• F-REQ：请对 FUNC-xxx 输出 F-REQ 技术实现无关需求规格 —— 输出需求文档 + ASCII Demo + 数据库对象模型。

步骤 3：运行自动校验

逆向产出后，用 PowerShell 运行内置校验脚本：

pwsh ./scripts/validate_meta_model.ps1 `
  -MetaModelPath ./docs/meta-model `
  -SourcePath   /path/to/your/java-project `
  -ReportPath   ./validation-report.md

脚本会核对：文档中登记的入口 / DAO / 模型文件是否真实存在于源码中、是否有未归属资产，并输出 PASS / ERROR 报告。只有当自动校验与人工 Pass A-O 均为 PASS、ERROR = 0 才算完成。

四、目录结构

codebase-reverse/
├── SKILL.md                         # 核心方法论（触发条件、规则、产物、完成门禁）
├── agents/
│   └── openai.yaml                  # OpenAI Agents 风格接口定义（display_name / default_prompt）
├── references/                      # 18 份规范文件（唯一事实源）
│   ├── output-language.md           # 中英文输出与一致性规则
│   ├── workflow.md                  # 模式、阶段、覆盖口径、停止规则
│   ├── output-contract.md           # 产物目录、稳定 ID、节点模板
│   ├── evidence-protocol.md         # 事实/推断/假设/缺失源码处理
│   ├── exhaustive-discovery.md      # 源码资产全量发现与归属
│   ├── business-function-requirements.md
│   ├── function-penetration.md
│   ├── database-reverse-engineering.md   # 含 MyBatis/JPA 专用说明
│   ├── technical-architecture.md
│   ├── common-capabilities.md
│   ├── non-menu-functions.md        # 定时/事件/回调/CDC 等无菜单功能
│   ├── single-function-drilldown.md
│   ├── single-function-requirements-spec.md
│   ├── source-tracing-playbook.md
│   ├── validation-and-consistency.md
│   ├── prompt-full-detail-drilldown.md
│   ├── prompt-requirements-drilldown.md
│   └── prompt-pack.md               # 可直接复制的提示词入口
├── scripts/
│   └── validate_meta_model.ps1      # 元模型自动校验脚本（PowerShell）
├── LICENSE
├── README.md                        # 本文件（中文）
└── README_EN.md                     # 英文版

五、设计原则（非协商规则摘录）

1. 覆盖完整度 ≠ 实现细节深度。基线必须全量枚举，只有细节可以分层；禁止用「核心功能」「代表表」缩小覆盖。
2. 每个业务功能建立独立 FUNC-*，并同时存在于「需求面板」与「实现穿透链」，二者一一对应。
3. 每条功能主链至少贯穿：入口 → 页面/触发 → API/JOB/EVENT → Controller/Listener → Service → DAO/Mapper → 对象 → 组件能力 → 物理表 R/C/U/D → 业务结果。
4. 数据库必须逐物理表、视图、字段逆向，缺失 DDL 时写 unknown，禁止省略字段或伪造长度/约束。
5. 从源码资产清单反查文档覆盖，存在未归属入口 / 接口 / 任务 / DAO / 模型 / 表时不得宣告完成。

六、许可证

本项目采用 MIT License，详见 LICENSE。你可自由使用、修改、再分发本技能。

提示：本技能产出的逆向文档可能包含你源码中的类名、表名、接口路径等，发布前请注意脱敏与合规。