setup-pre-commit

设置 Pre-Commit

使用 Husky 和 lint-staged 配置提交时自动执行的代码质量检查。

何时使用此技能

• 为新项目设置提交时质量门禁
• 为现有项目添加格式化和类型检查
• 在团队内统一提交前行为

何时不使用此技能

• CI 流水线设置 → 使用 deployment-automation
• Git 工作流策略 → 使用 git-workflow
• 完整测试策略 → 使用 testing-strategies

安装流程

步骤 1 — 检测包管理器

# Check for lockfiles in order of precedence
ls package-lock.json  # npm
ls yarn.lock          # yarn
ls pnpm-lock.yaml     # pnpm
ls bun.lockb          # bun

步骤 2 — 安装依赖

# npm
npm install --save-dev husky lint-staged prettier

# pnpm
pnpm add -D husky lint-staged prettier

# yarn
yarn add -D husky lint-staged prettier

步骤 3 — 初始化 Husky

npx husky init

这会创建 .husky/ 目录，并向 package.json 添加 prepare 脚本。

步骤 4 — 创建 pre-commit 钩子

创建 .husky/pre-commit：

npx lint-staged
npm run typecheck  # omit if script doesn't exist
npm test           # omit if script doesn't exist

注意：Husky v9+ 的钩子文件不需要 shebang。

步骤 5 — 配置 lint-staged

创建 .lintstagedrc：

{
  "**/*": "prettier --write --ignore-unknown"
}

步骤 6 — 配置 Prettier（如果尚未配置）

仅在 .prettierrc 不存在时创建：

{
  "tabWidth": 2,
  "printWidth": 80,
  "singleQuote": false,
  "trailingComma": "es5",
  "semi": true,
  "arrowParens": "always"
}

步骤 7 — 验证

git add -A
git commit -m "test: verify pre-commit hooks"

检查以下项目：lint-staged 格式化、typecheck 通过、测试通过。

执行顺序

lint-staged 首先运行（速度快，仅处理暂存文件）→ typecheck（整个项目）→ 测试（完整测试套件）

如果 package.json 中不存在 typecheck 或 test 脚本，请从 pre-commit 钩子中删除对应行。

说明

1. 确定任务触发条件和预期输出。
2. 从头到尾按照此技能中的工作流步骤操作。
3. 在进入下一步之前验证输出。
4. 如果任何步骤失败，请记录阻碍因素和备用方案。

示例

• 示例：先将此技能应用于较小范围，验证通过后再扩展到完整范围。

最佳实践

• 确保输出可确定且可审计。
• 优先进行小规模、可撤销的更改，避免大范围高风险编辑。
• 明确记录假设。

参考资料

• 项目规范：.agent-skills/skill-standardization/SKILL.md
• 验证脚本：.agent-skills/skill-standardization/scripts/validate_skill.sh