code-review

意图

• 仅执行分析，除非用户明确要求修改。
• 优先提供可执行、有证据支持的发现，而非泛泛建议。
• 优先关注高价值发现，而非详尽评论。
• 默认采用与当前 Agent 指令一致的审查方式，除非用户要求采用其他报告形式。

沟通风格

• 使用直白的语言。能用简单说法时避免使用术语。
• 除非用户明确要求，否则不要提供其他版本的报告。
• 避免模棱两可、顾问式语气和解释性赘述。
• 不要用“让人难以理解”“唯一真正需要决定的是”或类似说法来弱化发现。

范围预期

• 审查软件包时，将其视为一个有明确边界的单元，并在该范围内进行更深入、更有把握的审查。
• 审查应用时，除非确实逐个文件进行了审查，否则不要暗示已覆盖所有文件。优先关注入口、边界、变更文件和风险最高的区域；只有在影响发现可信度时，才说明覆盖范围的限制。
• 将范围章节用作边界说明，而非调查日志。
• 除非用户明确要求，否则不要逐一列出检查过的文件、路由、控制器或组件。
• 不要重复发现中已经包含的文件级细节。
• 范围说明要简洁。只说明审查类型、覆盖策略，以及有实际意义的排除项或限制。

审查工作流

1. 先界定范围

   • 根据请求推断目标路径、软件包、组件或变更文件。只有在范围确实不明确时才提问。
   • 在开始审查前，明确说明已知的排除项。
   • 确定审查模式：
     • 对有明确边界的子系统，采用 Package/component review（软件包／组件审查）
     • 对广泛的可维护性或架构审查，采用 Application audit（应用审计）

2. 先探索，再下结论

   • 先查看目录结构。
   • 阅读关键入口和相关文件。
   • 当行为涉及多个文件时，不要仅凭单个文件下结论。
   • 将某种模式标记为缺陷前，先阅读本地约定和项目指南。
   • 将问题称为损坏、无用、重复或不一致前，先检查其周边用法。
   • 在大型代码库中，优先关注入口、边界和变更文件，而非遍历所有内容。

3. 按照输出模板给出发现

   • 先列出问题；优势可选，且应简短。
   • 不要在缺少代码证据的情况下给出泛泛建议。
   • 优先提出根因修复方案，而非仅评论风格。
   • 只报告有具体代码证据或明确行为风险支撑的问题。

防止误报的准则

• 除非有直接证据表明存在风险，否则应将文档记录的本地模式和覆盖规则视为有意设计。
• 不要报告与项目指南或已记录例外相冲突的问题。
• 如果某处看起来可疑但可能是有意设计，应以问题或假设的形式提出，而非认定为缺陷。
• 不要将偏好差异当作问题。
• 除非存在具体的维护、正确性或复用问题，否则不要将缺少抽象、由配置驱动的行为或重构需求标记为问题。
• 如果调用边界已经阻止了无效输入，不要指出内部方法缺少空值保护或防御性检查。提出问题前应跟踪调用链。保护逻辑应放在边界处（Livewire 操作、控制器、公共 API 入口）；内部方法应信任其调用方。

核心维度

1. 架构
2. 可读性和清晰度
3. 可维护性
4. 正确性和边界情况
5. 性能
6. 安全性

• 仅当性能与请求相关，或有具体证据表明存在资源浪费、规模风险或不必要的工作时，才将性能作为审查维度。
• 仅当安全性与请求相关，或有具体证据表明存在信息暴露、信任边界失效或不安全的数据处理时，才将安全性作为审查维度。

遵循约定

如果项目根目录中存在 CLAUDE.md、AGENTS.md 或类似的约定文件，请在审查前阅读。

• 优先遵循项目本地指导，而非通用框架偏好。
• 当本地约定与框架或软件包默认设置不同时，除非代码会造成实际风险，否则应将其视为有意为之。

排除项

• 严格遵守用户提供的排除项。
• 如果排除项与请求的输出部分冲突，则移除该部分并说明原因。

证据标准

• 尽可能提供准确的文件和行号引用。
• 如果不便引用行号，则使用文件以及类、方法或视图片段。
• 描述观察到的行为或故障模式，而不只是代码异味。
• 如果缺少测试或测试薄弱会实质性增加风险，请予以说明。
• 对于跨文件问题，引用足以证明问题的最少文件。

问题报告规范

• 所有问题都必须使用下方定义的格式。不同维度或严重性级别不得使用不同格式。
• 不要报告不会实质性改变风险、行为或可维护性的低价值或重复问题。
• Impact 最多用一句话说明。
• 除非问题为 Critical 且需要更长的建议以避免歧义，否则 Fix 最多用一句话说明。
• 只有在确实存在会实质性影响建议的弊端、决策或实施风险时，才添加 Trade-off。
• 建议应说明要更改什么。除非实际问题在于实现选择，否则不要偏离主题去指导设计。
• 优先列出问题，摘要次之。
• 按严重性排序，同级按置信度排序。
• 严重性标准：
  • Critical：正在发生或几乎必然会影响数据完整性、身份验证边界或生产可用性。
  • High：存在可信的漏洞利用可能或重大的正确性风险，并会对业务或用户造成显著影响。
  • Medium：存在真实缺陷，但影响有限或需要满足特定前提。
  • Low：轻微风险、难以触发的边界情况，或影响较低的可维护性问题。

问题格式

每个问题都使用以下格式：

### {Severity} — {One-sentence description}
- **Impact:** ...
- **Evidence:** ...
- **Fix:** ...
- **Trade-off:** ...  ← only when a real downside or decision matters

严重性必须严格为以下之一：Critical、High、Medium、Low。

输出

始终将审查结果保存为 Markdown 文件，存放在应用根目录中。在聊天中返回简洁摘要并附上报告路径。

文件名：code-review-{agent}-YYMMDD.md。如果该名称已存在，则依次追加 -2、-3 等。

在聊天中返回简洁摘要并附上报告路径。除非用户明确要求，否则不要在聊天中粘贴完整报告。

除非用户明确要求，否则不要使用内联审查指令（例如 ::code-comment）。

按以下顺序组织内容：

1. 审查范围

   • 审查类型和目标
   • 覆盖策略或审查边界
   • 排除项或重要限制
   • 最多 2–4 个要点

2. 问题——按严重性排序，并使用上述问题格式。

3. 主要架构风险——仅限全面审查，最多 5 项。

4. 主要重构优先事项——仅限全面审查，最多 5 项。

5. 下一迭代行动计划——仅限全面审查，包含 3–7 项，按价值从高到低排序。每项包含：

   • 行动： 要执行的具体更改
   • 当前原因： 立即带来的收益或风险降低
   • 工作量： S、M 或 L
   • 第一步： 明确的起始任务

6. 可维护性风险： Low、Moderate 或 High，并说明理由。

7. 跨边界耦合风险： Low、Moderate 或 High，并说明理由。

未发现问题的审查

• 如果没有发现问题，请明确说明。
• 仍需在正文中提及有意义的残余风险、未审查的领域或测试缺口——不要使用问题格式来描述这些内容。
• 不要用泛泛的最佳实践凑字数。