first-five

First Five

参数

原始参数：$ARGUMENTS

将参数解析为要进行差异比较的基准分支。如果为空，则默认为 main。

目标

根据 First Five 检查清单扫描基准分支与 HEAD 之间发生变更的文件，并且仅报告值得调查的问题。这是一份简短、便于浏览的初步筛查清单，不是完整审查，也不是逐行罗列。

五项检查：

1. 错误处理 — 空的 catch 块、易失败调用缺少错误处理路径、异常被吞掉、静默失败。
2. 输入边界 — 缺少对用户输入的长度／类型／格式验证、未经验证就使用请求字段、无界输入被发送到数据库或外部系统。
3. 外部调用 — 调用的方法／门面／API 可能不存在，或其行为与预期不符（签名错误、命名空间错误、缺少 trait／宏）。
4. 状态变更 — 具有破坏性或出人意料的写入（删除、覆盖、级联），且其他代码依赖这些状态。
5. 假定的依赖项 — 代码引用的导入项、类、文件、路由、视图或配置键可能不存在。

说明

1. 获取差异

运行 git diff <base>...HEAD（三点语法——显示此分支从分叉以来的变更），并运行 git diff --name-status <base>...HEAD 查看文件级概览。如果没有变更，请说明并停止。

2. 扫描变更文件

逐个阅读每个变更文件的相关内容，根据五项检查进行评估。跳过自动生成的文件，除非发现可疑之处：

• 锁定文件（composer.lock、package-lock.json、pnpm-lock.yaml 等）
• 编译后的资源（public/build/、dist/）
• 生成的路由／类型定义（例如 Wayfinder action／route 文件、生成的 TS 类型）

3. 验证后再标记

列出问题前，不要仅凭猜测就标记：

• 假定的依赖项 — 使用 find 或 ls 确认导入的文件／类是否实际存在。只有确认确实缺失时才标记。
• 外部调用 — 对接收类／门面使用 grep 搜索该方法。只有确认方法确实未定义（或签名不同）时才标记。
• 输入边界 — 检查对应的 FormRequest／验证器／迁移中的列类型。只有确认确实缺少验证，或验证与字段的使用方式不匹配时才标记。
• 错误处理 — 只有当调用确实可能失败且没有处理时才标记。由任务的自动重试机制保护的代码，或能正确处理异常的全局异常处理器，都不算问题。
• 状态变更 — 只有当代码库的其他部分确实依赖被修改的状态时才标记。

如果无法确认有误，就不要标记。

4. 输出报告

每项检查单独设一个章节。仅在有问题需要标记时才包含该章节。 完全跳过没有问题的章节。不要用“（没有问题）”之类的占位文本。

严格使用以下格式：

**Error Handling**
- ⚠️ `file.php:42` — empty catch block hides notification failures
- `file.php:80` — no error handling around the API call

**Input Boundaries**
- ⚠️ `Request.php:15` — `message` field has no max length, goes into a text column

**External Calls**
- ⚠️ `Controller.php:40` — `Notification::sendLater()` doesn't exist on the facade

**State Mutations**
- `Observer.php:35` — deletes subscription permanently, other features read this relationship

**Assumed Dependencies**
- ⚠️ `Controller.php:3` — imports `App\Notifications\IdeaStatusChanged` but file doesn't exist

**X items across Y files.**

如果一切正常，则严格输出：

✅ Nothing flagged.

规则

• 少即是多。 只标出确实有问题或有风险的地方。5 个真实问题胜过 20 个吹毛求疵的意见。
• ⚠️ 仅用于高严重性问题——数据丢失、安全漏洞、静默失败、缺少文件或类、外部调用故障。其他问题一律使用普通项目符号。
• 始终包含 file:line。 每条项目都以反引号括起的路径和行号开头。
• 每条问题占一行。 在同一行中说明问题是什么，以及为什么重要。不要写多句解释。
• 标记前先核实假定的依赖项。 使用 find 或 ls。误报缺少文件是这项技能中最糟糕的结果。
• 跳过自动生成的文件（锁文件、编译后的资源、生成的路由/类型定义）。
• 不要添加前言或结尾总结，但 **X items across Y files.** 这一行除外。不要写“以下是我的发现”或修复建议。
• 不要提出修复方案。 这是一份分诊清单——指出问题即可。
• 不要复述代码。 “if ($x) { … } — 这会检查 x 是否成立”是废话。指出问题，不要复述代码。