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-howtoUse this template when documenting each issue found during code review.Issue: [TITLE]SeverityCritical (blocks deployment)High (should fix before merge)Medium (should fix soon)Low (nice to have)CategorySecurityPerformanceCode QualityMaintainabilityTestingDesign PatternDocumentationLocationFile:src/components/UserCard.tsxLines:45-52Function/Method:renderUserDetails()Issue DescriptionWhat: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 ExampleCurrent (Problematic)// Shows the N1 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 AnalysisAspectImpactSeverityPerformance100 queries for 20 usersHighUser ExperienceSlow page loadHighScalabilityBreaks at scaleCriticalMaintainabilityHard to debugMediumRelated IssuesSimilar issue inAdminUserList.tsxline 120Related PR: #456Related issue: #789Additional ResourcesN1 Query Problem 参考文档替换为你的内部文档或团队 Wiki 链接Database Join 官方文档链接替换为项目内维护的资料Reviewer NotesThis is a common pattern in this codebaseConsider adding this to the code style guideMight be worth creating a helper functionAuthor Response (for feedback)To be filled by the code author:Fix implemented in commit:abc123Fix status: Complete / In Progress / Needs DiscussionQuestions or concerns: (describe)Finding Statistics (for Reviewer)When reviewing multiple findings, track:Total Issues Found:XCritical:XHigh:XMedium:XLow:XRecommendation:✅ Approve / ⚠️ Request Changes / Needs DiscussionOverall 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 N1 queries 检查项对应的经典问题 typescript // 问题版循环内逐用户发查询20 个用户触发 20 次查询N1 问题 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发起一次数据库查询——这就是 N1 查询的典型形态1 次用户列表查询 N 次关联查询修复版则一次性联查带回全部posts把查询次数收敛为常数级。模板强调两点约定一是两个代码块必须成对出现只有问题没有修复方案、或只给结论不给证据都会让 finding 失去可操作性二是代码块都要标注语言如typescript便于高亮与复制。Impact Analysis用一张表量化影响的广度描述部分回答问题是什么Impact Analysis 则回答问题牵动哪些方面、各自多严重。模板把定性描述升级为多维度影响矩阵AspectImpactSeverityPerformance100 queries for 20 usersHighUser ExperienceSlow page loadHighScalabilityBreaks at scaleCriticalMaintainabilityHard to debugMedium每条影响用一行Aspect / Impact / Severity表达把一个 N1 问题同时映射到性能、体验、扩展性、可维护性四个维度——同一个问题在不同维度上的严重度可以不同例如本例中扩展性层面是 Critical而可维护性层面仅为 Medium。这一表格也是说服作者尽快修复的最有力论据影响不是主观抱怨而是可量化、可核对的清单。填写建议Impact 列尽量给出数量级如查询次数、耗时、内存量避免变慢了很多这类模糊表述。上下游关联Related Issues / Additional Resources / Reviewer Notes模板接着用三个板块把一条 finding 放进更大的上下文Related Issues关联同类问题的其他文件、PR、issue如AdminUserList.tsxline 120、PR #456、issue #789。这能帮助发现同一反模式是否扩散到全库是判断该问题属于个案还是系统性问题的一手证据Additional Resources附上参考文档与资料链接帮助作者理解问题背景与标准解法例如 N1 问题的原理说明、JOIN 查询的官方文档Reviewer Notes记录评审者的补充观察例如这是本代码库中的常见模式建议把它写进代码风格指南或许值得抽一个公共辅助函数——这些开放性建议是 Code Quality 与 Maintainability 改进的重要输入。Author Response让模板成为审查对话的载体模板末尾为代码作者预留了反馈区包含三个动作项Fix implemented in commit: abc123修复已落地并给出 commitFix 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 Quality1-5 星的整体质量评分。这条汇总层让模板同时服务两个角色逐条记录服务作者修什么聚合统计服务Reviewer 是否放行。例如若 Critical 与 High 合计大于 0Recommendation 几乎必然是 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.pyfunctions: 12.00 classes: 2.00 avg_line_length: 34.56 complexity_score: 18.00compare-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考