企业官网建设流程全解析

Code Review Finding Template

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

Use this template when documenting each issue found during code review.

Issue: [TITLE]

Severity

• Critical (blocks deployment)
• High (should fix before merge)
• Medium (should fix soon)
• Low (nice to have)

Category

• Security
• Performance
• Code Quality
• Maintainability
• Testing
• Design Pattern
• Documentation

Location

File:src/components/UserCard.tsx

Lines:45-52

Function/Method:renderUserDetails()

Issue Description

What:Describe what the issue is.

Why it matters:Explain the impact and why this needs to be fixed.

Current behavior:Show the problematic code or behavior.

Expected behavior:Describe what should happen instead.

Code Example

Current (Problematic)

// Shows the N+1 query problem const users = fetchUsers(); users.forEach(user => { const posts = fetchUserPosts(user.id); // Query per user! renderUserPosts(posts); });

Suggested Fix

// Optimized with JOIN query const usersWithPosts = fetchUsersWithPosts(); usersWithPosts.forEach(({ user, posts }) => { renderUserPosts(posts); });

Impact Analysis

Related Issues

• Similar issue inAdminUserList.tsxline 120
• Related PR: #456
• Related issue: #789

Additional Resources

• N+1 Query Problem 参考文档（替换为你的内部文档或团队 Wiki 链接）
• Database Join 官方文档链接（替换为项目内维护的资料）

Reviewer Notes

• This is a common pattern in this codebase
• Consider adding this to the code style guide
• Might be worth creating a helper function

Author Response (for feedback)

To be filled by the code author:

• Fix implemented in commit:abc123
• Fix status: Complete / In Progress / Needs Discussion
• Questions or concerns: (describe)

Finding Statistics (for Reviewer)

When reviewing multiple findings, track:

• Total Issues Found:X
• Critical:X
• High:X
• Medium:X
• Low:X

Recommendation:✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion

Overall Code Quality:1-5 stars

可以观察到模板按"**单条问题详情 + 汇总统计**"两段组织：上半段是一条 finding 的完整档案，下半段是对一批 finding 的聚合决策，二者配合构成一次审查的完整输出。 ## Severity 与 Category：先给问题定级、归类 模板把每个问题的"重要性"与"性质"拆成两个独立的单选维度，避免把"严重的安全漏洞"和"轻微的风格问题"混为一谈。 **四级 Severity 及其隐含的处理节奏**（以模板中的复选框注释为准）： | 级别 | 模板语义 | 处理要求 | |------|----------|----------| | Critical | blocks deployment | 阻塞发布，上线前必须解决 | | High | should fix before merge | 合入前应修复 | | Medium | should fix soon | 尽快安排修复即可 | | Low | nice to have | 锦上添花，可延后 | 严重度直接决定这条 finding 是"必须打断发布"还是"可排队处理"，是后续 Finding Statistics 汇总与 Approve / Request Changes 决策的基础。这与同仓库 [code-reviewer 子代理](https://link.gitcode.com/i/e7db80c60fc53d50d8b87eb11c48d6d4) 的输出分级一致，该子代理要求每条问题同样标注 Severity: Critical / High / Medium / Low，并按"必须先修的严重问题 → 应修警告 → 可优化建议"的顺序组织反馈。 **七类 Category**：Security、Performance、Code Quality、Maintainability、Testing、Design Pattern、Documentation。它实际上把 [SKILL.md](https://link.gitcode.com/i/1588033c97350791aa391c48c741a630) 关注的四大维度（安全分析、性能审查、代码质量、可维护性）扩成了更细的枚举——额外拆出了 Testing、Design Pattern 与 Documentation。分类不是形式主义：它决定了这条 finding 应该挂到哪张子清单上、由谁跟进，也方便统计某类问题的密度。模板作者还专门设计了复选框（`- [ ]`），一张 PR 里的每条 finding 都只能且必须勾选一个级别、一个类别，杜绝了"未定级"的模糊条目。 ## Location：让问题"一秒钟被找到" 再清晰的问题描述，若找不到代码位置也等于零。模板用三个字段做精确定位： - **File**：完整文件路径，例如 `src/components/UserCard.tsx`； - **Lines**：精确到行区间，例如 `45-52`； - **Function/Method**：定位到具体函数，例如 `renderUserDetails()`。 三项合起来给出了"文件 → 行号 → 函数"三层导航信息，评审者无需全文检索即可直达现场，作者也能立即对照上下文修改。实践上建议行号随代码变更及时回填，避免 diff 之后行号漂移导致引用失效。 ## Issue Description 与 Code Example：把"问题"讲成一段可执行的故事 这是模板信息密度最高的部分，采用"四段式描述 + 双代码块"的结构。 **四段式描述**要求逐项回答四个问题： | 字段 | 要回答的问题 | |------|--------------| | What | 问题本身是什么 | | Why it matters | 为什么必须修，影响面在哪 | | Current behavior | 当前实际行为/代码是怎么样的 | | Expected behavior | 正确行为应该是什么样 | **双代码块**则用"问题代码 / 建议修复"对照呈现。模板内置的 TypeScript 示例正是 [review-checklist.md](https://link.gitcode.com/i/64e07bef26a6fd377a67880cd4caee9a) 性能清单中 "No N+1 queries" 检查项对应的经典问题： ```typescript // 问题版：循环内逐用户发查询，20 个用户触发 20+ 次查询（N+1 问题） const users = fetchUsers(); users.forEach(user => { const posts = fetchUserPosts(user.id); // Query per user! renderUserPosts(posts); });

// 修复版：改为一次 JOIN 联查批量取数 const usersWithPosts = fetchUsersWithPosts(); usersWithPosts.forEach(({ user, posts }) => { renderUserPosts(posts); });

问题版在循环体内为每个user.id发起一次数据库查询——这就是 N+1 查询的典型形态：1 次用户列表查询 + N 次关联查询；修复版则一次性联查带回全部posts，把查询次数收敛为常数级。模板强调两点约定：一是两个代码块必须成对出现，只有问题没有修复方案、或只给结论不给证据，都会让 finding 失去可操作性；二是代码块都要标注语言（如```typescript），便于高亮与复制。

Impact Analysis：用一张表量化影响的广度

描述部分回答"问题是什么"，Impact Analysis 则回答"问题牵动哪些方面、各自多严重"。模板把定性描述升级为多维度影响矩阵：

每条影响用一行"Aspect / Impact / Severity"表达，把一个 N+1 问题同时映射到性能、体验、扩展性、可维护性四个维度——同一个问题在不同维度上的严重度可以不同（例如本例中"扩展性"层面是 Critical，而"可维护性"层面仅为 Medium）。这一表格也是说服作者尽快修复的最有力论据：影响不是主观抱怨，而是可量化、可核对的清单。填写建议：Impact 列尽量给出数量级（如查询次数、耗时、内存量），避免"变慢了很多"这类模糊表述。

上下游关联：Related Issues / Additional Resources / Reviewer Notes

模板接着用三个板块把一条 finding 放进更大的上下文：

• Related Issues：关联同类问题的其他文件、PR、issue，如AdminUserList.tsxline 120、PR #456、issue #789。这能帮助发现"同一反模式是否扩散到全库"，是判断该问题属于个案还是系统性问题的一手证据；
• Additional Resources：附上参考文档与资料链接，帮助作者理解问题背景与标准解法（例如 N+1 问题的原理说明、JOIN 查询的官方文档）；
• Reviewer Notes：记录评审者的补充观察，例如"这是本代码库中的常见模式""建议把它写进代码风格指南""或许值得抽一个公共辅助函数"——这些开放性建议是 Code Quality 与 Maintainability 改进的重要输入。

Author Response：让模板成为审查对话的载体

模板末尾为代码作者预留了反馈区，包含三个动作项：

• Fix implemented in commit: abc123：修复已落地并给出 commit；
• Fix status: Complete / In Progress / Needs Discussion：标记当前处理状态；
• Questions or concerns：记录作者的疑问或异议。

这意味着 finding 不是单向"评审者下发、作者被动接收"，而是一个带状态机的工作项：作者在abc123提交修复后勾选 Complete，评审者再去复核关闭。若作者有不同意见，也可通过 Needs Discussion 发起澄清，避免无效往返。与仓库中 07-plugins/pr-review/commands/review-pr.md 这类 PR 审查命令配合使用时，模板天然可以作为 PR 评论的规范格式。

Finding Statistics：从单条记录到整体决策

当一次审查产出多条 finding 后，模板进入下半段——为 Reviewer 准备的统计区：

• Total Issues Found / Critical / High / Medium / Low：按严重度聚合计数；
• Recommendation：✅ Approve（通过）/ ⚠️ Request Changes（要求修改）/ 🔄 Needs Discussion（需要讨论）；
• Overall Code Quality：1-5 星的整体质量评分。

这条"汇总层"让模板同时服务两个角色：逐条记录服务"作者修什么"，聚合统计服务"Reviewer 是否放行"。例如若 Critical 与 High 合计大于 0，Recommendation 几乎必然是 Request Changes；若只有 Low 级条目，则可 Approve 并把条目转为 backlog。整体星级则便于团队横向对比不同模块、不同时段的代码质量趋势。仓库中 04-subagents/code-reviewer.md 对整体输出同样要求 Summary（总体质量评估、发现数量、优先改进区域），与这里的统计区互为印证。

配套量化脚本：让每条 finding 都有数据背书

code-review-specialist 技能为模板补充了"量化证据"来源，使审查结论不依赖主观印象。

analyze-metrics.py 对单个文件统计四类指标：函数数量（^def正则匹配）、类数量（^class）、平均行长度、复杂度评分（统计if/elif/else/for/while/and/or等关键词出现次数）。运行方式：

python analyze-metrics.py <待审查文件.py>

输出示例（格式取自脚本 analyze-metrics.py）：

functions: 12.00 classes: 2.00 avg_line_length: 34.56 complexity_score: 18.00

compare-complexity.py 则用于对比重构前后两版文件，从 ComplexityAnalyzer 类 的实现可见它计算三类指标：

• Cyclomatic Complexity（圈复杂度）：按 McCabe 方法，以if/elif/for/while/except/and/or等判定点为基数从 1 累加；
• Cognitive Complexity（认知复杂度）：结合嵌套深度与控制流评估理解难度（if/for/while/def/class/try每深入一层加权）；
• Maintainability Index（可维护性指数，0-100）：由代码行数、圈复杂度与认知复杂度按公式171 - 5.2×(cyclomatic/lines) - 0.23×cognitive - 16.2×(lines/1000)估算，>85为 Excellent、>65为 Good、>50为 Fair、<50为 Poor。

运行方式：

python compare-complexity.py <重构前文件> <重构后文件>

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto