Skip to content

README_EN.md

Latest commit

 

History

History
176 lines (121 loc) · 10.3 KB

README_EN.md

File metadata and controls

176 lines (121 loc) · 10.3 KB
Raw

Complete Source Reverse Engineering Skill · codebase-reverse

Reverse an existing source project into a complete, traceable, drill-downable meta-model that can be reconciled back to the source to find gaps.

This skill is a set of prompt-methodology assets for AI coding assistants. It turns a legacy source project into a full meta-model spanning functions, implementations, architecture, interfaces, objects, components, configuration, and the physical database — and produces per-function drill-down documents (requirements + implementation chain + database traceability).

⚠️ Scope Note — Read First

This skill is deeply tailored for [Java Web projects] and [Java Microservice projects (Spring Boot / Spring Cloud)]. It is tightly bound to the Java ecosystem in the following ways:

Tailoring dimension Concrete behavior
Entry-point detection Recognizes @RestController / @Controller + @RequestMapping / @GetMapping / @PostMapping (Spring MVC), plus frontend routes like app.get/post/...
Scheduling & events Recognizes @Scheduled, @XxlJob, Kafka @KafkaListener, @RabbitListener, @JmsListener, CDC, and compensation tasks as non-menu automated functions
Data access Deep support for MyBatis Mapper XML / annotation SQL, JPA / ORM entity mapping, and DAO / Repository / Mapper file-by-file tracing
Object classification Classifies Entity / Model / DTO / VO / Command / Query / Event / Enum / Config in full, matching Java layered architecture
Database reverse Physical table / view / column as the smallest unit; when DDL is missing, infers the column model from Java types, SQL, DAO and assignment paths (length / nullability / index marked unknown explicitly)
Validation script scripts/validate_meta_model.ps1 recognizes .java / .kt / .cs / .ts / .py / .go extensions by default and validates Spring annotations against source assets

Although the validation script and several concepts (DAO, Service, Controller, DTO) originate from Java conventions, the skill also generalizes to C# / TypeScript / Python / Go / PHP / Ruby projects — simply re-calibrate entry-point and object naming conventions per references/exhaustive-discovery.md.

1. What the Skill Produces

In the full architecture & function baseline mode, the skill outputs (see references/output-contract.md for the authoritative list):

  • source-asset-inventory.md — source asset ledger & ownership
  • business-function-requirements.md — a requirement panel per business function
  • function-chain-index.md — a complete main implementation chain per function
  • database-inventory.md / database-schema.md / database-relations.md / database-access-matrix.md — table-by-table, column-by-column DB reverse + R/C/U/D matrix
  • source-coverage-report.md — reconcile documents back to source to verify completeness
  • consistency-report.md — independent semantic & relation consistency check
  • function-drilldowns/FUNC-xxx.md — F-FULL mode: full business + technical implementation drilldown (with ASCII page prototypes)
  • function-requirements/FUNC-xxx.md — F-REQ mode: implementation-independent requirements spec + ASCII Demo + DB object model

Two fine-grained modes

Mode Purpose
F-FULL A specific function needing the full business + technical implementation set: every page control/event drilled vertically through frontend, interface, class methods, rules, objects, and database
F-REQ A specific function needing an implementation-independent requirements document: only business UI, functions, rules, states, acceptance, and DB object model (no classes/methods/architecture)

2. Install & Use on Major AI Tools

This skill does not depend on any platform-specific private API (no WorkBuddy / MCP / Hook proprietary calls). It runs fully on Claude Code, Codex, Cursor, Cline, Aider, or any tool that can load prompt/skill files.

1. WorkBuddy

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

In chat, say: "reverse this project", "do an F-FULL drilldown on module xxx", or "produce an implementation-independent requirements spec (F-REQ)" to trigger it.

2. Claude Code

Claude Code's Skills format (front-matter name + description + SKILL.md + bundled files) is fully compatible — just copy it:

# user-level
cp -r codebase-reverse ~/.claude/skills/codebase-reverse
# or project-level
mkdir -p .claude/skills && cp -r codebase-reverse .claude/skills/

Claude Code auto-discovers the skill and executes the three-phase + human-confirmation gate per references/workflow.md.

3. Codex

Codex has no native skill registry, but you can drop the whole skill folder into the repo and reference it from codex.md / AGENTS.md:

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

Add this line to codex.md / AGENTS.md:

When reverse-engineering source code, load .codex/skills/codebase-reverse/SKILL.md, first read the 5 "Read First" files (e.g. references/output-language.md), then execute per references/workflow.md; pause for human confirmation after each phase.

Note: the validation script validate_meta_model.ps1 runs in PowerShell (native on Windows; use PowerShell 7 pwsh on macOS/Linux). If the Codex sandbox lacks PowerShell, skip the automated check and rely on the manual Pass A-O only.

4. Cursor / Cline / Aider, etc.

Treat SKILL.md as a "methodology instruction file" and inject it into project context (e.g. .cursorrules, .clinerules, or paste references/prompt-pack.md at the start of a conversation).

3. Quick Usage Flow

Step 0: Language gate

The skill first confirms output language (Chinese zh-CN / English en-US). If unspecified, it asks you to choose; once chosen, the whole document set stays consistent. Class names, method names, paths, and table columns stay verbatim from source — never translated.

Step 1: Full baseline (default)

Say to the target source project:

Perform a "full architecture & function baseline reverse" of this project, covering all business functions, entries, interfaces, jobs, events, objects, DAOs, physical tables, and component capabilities.

The skill runs B0–B9 phases in order: scope → source asset ledger → technical architecture → business architecture & requirement panels → interfaces & objects → DB design → function penetration chains → common capabilities → coverage reconciliation → independent validation.

Step 2: Single-function drilldown (optional)

  • F-FULL: "Do an F-FULL full-set reverse of FUNC-xxx" — outputs business + technical implementation set.
  • F-REQ: "Produce an F-REQ implementation-independent requirements spec for FUNC-xxx" — outputs requirements + ASCII Demo + DB object model.

Step 3: Run automated validation

After producing the meta-model, run the built-in validator with PowerShell:

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

The script checks whether entry / DAO / model files registered in the documents actually exist in source, whether any assets are unowned, and emits a PASS / ERROR report. Completion requires both the automated check and the manual Pass A-O to be PASS with ERROR = 0.

4. Directory Structure

codebase-reverse/
├── SKILL.md                         # core methodology (triggers, rules, deliverables, completion gate)
├── agents/
│   └── openai.yaml                  # OpenAI Agents-style interface def (display_name / default_prompt)
├── references/                      # 18 spec files (single source of truth)
│   ├── output-language.md           # zh/en output & consistency rules
│   ├── workflow.md                  # modes, phases, coverage, stop rule
│   ├── output-contract.md           # deliverable dirs, stable IDs, node templates
│   ├── evidence-protocol.md         # fact/inference/assumption/missing-source handling
│   ├── exhaustive-discovery.md      # full source asset discovery & ownership
│   ├── business-function-requirements.md
│   ├── function-penetration.md
│   ├── database-reverse-engineering.md   # MyBatis/JPA specifics
│   ├── technical-architecture.md
│   ├── common-capabilities.md
│   ├── non-menu-functions.md        # scheduled/event/callback/CDC functions
│   ├── 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               # copy-paste prompt entry points
├── scripts/
│   └── validate_meta_model.ps1      # meta-model validator (PowerShell)
├── LICENSE
├── README.md                        # this file's Chinese counterpart
└── README_EN.md                     # English version

5. Design Principles (non-negotiable rules excerpt)

  1. Coverage completeness ≠ implementation detail depth. The baseline must enumerate everything; only detail may be layered. Never shrink coverage with "core functions" / "representative tables".
  2. Every business function gets its own FUNC-*, present in both the requirement panel and the implementation chain, one-to-one.
  3. Every function's main chain must pass through: entry → page/trigger → API/JOB/EVENT → Controller/Listener → Service → DAO/Mapper → object → component capability → physical table R/C/U/D → business result.
  4. Database must be reversed table-by-table, view-by-view, column-by-column; when DDL is missing write unknown, never omit columns or fabricate length/constraints.
  5. Reconcile from the source asset ledger back to documents; do not declare completion while any entry / interface / job / DAO / model / table is unowned.

6. License

Released under the MIT License — see LICENSE. You are free to use, modify, and redistribute this skill.

Heads-up: the reversed documents may contain class names, table names, and API paths from your source. Sanitize and check compliance before publishing.