Kiro AI 助手完整使用指南

需求文档 → 设计文档 → 任务清单

适合业务需求明确，但技术方案待定的情况。例如：'我需要一个帮助客户追踪订单的系统'。

Bugfix Spec 工作流则遵循：

Bug 条件探索 → 设计修复方案 → 任务清单

使用 Bug Condition 方法论，并通过属性测试验证修复。

如何创建 Spec

方式 1: 直接对话

"创建一个用户认证的 spec"
"我想为购物车功能写一个规范"

方式 2: 使用命令面板 打开命令面板（Ctrl/Cmd + Shift + P），搜索'Kiro: Create Spec'。

Spec 文件结构

.kiro/specs/
└── user-authentication/ # 功能名称（kebab-case）
    ├── .config.kiro     # 配置文件
    ├── requirements.md  # 需求文档
    ├── design.md        # 设计文档
    └── tasks.md         # 任务清单

执行 Spec 任务

执行单个任务:

"执行任务 2"
"开始任务 1.3"

执行所有任务:

"运行所有任务"
"执行完整的 spec"

Spec 文件引用

在 Spec 文档中，你可以引用其他文件，Kiro 会自动读取内容：

#[[file:openapi.yaml]]
#[[file:schema.graphql]]

Hooks - 自动化触发器

Hooks 允许你在特定事件发生时自动触发 AI 操作，让重复性工作自动化。

Hook 事件类型

• 文件事件: fileEdited, fileCreated, fileDeleted
• 对话事件: promptSubmit, agentStop
• 工具事件: preToolUse, postToolUse
• 任务事件: preTaskExecution, postTaskExecution
• 手动触发: userTriggered

Hook 动作类型

1. askAgent（询问 AI）: 向 AI 发送提示，适合代码审查、提醒、建议。
2. runCommand（运行命令）: 执行 Shell 命令，适合运行测试、代码检查、构建。

Hook 配置示例

示例 1: 保存时自动 Lint

{
  "name": "Lint on Save",
  "version": "1.0.0",
  "when": { "type": "fileEdited", "patterns": ["*.ts", "*.tsx"] },
  "then": { "type": "runCommand", "command": "npm run lint" }
}

示例 2: 写操作前审查

{
  "name": "Review Write Operations",
  "version": "1.0.0",
  "when": { "type": "preToolUse", "toolTypes": ["write"] },
  "then": { "type": "askAgent", "prompt": "验证此写操作是否符合编码标准" }
}

示例 3: 任务完成后运行测试

{
  "name": "Run Tests After Task",
  "version": "1.0.0",
  "when": { "type": "postTaskExecution" },
  "then": { "type": "runCommand", "command": "npm run test" }
}

管理 Hooks

• UI 管理: 打开命令面板，搜索'Open Kiro Hook UI'，可视化创建和管理。
• 直接编辑: Hooks 存储在 .kiro/hooks/ 目录，每个 Hook 是一个 JSON 文件。
• 对话创建: 直接告诉 Kiro 你想创建的 Hook，例如'创建一个 Hook，在保存 TypeScript 文件时运行 lint'。

Hook 文件位置

.kiro/hooks/
├── lint-on-save.json
├── review-writes.json
└── test-after-task.json

Steering - 行为定制规则

Steering 规则允许你定制 Kiro 的行为和工作方式，确保它符合团队或个人习惯。

什么是 Steering？

Steering 是 Markdown 文件，包含额外的上下文和指令，影响 Kiro 的所有或部分交互。

Steering 类型

1. Always Included（始终包含）: 全局生效的编码标准。

   --- inclusion: always ---
   # 我的编码标准
   - 使用 TypeScript 严格模式
   - 所有函数必须有 JSDoc 注释
   - 使用 4 空格缩进
   

2. File Match（文件匹配）: 针对特定文件模式的规则。

   --- inclusion: fileMatch
   fileMatchPattern: '**/*.test.ts'
   ---
   # 测试文件规则
   - 使用 Jest 框架
   - 每个测试必须有描述性名称
   - 使用 AAA 模式（Arrange-Act-Assert）
   

3. Manual（手动引用）: 通过聊天中的 # 引用。

   --- inclusion: manual ---
   # API 设计指南
   - RESTful 风格
   - 使用语义化的 HTTP 状态码
   - 统一的错误响应格式
   

   在聊天中使用 #API 设计指南 引用。

Steering 文件位置

• 工作区级别（优先级更高）: .kiro/steering/
• 用户级别（全局）: ~/.kiro/steering/

创建 Steering 规则

• 对话创建: '创建一个 Steering 规则，要求所有组件使用函数式写法'。
• 直接编辑: 在 .kiro/steering/ 创建 .md 文件，添加 front-matter 配置并编写规则内容。

实际应用示例

代码变更追踪规则

--- inclusion: always ---
# 代码变更自动记录规则
当完成文件变更后，自动调用记录工具追踪变更。
触发条件：
- 创建新文件
- 修改现有文件
- 删除文件内容
- 重构代码

这就是你当前激活的 Steering 规则！

MCP - 模型上下文协议

MCP 允许 Kiro 连接外部工具和服务，扩展其能力。

什么是 MCP？

Model Context Protocol（模型上下文协议）是一个标准，允许 AI 模型与外部系统交互。

MCP 配置文件

• 用户级别（全局）: ~/.kiro/settings/mcp.json
• 工作区级别: .kiro/settings/mcp.json

MCP 配置示例

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "disabled": false,
      "autoApprove": []
    },
    "database": {
      "command": "uvx",
      "args": ["mcp-server-postgres"],
      "env": { "DATABASE_URL": "postgresql://localhost/mydb" },
      "disabled": false,
      "autoApprove": ["query_read"]
    }
  }
}

配置字段说明

• command: 启动 MCP 服务器的命令（通常是 uvx）
• args: 命令参数（包名和版本）
• env: 环境变量
• disabled: 是否禁用此服务器
• autoApprove: 自动批准的工具列表

安装 MCP 依赖

大多数 MCP 服务器使用 uvx 运行，需要先安装 uv：

• 使用 pip: pip install uv
• 使用 Homebrew (macOS): brew install uv
• 使用 Cargo (Rust): cargoinstall uv

管理 MCP 服务器

• 命令面板: 搜索'MCP'，查看可用的 MCP 命令。
• MCP Server 视图: 在 Kiro 功能面板中找到'MCP Server'视图，查看、启用、禁用服务器。
• 对话配置: '配置 MCP 连接到我的 PostgreSQL 数据库'。

常用 MCP 服务器

• aws-documentation-mcp-server - AWS 文档查询
• mcp-server-postgres - PostgreSQL 数据库操作
• mcp-server-git - Git 仓库操作
• mcp-server-filesystem - 文件系统访问

聊天上下文

Kiro 可以访问多种上下文信息，帮助它更好地理解你的需求。

使用 # 引用上下文

• #File - 引用文件: "查看 #src/App.tsx 的实现"
• #Folder - 引用文件夹: "分析 #src/components 目录结构"
• #Problems - 当前文件的问题: "修复 #Problems"
• #Terminal - 终端输出: "分析 #Terminal 中的错误"
• #Git Diff - Git 变更: "审查 #Git Diff"

拖拽图片

你可以直接拖拽图片到聊天框，Kiro 可以分析图片内容：

• UI 设计稿 → 生成代码
• 错误截图 → 诊断问题
• 架构图 → 理解系统设计

实战示例

示例 1: 创建新功能（使用 Spec）

你："创建一个用户认证功能的 spec"
Kiro：这是新功能还是修复 bug？ [选项：新功能 / 修复 Bug]
你："新功能"
Kiro：你想从哪里开始？ [选项：需求文档 / 技术设计]
你："需求文档"
Kiro：[创建 requirements.md] 需求文档已创建，包含：用户故事、验收标准、正确性属性
你："看起来不错，继续"
Kiro：[创建 design.md] 设计文档已创建，包含：系统架构、数据模型、API 设计
你："继续"
Kiro：[创建 tasks.md] 任务清单已创建，共 8 个任务
你："执行所有任务"
Kiro：[依次执行任务 1-8] ✓ 任务 1: 创建用户模型 ... ✓ 任务 8: 编写集成测试
所有任务已完成！

示例 2: 快速修改（不使用 Spec）

你："在 #src/App.tsx 中添加一个加载状态"
Kiro：[修改文件] 已添加 loading 状态和 Spinner 组件
[自动记录变更] - 文件修改：src/App.tsx - 新增：15 行 - 删除：3 行

示例 3: 使用 Hook 自动化

你："创建一个 Hook，每次保存 TypeScript 文件时运行 ESLint"
Kiro：[创建 Hook 文件] Hook 已创建：.kiro/hooks/lint-on-save.json
现在每次保存 .ts 或 .tsx 文件时，会自动运行 ESLint

示例 4: 使用 Steering 定制行为

你："创建一个 Steering 规则，要求所有 API 响应使用统一格式"
Kiro：[创建 Steering 文件] Steering 规则已创建：.kiro/steering/api-response-format.md
现在我会确保所有 API 响应遵循这个格式：
{
  "success": boolean,
  "data": any,
  "error": string | null
}

示例 5: 联网搜索最新信息

你："React 19 有哪些新特性？"
Kiro：[搜索网络] 根据最新文档，React 19 的主要新特性包括：
1. Server Components 正式发布
2. Actions 简化表单处理
3. 新的 use() Hook
... [来源：react.dev]

示例 6: 修复 Bug（使用 Bugfix Spec）

你："创建一个 spec 修复数量为零时的崩溃"
Kiro：这是新功能还是修复 bug？ [选项：新功能 / 修复 Bug]
你："修复 Bug"
Kiro：[创建 bugfix.md] Bug 条件文档已创建：Bug 描述、重现步骤、Bug 条件 C(X)
你："继续"
Kiro：[创建 design.md] 修复设计已创建：根因分析、修复方案、验证策略
你："执行所有任务"
Kiro：[执行任务] ✓ 任务 1: 编写 Bug 探索测试（测试失败 ✓ - 确认 Bug 存在）
✓ 任务 2: 实现修复
✓ 任务 3: 验证修复（测试通过 ✓）
Bug 已修复并验证！

最佳实践

1. 选择合适的工作方式

• 使用 Spec 当: 功能复杂需要规划、团队协作需要文档、需要追踪进度、想要结构化开发。
• 直接对话当: 快速修改、简单任务、探索性编程、学习和实验。

2. 善用上下文引用

# 好的做法
"重构 #src/utils/helper.ts 中的日期处理函数"

# 不够好的做法
"重构 helper.ts"（Kiro 可能找不到文件）

3. 利用 Hooks 自动化重复任务

常见的自动化场景：保存时 Lint、提交前运行测试、文件创建时添加模板、任务完成后运行验证。

4. 用 Steering 建立团队标准

--- inclusion: always ---
# 团队编码标准
## TypeScript
- 启用严格模式
- 使用接口而非类型别名（公共 API）
- 所有导出函数必须有 JSDoc
## React
- 使用函数组件
- Props 使用接口定义
- 使用 React.FC 类型

5. 渐进式采用

1. 开始：直接对话完成简单任务
2. 进阶：使用 Hooks 自动化常见操作
3. 高级：使用 Spec 管理复杂功能
4. 专家：结合 Steering + Hooks + Spec 建立完整工作流

快速参考

常用命令

# 创建 Spec
"创建一个 [功能名] 的 spec"

# 执行任务
"执行任务 [编号]"
"运行所有任务"

# 文件操作
"创建 [文件名]"
"修改 #[文件路径]"
"重构 #[文件夹]"

# 上下文引用
"查看 #File"
"分析 #Folder"
"修复 #Problems"
"解释 #Terminal"
"审查 #Git Diff"

# Hook 管理
"创建一个 Hook [描述]"
"打开 Hook UI"

# Steering 管理
"创建 Steering 规则 [描述]"
"添加编码标准"

# MCP 管理
"配置 MCP [服务名]"
"测试 MCP 工具"

文件结构

项目根目录/
├── .kiro/
│   ├── hooks/          # Hook 配置文件
│   │   └── *.json
│   ├── steering/       # Steering 规则文件
│   │   └── *.md
│   ├── settings/       # 设置文件
│   │   └── mcp.json    # MCP 配置
│   └── specs/          # Spec 文件
│       └── feature-name/
│           ├── .config.kiro
│           ├── requirements.md
│           ├── design.md
│           └── tasks.md
└── .ai-activity/       # AI 活动日志
    └── ai-code-tracker.log

总结

Kiro 是一个强大而灵活的 AI 编程助手，核心价值在于：

• 直接对话: 快速完成简单任务
• Specs: 结构化开发复杂功能
• Hooks: 自动化重复工作
• Steering: 定制行为和标准
• MCP: 扩展能力连接外部服务

选择适合你的工作方式，逐步探索更高级的功能。