Docs From Code

---
name: docs-from-code
description: 从代码反推需求文档（L1 补写）的通用方法论 skill。任何项目里需要为已有代码补写需求文档时使用。提供 7 步操作流程、前后端代码阅读重点、归档使用规则、不确定信息处理、需求文档模板。项目特定约定（目录结构、版本制、命名规则）见该项目自己的项目级补丁 skill。触发词："补写需求文档"、"从代码反推"、"L1 补写"、"反推 L1"。
---

# 从代码反推需求文档（L1 补写）

> 项目特定约定（目录结构、版本制、命名规则）优先参考该项目自己的项目级补丁 skill（见 `templates/项目级补丁模板/`）。
> 本 skill 只提供通用方法论。

## 1. 操作流程

补写 `<项目>/docs/01-需求/` 时，按以下顺序操作：

```
1. 确定模块边界
2. 从前端找：页面、入口、交互动作
3. 从后端找：接口、业务能力、规则与状态
4. 从枚举和模型补充：状态、类型、边界条件
5. 查看项目归档目录，与代码证据交叉核对；任一来源都不能自动取得裁决权
6. 用业务语言重写成需求文档
7. 最后清理："是否写进了实现细节？"
```

## 2. 代码阅读重点

**前端**
- 页面名称与层级、tab 与分包结构
- 服务调用名称、按钮文案
- 空状态 / 错误状态处理、页面跳转关系

**后端**
- Controller 对外能力
- 枚举体现的状态和值域
- Biz / Service 中的规则与限制
- 权限校验、状态流转、外部依赖

## 3. 归档使用规则

**可以用归档补充**：模块命名、业务意图、代码中不明显的边界规则

**不能用归档**：覆盖代码事实、把旧方案当成当前事实

## 4. 不确定信息处理

1. 回到代码继续验证
2. 用归档做交叉核对
3. 仍无法确认 → 写入任务底稿的「待确认」清单，不得混入正式 L1

---

## 5. 需求文档推荐模板

> 代码只能反推候选业务语义。正式 L1 只保留裁决后的当前需求；来源、置信度、实现状态和“待确认”统一留在任务底稿。若意图仍未闭合，交付候选底稿而不是缩水版正式 L1。

每个模块的编号 README（例如 `01-xx-00-README.md`）或模块说明文档推荐章节：

```
0. 版本归属 / 适用版本
1. 模块目标
2. 用户价值
3. 页面与入口
4. 功能列表
5. 业务规则
6. 状态流转
7. 系统支撑能力
8. 异常与边界场景
9. 与其他模块的关系
10. 验收标准
```