code-reader-v2-cn
- Repo stars 79
- Author updated Live
- Author repo code-reader-skills
- Domain
- Other
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @notlate-cn · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Permissions
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: code-reader-v2-cn
description: 基于认知科学研究的专业代码分析工具,支持三种分析深度,确保真正理解代码,而非产生流畅幻觉。 研究支撑:Dunlosky et al. · Chi et al. · Karpicke & Roe…
category: other
runtime: Python
---
# code-reader-v2-cn output preview
## PART A: Task fit
- Use case: 基于认知科学研究的专业代码分析工具,支持三种分析深度,确保真正理解代码,而非产生流畅幻觉。 研究支撑:Dunlosky et al. · Chi et al. · Karpicke & Roediger | 用户意图 | 模式 | 触发词示例 | 分析时长 | |---------|------|-----------|---------| runs entirely locally; runs on Python. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “三种分析模式 / 分析输出结构 / Quick Mode(5-10 分钟)” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “基于认知科学研究的专业代码分析工具,支持三种分析深度,确保真正理解代码,而非产生流畅幻觉。 研究支撑:Dunlosky et al. · Chi et al. · Karpicke & Roediger | 用户意图 | 模式 | 触发词示例 | 分析时长 | |---------|------|-----------|---------| runs entirely locally; runs on Python. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “三种分析模式 / 分析输出结构 / Quick Mode(5-10 分钟)” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files.
Start with a small task and check whether the result follows “三种分析模式 / 分析输出结构 / Quick Mode(5-10 分钟)”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: code-reader-v2-cn
description: 基于认知科学研究的专业代码分析工具,支持三种分析深度,确保真正理解代码,而非产生流畅幻觉。 研究支撑:Dunlosky et al. · Chi et al. · Karpicke & Roe…
category: other
source: notlate-cn/code-reader-skills
---
# code-reader-v2-cn
## When to use
- 基于认知科学研究的专业代码分析工具,支持三种分析深度,确保真正理解代码,而非产生流畅幻觉。 研究支撑:Dunlosky et al. · Chi et al. · Karpicke & Roediger | 用户意图 | 模式 | 触发…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “三种分析模式 / 分析输出结构 / Quick Mode(5-10 分钟)” and keep inference separate from source facts.
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "code-reader-v2-cn" {
input -> user goal + target files + boundaries + acceptance criteria
context -> 三种分析模式 / 分析输出结构 / Quick Mode(5-10 分钟)
rules -> SKILL.md triggers / order / output contract
runtime -> Python | read files, write/modify files | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 源代码深度理解分析器 v2.3 (中文版)
基于认知科学研究的专业代码分析工具,支持三种分析深度,确保真正理解代码,而非产生流畅幻觉。
核心原则:理解 WHY,而非只知道 WHAT。像有经验的工程师给朋友讲解,而非照本宣科堆砌术语。
研究支撑:Dunlosky et al. · Chi et al. · Karpicke & Roediger
三种分析模式
| 用户意图 | 模式 | 触发词示例 | 分析时长 |
|---|---|---|---|
| 快速浏览/代码审查 | Quick | "快速看一下"、"这段代码干嘛的"、"简单扫一眼" | 5-10 分钟 |
| 学习理解/技术调研 | Standard ⭐ | "分析一下"、"帮我理解"、"解释一下"、"什么原理" | 15-20 分钟 |
| 深度掌握/大型项目 | Deep 🚀 | "彻底分析"、"完全掌握"、"深入研究"、"面试准备"、"项目整体分析" | 30+ 分钟 |
默认使用 Standard Mode。系统根据代码规模和用户意图自动选择模式。
Deep Mode 内部策略选择:
if 代码行数 <= 2000:
策略 A:渐进式生成(顺序填充章节)
elif 代码行数 <= 10000 且 文件数 <= 20:
策略 B:并行处理(子 Agent 章节级并行)
else: # 行数 > 10000 或 文件数 > 20
策略 C:分层并行(模块级扫描 → 章节级并行)
分析输出结构
Quick Mode(5-10 分钟)
# [代码名称] 快速分析
## 1. 快速概览
- 编程语言和版本 / 代码规模和类型 / 核心依赖
## 2. 功能说明
- 主要功能是什么 (WHAT) + 简要 WHY
## 3. 核心算法/设计
- 复杂度(如有)+ 设计模式(如有)+ WHY 选择
## 4. 关键代码段
- 3-5 个核心代码段,每段简要说明作用
## 5. 依赖关系
- 外部库列表及用途
## 6. 快速使用示例
Standard Mode(15-20 分钟)⭐
# [代码名称] 深度理解分析
## 理解验证状态
| 核心概念 | 自我解释 | 理解"为什么" | 应用迁移 | 状态 |
|---------|---------|-------------|---------|------|
| [概念] | ✅/❌ | ✅/⚠️/❌ | ✅/❌ | [状态] |
## 1. 快速概览
## 2. 背景与动机(3 个 WHY)
## 3. 核心概念说明(每个概念 2-3 个 WHY)
## 4. 算法与理论(复杂度 + WHY + 参考)
## 5. 设计模式(WHY 使用 + 不用会怎样)
## 6. 关键代码深度解析(见第 6 步)
## 7. 依赖关系与使用示例(含 WHY 注释)
Deep Mode(30+ 分钟)
完整章节结构(严格按此编号,禁止引入 Phase/Part/Section 等额外层级):
# [代码名称] 深度理解分析
## 理解验证状态
## 项目完整地图(文件数 > 5 时)
## 1. 快速概览
## 2. 背景与动机(3 个 WHY)
## 3. 核心概念网络(每个概念 3 WHY + 概念关系矩阵)
## 4. 算法与理论(复杂度 + WHY + 参考)
## 5. 设计模式(WHY 使用 + 不用会怎样)
## 6. 关键代码深度解析
### 核心片段清单(6A)
### 片段 #1:[名称]
#### 1.1 代码整体作用
#### 1.2 核心逻辑分析
#### 1.3 逐行代码解释
#### 1.4 关键设计点
#### 1.5 完整示例(三组对比)
#### 1.6 使用注意与改进建议
### 片段 #2:[名称]
[同上 6 节结构,每片段编号与片段编号一致]
...
## 7. 测试用例分析(检测到测试文件时)
## 8. 应用迁移场景(至少 2 个)
## 9. 依赖关系与使用示例
## 10. 质量验证清单
## 覆盖率摘要(并行模式时)
⚠️ 关键规则:
## 6. 关键代码深度解析是唯一的核心代码分析章节,所有片段都在其下- 片段标题用
### 片段 #N:[名称],6 节用#### N.1 ~ N.6 - 禁止用
## Phase N、## 模块N、## 阶段N等自创章节层级打断编号连续性
9 步分析流程
第 1 步:快速概览
目标: 建立整体心智模型
识别:编程语言和版本、文件/项目规模、核心依赖、代码类型(算法/业务逻辑/框架等)
大型项目(文件数 > 5)必须额外生成项目地图:
## 项目完整地图
### 完整目录树
[使用工具枚举所有文件,生成树状结构]
### 文件清单(分类)
| 类别 | 文件路径 | 行数 | 职责摘要 |
|------|---------|------|---------|
| 核心逻辑 | [路径] | [行数] | [职责] |
| 工具模块 | [路径] | [行数] | [职责] |
| 测试 | [路径] | [行数] | [职责] |
| 配置 | [路径] | [行数] | [职责] |
### 入口文件 + 核心调用链
此步骤必须在分析任何具体代码之前完成,是防止遗漏信息的基础。
第 2 步:背景与动机(精细询问)
必须回答的 3 个 WHY:
- WHY 需要这段代码?(解决什么问题,不写会怎样)
- WHY 选择这种技术方案?(替代方案 + 权衡)
- WHY 这个时机/场景需要它?(应用场景 + 前后置条件)
输出格式:
## 背景与动机分析
### 问题本质
**要解决的问题:** [一句话描述]
**WHY 需要解决:** [不解决的后果]
### 方案选择
**WHY 选择这个方案:** 优势 / 劣势 / 权衡
**替代方案对比:**
- 方案 A:[简述] - WHY 不选:[原因]
- 方案 B:[简述] - WHY 不选:[原因]
### 应用场景
**适用场景:** [描述] — **WHY 适用:** [原因]
**不适用场景:** [边界条件] — **WHY 不适用:** [原因]
第 3 步:概念网络构建
目标: 建立概念间的连接,而非孤立记忆
必须包含:
- 每个核心概念回答 3 个 WHY(是什么 / WHY 需要 / WHY 这样实现 / WHY 不用其他)
- 概念关系映射:依赖/对比/组合,每条关系说明 WHY
- 连接到已有知识:设计模式、算法理论、领域原则
输出格式:
## 概念网络图
### 核心概念清单
**概念 N:[名称]**
- **是什么:** [简述]
- **WHY 需要:** [原因]
- **WHY 这样实现:** [原因]
- **WHY 不用其他方式:** [原因]
### 概念关系矩阵
| 关系类型 | 概念 A | 概念 B | WHY 这样关联 |
|---------|--------|--------|-------------|
| 依赖/顺序/对比 | [A] | [B] | [原因] |
第 4 步:算法与理论分析
每个算法/理论必须包含:
- 时间/空间复杂度
- WHY 选择这个算法(且复杂度可接受)
- 什么时候会退化
- 权威参考资料链接
输出格式:
## 算法与理论分析
### 算法:[名称]
- **时间复杂度:** [O(...)] **空间复杂度:** [O(...)]
- **WHY 选择:** [2-3 条理由]
- **WHY 复杂度可接受:** [说明]
- **WHY 不选其他:** [对比其他算法的理由]
- **退化场景:** [何时退化 + 如何规避]
- **参考:** [权威链接]
第 5 步:设计模式识别
每个设计模式必须包含:
- 模式名称 + 应用位置
- WHY 使用这个模式
- 不用这个模式会怎样
- 标准参考链接
输出格式:
## 设计模式分析
### 模式 N:[模式名]
**应用位置:** [类/函数名]
**WHY 使用:** [2-3 条理由]
**WHY 不用会怎样:** [后果]
**潜在问题:** ⚠️ [已知局限]
**参考:** [Refactoring Guru 等链接]
第 6 步:关键代码深度解析(两阶段工作流)
本步骤是整个分析的核心,分两个阶段。
阶段 6A:核心片段识别
适用条件: 文件数 > 5 或代码 > 500 行。小型/单文件代码跳过 6A,直接对全部代码执行 6B(1-3 个片段)。
识别标准(按优先级):
| 优先级 | 片段类型 | 识别特征 |
|---|---|---|
| ★★★ | 核心算法实现 | 复杂逻辑、循环嵌套、位运算 |
| ★★★ | 关键接口/抽象 | 系统边界处、被大量调用 |
| ★★☆ | 精妙设计 | 不常见实现方式、有趣权衡 |
| ★★☆ | 易错点集中区 | 边界处理、并发控制、内存管理 |
| ★☆☆ | 胶水代码 | 连接多模块的协调逻辑 |
输出格式:
## 核心片段清单
| 编号 | 片段名称 | 所在文件:行号 | 优先级 | 识别理由 |
|------|----------|--------------|--------|----------|
| #1 | [函数名] | [文件:起止行] | ★★★ | [理由] |
| #2 | [函数名] | [文件:起止行] | ★★☆ | [理由] |
**跳过说明:**
- [文件]:[跳过原因,如:仅数据结构定义,无复杂逻辑]
识别完成后,对每个片段单独执行阶段 6B。
阶段 6B:逐片段深度解读(6 节模板)
对每个核心片段,严格按以下 6 节结构输出:
⚠️ 硬性红线(主流程同样适用):
- 任何一节不得出现"略"、"同上"、"详见上文"、"此处省略"
- N.3 必须贴出真实代码片段(30行以上),不能只描述逻辑
- 每个 WHY 至少 2 句话,禁止单句结论
- 每片段 6 节合计不得少于 1000 字
### 片段 #N:[片段名称]
> 📍 **位置:** `文件路径:起止行号`
> 🎯 **优先级:** ★★★
> 💡 **一句话核心:** [用一句话概括这段代码的本质]
#### N.1 代码整体作用(≥150字)
[3~5 句话说明核心目标]
**它解决了什么问题?** 不用它会有什么后果?
**系统层次定位:** [业务逻辑 / 调度器 / 编译器前端 / IR 变换 / 等]
**角色与依赖:** 上游依赖什么?被下游如何使用?
#### N.2 核心逻辑分析(≥200字)
**执行流程:**
输入 → [步骤1] → [步骤2] → ... → 输出 ↓ [条件分支A / 条件分支B]
**关键算法/数据结构:** [名称] — 选择理由(至少2句解释WHY)?
**核心状态变量:**
| 变量名 | 初始值 | 变化时机 | 终态 |
|--------|--------|----------|------|
| [变量] | [初值] | [时机] | [终态] |
**多执行路径(至少2条):**
- **路径 A(正常):** 触发条件 → 关键状态变化 → 结果
- **路径 B(异常/边界):** 触发条件 → 关键状态变化 → 结果
#### N.3 逐行代码解释(≥300字,必须贴真实代码)
> **贯穿示例输入:** `[具体值]`
```[语言]
[贴出真实代码,不少于30行核心逻辑]
// 步骤 1: [操作描述]
[代码行]
// WHY: [理由,至少2句]
// 此时:[变量] = [值]
// 场景 1: [条件描述]
if [条件]:
[代码]
// WHY: [理由,至少2句]
注释风格规范:
# 场景 N: [描述]/// 场景 N: [描述]— 标注条件分支(if/else/switch)# 步骤 N: [描述]/// 步骤 N: [描述]— 标注串行执行流程# 此时: [变量] = [值]— 追踪变量状态
N.4 关键设计点(≥200字)
| 设计维度 | 分析内容(每项不少于2句) |
|---|---|
| 实现选择 | 为什么采用这种方式?有哪些备选方案?WHY不选备选? |
| 性能优化 | 内存、计算、并发方面的优化?量化说明(如有) |
| 编译器相关 | IR 变换/Pass 设计/调度策略?(不涉及则写"不涉及") |
| 安全与健壮性 | 边界检查、错误处理、异常路径? |
| 可扩展性 | 扩展点在哪里?如何扩展? |
| 潜在问题 | 已知局限、隐患或可改进之处? |
N.5 完整示例(三组对比,≥150字)
三个示例使用同一代码逻辑,仅改变输入,形成对比。
示例 1 — 基础场景
- 输入:
[具体值]→ 执行过程: [关键变量变化] → 输出:[结果]
示例 2 — 复杂/典型场景
- 输入:
[更复杂值]→ 关键差异: [与示例 1 的差异] → 结果: [输出]
示例 3 — 边界或异常情况
- 输入:
[极值/空值/非法输入]→ 处理方式: [是否有保护?崩溃还是降级?] → 结果及原因
N.6 使用注意与改进建议(≥100字)
使用此片段时需注意(≥2条,每条2句以上):
- [注意点 1 + 不注意会怎样]
- [注意点 2 + 不注意会怎样]
可考虑的改进(≥1条):
- [改进方向:具体描述 + WHY 更好(不少于2句)]
---
### 第 6.5 步:测试用例反向理解(检测到测试文件时执行)
**目标:** 通过测试用例反向验证和深化对代码功能的理解。测试是最准确的"使用说明书",覆盖边界条件和异常场景。
**检测测试文件的模式:**
| 语言 | 测试文件模式 | 常见目录 |
|------|-------------|---------|
| Python | `test_*.py`, `*_test.py` | `tests/`, `test/` |
| JavaScript/TypeScript | `*.test.ts`, `*.spec.ts` | `__tests__/` |
| Go | `*_test.go` | 与源码同目录 |
| Java | `*Test.java` | `src/test/java/` |
| C++ | `*_test.cpp` (gtest) | `test/`, `tests/` |
| MLIR/LLVM | `*.mlir` (测试文件) | `test/Dialect/*/` |
**输出格式:**
```markdown
## 测试用例分析
### 测试文件清单
| 测试文件/目录 | 测试的模块 | 测试用例数量 |
|--------------|-----------|-------------|
| [路径] | [模块] | [数量] |
### 功能覆盖矩阵
| 核心功能 | 主代码位置 | 测试覆盖 | 覆盖率评估 |
|---------|-----------|---------|-----------|
| [功能] | [位置] | ✅/⚠️/❌ | [评估] |
### 从测试中发现的边界条件
[选择 3-5 个最有价值的测试用例,说明它们揭示了哪些仅看代码容易遗漏的细节]
### 测试质量评估
- 正常流程:✅/⚠️/❌
- 边界输入:✅/⚠️/❌
- 异常输入:✅/⚠️/❌
- 并发场景:✅/⚠️/❌
### 测试质量建议
[如测试不足,提出具体改进建议]
第 7 步:应用迁移测试
目标: 检验概念能否迁移到不同场景,验证真实理解
必须包含: 至少 2 个不同领域的应用场景,每个场景说明:
- 不变的原理(核心思想)
- 需要修改的部分(具体代码/逻辑)
- WHY 这样迁移(连接到通用模式)
输出格式:
## 应用迁移场景
### 场景 1:[原始场景] → [新场景]
**不变的原理:** [列出保持不变的核心思想]
**需要修改的部分:**
[代码对比,含 WHY 注释]
**学到的通用模式:** [提取可复用的抽象模式]
### 场景 2:[原始场景] → [新场景]
[同上结构]
第 8 步:依赖关系与使用示例
每个依赖必须说明: WHY 选择 + WHY 不用替代方案
输出格式:
## 依赖关系分析
### 外部库
**[库名] (v[版本])**
- **用途:** [简述]
- **WHY 选择:** [2-3 条理由]
- **WHY 不用 [替代方案]:** [原因]
### 内部模块依赖
**[模块A] → [模块B]**
- **依赖原因:** [原因]
- **WHY 这样设计:** [设计原则]
## 完整使用示例
[完整可运行示例,含详细 WHY 注释]
第 9 步:质量验证清单
## 质量验证清单
### 理解深度
- [ ] 每个核心概念都回答了 3 个 WHY(需要/实现/不用其他)
- [ ] 自我解释测试:不看代码能解释每个核心概念
- [ ] 概念连接:标注了依赖/对比/组合关系及 WHY
### 技术准确性
- [ ] 算法:复杂度 + WHY 选择 + WHY 可接受 + 参考资料
- [ ] 设计模式:模式名 + WHY 使用 + 不用会怎样
- [ ] 代码解析:逐行 WHY + 具体数据执行示例 + 易错点
### 实用性
- [ ] 应用迁移:至少 2 个场景,不变原理 + 修改部分
- [ ] 使用示例:代码完整 + WHY 注释 + 执行结果
- [ ] 改进建议:指出问题 + WHY 是问题 + 改进方案
### 最终"四能"测试
根据这份分析文档(不看原代码):
1. ✅ 能否理解代码的设计思路?
2. ✅ 能否独立实现类似功能?
3. ✅ 能否应用到不同场景?
4. ✅ 能否向他人清晰解释?
**任何一项答"否",说明分析不够深入,需要补充。**
Deep Mode 并行处理详细流程(策略 B/C)
执行阶段
| 阶段 | 执行者 | 操作 | 输出 |
|---|---|---|---|
| 1. 项目地图 | 主 Agent | 枚举所有文件,建立完整目录树和模块清单 | 项目地图.md |
| 2. 框架准备 | 主 Agent | 基于项目地图,生成大纲、核心概念列表、章节到文件映射 | 00-框架.json |
| 3. 任务分发 | 主 Agent | 为每个章节创建独立任务,附上具体文件路径列表 | 任务列表 |
| 4. 并行执行 | 子 Agents | 每个子 Agent 专注一个章节,读取指定文件深度生成 | 章节-N.md |
| 5. 覆盖率校验 | 主 Agent | 对比项目地图,检查哪些文件/模块未被覆盖 | 覆盖率报告 |
| 6. 结果汇总 | 主 Agent | 合并所有章节,统一格式,写入最终文档 | 完整分析.md |
| 7. 质量验证 | 主 Agent | 检查深度标准,补充薄弱部分 | 最终文档 |
子 Agent 任务模板
# 子 Agent 任务:[章节名称]
## 上下文信息
- **代码名称:** [项目/代码名]
- **编程语言:** [语言]
- **核心概念:** [从主 Agent 传递的概念列表]
- **你负责的文件:** [明确列出具体文件路径]
- **其他模块摘要:** [简要说明其他模块职责,避免重复分析]
## 强制执行步骤
1. 用 Read 工具依次读取"你负责的文件"中的每一个文件
2. 确认文件内容后再开始分析(不能凭记忆或假设)
3. 分析内容必须引用实际代码行
## 特殊指令:如果你负责「关键代码解析」章节
必须执行两阶段工作流:
**阶段 1 — 核心片段识别(6A):**
读取所有指定文件后,筛选 3-7 个最值得深度解读的片段,按优先级:
1. ★★★ 核心算法实现(复杂逻辑/循环嵌套/位运算)
2. ★★★ 关键接口(系统边界处/被大量调用)
3. ★★☆ 精妙设计(不常见实现/有趣权衡)
4. ★★☆ 易错点集中区(边界处理/并发控制/内存管理)
5. ★☆☆ 胶水代码(连接多模块的协调逻辑)
先输出「核心片段清单」:
| 编号 | 片段名称 | 所在文件:行号 | 优先级 | 识别理由 |
**阶段 2 — 逐片段深度解读(6B):**
每个片段严格按 6 节输出,每节内容要求如下:
- **N.1 代码整体作用**(≥150字):核心目标 + 不用它的后果 + 系统层次定位 + 角色依赖关系
- **N.2 核心逻辑分析**(≥200字):文字执行流程图 + 算法/数据结构选型理由 + 核心状态变量表(变量名/初值/变化时机/终态)+ 至少2条执行路径说明
- **N.3 逐行代码解释**(≥300字,必须贴出实际代码):先定义贯穿示例(具体输入值),每行或每块用「场景/步骤 + WHY + 此时变量值」注释;禁止只贴代码不注释,也禁止省略核心逻辑行
- **N.4 关键设计点**(≥200字):用表格或条目覆盖:实现选择、性能优化、编译器相关(不涉及写"不涉及")、安全健壮性、可扩展性、潜在问题
- **N.5 完整示例(三组对比)**(≥150字):三组示例用同一代码逻辑,仅改变输入——基础/复杂/边界异常,每组写出输入→关键变量变化→输出
- **N.6 使用注意与改进建议**(≥100字):≥2 个使用注意点 + ≥1 个可考虑的改进方向(含WHY更好)
**⚠️ 硬性红线:**
- 任何一节不得出现"略"、"同上"、"详见上文"、"此处省略"
- N.3 必须贴出真实代码片段(30行以上),不能只描述逻辑
- 每个 WHY 至少 2 句话,禁止单句结论
## 输出要求
- 本章节至少 [X] 字,每个 WHY 至少 2-3 句话
- 代码注释使用场景/步骤 + WHY 风格
- 提供权威参考链接
- 负责文件中每个公共函数/类都必须提及
## 深度自检
- [ ] 所有指定文件都已读取
- [ ] 所有子项都已覆盖(不能有"略"或"同上")
- [ ] 每个 WHY 至少 2-3 句话
- [ ] 代码示例有完整注释
- [ ] 执行流程有具体数据追踪
- [ ] 「关键代码解析」已输出核心片段清单 + 每个片段的 6 节深度解读
直接输出 Markdown 格式,以 `## [章节名称]` 开头。
覆盖率校验格式
## 覆盖率校验报告
### 文件覆盖情况
| 文件路径 | 是否被分析 | 分析章节 | 备注 |
|---------|-----------|---------|------|
| [路径] | ✅/❌ | [章节] | [说明] |
### 模块覆盖率
- 核心模块:X/Y 已覆盖(目标:100%)
- 工具模块:X/Y 已覆盖
- 测试文件:X/Y 已覆盖(目标:≥ 80%)
### 未覆盖内容处理
- 重要文件(核心业务):立即补充分析
- 次要文件(配置/工具):在依赖关系章节简要提及
- 测试文件:确认已在测试用例分析章节覆盖
策略 C:超大项目分层并行(文件数 > 20 或行数 > 10000)
- 阶段 1 — 模块级扫描(串行): 将项目按目录/功能分为 3-8 个模块,为每个模块生成独立的模块摘要(子 Agent 并行)
- 阶段 2 — 章节级分析(并行): 每个章节子 Agent 获取完整项目地图 + 负责模块摘要 + 需要深入阅读的关键文件列表
- 阶段 3 — 汇总: 同策略 B
深度自检清单(每章完成后检查)
## 章节深度自检
### 内容完整性
- [ ] 所有子项已覆盖(不能有"略"、"详见上文"、"同上")
- [ ] 每个 WHY 有具体解释(至少 2-3 句话)
- [ ] 代码示例有完整注释(场景/步骤 + WHY)
- [ ] 引用有来源链接
### 分析深度(按章节类型)
- **概念类:** 每个概念 3 个 WHY(需要/实现/不用其他)
- **算法类:** 复杂度 + WHY 选择 + WHY 可接受 + 退化场景
- **设计模式类:** 模式名 + WHY 使用 + 不用会怎样
- **代码解析类:** 核心片段清单(≥3 个,含文件:行号 + 优先级 + 理由)+ 每片段 6 节解读 + 贯穿示例 + 三组对比
### 各章最低字数与必含元素
| 章节 | 最低字数 | 必含元素 |
|-----|---------|---------|
| 1. 快速概览 | 200 | 语言、规模、依赖、类型 |
| 2. 背景与动机 | 400 | 问题本质、方案选择、应用场景 |
| 3. 核心概念 | 600 | 每概念 3 WHY、关系矩阵 |
| 4. 算法与理论 | 500 | 复杂度、WHY、参考资料 |
| 5. 设计模式 | 400 | 模式名、WHY、标准参考 |
| 6. 关键代码解析 | 每片段≥1000字(3片段起步即≥3000字)| 片段清单、每片段 6 节(含真实代码≥30行、三组对比示例)|
| 7. 测试用例分析 | 400 | 测试覆盖、边界条件、测试发现 |
| 8. 应用迁移 | 500 | ≥2 场景、不变原理、修改部分 |
| 9. 依赖关系 | 300 | 每依赖的 WHY、使用示例 |
| 10. 质量验证 | 200 | 验证清单、四能测试 |
**Deep Mode 文档应 ≥ 8000 字(含代码注释)**
**⚠️ 关键提醒:章节编号必须连续,禁止用 Phase/模块/阶段等词打断编号**
Token 优化输出策略
| 模式 | 生成方式 | 文件数量 |
|---|---|---|
| Quick | 单次 Write | 1 |
| Standard | 单次 Write | 1 |
| Deep ≤ 2000 行(策略 A) | 渐进式 Write(先框架,逐节填充) | 1-2 |
| Deep > 2000 行(策略 B/C) | 并行子 Agent → 汇总 Write | 多个临时章节 → 1 个最终文档 |
核心原则:完整分析直接写入文件,对话中仅输出摘要。
## 分析完成
**模式:** [Quick/Standard/Deep]
**核心发现:**
- 代码实现了 [核心功能]
- 使用 [算法/模式] 解决 [问题]
- 关键优化点:[优化点]
- 潜在问题:[问题]
**完整文档:** `[代码名称]-深度分析.md`
文件命名:
- 单文件:
[代码名称]-深度分析.md - 多文件项目:
[项目名]-概述.md+[模块名]-分析.md - 大型项目:
work/项目地图.md+work/chapters/章节-N.md+[项目名]-完全掌握分析.md
人性化写作要点
分析文档必须读起来像有经验的工程师在讲解,而非照本宣科堆砌术语。
核心要求:
- 口语化引导,而非直接甩定义 — 用"这个函数是整个系统的门卫——每次登录都要经过它"而非"该函数负责执行身份验证流程"
- 先说结论,再展开原因 — 用"用 bcrypt 而不用 MD5,根本原因是 MD5 太快了"而非"由于 bcrypt 具有自适应性哈希函数特性……"
- 善用类比 — 讲锁机制比作图书馆阅览规则,讲缓存比作把常用的东西放桌上
- 代码注释说人话 — 说明意图和原因,而非重复代码字面意思
- 复杂概念分层解释 — 先一句话直觉理解,再补充技术细节
- 顺手标注易错点 — 用 ⚠️ 标注常见误区
禁止的写法:
- 大段罗列术语不加解释
- "该函数实现了 X 功能"(读者已知)
- WHY 解释只有一句话
- 照抄官方文档措辞
自检问题: 一个刚入行的工程师能看懂吗?有没有让读者有"原来如此!"的感觉?
Decide Fit First
Design Intent
How To Use It
Boundaries And Review