作者：尘
更新日期：2026年4月
适用版本：Kiro CLI / IDE（Steering 机制）

什么是 Steering？

Steering 是 Kiro 最强大的特性之一。它允许你通过 Markdown 文件 把项目规范、偏好、规则永久“教”给 Kiro。这样每次对话时，Kiro 都会自动遵守你的习惯，无需反复提醒。

核心价值：

  • 代码/文档风格一致性
  • 减少重复说明
  • 团队规范统一
  • 项目知识随时间积累

两种作用范围

类型目录位置适用范围优先级
Workspace（工作区）项目根目录 /.kiro/steering/当前项目高
Global（全局）用户主目录 ~/.kiro/steering/所有项目低

工作区规则会覆盖全局规则，适合项目特殊需求。

配置步骤

1. 创建 Steering 目录

# 项目内（推荐）
mkdir -p .kiro/steering

# 或全局
mkdir -p ~/.kiro/steering

2. 创建 Steering 文件

文件名建议使用英文+描述性（如 project-structure.md、code-style.md、document-output.md），内容用自然语言 + 表格 + 示例写得越清晰越好。

最佳实践：

  • 一个文件专注一个主题（保持简短，1-2页最佳）
  • 包含核心规则、为什么、示例
  • 使用表格清晰展示分类/规范
  • 加上优先级声明和必须严格遵守字样
  • 可让 Kiro 使用 “Refine” 按钮优化你的规则

基础推荐 Steering 文件

建议至少创建以下三个基础文件：

  1. product.md —— 产品概述、目标用户、核心功能
  2. tech.md —— 技术栈、框架、库、约束
  3. structure.md —— 项目目录结构、命名规范、架构原则

具体案例：文档自动分类保存到 doc/ 目录

文件名：.kiro/steering/document-output-rules.md

# 文档生成输出规则（Document Output Rules）

## 核心规则（必须严格遵守）

## 1. 单文档原则

- 对于任何一个**业务需求、功能模块、特性**或**需求描述**，只生成**一个完整的 Markdown 文档**。
- **严禁**拆分成多个文件，例如：
  - 不要额外生成「总结.md」「快速参考卡片.md」「概要.md」「Checklist.md」等
  - 不要生成配套的独立附件或辅助文档
- 所有内容（概述、详细说明、流程、API、注意事项、总结等）必须整合在**同一个文件中**，使用清晰的二级/三级标题分隔章节。

## 2. 文档输出位置与命名

- 所有文档（文档、报告、规范、设计文档、README 等）必须保存在项目根目录的 `doc/` 下（不存在则自动创建）
- 根据类型使用子目录分类（见下表）
- 文件名**必须使用中文**，清晰描述内容，可加版本号（如 `_v1.0`、`_20260420`），避免英文或纯编号命名。
- 生成前先检查同名文件是否存在，如需覆盖必须确认。
- 始终使用工具 `write` 或 `fs_write` 将文档写入对应路径。

## 3. 分类目录

| 文档类型  | 保存路径                           | 示例文件名              |
| --------- | ---------------------------------- | ----------------------- |
| 需求/规格 | `doc/requirements/`                | 用户登录功能需求规格.md |
| 设计/架构 | `doc/design/`                      | 系统架构设计_v1.0.md    |
| API/接口  | `doc/api/`                         | 支付模块API接口文档.md  |
| 用户手册  | `doc/manual/`                      | 使用手册_管理员版.md    |
| 测试文档  | `doc/test/`                        | 登录模块测试用例.md     |
| 其他/通用 | `doc/general/`(或根据内容合理分类) | 项目周报_20260420.md    |

## 4.示例

- “生成用户登录功能的需求文档” → `doc/requirements/用户登录功能需求规格.md`
- “写系统整体架构设计” → `doc/design/系统架构设计.md`
- “输出支付接口文档” → `doc/api/支付模块API接口文档.md`

## 5.优先级

此规则优先级最高。除非用户本次明确说“允许拆分成多个文档”、“输出到指定目录”，否则必须严格执行该输出规则。
# 文档生成输出规则（Document Output Rules）

## 核心规则（必须严格遵守）

- 每次生成任何文档（文档、报告、规范、设计文档、README 等）时，都必须先确保根目录下存在 `doc/` 目录。如果不存在，自动创建它。
- 所有生成的文档**必须保存到 `doc/` 根目录下**，不得保存到其他位置。
- 根据文档类型自动创建并使用子目录进行分类：
  - 需求/规格类 → `doc/requirements/`
  - 设计/架构类 → `doc/design/`
  - API/接口类 → `doc/api/`
  - 用户手册/说明类 → `doc/manual/`
  - 其他通用文档 → `doc/general/` 或根据内容合理分类
- **文件命名**：必须使用**中文**，清晰描述内容，例如：
  - `用户登录功能需求规格.md`
  - `系统架构设计_v1.0.md`
  - `API接口文档_支付模块.md`
  - 避免英文或纯编号命名。
- 如果文档有版本，可在文件名后加 `_v1.0` 等。
- 生成前先检查同名文件是否存在，如需覆盖必须确认。
- 始终使用工具 `write` 或 `fs_write` 将文档写入对应路径。

## 示例

- 生成用户登录需求文档 → 保存到 `doc/requirements/用户登录功能需求规格.md`
- 生成整体架构设计 → 保存到 `doc/design/系统架构设计.md`

## 优先级

此规则优先于其他任何指令，除非用户在本次会话中明确要求覆盖或明确要求生成在指定目录下。

其他常用 Steering 示例

  • code-style.md —— 代码风格、命名规范、注释要求
  • api-design.md —— REST/GraphQL 接口设计规范
  • git-workflow.md —— 分支策略、Commit 规范
  • testing.md —— 测试策略、覆盖率要求
  • security.md —— 安全最佳实践
  • pr-review.md —— PR 审查 checklist

自定义 Agent 如何加载 Steering

在 Agent 配置文件中加入：

{
  "resources": ["file://.kiro/steering/**/*.md"]
}

使用技巧

  1. 测试规则：生成一个测试文档，验证是否生效。
  2. 多个文件：Kiro 会自动合并所有 .md 文件的内容。
  3. 动态优化：写完规则后，可在 Kiro 中打开文件点击 Refine 让 AI 帮你完善。
  4. 团队共享：把全局 ~/.kiro/steering/ 内容放到 Git 仓库，团队统一拉取。
  5. 版本控制：建议把 .kiro/steering/ 目录提交到 Git。

验证方法

配置完成后，输入指令：

“生成一个关于用户登录的 API 设计文档”

观察 Kiro 是否自动创建 doc/api/ 目录并使用中文文件名保存。

总结：
Steering 是把 Kiro 从“临时助手”变成“长期项目伙伴”的关键。花一点时间建立好规则，后续开发效率会大幅提升。