code-walkthrough

name code-walkthrough version 1.0.0 last_updated 2026-04-08T00:00:00.000Z repository https://github.com/312362115/claude description 代码导读技能：帮助快速理解不熟悉的项目或模块，建立心智模型。 从全局架构到核心流程再到关键设计决策，分层递进地梳理代码。 不是简单地读文件列目录，而是提炼出"这段代码在做什么、为什么这么做、和其他部分怎么连接"。 触发词：帮我梳理一下、这块代码怎么运作的、导读、接手项目、看看这个模块、代码走读、walkthrough。 触发场景：接手新项目、进入不熟悉的模块、重构前理解现状、Code Review 需要理解上下文。 即使用户没有说"导读"，只要意图是"理解一段不熟悉的代码"，都应触发此技能。 代码导读（Code Walkthrough） 读代码和读书一样——先看目录了解结构，再看核心章节理解逻辑，最后看细节。 不是逐行翻译代码，而是帮读者建立"这个系统怎么运转"的心智模型。 第一步：确定导读范围和深度 导读请求 │ ├─ 整个项目？ │ └─ 全局导读：项目架构 → 模块职责 → 核心流程 → 关键决策 │ ├─ 某个模块/目录？ │ └─ 模块导读：模块职责 → 内部结构 → 核心逻辑 → 对外接口 │ └─ 某个具体功能/流程？ └─ 流程导读：入口 → 数据流 → 关键分支 → 输出 用 AskUserQuestion 确认： 导读目标 ：看什么？整个项目、某个模块、还是某个功能？ 导读目的 ：为什么要看？接手维护、准备改动、还是纯了解？ 已有认知 ：对这块代码已经了解多少？（避免输出用户已知的信息） 第二步：全局扫描 不管导读什么范围，先花 2-3 个工具调用建立全局感知： 2.1 项目全局（如果是项目/模块导读） 1. 读项目根目录结构（ls / Glob） 2. 读配置文件（package.json / pyproject.toml / tsconfig.json） 3. 读 README / CLAUDE.md / docs/（如果有） 4. 检查 git log 最近 20 条提交（了解活跃区域） 提取关键信息： 技术栈 ：语言、框架、主要依赖 项目类型 ：前端应用 / 后端服务 / 全栈 / CLI 工具 / 库 目录组织 ：按功能分还是按类型分？有没有约定 2.2 目标区域 定位到导读目标后，了解： 入口文件 ：这个模块/功能从哪里开始？ 文件清单 ：涉及哪些文件？各自大概多少行？ 依赖关系 ：依赖了什么外部模块？被谁依赖？ 第三步：分层梳理 按照 架构 → 流程 → 细节 的顺序递进，每一层解决不同的问题。 Layer 1：架构层 — "系统由什么组成" 回答： 这个系统/模块的整体结构是什么？各部分各司什么职？ 输出格式： ## 架构概览 ### 模块组成 - `src/api/` — API 路由层，接收请求、参数校验、调用 service - `src/services/` — 业务逻辑层，核心计算和编排 - `src/models/` — 数据模型，定义实体和数据库交互 - `src/utils/` — 工具函数，无业务语义 ### 依赖关系 api → services → models ↓ utils ### 数据流向 请求 → 路由 → 中间件（认证/校验）→ service → model → 数据库 ↓ 响应 ← 路由 ← ─────────────────────── service ← model Layer 2：流程层 — "核心功能怎么运转" 回答： 一个请求/操作从头到尾经过了哪些步骤？ 选择 1-3 个 最核心的流程 做详细走读： ## 核心流程 ### 流程 1：用户登录 1. `POST /api/login` → `src/api/auth.ts:handleLogin()` - 参数校验：email + password 2. → `src/services/auth.ts:login()` - 查询用户： `UserModel.findByEmail(email)` - 验证密码： `bcrypt.compare(password, user.hash)` - 生成 token： `jwt.sign({ userId: user.id }, secret, { expiresIn: '7d' })` 3. → 返回： `{ token, user: { id, name, email } }` 关键点： - token 过期时间 7 天，写死在代码里（可能需要改为配置） - 密码验证用 bcrypt，安全 - 没有登录失败次数限制 Layer 3：细节层 — "关键设计决策和隐含知识" 回答： 为什么这么写？有什么不明显的约定或陷阱？ ## 关键设计决策 ### 决策 1：为什么用 Redis 做 session 而不是 JWT 无状态？ - 见 `docs/specs/2026-03-23-auth-session-design.md` （如果有文档） - 或从代码推断：支持主动注销（删 Redis key 即失效） ### 决策 2：为什么 UserModel 同时用了 ORM 和 raw SQL？ - ORM 用于常规 CRUD - raw SQL 用于复杂聚合查询（ `src/models/user.ts:237` 的注释说明了原因） ## 隐含约定 - 所有 API 响应统一包装为 `{ code, data, message }` 格式（见 `src/middleware/response.ts` ） - 错误处理走全局 error handler（ `src/middleware/error.ts` ），不需要每个路由单独 catch - 环境变量从 `.env` 加载，必填项在 `src/config.ts` 中校验 ## 注意事项 / 潜在风险 - `src/services/order.ts:89` — 库存扣减没有并发保护 - `src/utils/cache.ts` — 缓存 key 没有 namespace，多服务共用可能冲突 第四步：输出导读文档 输出格式 根据导读深度选择输出方式： 深度 输出 快速了解（聊天中回答） 直接在对话中输出，不存文件 完整导读（需要沉淀） 写入 docs/guides/<模块名>-walkthrough.md 完整导读文档结构 # 代码导读：<模块/项目名> > 一句话概括这个模块/项目做什么 ## 技术栈 - 语言/框架/主要依赖 ## 架构概览 （Layer 1 的输出） ## 核心流程 （Layer 2 的输出，1-3 个关键流程） ## 关键设计决策 （Layer 3 的输出） ## 隐含约定 （不写在代码注释里但需要知道的规则） ## 注意事项 （潜在风险、技术债、容易踩的坑） ## 相关文档 - 指向 docs/ 下的相关 spec、plan、decision 导读准则 不逐行翻译 ：读者是开发者，能读代码。导读要提炼的是"代码没直接告诉你的东西"——架构意图、设计理由、隐含约定 先宏观后微观 ：先给全景地图，再放大关键区域。不要一上来就钻进某个函数 关注连接 ：模块之间怎么交互？数据怎么流转？比单个模块内部逻辑更重要 标注位置 ：提到具体逻辑时标注 文件:行号 ，方便读者跳转查看 诚实说不知道 ：如果某个设计决策从代码看不出原因，说"从代码推断可能是因为 X，但不确定"，不要编理由 按读者水平调整 ：用户说"我是 Go 高手但不懂 React"，就用 Go 的类比解释 React 的概念 与其他 skill 的关系 接手新项目 → code-walkthrough（建立心智模型） ↓ 准备改动 → refactoring（影响分析可以复用导读的架构理解） ↓ 改动前评估 → dependency-map（导读关注"是什么"，依赖分析关注"改了影响谁"） code-walkthrough vs dependency-map 的区别 ： code-walkthrough：理解代码，回答"这是什么、怎么运转、为什么这么写" dependency-map：评估影响，回答"改这里会动到哪里" 通常先 walkthrough 理解，再 dependency-map 评估影响