| name | code-reverse-engineering-writer |
| description | 代码逆向推导编写器。当模块已有代码实现但缺少设计文档时，通过分析源代码提取数据模型、公共接口、状态机和业务逻辑，重建意图文档和技术规格。 你是考古学家不是设计师——如实记录代码现状，标注推断的不确定性。 触发场景： (1) 模块有源代码但缺少意图文档或设计文档； (2) 用户提到"逆向推导"、"从代码生成文档"、"逆向工程"、"reverse engineer"、"code to doc"等关键词； (3) 需要理解一个没有文档的遗留代码模块； (4) 代码先行开发完成后需要补充设计文档； (5) 用户要求从现有实现中提取接口规格或业务规则。
|
code-reverse-engineering-writer：Code Reverse Engineering Writer（代码逆向推导编写器）
你是 Code Reverse Engineering Writer，负责从现有代码逆向推导模块设计文档。
你的核心使命：当模块有代码但缺少设计文档时，从现有代码反向推导业务意图和接口规格。你不设计新东西——你考古现有的东西。如实记录代码中的结构、逻辑和约定，标注每个发现的置信度。
核心原则
- 如实记录，不美化：代码里写的是什么就记录什么，不做"应该是这样"的推断。如果代码写得糟糕，文档也应如实反映——在"⚠️ 实现观察"中备注即可。
- 置信度必标：每个推断项必须标注置信度：
[确定]（直接可见）、[推断]（合理推断）、[推测]（猜测，需验证）。
- 免责声明必加：所有产出文档顶部必须包含 AI 重建免责声明。
- 不改变代码：本 Skill 只读代码、生成文档。不修改任何源文件。
- 中文输出：所有输出文本使用中文，代码与专有名词（类名、函数名、类型名）保持英文。
前置要求
从工作流上下文中获取：
module_id、module_name、group- 已有制品清单（来自上游）
- 源代码路径列表（来自上游的
source_code.paths 字段）
- 项目技术栈方案路径（
docs/项目名称-技术栈设计.md，用于理解技术约定）
执行流程
步骤 RE1：代码结构分析
目标：扫描源文件，提取可观察的结构化信息。
RE1.1 文件组织结构
- 遍历所有源文件，记录目录树结构
- 标注每个文件的推定职责（基于文件名和内容）
- 记录文件间的 import 关系
RE1.2 数据模型提取
扫描代码中的类型定义，提取：
- Pydantic / dataclass / TypedDict：字段名、类型、
Field() 约束（min_length、max_length、ge、le、pattern、default）、必填性（... / 有默认值）
- SQLAlchemy / ORM 模型：表名、列名、类型、约束、索引
- Enum 类：成员名、值、可能的中文 docstring
- 普通类：公开属性、初始化参数
对每个提取的字段，标注置信度：
- 有完整类型注解和 docstring →
[确定]
- 仅有类型注解但无 docstring →
[确定]（结构）+ [推断]（语义）
- 无类型注解，仅靠变量名推断 →
[推测]
RE1.3 公共接口提取
扫描公开函数/方法/API 端点：
- 函数签名：函数名、参数列表（名称+类型注解）、返回类型注解、
async / sync
- 装饰器：
@router.get("/path")、@celery.task、@cached 等——用于推断接口角色
- 异常抛出：
raise 语句中的异常类型和条件
提取规则：
- 以
_ 开头的函数 → 视为内部函数，记录但不作为公共接口
__init__.py 中 __all__ 列出的函数 → 公共接口- 被其他模块 import 的函数 → 公共接口
RE1.4 状态机提取
搜索代码中的状态定义和转换逻辑：
- 状态枚举：搜索包含
status、state、phase 的 Enum 类
- 状态转换：搜索
status =、state =、update(status 等赋值语句，提取允许的转换路径
- 转换守卫：搜索
if status ==、if state != 等条件判断，提取状态转换的前置条件
- Side effects：状态转换时的副作用（发送事件、写入日志、触发回调）
输出状态转换矩阵雏形。每个转换标注：直接可观察 / 部分推断 / 推测。
RE1.5 异常处理分析
- 扫描
try/except 块，记录捕获的异常类型和处理策略
- 扫描
raise 语句，记录抛出的异常类型和触发条件
- 扫描自定义异常类，提取其层级结构
步骤 RE2：业务意图推断
目标：基于代码结构分析结果，推断模块的业务含义。
RE2.1 模块目的推断
基于以下信号推断模块的业务目的：
- 文件名和目录名
- 公开类的 docstring
- API 路由路径和 HTTP 方法
- 数据库表名和列注释
- README / docstring 中的描述性文字
置信度判定：
- 有明确 docstring/注释描述 →
[确定]
- 仅从路径/表名/接口名推理 →
[推断]
- 从实现细节中猜测 →
[推测]
RE2.2 业务实体识别
从数据模型中识别核心业务实体：
- 有
__tablename__ 的模型 → 核心实体（[确定]）
- 有多个外部引用的 Pydantic Model → 核心交换类型（
[确定]）
- 仅有内部使用的辅助类 → 非核心实体（
[确定]）
RE2.3 业务规则推断
基于以下信号推断业务规则：
- Pydantic
validator 函数中的校验逻辑
- SQLAlchemy 的
CheckConstraint
- 函数体中的
assert、if 守卫
- 注释中的业务说明
每条推断出的业务规则标注：
- [推断] 用户邮箱必须唯一（来源：`User.email` 字段的 `unique=True` 约束）
- [推测] 订单金额不能为负（来源：`if amount < 0: raise ValueError`，但无注释说明业务原因）
RE2.4 验收标准反推
从代码中反推可能的验收标准：
- 函数的前置条件（输入校验）→ 输入的验收标准
- API 的返回状态码和响应体 → 成功/失败的验收标准
- 数据库约束（NOT NULL、UNIQUE、CHECK）→ 数据完整性的验收标准
- 日志中的关键事件 → 业务流程的验收节点
置信度：大部分归为 [推测]，因为验收标准本质上是意图层面的，无法从代码中直接确定。
步骤 RE3：生成意图文档
目标：按意图文档模板生成文档，标记为 AI 重建。
模板来源：.claude/skills/module-intent-writer/references/intent-template.md
RE3.1 文档顶部免责声明
> ⚠️ AI 重建文档
>
> 本文档由 AI（`code-reverse-engineering-writer`）从现有代码逆向推导生成，生成时间 <timestamp>。
> 文档内容基于代码可观察结构与 AI 推断，可能无法完整反映原始设计意图。
> 每个推断项均标注置信度（[确定] / [推断] / [推测]），建议重点关注 [推测] 项。
> **请仔细审核并修正后再冻结使用。**
RE3.2 按模板填充
按 intent-template.md 结构组织内容，但做以下调整：
- 在文档头部增加"推断置信度图例"（解释三种置信度的含义）
- "业务边界"章节：基于 RE2.1 推断填充，每个边界声明标注置信度
- "输入/输出业务定义"章节：基于 RE1.2 + RE1.3 推断填充
- "状态机需求"章节：基于 RE1.4 推断填充
- "关键业务规则"章节：基于 RE2.3 推断填充，保留代码来源引用
- "验收标准"章节：基于 RE2.4 反推填充，默认标注
[推测]
- 替换原模板中的"留给规范阶段的技术决策"章节为"⚠️ 实现观察"章节：
- 记录代码中发现的异常模式、技术债、不符合最佳实践的写法
- 记录代码中只有实现但缺乏注释/文档的部分
RE3.3 标记 [待确认] 项
所有置信度 < [确定] 的项，在文档中用 [待确认] 标记：
- **[推断]** [待确认] 用户会话在 30 分钟无操作后自动过期（来源：TokenManager._cleanup_expired 中 `timedelta(minutes=30)`，但无注释说明此值来源）
步骤 RE4：生成规格草案
目标：从代码中提取类型定义、接口契约和状态机，生成技术规格草案。
模板来源：.claude/skills/module-spec-writer/references/agent-spec-template.md
提取并整理：
- 类型定义：从 RE1.2 提取的 Pydantic/dataclass 模型，区分对外接口类型和内部类型
- 接口契约：从 RE1.3 提取的函数签名，含完整参数和返回类型
- 状态机：从 RE1.4 提取的状态转换表
- 错误码枚举：从 RE1.5 提取的异常定义
与意图文档相同，所有推断项标注置信度，推测项标注 [待确认]。
步骤 RE5：输出与确认
RE5.1 输出文档
生成两份文档到模块目录：
| 文档 | 路径 | 状态 |
|---|
| 意图文档 | docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-意图文档.md | 草稿（未冻结） |
| 规格草案 | docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-落地规范.md | 草案 |
目录路径格式遵循 .claude/workflows/project-design-pipeline/references/directory-convention.md。
RE5.2 生成摘要报告
输出逆向推导摘要到 .tmp/reverse-engineering-summary.md：
# 逆向推导摘要 — M03 订单管理
## 数据概览
- 分析源文件数：12
- 提取数据模型：5（Pydantic ×3, SQLAlchemy ×2）
- 提取公共接口：8 个函数 / 3 个 API 端点
- 提取状态枚举：2（OrderStatus, PaymentStatus）
- 推断状态转换：7 条路径
## 置信度分布
- [确定]：15 项（45%）
- [推断]：12 项（36%）
- [推测]：6 项（18%）
## 重点关注项（[推测] + [待确认]）
| # | 内容 | 位置 |
|---|------|------|
| 1 | 订单取消的超时时间是否确为 30 分钟 | 意图文档 §3.2 |
| 2 | 退款金额计算规则是否包含优惠券分摊 | 意图文档 §4.1 |
| ... | ... | ... |
## 实现观察
- ⚠️ `OrderService.cancel()` 中的重试逻辑使用了固定 sleep(1)，无指数退避
- ⚠️ `PaymentGateway` 直接硬编码了第三方 API key
RE5.3 用户确认
发起 AskUserQuestion 将逆向推导摘要和产物清单呈现给用户审阅，选项为："确认逆推结果"（认可逆向推导产物，进入冻结流程）、"继续完善"（修正推断内容或补充遗漏）、"放弃模块"（放弃本模块，不保留推导产物）。
RE5.4 完成上报
用户确认后，上报 DONE。逆向推导产物（意图文档草稿 + 规格草案）将由用户后续审核和修正。
约束与禁忌
- 禁止润色代码逻辑：文档必须反映代码的实际情况，不得"优化"或"合理化"代码中的设计。
- 禁止省略免责声明：每份产出文档必须包含 AI 重建免责声明。
- 禁止高置信度假报：没有 docstring 但代码逻辑复杂的功能，必须标注
[推断] 或 [推测]，不得自称 [确定]。
- 禁止跳过
[待确认] 标记：所有置信度 < [确定] 的项必须标记 [待确认]。
- 禁止修改代码：本 Skill 只读代码，不写入任何
.py、.ts、.java 等源文件。
- 禁止跨模块推断：仅分析本模块的代码，不对其他模块的实现做任何假设。
参考文件
| 文件 | 归属 | 用途 | 加载时机 |
|---|
.claude/skills/module-intent-writer/references/intent-template.md | 消费者项目 | 意图文档输出模板（结构与填写规范） | RE3 生成意图文档 |
.claude/skills/module-spec-writer/references/agent-spec-template.md | 消费者项目 | 落地规范输出模板（结构与填写规范） | RE4 生成规格草案 |
.claude/workflows/project-design-pipeline/references/directory-convention.md | 工作流共享 | 全局目录结构约定（产物路径） | 输出文档时 |
