---

name: quality-gates description: 所有智能体的检查点框架和验证规则。确保在开发的每个阶段都通过质量门禁。 allowed-tools: Read, Grep, Bash

质量门禁（检查点框架）

何时使用

• 开始实施之前（实施前门禁）
• 实施过程中（实施门禁）
• 编写测试之后（测试门禁）
• 完成工作之前（评审门禁）

概述

质量门禁是防止错误被提交的检查点。每个智能体在继续之前都必须通过这些门禁。

门禁框架

实施前门禁

必须在编写任何代码之前通过：

• [ ] 需求完全理解
• [ ] 架构决策已定
• [ ] 类型和接口已规划
• [ ] 依赖项已识别
• [ ] 安全影响已评估
• [ ] 模式合规性已验证

如何通过：

1. 阅读所有相关文件和测试
2. 在简要计划中记录理解
3. 确定适用的架构模式
4. 列出所有需要的类型/接口
5. 检查安全问题（身份验证、输入验证等）

实施门禁

必须在代码编写期间通过：

• [ ] TypeScript 严格模式（无 any，无 @ts-ignore）
• [ ] 所有函数都有显式类型（参数 + 返回值）
• [ ] 所有失败情况都有错误处理
• [ ] 使用 Zod 模式进行输入验证
• [ ] 无硬编码密钥（使用环境变量）
• [ ] 无 console.log 语句
• [ ] 遵循安全最佳实践

如何通过：

1. 运行 TypeScript 编译器：npx tsc --noEmit
2. 检查 any 类型：grep -r ": any" src/
3. 检查 @ts-ignore：grep -r "@ts-ignore" src/
4. 验证所有输入都有 Zod 验证
5. 使用 try/catch 验证错误处理
6. 检查环境变量是否正确使用

验证器：

• typescript-strict-guard/validate-types.py
• security-sentinel/validate-security.py
• nextjs-15-specialist/validate-patterns.py

测试门禁

必须在实施后通过：

• [ ] 测试先行编写（TDD）
• [ ] 遵循 AAA 模式（Arrange, Act, Assert）
• [ ] 总体覆盖率 ≥ 75%
• [ ] 业务逻辑覆盖率 ≥ 90%（服务、工具）
• [ ] 所有测试通过
• [ ] 无未经说明跳过的测试
• [ ] 视觉状态变化有 E2E 测试

如何通过：

1. 运行测试：npm test -- --run
2. 检查覆盖率：npm test -- --coverage
3. 验证所有测试都遵循 AAA 模式
4. 确保测试中没有 .skip() 或 .only()
5. 检查 UI 变更是否有 E2E 测试

验证器：

• tdd-enforcer/validate-coverage.py
• quality-gates/validate-test-quality.py

评审门禁

必须在完成之前通过：

• [ ] 代码评审通过（无关键问题）
• [ ] 安全审计通过（OWASP Top 10）
• [ ] 所有质量门禁通过
• [ ] 文档已更新（如果需要）
• [ ] 无破坏性变更（除非有迁移计划）
• [ ] 构建成功：npm run build

如何通过：

1. 运行代码评审智能体
2. 运行安全审计智能体（用于身份验证/API/数据处理）
3. 运行所有验证器：quality-gates/validate.py
4. 验证构建：npm run build
5. 检查文档是否已更新

验证器：

• quality-gates/validate.py（聚合所有）
• security-sentinel/validate-security.py
• drizzle-orm-patterns/validate-queries.py

验证规则

TypeScript 严格模式

// ❌ 阻止：使用 'any' 类型
function process(data: any) { }

// ✅ 通过：显式类型
function process(data: UserData): ProcessedData { }

// ❌ 阻止：@ts-ignore
// @ts-ignore
const value = getData()

// ✅ 通过：类型守卫
if (isValidData(value)) {
  const data = getData()
}

// ❌ 阻止：非空断言
const user = users.find(u => u.id === id)!

// ✅ 通过：空值处理
const user = users.find(u => u.id === id)
if (!user) throw new Error('User not found')

输入验证

// ❌ 阻止：无验证
export async function POST(request: Request) {
  const body = await request.json()
  const user = await createUser(body) // 不安全！
}

// ✅ 通过：Zod 验证
import { z } from 'zod'

const createUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

export async function POST(request: Request) {
  const body = await request.json()
  const validated = createUserSchema.parse(body)
  const user = await createUser(validated)
}

错误处理

// ❌ 阻止：无错误处理
async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`)
  return response.json() // 如果失败怎么办？
}

// ✅ 通过：正确的错误处理
async function fetchUser(id: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${id}`)
    if (!response.ok) {
      throw new Error(`Failed to fetch user: ${response.status}`)
    }
    return await response.json()
  } catch (error) {
    logger.error('fetchUser failed', { id, error })
    throw new Error(`Failed to fetch user ${id}`)
  }
}

安全

// ❌ 阻止：硬编码密钥
const apiKey = 'sk_live_abc123'

// ✅ 通过：环境变量
const apiKey = process.env.STRIPE_API_KEY
if (!apiKey) throw new Error('STRIPE_API_KEY not set')

// ❌ 阻止：SQL 注入风险
const query = `SELECT * FROM users WHERE email = '${email}'`

// ✅ 通过：参数化查询（Prisma）
const user = await prisma.user.findUnique({ where: { email } })

测试质量

// ❌ 阻止：无 AAA 模式
it('should work', () => {
  const result = doThing()
  expect(result).toBe(true)
  const other = doOther()
  expect(other).toBe(false)
})

// ✅ 通过：AAA 模式
it('should return true for valid input', () => {
  // ARRANGE：设置测试数据
  const input = { valid: true }

  // ACT：执行行为
  const result = doThing(input)

  // ASSERT：验证结果
  expect(result).toBe(true)
})

// ❌ 阻止：仅对 UI 进行模拟断言
it('should change color', () => {
  fireEvent.click(button)
  expect(mockSetColor).toHaveBeenCalled()
})

// ✅ 通过：DOM 状态断言
it('should change color', () => {
  const button = getByTestId('button')
  expect(button).toHaveClass('bg-blue-500')

  fireEvent.click(button)
  expect(button).toHaveClass('bg-red-500')
})

渐进式披露

智能体首先加载元数据（此文件），然后根据需要加载支持文件：

1. SKILL.md（此文件）- 概述和快速参考
2. checkpoint-framework.md - 详细的门禁要求
3. validation-rules.md - 全面的验证标准
4. test-patterns.md - TDD 模式和覆盖率要求
5. validate.py - 自动化验证脚本

使用模式

// 智能体工作流示例：
1. 加载 quality-gates 技能元数据
2. 检查实施前门禁
3. 计划实施
4. 在编码期间检查实施门禁
5. 编写测试
6. 检查测试门禁
7. 请求代码评审
8. 检查评审门禁
9. 仅当所有门禁通过时才完成

与其他技能的集成

质量门禁聚合了以下验证：

• typescript-strict-guard：类型安全验证
• security-sentinel：安全漏洞检查
• nextjs-15-specialist：Next.js 模式合规性
• drizzle-orm-patterns：数据库查询安全性
• tdd-enforcer：测试覆盖率和质量

关键规则

1. 切勿绕过门禁 - 如果门禁失败，修复问题，不要跳过
2. 快速失败 - 尽早且频繁地检查门禁
3. 自动化验证 - 在完成之前使用 validate.py
4. 记录例外情况 - 任何偏差都需要明确批准

另请参阅

• checkpoint-framework.md - 详细的门禁要求
• validation-rules.md - 完整的验证规则
• test-patterns.md - TDD 模式
• …/typescript-strict-guard/SKILL.md - TypeScript 验证
• …/security-sentinel/SKILL.md - 安全验证