Back to Details

drive-to-legacy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Drive to Legacy - Systematic Legacy Code Exploration

Drive to Legacy——系统化遗留代码探索

Overview

概述

A 6-phase systematic approach to fully understand an unfamiliar codebase, producing a comprehensive architecture document with mermaid diagrams that both humans and AI can use for porting, migration, or onboarding.
Core principle: Explore wide before deep. Map the full territory first, then drill into each layer. Every finding goes into a living ARCHITECTURE.md with diagrams.
这是一种分为6个阶段的系统化方法，用于全面理解不熟悉的代码库，生成包含Mermaid图表的综合性架构文档，供人类和AI用于移植、迁移或入职培训。
核心原则：先广度探索，再深度钻研。先绘制完整的代码版图，再深入每个层级。所有发现都要记录到动态更新的ARCHITECTURE.md文档中，并附带图表。

When to Use

适用场景

  • Onboarding to an unfamiliar codebase
  • Preparing to port or rewrite an application
  • Documenting a legacy system that lacks documentation
  • Studying code you need to maintain but did not write
  • Any "how does this work?" question about a full project
When NOT to use:
  • Small bug fixes in code you already understand
  • Greenfield projects (no legacy to explore)
  • Single-file scripts or utilities
  • 入职新代码库时
  • 准备移植或重写应用时
  • 为缺乏文档的遗留系统编写文档时
  • 研究需要维护但并非自己编写的代码时
  • 针对整个项目提出的任何「这是如何工作的？」问题
不适用场景：
  • 在已理解的代码中进行小bug修复
  • 全新项目（无遗留代码需要探索）
  • 单文件脚本或工具类代码

The 6 Phases

6个阶段

Follow these phases in order. Each phase builds on the previous. Use parallel Explore agents where possible to speed up discovery.
请按顺序遵循这些阶段，每个阶段都建立在前一阶段的基础上。尽可能使用并行Explore Agent来加快探索速度。

Phase 1: User Stories

阶段1：用户故事

Goal: Describe WHAT the app does from the user's perspective. This comes first because it answers "why does this app exist?" — the context that makes all technical details meaningful.
  1. Read 
    package.json
    / 
    README.md
    to understand the app's purpose
  2. Read entry points and main container components to identify the UI flow
  3. Walk through component render methods to find every user action
  4. Trace each action to its handler and side effects
  5. Note conditional paths (different behavior for different roles or data states)
Write to ARCHITECTURE.md:
  • Section: "User Stories" with one subsection per story
  • Each story: user story statement + mermaid 
    sequenceDiagram
    showing the interaction
Template per story:
markdown
undefined
目标： 从用户视角描述应用的功能。这一步要优先完成，因为它回答了「这个应用存在的意义是什么？」——这是让所有技术细节变得有意义的上下文。
  1. 阅读
    package.json
    /
    README.md
    以理解应用的用途
  2. 阅读入口文件和主容器组件，识别UI流程
  3. 遍历组件渲染方法，找出所有用户操作
  4. 追踪每个操作对应的处理器和副作用
  5. 记录条件分支（不同角色或数据状态下的不同行为）
写入ARCHITECTURE.md：
  • 章节：「用户故事」，每个故事对应一个子章节
  • 每个故事：用户故事陈述 + 展示交互流程的mermaid 
    sequenceDiagram
故事模板：
markdown
undefined

US-XX: Story Title

US-XX: 故事标题

AS A [role] I WANT TO [action] SO THAT [outcome]
(mermaid sequence diagram)
undefined
作为[角色] 我想要[操作] 以便[结果]
(mermaid sequence diagram)
undefined

Phase 2: Project Identity and Component Map

阶段2：项目标识与组件映射

Goal: Know the tech stack, file layout, and component tree.
  1. Read build config (
    vite.config.ts
    , 
    webpack.config.js
    , 
    tsconfig.json
    , etc.)
  2. List the top-level directory structure
  3. Glob for all source files to see the shape: 
    **/*.tsx
    , 
    **/*.ts
    , 
    **/*.vue
    , etc.
  4. Read each main component/module entry point (not every file, just the key ones)
  5. Trace the component hierarchy from root down
  6. Identify reusable/shared components vs. page-specific ones
Write to ARCHITECTURE.md:
  • Section: "What This App Does" (3 sentences max)
  • Section: "Tech Stack and Key Dependencies" (bullet list)
  • Section: "File-to-Responsibility Map" (tree with one-line descriptions)
  • Section: "Component Hierarchy" (mermaid 
    graph TD
    diagram)
  • Section: "State Management Overview" (mermaid diagram showing where state lives)
目标： 了解技术栈、文件布局和组件树。
  1. 阅读构建配置文件（
    vite.config.ts
    、
    webpack.config.js
    、
    tsconfig.json
    等）
  2. 列出顶级目录结构
  3. 全局搜索所有源文件以了解代码形态：
    **/*.tsx
    、
    **/*.ts
    、
    **/*.vue
    等
  4. 阅读每个主要组件/模块的入口文件（无需阅读每个文件，只需关键文件）
  5. 从根组件向下追踪组件层级
  6. 区分可复用/共享组件与页面专属组件
写入ARCHITECTURE.md：
  • 章节：「应用功能概述」（最多3句话）
  • 章节：「技术栈与核心依赖」（项目符号列表）
  • 章节：「文件职责映射」（带单行描述的树形结构）
  • 章节：「组件层级」（mermaid 
    graph TD
    图表）
  • 章节：「状态管理概述」（展示状态存储位置的mermaid图表）

Phase 3: Data Model

阶段3：数据模型

Goal: Understand every entity, type, and relationship.
  1. Read all type/interface/model files
  2. Read the service/API layer to find all entities referenced
  3. Map relationships between entities (foreign keys, lookups, joins)
  4. Identify choice/enum fields and their values
Capture:
  • Every TypeScript interface / database model / API schema
  • Entity relationships (one-to-many, many-to-many)
  • Key constants and magic numbers with their meanings
Write to ARCHITECTURE.md:
  • Section: "CRM/Database Entity Relationship Diagram" (mermaid 
    erDiagram
    with field lists)
  • Section: "Key Constants and Option Set Values" (table)
目标： 理解每个实体、类型及其关系。
  1. 阅读所有类型/接口/模型文件
  2. 阅读服务/API层，找出所有引用的实体
  3. 映射实体间的关系（外键、查找、关联）
  4. 识别选项/枚举字段及其值
记录内容：
  • 所有TypeScript接口/数据库模型/API schema
  • 实体关系（一对多、多对多）
  • 关键常量和魔法数字及其含义
写入ARCHITECTURE.md：
  • 章节：「CRM/数据库实体关系图」（带字段列表的mermaid 
    erDiagram
    ）
  • 章节：「关键常量与选项集值」（表格）

Phase 4: Business Logic

阶段4：业务逻辑

Goal: Extract every rule, validation, cascade, and conditional behavior.
This is the deepest phase. Read line by line through:
  1. Form validation rules - what is required, when, why
  2. Field cascade logic - selecting A resets B, populates C
  3. Conditional rendering - what shows/hides and when
  4. Data transformation - how input maps to output on save
  5. Silent fallbacks - what happens when data is missing (nullability chains)
Write to ARCHITECTURE.md:
  • Section: "Business Logic and Rules" with subsections for each rule domain
  • Use mermaid 
    flowchart TD
    for decision trees
  • Use tables for validation rules and field mappings
  • Include a "Nullability and Silent Fallbacks" table (what can be undefined and what happens)
  • Include an "Auto-Population Rules" section (what triggers auto-fill of which fields)
目标： 提取所有规则、验证、级联逻辑和条件行为。
这是最深入的阶段，需要逐行阅读以下内容：
  1. 表单验证规则 - 哪些字段是必填项、何时需要验证、原因是什么
  2. 字段级联逻辑 - 选择A会重置B、填充C
  3. 条件渲染 - 哪些内容会显示/隐藏以及触发条件
  4. 数据转换 - 保存时输入如何映射到输出
  5. 静默降级逻辑 - 数据缺失时的处理方式（空值链）
写入ARCHITECTURE.md：
  • 章节：「业务逻辑与规则」，每个规则领域对应一个子章节
  • 使用mermaid 
    flowchart TD
    绘制决策树
  • 使用表格展示验证规则和字段映射
  • 包含「空值处理与静默降级」表格（哪些字段可为undefined以及对应的处理逻辑）
  • 包含「自动填充规则」章节（哪些触发条件会自动填充哪些字段）

Phase 5: API Reference

阶段5：API参考

Goal: Document every data query with exact parameters, filters, joins, and purpose.
CRITICAL RULE: Every API endpoint MUST have a Why row. The Why explains the business reason the data is needed - not just "fetches X from Y" but why the application cannot function without this call. Without Why, a developer porting the code cannot tell which APIs are essential vs. nice-to-have, or what would break if the API were removed or changed.
For each service method / API call:
  1. Read the exact query (SQL, FetchXml, OData, GraphQL, REST URL)
  2. Document parameters, entity, joins, filters
  3. Note when it is called and by which component
  4. Explain WHY it exists (business purpose, not just technical description)
The Why row must answer: "What business goal does this query serve? What breaks or becomes impossible without it?"
Good Why examples:
  • "Populates dropdown options so the form can render selectable choices. These are CRM choice-column labels, not hardcoded."
  • "Finds the pre-defined stock item (inventory lane) for a customer + make between POL/POD ports. Links cargo to inventory forecasting."
  • "Determines which other schedules can carry cargo onward. Same vessel for Cross, different vessel for Transshipment."
Bad Why examples:
  • "Fetches data from the database" (too vague, says nothing about business purpose)
  • "Called when user clicks save" (that's When, not Why)
  • "Returns a list of records" (describes what, not why)
Write to ARCHITECTURE.md:
  • Section: "API Reference" with one subsection per endpoint
  • Each endpoint gets a properties table with Why always after When:
PropertyValue
Called byComponent or function name
API methodThe actual call pattern
EntityTable/endpoint queried
ParametersInput values
WhenTrigger condition
WhyBusiness reason this data is needed
  • Include the exact query (SQL/FetchXml/GraphQL) in a code block
  • Include a mermaid join diagram for complex multi-table queries
  • End with an "API Call Map by User Action" (mermaid flowchart showing which APIs fire on which user action)
Also document inline queries - queries defined inside components (not just in the service layer). These are easy to miss.
目标： 记录每个数据查询的精确参数、过滤器、关联和用途。
关键规则：每个API端点必须包含「原因（Why）」行。 「原因」要解释获取该数据的业务理由——不仅仅是「从Y获取X」，还要说明应用没有这个调用就无法正常运行的原因。如果没有「原因」，移植代码的开发者无法判断哪些API是必需的、哪些是锦上添花的，也无法知道如果API被移除或修改会导致什么问题。
针对每个服务方法/API调用：
  1. 阅读精确的查询语句（SQL、FetchXml、OData、GraphQL、REST URL）
  2. 记录参数、实体、关联、过滤器
  3. 记录调用时机和调用组件
  4. 解释存在的原因（业务目的，而非仅技术描述）
「原因」行必须回答：「这个查询服务于什么业务目标？没有它会导致什么功能失效或无法实现？」
优秀的「原因」示例：
  • 「填充下拉选项，以便表单渲染可选择的选项。这些是CRM选择列的标签，而非硬编码值。」
  • 「为客户+运输航线在POL/POD港口之间查找预定义的库存项（库存通道）。将货物与库存预测关联起来。」
  • 「确定哪些其他班次可以转运货物。Cross航线使用同一艘船，Transshipment航线使用不同的船。」
糟糕的「原因」示例：
  • 「从数据库获取数据」（过于模糊，未说明业务目的）
  • 「用户点击保存时调用」（这是调用时机，不是原因）
  • 「返回记录列表」（描述了内容，而非原因）
写入ARCHITECTURE.md：
  • 章节：「API参考」，每个端点对应一个子章节
  • 每个端点包含属性表格，「原因」始终紧跟「时机」：
属性值
调用方组件或函数名称
API方法实际调用模式
实体查询的表/端点
参数输入值
时机触发条件
原因获取该数据的业务理由
  • 在代码块中包含精确的查询语句（SQL/FetchXml/GraphQL）
  • 复杂的多表查询使用mermaid关联图展示
  • 最后添加「按用户操作分类的API调用映射」（mermaid流程图展示哪些用户操作会触发哪些API调用）
还要记录内联查询——在组件内部定义的查询（不仅仅是服务层中的查询），这些很容易被遗漏。

Phase 6: Build and Deploy

阶段6：构建与部署

Goal: Know how to run, build, and ship.
  1. Read build scripts and CI/CD config
  2. Read deployment scripts or docs
  3. Note environment-specific configs
Write to ARCHITECTURE.md:
  • Section: "Build and Deploy Pipeline" (mermaid 
    graph TD
    from dev to production)
  • Section: "LookupFieldInput / Reusable Components" (document non-obvious reusable patterns)
目标： 了解如何运行、构建和发布应用。
  1. 阅读构建脚本和CI/CD配置
  2. 阅读部署脚本或文档
  3. 记录环境特定的配置
写入ARCHITECTURE.md：
  • 章节：「构建与部署流水线」（从开发到生产的mermaid 
    graph TD
    图表）
  • 章节：「LookupFieldInput / 可复用组件」（记录非显而易见的可复用模式）

ARCHITECTURE.md Structure

ARCHITECTURE.md结构

The final document should follow this reading order (user stories first — they answer "why does this app exist?" and make everything else meaningful):
undefined
最终文档应遵循以下阅读顺序（用户故事优先——它们回答了「这个应用存在的意义是什么？」，让其他所有内容都变得有意义）：
undefined

Project Name - Architecture Reference

项目名称 - 架构参考

One-paragraph summary
一段摘要

Table of Contents (clickable anchor links)

目录（可点击锚点链接）

(overview Mermaid diagram here — the convention's mandatory document thumbnail)
（此处放置概述Mermaid图表——这是约定的必备文档缩略图）

Part 1: User Stories

第一部分：用户故事

  • One subsection per story with sequence diagrams
  • 每个故事对应一个子章节，附带序列图

Part 2: Overview and Project Structure

第二部分：概述与项目结构

  • What This App Does
    • Tech Stack and Key Dependencies
    • File-to-Responsibility Map
    • Key Constants and Option Set Values
    • Component Hierarchy (diagram)
    • Entity Relationship Diagram
    • State Management Overview (diagram)
  • 应用功能概述
    • 技术栈与核心依赖
    • 文件职责映射
    • 关键常量与选项集值
    • 组件层级（图表）
    • 实体关系图
    • 状态管理概述（图表）

Part 3: Application Flow

第三部分：应用流程

  • Bootstrap / initialization sequence
    • Main user flows as sequence diagrams
    • Save / submit flow
  • 启动/初始化序列
    • 主要用户流程（序列图）
    • 保存/提交流程

Part 4: Business Logic and Rules

第四部分：业务逻辑与规则

  • Subsection per rule domain with flowcharts
    • Validation rules
    • Cascade logic
    • Conditional rendering rules
    • Auto-population rules
    • Nullability and silent fallbacks
  • 每个规则领域对应一个子章节，附带流程图
    • 验证规则
    • 级联逻辑
    • 条件渲染规则
    • 自动填充规则
    • 空值处理与静默降级

Part 5: Data Model and Field Mapping

第五部分：数据模型与字段映射

  • TypeScript-to-database field mapping (diagram)
    • Conditional field mapping rules
  • TypeScript到数据库的字段映射（图表）
    • 条件字段映射规则

Part 6: API Reference

第六部分：API参考

  • Overview of query patterns used
    • One subsection per endpoint (properties table + exact query + why)
    • Inline component queries
    • API call map by user action (diagram)
  • 使用的查询模式概述
    • 每个端点对应一个子章节（属性表格 + 精确查询 + 原因）
    • 组件内联查询
    • 按用户操作分类的API调用映射（图表）

Part 7: Technical Components

第七部分：技术组件

  • Reusable components worth understanding
    • Build and deploy pipeline
undefined
  • 需要重点理解的可复用组件
    • 构建与部署流水线
undefined

Rules for the Architecture Document

架构文档规则

  1. Clickable TOC - every section linked with anchor. Avoid 
    &
    , 
    --
    , 
    /
    , 
    *
    , 
    ()
    in headings (they break anchor generation).
  2. Mermaid diagrams everywhere - sequence diagrams for flows, flowcharts for logic, ER diagrams for data, graph TD for hierarchies. This implements the marketplace diagram convention (
    ${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md
    ) — including its mandatory overview diagram at the top of the document.
  3. Every API table must have a Why row - business purpose, not just technical trigger.
  4. Tables for scannable data - validation rules, field mappings, constants, nullability.
  5. No speculation - only document what you read in the code. If behavior is unclear, note it as unclear.
  6. Horizontal rules (
    ---
    ) between Parts     for visual separation.
  1. 可点击目录 - 每个章节都带有锚点链接。标题中避免使用
    &
    、
    --
    、
    /
    、
    *
    、
    ()
    等字符（它们会破坏锚点生成）。
  2. 处处使用Mermaid图表 - 序列图展示流程、流程图展示逻辑、ER图展示数据、graph TD展示层级。这遵循了市场图表约定（
    ${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md
    ）——包括在文档顶部放置必备的概述图表。
  3. 每个API表格必须包含「原因」行 - 说明业务目的，而非仅技术触发条件。
  4. 表格展示可扫描数据 - 验证规则、字段映射、常量、空值处理。
  5. 不做推测 - 仅记录从代码中读取到的内容。如果行为不明确，要标注为「不明确」。
  6. 各部分之间使用水平分隔线（
    ---
    ）     - 用于视觉区分。

Parallel Exploration Strategy

并行探索策略

Use multiple Explore agents in parallel to speed up Phase 1-3:
Agent 1: Read entry points, config, types, UI flows → Phase 1 + Phase 2
Agent 2: Read all types, service layer, entity references → Phase 3
Agent 3: Read service layer, extract all queries → Phase 5
Then do Phase 4 (business logic) sequentially — it requires understanding from all previous phases.
使用多个Explore Agent并行处理以加快阶段1-3的进度：
Agent 1: 读取入口文件、配置、类型、UI流程 → 阶段1 + 阶段2
Agent 2: 读取所有类型、服务层、实体引用 → 阶段3
Agent 3: 读取服务层、提取所有查询 → 阶段5
然后按顺序处理阶段4（业务逻辑）——它需要基于前几个阶段的理解。

Common Mistakes

常见错误

MistakeFix
Starting with business logic before understanding structureFollow phases in order. Phase 1-3 first.
Missing inline queries in componentsGrep for query patterns in component files, not just service files
Writing "what" without "why" in API docsEvery API endpoint MUST have a Why row explaining the business reason, not just technical description. "Fetches data" is not a Why.
Why row says "fetches X" or "returns Y"That describes What, not Why. Ask: "What breaks without this call? What business goal does it serve?"
Headings with special characters breaking TOCUse only alphanumeric, spaces, and hyphens in headings
Enormous single-pass explorationUse parallel agents. Split by concern.
Documenting only the happy pathInclude error handling, fallbacks, and nullability chains
Skipping the user storiesUser stories provide the "why" context that makes technical docs useful
错误修复方案
在理解结构之前就开始研究业务逻辑按顺序遵循阶段，先完成阶段1-3。
遗漏组件中的内联查询在组件文件中搜索查询模式，而不仅仅是服务文件
API文档只写「是什么」不写「为什么」每个API端点必须包含「原因」行，说明业务理由，而非仅技术描述。「获取数据」不是有效的原因。
「原因」行写「获取X」或「返回Y」这描述的是「是什么」，不是「为什么」。要问：「没有这个调用会导致什么失效？它服务于什么业务目标？」
标题包含特殊字符导致目录失效标题中仅使用字母数字、空格和连字符
单次探索范围过大使用并行Agent，按关注点拆分任务。
仅记录正常流程要包含错误处理、降级逻辑和空值链
跳过用户故事用户故事提供了「为什么」的上下文，让技术文档更有价值