Quality Gates

质量门禁

目的

在开发的每个阶段自动进行质量验证，从单个文件的编辑到完整部署。质量门禁能及早发现错误，此时修复成本最低。

PostToolUse 钩子

最强大的质量门禁：每次编辑或创建文件时都会自动进行验证。

工作原理

1. Agent 使用 Edit 或 Write 修改文件
2. PostToolUse 钩子自动触发
3. 验证脚本检测文件类型并运行相应的检查器
4. 结果会立即显示给 Agent
5. Agent 发现错误后，可在同一会话中修复

设置

此插件在 hooks/hooks.json 中包含一个开箱即用的钩子，用于运行 scripts/post-edit-check.sh。作为插件安装时，该钩子会自动生效。

如需在项目中手动设置，请添加到 .claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/scripts/post-edit-check.sh"
          }
        ]
      }
    ]
  }
}

**重要：**命令必须严格为 bash .claude/scripts/post-edit-check.sh，不要添加参数。该脚本会自动从环境中读取 $CLAUDE_TOOL_INPUT。

有关针对不同技术栈的钩子示例，请参阅 references/hook-patterns.md。

部署检查清单

部署任何应用程序之前，请完成以下 5 个验证阶段：

阶段	内容	门槛
1. 代码质量	Lint + 类型检查 + 测试	全部通过
2. 构建	完整构建成功	产物存在
3. 环境	必需的环境变量均已配置	全部已设置（绝不读取变量值）
4. 容器	镜像构建并启动	无错误
5. 部署后	健康检查端点、日志	200 OK，日志无异常

有关各技术栈的完整验证命令，请参阅 references/deploy-checklist.md。

CI 推送前门禁

推送到远程之前，请在本地运行完整的质量检查套件：

Lint → Build → Test → Security Scan

关键规则：

• 按顺序运行各阶段
• 首次失败时立即退出
• 总耗时控制在 2 分钟以内
• 不要跳过任何阶段
• 将结果保存到 .claude/reports/ci/

有关完整的流水线模板，请参阅 references/ci-pipeline.md。

技术栈检测

质量门禁系统会自动检测项目的技术栈，以运行合适的验证器。

检测优先级

检查项	检测到的技术栈	主要验证器
存在 tsconfig.json	TypeScript	npx tsc --noEmit
存在 package.json（无 tsconfig）	JavaScript	npx eslint
存在 pyproject.toml 或 setup.py	Python	ruff check
存在 Cargo.toml	Rust	cargo check
存在 go.mod	Go	go vet ./...

文件扩展名回退

编辑单个文件时，根据扩展名检测：

扩展名	验证器
.ts、.tsx	TypeScript 检查器
.js、.jsx	ESLint（如果已配置）
.py	ruff 或 py_compile
.rs	cargo check
.go	go vet
其他	静默通过

工作流集成

开发期间

• PostToolUse 钩子会在每次编辑时捕获错误
• Agent 会立即修复问题，避免问题累积

推送之前

• 在本地运行 CI 流水线：lint → build → test → security
• 推送前所有阶段都必须通过

部署之前

• 完成部署检查清单
• 验证构建、环境和健康检查端点
• 确保回滚方案已准备就绪

交叉引用

• references/hook-patterns.md — 各技术栈的 PostToolUse 钩子示例
• references/deploy-checklist.md — 部署前的 5 阶段验证
• references/ci-pipeline.md — 本地 CI 流水线模式