钩子最佳实践
设计原则
1. 具体和清晰
编写详细明确的指令
创建钩子时要确保指令清晰、无歧义：
好的指令示例：
name: "React 组件验证器"
instructions: |
1. 检查组件是否包含 PropTypes 定义
2. 验证组件名称是否采用 PascalCase
3. 确保导出语句格式正确
4. 检查是否包含必要的 import 语句
5. 验证 JSX 语法的正确性避免的写法：
name: "代码检查"
instructions: "检查代码质量"每个钩子专注单一任务
将复杂的任务拆分为多个专门的钩子：
# 拆分前 - 过于复杂
name: "代码质量检查器"
instructions: "检查格式、lint、测试、文档和安全问题"
# 拆分后 - 清晰专注
hooks:
- name: "代码格式化器"
instructions: "应用 Prettier 格式化"
- name: "Lint 检查器"
instructions: "运行 ESLint 并修复可自动修复的问题"
- name: "测试覆盖率检查"
instructions: "验证新代码是否有对应的测试"使用编号步骤处理复杂操作
对于多步骤操作，使用清晰的编号列表：
name: "API 端点验证器"
instructions: |
1. 检查路由定义的语法正确性
2. 验证请求/响应模型是否存在
3. 确保包含适当的错误处理
4. 检查是否添加了相应的测试用例
5. 验证 API 文档是否已更新
6. 确认安全验证是否实施2. 测试和性能
样本文件测试
在部署钩子之前进行充分测试：
测试流程：
testing_workflow:
1. 创建测试文件集
2. 在测试环境运行钩子
3. 验证输出结果
4. 测试边界情况
5. 确认性能表现
6. 部署到生产环境测试文件示例：
// test-files/sample-component.jsx
import React from 'react';
// 故意包含一些问题用于测试钩子
const TestComponent = (props) => {
return <div>{props.content}</div>
}
export default TestComponent边界情况处理
确保钩子能够处理各种异常情况：
edge_cases_testing:
empty_files: "测试空文件的处理"
malformed_syntax: "测试语法错误文件"
large_files: "测试大文件的性能"
special_characters: "测试特殊字符和编码"
binary_files: "测试二进制文件的跳过"性能优化
确保钩子不会拖慢开发工作流程：
性能考虑因素：
- 触发事件的频率
- 处理文件的大小
- 外部工具的调用时间
- 网络请求的延迟
优化策略：
performance_optimization:
file_filtering:
- 使用精确的文件模式
- 排除不相关的目录
- 限制文件大小范围
execution_efficiency:
- 缓存重复计算结果
- 并行处理独立任务
- 设置合理的超时时间
resource_management:
- 限制并发执行数量
- 及时清理临时文件
- 监控内存使用情况安全考虑
输入验证
谨慎验证输入
钩子应该能够安全处理各种输入：
name: "安全的配置文件处理器"
instructions: |
1. 验证 JSON 文件的格式正确性
2. 检查是否包含敏感信息（密码、API 密钥）
3. 验证配置项的有效性
4. 如发现敏感信息，建议使用环境变量
5. 确保配置符合项目安全标准优雅处理异常内容
当遇到意外的文件内容时，钩子应该：
error_handling_strategy:
invalid_syntax:
action: "报告语法错误位置"
fallback: "跳过处理，记录警告"
unsupported_format:
action: "识别文件类型"
fallback: "提示用户检查文件格式"
corrupted_data:
action: "尝试恢复部分数据"
fallback: "建议从备份恢复"目标特定化
精确的文件模式
使用精确的文件模式避免不必要的执行：
# 好的文件模式
precise_patterns:
react_components: "src/components/**/*.{jsx,tsx}"
api_routes: "api/routes/**/*.js"
test_files: "tests/**/*.test.{js,ts}"
config_files: "config/*.{json,yaml,yml}"
# 避免的文件模式
avoid_patterns:
too_broad: "**/*" # 匹配所有文件
no_extension: "src/**/*" # 包含非代码文件目录级别的控制
为不同目录设置不同的钩子策略：
directory_specific_hooks:
src/:
hooks:
- code_formatter
- lint_checker
- test_generator
docs/:
hooks:
- markdown_formatter
- link_checker
- content_validator
config/:
hooks:
- security_scanner
- format_validator恶意输入防护
输入清理
name: "安全输入处理器"
instructions: |
1. 扫描文件内容中的潜在恶意代码
2. 检查是否包含可疑的脚本注入
3. 验证外部链接的安全性
4. 确保文件大小在合理范围内
5. 报告任何安全隐患团队协作
文档和标准
清晰的文档说明
为每个钩子维护详细的文档：
hook_documentation:
name: "钩子名称"
purpose: "钩子的主要功能和目标"
trigger_conditions: "什么情况下会触发"
file_targets: "处理哪些类型的文件"
expected_behavior: "预期的行为和输出"
examples: "使用示例和效果展示"
maintenance_notes: "维护说明和注意事项"
version_history: "版本更新记录"行为示例
提供具体的行为示例帮助团队理解：
name: "API 文档生成器"
examples:
input_file: |
// api/users.js
app.get('/api/users', (req, res) => {
// 获取用户列表
});
expected_output: |
/**
* @api {get} /api/users 获取用户列表
* @apiName GetUsers
* @apiGroup Users
* @apiSuccess {Object[]} users 用户列表
*/版本控制集成
钩子配置版本化
将钩子配置纳入版本控制：
# .kiro/hooks.yml
team_hooks:
version: "1.2.0"
last_updated: "2025-07-21"
maintainer: "team@company.com"
hooks:
security_scanner:
enabled: true
trigger: onSave
pattern: "**/*.{js,ts,jsx,tsx}"
instructions: "扫描潜在的安全漏洞"
test_coverage:
enabled: true
trigger: preCommit
instructions: "确保新代码有测试覆盖"变更管理流程
change_management:
proposal:
- 创建钩子变更提案
- 说明变更原因和影响
- 获得团队评审和批准
testing:
- 在分支环境测试新钩子
- 验证不会破坏现有工作流
- 收集团队成员反馈
deployment:
- 逐步部署到团队成员
- 监控钩子执行效果
- 收集使用数据和反馈
maintenance:
- 定期审查钩子效果
- 根据反馈优化配置
- 更新文档和示例团队标准化
创建标准钩子
为常见的团队工作流程创建标准钩子：
standard_team_hooks:
code_quality:
- format_on_save
- lint_check
- import_organizer
security:
- secret_scanner
- dependency_audit
- vulnerability_check
documentation:
- comment_generator
- readme_updater
- changelog_maintainer
testing:
- test_generator
- coverage_checker
- e2e_validator工作流程集成
将钩子集成到团队的开发工作流程中：
workflow_integration:
development_phase:
- auto_formatter: "保持代码一致性"
- test_runner: "确保功能正确性"
- documentation_helper: "维护代码文档"
code_review_phase:
- security_scanner: "识别安全风险"
- complexity_analyzer: "评估代码复杂度"
- performance_checker: "检查性能影响"
deployment_phase:
- build_validator: "验证构建成功"
- dependency_checker: "检查依赖完整性"
- deployment_script: "自动化部署流程"持续维护
定期更新
根据项目演进更新钩子逻辑
随着项目的发展，钩子也需要相应更新：
update_triggers:
technology_changes:
- "采用新的框架或库"
- "更新构建工具配置"
- "变更代码规范标准"
team_changes:
- "团队规模变化"
- "工作流程调整"
- "质量标准更新"
project_changes:
- "功能需求变化"
- "性能要求提升"
- "安全标准强化"更新策略
update_strategy:
assessment:
- 评估当前钩子的效果
- 识别改进机会
- 收集团队反馈
planning:
- 制定更新计划
- 评估变更影响
- 安排测试时间
implementation:
- 在测试环境实施变更
- 验证新功能效果
- 逐步推广到生产环境
monitoring:
- 监控更新后的表现
- 收集使用数据
- 根据反馈进一步优化清理和优化
移除不需要的钩子
定期清理不再使用的钩子：
cleanup_checklist:
usage_analysis:
- 分析钩子执行频率
- 评估钩子实际价值
- 识别重复功能
impact_assessment:
- 评估移除的影响
- 确认无依赖关系
- 通知相关团队成员
removal_process:
- 先禁用钩子观察影响
- 备份钩子配置
- 正式删除不需要的钩子提示优化
基于实际结果优化提示
根据钩子的实际执行结果持续改进：
prompt_optimization:
effectiveness_metrics:
- 成功率统计
- 执行时间分析
- 错误率评估
- 用户满意度调查
improvement_strategies:
- 简化复杂指令
- 增加具体示例
- 改进错误处理
- 优化执行逻辑
testing_approach:
- A/B 测试不同的提示版本
- 收集性能数据
- 比较用户反馈
- 选择最优方案提示迭代示例
# 初始版本
v1_prompt: "检查代码质量"
# 改进版本
v2_prompt: |
检查以下代码质量问题：
1. 语法错误
2. 格式问题
3. 未使用的变量
# 最终优化版本
v3_prompt: |
执行代码质量检查：
1. 运行 ESLint 检查语法和样式问题
2. 识别未使用的导入和变量
3. 验证函数和变量命名规范
4. 检查代码复杂度是否合理
5. 确保包含必要的注释
6. 提供具体的修复建议高级技巧
条件执行
智能触发条件
使用复杂的条件逻辑优化钩子执行：
name: "智能测试运行器"
trigger: onSave
conditions:
- file_extension: [".js", ".ts", ".jsx", ".tsx"]
- file_size: "<1MB"
- not_in_directory: ["node_modules", "dist", "build"]
- contains_functions: true
instructions: |
如果文件包含新增或修改的函数：
1. 识别变更的函数
2. 查找相关的测试文件
3. 运行相关测试
4. 如无测试，生成基础测试模板钩子链
name: "完整 CI 流程"
chain:
- name: "代码格式化"
instructions: "格式化代码并修复基本问题"
- name: "安全扫描"
instructions: "扫描安全漏洞和敏感信息"
condition: "previous_step_success"
- name: "测试执行"
instructions: "运行相关测试用例"
condition: "no_security_issues"
- name: "构建验证"
instructions: "验证代码能正确构建"
condition: "tests_passing"性能监控
performance_monitoring:
metrics:
- execution_time
- memory_usage
- success_rate
- error_frequency
alerting:
slow_execution: ">10s"
high_memory: ">100MB"
error_rate: ">5%"
optimization_triggers:
- "连续5次执行超过阈值"
- "错误率超过10%"
- "用户投诉性能问题"页面最后更新：2025年7月21日