---
name: setup-pre-commit
description: 为仓库配置只检查暂存改动的 pre-commit 质量门，沿用现有包管理器、格式化器、测试命令和 Git hook 工具。
disable-model-invocation: true
---

# 配置 pre-commit 检查

在提交前提供快速、确定、可重复的反馈，同时避免修改未暂存文件或把过慢的全量检查塞进每次提交。

## 过程

### 1. 探索现有约定

检查包管理器锁文件、`package.json` 或同类任务配置、格式化器、lint、类型检查、测试、已有 hook 和 CI。优先沿用仓库已经使用的 hook 工具；没有既有选择时，再根据语言生态推荐轻量方案。

把检查分为两组：

- **提交前**：通常在几十秒内完成，且能限定到暂存文件或受影响范围
- **CI 或 pre-push**：全量构建、端到端测试、耗时集成测试

**完成条件：** 已确认包管理器、现有 hook、可复用命令及其典型耗时，没有引入第二套包管理器或重复格式化器。

### 2. 展示配置方案

向用户展示将运行的命令、适用文件、预计成本，以及哪些检查继续留在 CI。获得确认后再安装依赖或修改配置。

默认原则：

- 格式化和可按文件运行的 lint 只处理暂存文件；
- hook 失败时保留清楚的原始错误和可直接重跑的命令；
- 缺少对应脚本时不虚构 `test` 或 `typecheck`；
- 不自动暂存用户原本未暂存的文件；
- 安装依赖时使用已检测到的包管理器并保持现有锁文件。

**完成条件：** 用户知道每次提交会新增哪些成本，并明确同意配置范围。

### 3. 实施并验证

合并现有配置，不覆盖已有 hook。工具支持暂存文件保护时启用；否则先证明失败不会丢失工作区或暂存区状态。

按 `CONTEXT.md` 的"变红"方法验证，再加一条暂存区检查：

1. 在临时或可恢复的测试文件上制造一个会被检查捕获的问题；
2. 直接运行 hook，确认它因正确原因失败（变红）；
3. 修正问题并再次运行，确认恢复通过；
4. 比较 `git status --short` 和暂存 diff，确认未暂存改动未被意外加入或覆盖。

不以创建真实提交作为验证手段，除非用户明确要求提交。

**完成条件：** hook 已观察到一次预期失败和一次通过，暂存区与工作区中用户原有改动保持不变，使用说明已写入仓库现有的开发文档入口。