Kiro Hook 实战指南：保存文件自动 lint、commit 自动测试，6 个场景配置详解

2026/6/18 20:16:10

Kiro 除了 Specs（规格驱动开发），还有一个实用功能叫 Hook——类似 Git Hook 的概念，但触发范围更广：文件保存、终端命令、Agent 动作都能触发自定义脚本。

说白了就是：定义"当X发生时，自动做Y"的规则。

今天用几个实际场景演示怎么配。

Hook 是什么

Hook 是 Kiro 的事件驱动自动化机制。你在 .kiro/hooks/ 目录下写配置文件，定义触发条件和执行动作。

.kiro/
├── hooks/
│   ├── on-save-lint.toml
│   ├── on-commit-test.toml
│   └── on-create-doc.toml
└── specs/└── ...

场景 1：保存 Python 文件时自动跑 Ruff

每次保存 .py 文件，自动格式化 + lint：

# .kiro/hooks/on-save-lint.toml
[trigger]
event = "file.save"
pattern = "**/*.py"[action]
type = "shell"
command = "ruff format {file} && ruff check --fix {file}"
on_failure = "notify"  # 失败时在编辑器底部提示，不阻塞

这样省了手动跑 ruff format 的步骤。{file} 是 Kiro 自动替换的变量，指向当前保存的文件路径。

场景 2：Commit 前自动跑单元测试

# .kiro/hooks/on-commit-test.toml
[trigger]
event = "git.pre-commit"[action]
type = "shell"
command = "pytest tests/unit/ -x --timeout=30"
on_failure = "block"  # 测试不过就阻止 commit[action.env]
PYTHONPATH = "src"

关键是 on_failure = "block" —— 测试红了就不让提交。和 husky + lint-staged 是一个思路，但 Kiro 原生支持，不需要额外装包。

场景 3：新建文件时自动生成文档骨架

# .kiro/hooks/on-create-doc.toml
[trigger]
event = "file.create"
pattern = "src/handlers/*.py"[action]
type = "agent"
prompt = """
为新建的 handler 文件 {file} 生成文档注释：
1. 模块级 docstring（说明这个 handler 做什么）
2. 每个公开函数的 docstring（参数、返回值、异常）
3. 如果有 AWS 服务调用，标注需要的 IAM 权限遵循 Google Python Style 的 docstring 格式。
"""

注意 type = "agent" —— 这个 hook 不是跑 shell 命令，而是让 Kiro Agent 执行一段 prompt。适合需要理解代码上下文的任务。

场景 4：CDK 部署前检查安全规则

# .kiro/hooks/on-deploy-check.toml
[trigger]
event = "terminal.command"
pattern = "cdk deploy*"[action]
type = "shell"
command = """
echo "Running security checks before deploy..."
cdk synth --quiet
cfn-nag-scan --input-path cdk.out/*.template.json
"""
on_failure = "block"[action.timeout]
seconds = 120

每次你在终端敲 cdk deploy，Kiro 先拦截，跑一遍 cfn-nag 安全扫描。有安全问题就阻止部署。

场景 5：API 文件变更时同步更新 OpenAPI Spec

# .kiro/hooks/on-api-change.toml
[trigger]
event = "file.save"
pattern = "src/routes/**/*.ts"[action]
type = "agent"
prompt = """
文件 {file} 被修改了。请检查其中的路由定义是否和 docs/openapi.yaml 一致。如果发现不一致：
1. 更新 openapi.yaml 中对应的路径定义
2. 保持 description、parameters、response schema 准确
3. 不要修改其他未变更的路径只更新有差异的部分，不要重写整个文件。
"""

场景 6：组合多个动作

# .kiro/hooks/on-pr-ready.toml
[trigger]
event = "git.push"
branch = "feature/*"[[action]]
type = "shell"
command = "pytest tests/ --cov=src --cov-report=term-missing"
on_failure = "notify"[[action]]
type = "shell"
command = "ruff check src/ --output-format=github"
on_failure = "notify"[[action]]
type = "agent"
prompt = """
检查最近的 git diff，生成一份简短的 PR description：
- 改了什么（一句话总结）
- 影响范围
- 需要 reviewer 关注的点输出为 Markdown 格式，保存到 .github/pr-description.md
"""

Push 到 feature 分支时，自动跑测试 + lint + 生成 PR 描述。三个动作串行执行。

Hook 变量

Kiro Hook 支持的内置变量：

变量	含义	可用事件
`{file}`	触发文件的完整路径	file.save, file.create
`{filename}`	文件名（不含路径）	file.save, file.create
`{dir}`	文件所在目录	file.save, file.create
`{branch}`	当前 Git 分支	git.*
`{commit_msg}`	Commit 消息	git.pre-commit, git.post-commit
`{command}`	触发的终端命令	terminal.command
`{workspace}`	项目根目录	所有事件

和 Git Hooks / Husky 的区别

维度	Git Hooks / Husky	Kiro Hooks
触发范围	只有 Git 事件	文件/Git/终端/Agent 动作
配置方式	shell 脚本	TOML 声明式
AI 集成	无	`type = "agent"` 原生支持
跨平台	shell 兼容性问题	Kiro 统一处理
团队共享	.husky/ 目录	.kiro/hooks/ 目录（同样可 git track）
调试	echo 打印	Kiro 日志面板