# codebase-reverse

**Repository Path**: 8686555/codebase-reverse

## Basic Information

- **Project Name**: codebase-reverse
- **Description**: 把存量源码逆向成完整、可追溯、可继续钻取、能从源码反查遗漏项的项目元模型。

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

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

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

---

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

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

| 定制维度 | 具体体现 |
|---|---|
| 入口识别 | 识别 `@RestController` / `@Controller` + `@RequestMapping` / `@GetMapping` / `@PostMapping` 等 Spring MVC 注解；同时识别 `app.get/post/put/delete` 等前端路由 |
| 调度与事件 | 识别 `@Scheduled`、`@XxlJob`、Kafka `@KafkaListener`、`@RabbitListener`、`@JmsListener`、CDC、补偿任务等**无菜单自动功能** |
| 数据访问 | 深度支持 **MyBatis Mapper XML / 注解 SQL**、JPA / ORM 实体映射、DAO / Repository / Mapper 逐文件追踪 |
| 对象分类 | 将 Entity / Model / DTO / VO / Command / Query / Event / Enum / Config 全量分类，契合 Java 分层架构 |
| 数据库逆向 | 以物理表 / 视图 / 字段为最小单元；DDL 缺失时由 Java 类型、SQL、DAO、赋值路径推断字段模型（长度/可空/索引未知项显式标记 `unknown`） |
| 校验脚本 | `scripts/validate_meta_model.ps1` 默认识别 `.java / .kt / .cs / .ts / .py / .go` 等扩展名，并对 Spring 注解做源码资产核对 |

> 虽然校验脚本与若干概念（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 + 数据库对象模型

### 两种细粒度模式

| 模式 | 用途 |
|---|---|
| `F-FULL` | 指定功能且需要业务 **+ 技术实现全集**：每个页面控件/事件纵向贯穿前端、接口、类方法、规则、对象、数据库 |
| `F-REQ` | 指定功能且需要**技术实现无关需求文档**：只输出业务界面、功能、规则、状态、验收、数据库对象模型（不混入类/方法/架构） |

---

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

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

### 1. WorkBuddy

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

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

### 2. Claude Code

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

```bash
# 用户级
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` 引用：

```bash
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 运行内置校验脚本：

```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`。你可自由使用、修改、再分发本技能。

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