Menu
以内容优先、证据支撑的方式，从现有代码库生成详细的架构解析、工作流解析与参考文档体系。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | codebase-to-docs |
| description | 以内容优先、证据支撑的方式，从现有代码库生成详细的架构解析、工作流解析与参考文档体系。 |
将现有代码库转化为"可阅读、可核验、可维护、可演进"的文档体系。默认目标不是堆结构图或证据路径，而是先讲清系统在做什么、为什么这样设计、如何运行、如何失败、如何恢复，再用证据回溯这些结论。
核心方法： 采用"详细解析型输出"，同时覆盖两条主轴：架构解析主轴 + 工作流解析主轴。先规划页面树，再生成正文，再补 Mermaid 图与证据索引。
不适用： 纯营销文案、与工程执行无关的随笔；换用对应技能。
详细解析型输出必须同时覆盖以下两条主轴：
每个核心架构页或工作流页至少包含：
逐跳解析必须写明：调用点、被调用点、输入、输出、副作用、失败模式、恢复策略
每个核心页面至少包含 1 组设计取舍：
风险不能泛写。每个风险项至少包含：
1.1 确认范围（完整 / 仅架构 / 仅工作流 / 仅模块 / 仅参考）
1.2 确认 L 级别（L1 / L2 / L3）
1.3 确认输出语言（默认中文）
产出： 范围 + L 级别 + 语言确认
2.1 定义主轴（架构解析主轴 + 工作流解析主轴）
2.2 定义页面职责（每个页面解决什么问题）
2.3 标记长文深挖页
2.4 定义每页的关键流程/机制
产出： page-tree + 页面职责
3.1 收集文件路径
3.2 收集符号（类名/函数名）
3.3 收集配置键
3.4 收集测试用例
产出： evidence-index 草稿
4.1 结构层建模（C4 Context / Container / Component）
4.2 行为层建模（调用链、数据流、状态流转）
4.3 运行层建模（正常流、异常流、恢复路径）
产出： 结构模型 + 行为模型 + 运行模型
5.1 先写正文（背景、边界、机制、流程、异常、取舍、风险）
5.2 再补图（结构图、运行时图、工作流图、故障恢复图）
5.3 再补附录证据（evidence-index）
产出： 完整文档
6.1 完整性：页面树、双主轴、正常/异常流、设计取舍、风险、证据、图
6.2 一致性：术语、图文、结论与证据、页面职责、正常/异常流
6.3 深度性：连续叙述、逐跳调用链、输入/输出/副作用、反例/边界、替代方案、结构化风险
6.4 可读性：页面目标、路径/符号/清单堆砌、图后解释、阅读顺序、相关页面
产出： 验证报告
7.1 修复完整性问题
7.2 修复一致性问题
7.3 修复深度性问题
7.4 修复可读性问题
7.5 最终汇总
产出： 最终文档
docs/
├── index.md
├── overview/
│ ├── architecture-at-a-glance.md
│ ├── workflow-map.md
│ └── reading-guide.md
├── architecture/
│ ├── system-context.md
│ ├── container-and-component-view.md
│ ├── request-lifecycle.md
│ ├── failure-model.md
│ ├── deployment-and-operations.md
│ ├── cross-cutting-concerns.md
│ ├── design-decisions.md
│ └── risks-and-tech-debt.md
├── workflows/
│ ├── core-business-flows.md
│ ├── workflow-<name>-deep-dive.md
│ ├── state-transitions.md
│ ├── exception-and-recovery.md
│ ├── troubleshooting-playbook.md
│ └── rollback-and-compensation.md
├── modules/
│ ├── module-<name>.md
│ └── module-<name>-runtime.md
├── reference/
│ ├── api.md
│ ├── config.md
│ ├── data-models.md
│ └── glossary.md
└── appendix/
├── evidence-index.md
├── assumptions.md
└── verification-notes.md
若范围为完整详细解析，至少必须有：
index.mdoverview/architecture-at-a-glance.mdoverview/workflow-map.mdarchitecture/request-lifecycle.mdarchitecture/failure-model.mdworkflows/core-business-flows.mdworkflows/exception-and-recovery.mdreference/config.mdappendix/evidence-index.md| 借口 | 事实 |
|---|---|
| "代码就是证据" | 代码路径不能替代解释；必须先解释原理再引用代码 |
| "先写结构，内容以后补" | 禁止边写边发散；必须先规划页面树再生成正文 |
| "异常流不重要" | 每个核心页面必须包含正常流 + 至少 1 条异常流 |
| "设计取舍很难" | 每个核心页面至少 1 组设计取舍；必须说明替代方案和代价 |
| "风险以后再说" | 风险不能泛写；每个风险项必须包含触发条件、影响范围、可观测信号、缓解动作 |
| "只有架构页就够了" | 必须同时覆盖架构解析主轴和工作流解析主轴 |
| "图后不用解释" | 每张 Mermaid 图后都必须有解释；无解释的图视为无效 |
差： 先按章节复述代码结构，最后说"整体架构清晰"。
好： 先写背景和系统边界，然后逐跳解释调用链，每跳写明调用点、被调用点、输入、输出、副作用、失败模式、恢复策略，最后补设计取舍和风险分析。
差： "相关文件：src/service/order_service.py。下单流程：验证 → 创建 → 通知。"
好： "下单流程采用三步管道：先验证请求参数和库存，再创建订单记录并扣减库存，最后发送通知到消息队列。每一步失败时触发不同恢复策略：验证失败返回错误信息，创建失败回滚库存扣减，通知失败重试三次后记录到死信队列。证据：src/service/order_service.py -> OrderService.create_order。"
差： "采用队列而不是直接通知。"
好： "当前方案：消息队列。替代方案：直接调用通知服务。为何不选：直接调用会导致下单流程阻塞在通知环节，影响吞吐量。代价量化：队列引入约 10ms 延迟，但吞吐量提升约 5 倍。"
差： "风险：通知可能失败。"
好： "风险：通知服务不可达导致消息堆积。触发条件：通知服务宕机超过 30 秒。影响范围：死信队列堆积，需要人工介入。可观测信号：dead_letter_queue_size 指标超过 1000。缓解动作：告警 + 自动扩容 + 死信队列重试机制。"
交付前须将下列待勾选框逐项勾为已满足；全部勾选后，方可将本轮文档生成标为"完成"。
以上验证项已全部满足，本轮交付物符合本技能质量契约。
输出文档的模板位于 reference/ 目录，包含以下模板：
| 模板文件 | 用途 |
|---|---|
template-docs-index.md | 文档导航首页模板 |
template-architecture-at-a-glance.md | 架构概览模板 |
template-workflow-map.md | 工作流地图模板 |
template-request-lifecycle.md | 请求生命周期模板（长文深挖页） |
template-failure-model.md | 失败模型模板（长文深挖页） |
template-workflow-deep-dive.md | 工作流深挖模板（长文深挖页） |
template-risk-register.md | 风险登记表模板 |
template-evidence-index.md | 证据索引模板 |
validation.md | 验证标准与报告格式 |
使用方法：复制相应模板，将占位符替换为实际内容，按模板结构生成文档。
Use when executing implementation plans with independent tasks in the current session
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
Use when creating new skills, editing existing skills, or verifying skills work before deployment
Use when you have a spec or requirements for a multi-step task, before touching code