checklist-generator

质量检查清单生成器

概述

生成全面且感知上下文的质量检查清单，将 IEEE 1028 标准（80-90%）与 LLM 生成的上下文相关条目（10-20%）相结合，确保在完成前进行系统的质量验证。

**核心原则：**以通用质量标准为基础，并结合项目特定的上下文加以完善。

适用时机

始终适用：

• 完成实现任务前
• 代码审查期间
• QA 验证阶段
• 提交前验证
• 将任务标记为完成前

例外情况：

• 一次性原型
• 仅涉及配置的更改

目的

1. **IEEE 1028 基础：**成熟的质量审查标准（通用）
2. **上下文增强：**LLM 添加项目特定条目
3. **系统验证：**确保全面覆盖质量检查

IEEE 1028 基础类别

以下类别会包含在每份检查清单中（占条目的 80-90%）：

代码质量

• 代码遵循项目风格指南
• 无代码重复（DRY 原则）
• 每个函数的圈复杂度 < 10
• 函数各自承担单一职责
• 变量名称清晰且具有描述性
• 使用命名常量替代魔法数字
• 移除无用代码

测试

• 先编写测试（遵循 TDD）
• 所有新增代码都有对应的测试
• 测试覆盖边缘情况和错误条件
• 新增代码的测试覆盖率 ≥ 80%
• 针对多组件交互编写集成测试
• 测试相互隔离，且不依赖执行顺序

安全

• 验证所有用户输入
• 不存在 SQL 注入漏洞
• 不存在 XSS 漏洞
• 静态存储和传输中的敏感数据均已加密
• 包含身份验证和授权检查
• 不存在硬编码的密钥或凭据
• 考虑 OWASP Top 10

性能

• 不存在明显的性能瓶颈
• 优化数据库查询（无 N+1 查询）
• 使用适当的缓存
• 清理资源（关闭连接、释放内存）
• 不存在无限循环或递归风险
• 对大型数据操作进行分页

文档

• 为公共 API 编写文档
• 为复杂逻辑添加说明性注释
• 必要时更新 README
• 更新 CHANGELOG
• 记录破坏性更改
• 若结构发生变化，则更新架构图

错误处理

• 处理所有错误情况
• 提供对用户友好的错误消息（用户错误使用 4xx）
• 提供用于调试的详细日志（系统错误使用 5xx）
• 不吞掉异常
• 实现优雅降级
• 为故障制定回滚流程

上下文补充逻辑

该技能会分析当前项目上下文，以添加 10-20% 的上下文相关条目：

检测策略

1. 读取项目文件，以识别：

   • 框架（React、Vue、Angular、Next.js、FastAPI 等）
   • 语言（TypeScript、Python、Go、Java 等）
   • 模式（REST API、GraphQL、微服务、单体架构）
   • 基础设施（Docker、Kubernetes、无服务器）

2. 根据发现生成相关条目：

TypeScript 项目：

• [AI-GENERATED] 正确导出 TypeScript 类型
• [AI-GENERATED] 除非有注释说明理由，否则不使用 any 类型
• [AI-GENERATED] 满足严格空值检查要求

React 项目：

• [AI-GENERATED] 组件正确使用 memo/useCallback
• [AI-GENERATED] 不存在不必要的重新渲染（已使用 React DevTools 检查）
• [AI-GENERATED] Hooks 遵循 Hooks 规则
• [AI-GENERATED] 交互元素包含无障碍属性（aria-*）

API 项目：

• [AI-GENERATED] 已实现速率限制
• [AI-GENERATED] 遵循 API 版本策略
• [AI-GENERATED] 已更新 OpenAPI/Swagger 文档
• [AI-GENERATED] 使用架构对请求/响应进行验证

数据库项目：

• [AI-GENERATED] 迁移脚本可逆
• [AI-GENERATED] 已为查询性能添加索引
• [AI-GENERATED] 适当使用数据库事务
• [AI-GENERATED] 已配置连接池

Python 项目：

• [AI-GENERATED] 所有公共函数均包含类型提示
• [AI-GENERATED] 文档字符串遵循 Google/NumPy 风格
• [AI-GENERATED] 已更新虚拟环境的 requirements.txt

移动项目：

• [AI-GENERATED] 妥善处理离线模式
• [AI-GENERATED] 优化电池用量（不持续轮询）
• [AI-GENERATED] 尽量减少数据用量（压缩、缓存）
• [AI-GENERATED] 已测试特定平台的功能

DevOps/基础设施：

• [AI-GENERATED] 基础设施即代码（Terraform、CloudFormation）
• [AI-GENERATED] 已配置监控和告警
• [AI-GENERATED] 已测试备份和灾难恢复
• [AI-GENERATED] 安全组/防火墙规则仅授予最低限度的访问权限

输出格式

检查清单以带复选框的 Markdown 格式返回：

# Quality Checklist

Generated: {timestamp}
Context: {detected frameworks/languages}

## Code Quality (IEEE 1028)

- [ ] Code follows project style guide
- [ ] No code duplication
- [ ] Cyclomatic complexity < 10

## Testing (IEEE 1028)

- [ ] Tests written first (TDD followed)
- [ ] Test coverage ≥ 80%
- [ ] Tests cover edge cases

## Security (IEEE 1028)

- [ ] Input validation on all user inputs
- [ ] No hardcoded secrets
- [ ] OWASP Top 10 considered

## Performance (IEEE 1028)

- [ ] No obvious performance bottlenecks
- [ ] Database queries optimized
- [ ] Appropriate caching used

## Documentation (IEEE 1028)

- [ ] Public APIs documented
- [ ] README updated if needed
- [ ] CHANGELOG updated

## Error Handling (IEEE 1028)

- [ ] All error conditions handled
- [ ] User-friendly error messages
- [ ] Detailed logs for debugging

## Context-Specific Items (AI-Generated)

{Detected: TypeScript + React + REST API}

- [ ] [AI-GENERATED] TypeScript types exported properly
- [ ] [AI-GENERATED] React components use proper memo
- [ ] [AI-GENERATED] API rate limiting implemented
- [ ] [AI-GENERATED] OpenAPI docs updated

---

**Total Items**: {count}
**IEEE Base**: {ieee_count} ({percentage}%)
**Contextual**: {contextual_count} ({percentage}%)

用法

基本调用

Skill({ skill: 'checklist-generator' });

这将：

1. 分析当前项目上下文
2. 加载 IEEE 1028 基础检查清单
3. 生成相关条目（10-20%）
4. 返回合并后的 Markdown 检查清单

指定具体上下文

// Provide explicit context
Skill({
  skill: 'checklist-generator',
  args: 'typescript react api',
});

集成到 QA 工作流

// Part of QA validation
Skill({ skill: 'checklist-generator' });
// Use checklist for systematic validation
Skill({ skill: 'qa-workflow' });

集成点

QA Agent

qa Agent 使用此技能进行验证：

1. 在任务开始时生成检查清单
2. 系统地验证每个条目
3. 报告检查清单的完成状态

完成前验证

用作完成前的关卡：

1. 在标记任务完成前生成检查清单
2. 确保所有条目均已验证
3. 如果关键条目未通过，则阻止任务完成

Code-Reviewer Agent

在代码审查期间使用：

1. 为 PR 生成检查清单
2. 根据变更检查每个条目
3. 针对缺失条目发表评论

上下文检测算法

1. Read package.json or requirements.txt or go.mod
   → Extract dependencies

2. Glob for framework-specific files:
   - React: **/*.jsx, **/*.tsx, package.json with "react"
   - Vue: **/*.vue, package.json with "vue"
   - Next.js: next.config.js, app/**, pages/**
   - FastAPI: **/main.py with "from fastapi"
   - Django: **/settings.py, **/models.py

3. Analyze imports/dependencies:
   - TypeScript: tsconfig.json
   - GraphQL: **/*.graphql, **/*.gql
   - Docker: Dockerfile, docker-compose.yml
   - Kubernetes: **/*.yaml in k8s/ or manifests/

4. Generate contextual items based on detected stack
5. Mark all generated items with [AI-GENERATED]

示例：TypeScript + React + API 项目

输入上下文：

• package.json 包含："react": "^18.0.0", "typescript": "^5.0.0"
• 文件包括：src/components/*.tsx、src/api/*.ts

生成的检查清单：

# Quality Checklist

Generated: 2026-01-28 10:30:00
Context: TypeScript, React, REST API

## Code Quality (IEEE 1028)

- [ ] Code follows project style guide
- [ ] No code duplication
- [ ] Cyclomatic complexity < 10
- [ ] Functions have single responsibility
- [ ] Variable names clear and descriptive
- [ ] Magic numbers replaced with constants
- [ ] Dead code removed

## Testing (IEEE 1028)

- [ ] Tests written first (TDD)
- [ ] All new code has tests
- [ ] Tests cover edge cases
- [ ] Test coverage ≥ 80%
- [ ] Integration tests present
- [ ] Tests isolated (no order dependency)

## Security (IEEE 1028)

- [ ] Input validation on all inputs
- [ ] No SQL injection risks
- [ ] No XSS vulnerabilities
- [ ] Sensitive data encrypted
- [ ] Auth/authz checks present
- [ ] No hardcoded secrets
- [ ] OWASP Top 10 reviewed

## Performance (IEEE 1028)

- [ ] No performance bottlenecks
- [ ] Database queries optimized
- [ ] Caching used appropriately
- [ ] Resource cleanup (connections)
- [ ] No infinite loop risks
- [ ] Large data paginated

## Documentation (IEEE 1028)

- [ ] Public APIs documented
- [ ] Complex logic has comments
- [ ] README updated
- [ ] CHANGELOG updated
- [ ] Breaking changes documented

## Error Handling (IEEE 1028)

- [ ] All errors handled
- [ ] User-friendly error messages
- [ ] Detailed logs for debugging
- [ ] No swallowed exceptions
- [ ] Graceful degradation
- [ ] Rollback procedures

## TypeScript (AI-Generated)

- [ ] [AI-GENERATED] Types exported from modules
- [ ] [AI-GENERATED] No `any` types (justified if used)
- [ ] [AI-GENERATED] Strict null checks satisfied
- [ ] [AI-GENERATED] Interfaces prefer over types

## React (AI-GENERATED)

- [ ] [AI-GENERATED] Components use React.memo appropriately
- [ ] [AI-GENERATED] Hooks follow Rules of Hooks
- [ ] [AI-GENERATED] No unnecessary re-renders
- [ ] [AI-GENERATED] Keys on list items

## REST API (AI-GENERATED)

- [ ] [AI-GENERATED] Rate limiting implemented
- [ ] [AI-GENERATED] API versioning in URLs
- [ ] [AI-GENERATED] Request/response validation
- [ ] [AI-GENERATED] OpenAPI/Swagger updated

---

**Total Items**: 38
**IEEE Base**: 30 (79%)
**Contextual**: 8 (21%)

最佳实践

应做事项

• 从 IEEE 1028 基础清单开始（通用质量要求）
• 生成前分析项目上下文
• 为所有 LLM 条目标注 [AI-GENERATED]
• 让相关条目保持精简（10-20%）
• 返回可执行的检查清单（而非泛泛的建议）

不应做事项

• 未分析上下文就生成检查清单
• 相关条目超过 20%（会稀释 IEEE 基础清单）
• 忘记 [AI-GENERATED] 前缀
• 包含无法验证的条目
• 让检查清单过长（超过 50 项）

铁律

1. 绝不在未验证清单的情况下完成任务——使用 verification-before-completion 强制执行这道关卡；跳过清单验证就违背了这项技能的全部意义。
2. 始终先分析项目上下文，再生成清单——先识别框架、语言和模式；没有上下文的通用清单会遗漏特定技术栈的检查项，也会包含无关项。
3. 绝不超过 50 个清单项——实际执行中，超过 50 项的清单往往无法完成；务必精简，优先处理阻塞项，而非锦上添花的事项。
4. 始终为 LLM 生成的项目添加 [AI-GENERATED] 前缀——IEEE 1028 的基础项目是经过验证的标准；AI 生成的项目则是需要人工判断的上下文建议。
5. 绝不包含无法验证的项目——每个清单项都必须能以“是”或“否”客观核查；“代码整洁”之类的模糊项目无法得到明确验证。

反模式

反模式	失败原因	正确做法
未分析上下文就生成	生成的清单项通用且无关	先识别框架／语言／模式
超过 50 项	清单太长，审查进行到一半就会被放弃	大胆删减；保留不超过 50 个高价值项目
上下文相关项目未加 [AI-GENERATED] 前缀	混淆标准与建议	清楚标记所有 AI 上下文相关项目
包含无法验证的项目（“代码整洁”）	无法明确勾选完成	只包含能客观判定通过或失败的项目
因变更“很小”而跳过清单	小变更也可能引入大问题	每次变更都按比例应用清单

相关技能

• qa-workflow - 通过修复循环进行系统化 QA 验证
• verification-before-completion - 完成前关卡
• tdd - 测试驱动开发（用于测试清单项）
• security-architect - 安全专项验证

指定 Agent

此技能由以下角色使用：

• qa - 质量保证验证
• developer - 完成前检查
• code-reviewer - 代码审查标准

记忆协议（强制）

开始前： 阅读 .claude/context/memory/learnings.md

检查以下内容：

• 之前生成的清单
• 项目特定的质量模式
• 此代码库中常见的质量问题

完成后：

• 新的清单模式 → .claude/context/memory/learnings.md
• 发现质量问题 → .claude/context/memory/issues.md
• 上下文识别方面的改进 → .claude/context/memory/decisions.md

假设工作会中断：如果没有记录在记忆中，就等于没有发生。