AI 编程工具 Kiro 实用指南：通过 Steering 文件解决 AI 工作流一致性问题

1. 什么是 Steering 文件

Steering 文件是 Kiro IDE 中的一种上下文注入机制，用于在与 AI 交互时自动加载和应用特定的规则、指南和上下文信息。

简单来说：Steering 文件让你能够定义一套规则，然后在每次与 AI 交互时自动应用这些规则。

1.1 为什么需要 Steering 文件

想象你有一个翻译项目，需要遵循特定的术语表、格式规范和风格指南。如果每次都手动告诉 AI 这些规则，会很低效。Steering 文件解决了这个问题：

• 一次定义，多次使用：定义一次规则，在所有交互中自动应用
• 保证一致性：确保每次 AI 的输出都遵循相同的标准
• 减少重复工作：无需每次都重新输入相同的指令
• 易于维护：修改规则时只需更新一个文件

1.2 Steering 文件的位置

项目根目录/
├── .kiro/
│   ├── steering/          # Steering 文件目录
│   │   ├── translation-workflow.md
│   │   ├── code-style.md
│   │   └── documentation-rules.md
│   └── skills/            # Skill 文件目录
└── docs/
    └── glossary.yaml      # 术语表等参考文件

2. Steering 文件的结构

2.1 基本格式

---
inclusion: manual
---

# 文件标题

## 第一部分
内容...

## 第二部分
内容...

2.2 FrontMatter 配置

Steering 文件的 FrontMatter 决定了它如何被加载和使用：

---
inclusion: auto              # 包含方式
fileMatchPattern: '*.md'     # 可选：文件匹配模式
---

支持的 inclusion 类型如下：

2.3 引用其他文件

Steering 文件可以引用其他文件，这些文件会被自动加载到上下文中：

# 翻译规则

## 术语表

翻译时必须遵守以下术语表：

#[[file:docs/glossary.yaml]]

## 代码示例

参考以下示例：

#[[file:examples/translation-example.md]]

语法：#[[file:相对路径/文件名]]

特点：

• 支持相对路径
• 自动加载引用的文件内容
• 可以引用任何文本格式的文件（.md、.yaml、.txt 等）

3. Steering 文件示例

3.1：翻译工作流

---
inclusion: manual
---

# 技术文档翻译工作流

## 概述
将英文技术文档翻译为中文。

## 术语表
#[[file:docs/glossary.yaml]]

## 翻译规则

### 不翻译的内容
- 公司名称（Google、Microsoft 等）
- 技术术语（API、SDK、LLM 等）
- 人名（Andrej Karpathy 等）

### 必须翻译的内容
- 正文段落
- 标题
- 列表项

### 格式规则
- 使用中文标点符号
- 英文术语与中文之间加空格
- 保持原文段落结构

## 质量检查清单
1. 术语是否正确应用
2. 代码块是否完整
3. 链接是否保留
4. 格式是否正确

使用方式：在聊天中输入 #translation-workflow

3.2：统一代码风格

---
inclusion: auto
fileMatchPattern: '**/*.ts'
---

# TypeScript 代码风格指南

## 命名规范
- 类名：PascalCase（如 `UserService`）
- 函数名：camelCase（如 `getUserById`）
- 常量：UPPER_SNAKE_CASE（如 `MAX_RETRIES`）

## 类型注解
- 所有函数参数必须有类型注解
- 所有函数返回值必须有类型注解
- 避免使用 `any` 类型

## 错误处理
- 使用 try-catch 处理异步操作
- 提供有意义的错误消息
- 记录错误堆栈跟踪

## 注释规范
- 为复杂逻辑添加注释
- 使用 JSDoc 格式记录公共 API
- 避免过度注释

使用方式：自动应用于所有 TypeScript 文件

3.3：文档生成工作流

---
inclusion: manual
---

# API 文档生成规范

## 文档结构
1. 概述
2. 参数说明
3. 返回值说明
4. 错误处理
5. 使用示例

## 参数文档格式

• 参数名 (类型): 说明
  • 默认值: xxx
  • 可选/必需

## 示例格式
\`\`\`javascript
// 示例代码
\`\`\`

## 注意事项
- 保持一致的格式
- 提供完整的示例
- 说明所有可能的错误

使用方式：在聊天中输入 #api-documentation

4. Steering vs Skill

何时使用哪个

使用 Steering 文件：

• 定义项目级别的工作流
• 指定 AI 应该遵循的规则
• 创建可重复的流程
• 需要自动应用的指南

使用 Skill 文件：

• 记录详细的技术知识
• 保存最佳实践和经验
• 提供参考资料和示例
• 团队知识库

最佳实践是两者结合：

---
inclusion: manual
---

# 翻译工作流

## 快速规则
#[[file:.kiro/skills/translation-rules.md]]

## 术语表
#[[file:docs/glossary.yaml]]

## 工作流步骤
1. 读取源文件
2. 应用术语表
3. 逐段翻译
4. 质量检查

5. Steering 工作机制

用户手动触发 Steering 文件

用户在聊天中输入：#translation-workflow
    ↓
Kiro 识别引用
    ↓
加载 .kiro/steering/translation-workflow.md
    ↓
解析 FrontMatter 和文件引用
    ↓
自动加载 #[[file:docs/glossary.yaml]]
    ↓
所有规则和术语表被注入到 AI 上下文
    ↓
AI 在后续交互中遵循这些规则

自动应用 Steering 文件

用户打开或编辑文件
    ↓
Kiro 检查文件类型
    ↓
查找 inclusion: auto 且 fileMatchPattern 匹配的 steering 文件
    ↓
自动加载匹配的 steering 文件
    ↓
AI 在交互中自动应用这些规则

6. Steering 最佳实践

6.1 组织结构清晰

.kiro/steering/
├── translation-workflow.md      # 翻译工作流
├── code-style-python.md         # Python 代码风格
├── code-style-typescript.md     # TypeScript 代码风格
├── documentation-rules.md       # 文档规范
└── testing-guidelines.md        # 测试指南

6.2 命名规范

• 使用描述性名称：translation-workflow.md 而不是 workflow.md
• 使用小写和连字符：code-style-python.md
• 包含上下文：api-documentation-rules.md

6.3 内容组织

---
inclusion: manual
---

# 清晰的标题

## 概述
简要说明这个 steering 文件的用途

## 核心规则
最重要的规则放在前面

## 详细说明
具体的实现细节

## 参考资料
#[[file:相关文件]]

## 常见问题
Q: ...
A: ...

6.4 文件引用最佳实践

# ✅ 好的做法

## 术语表
#[[file:docs/glossary.yaml]]

## 代码示例
#[[file:examples/good-example.md]]

---

# ❌ 避免的做法

## 不要引用过多文件
#[[file:file1.md]]
#[[file:file2.md]]
#[[file:file3.md]]
#[[file:file4.md]]
# 这会导致上下文过大

## 不要使用绝对路径
#[[file:/Users/username/project/docs/file.md]]  # ❌
#[[file:docs/file.md]]  # ✅

6.5 保持简洁

• 避免过长的 steering 文件
• 如果超过 500 行，考虑拆分为多个文件
• 使用清晰的标题和分段

6.6 版本控制

---
inclusion: manual
version: "1.0"
last_updated: "2026-05-12"
---

# 翻译工作流 v1.0

## 更新日志
- v1.0 (2026-05-12): 初始版本
- v0.9 (2026-05-10): 测试版本

7. 常见使用场景

场景 1：多语言翻译项目

创建针对不同语言的 steering 文件：

.kiro/steering/
├── translation-zh-CN.md    # 中文翻译规则
├── translation-ja-JP.md    # 日文翻译规则
└── translation-es-ES.md    # 西班牙文翻译规则

场景 2：多项目代码风格

为不同项目定义不同的代码风格：

.kiro/steering/
├── project-a-style.md      # 项目 A 的代码风格
├── project-b-style.md      # 项目 B 的代码风格
└── shared-rules.md         # 共享规则

场景 3：内容创建工作流

为不同类型的内容创建定制工作流：

.kiro/steering/
├── blog-post-workflow.md       # 博客文章工作流
├── technical-doc-workflow.md   # 技术文档工作流
├── social-media-workflow.md    # 社交媒体工作流
└── video-script-workflow.md    # 视频脚本工作流

8. 故障排除

问题 1：Steering 文件没有被加载

症状：手动引用 steering 文件后，规则没有被应用

解决方案：

1. 检查文件路径是否正确
2. 确认 FrontMatter 配置正确
3. 检查文件是否存在于 .kiro/steering/ 目录
4. 尝试重新启动 Kiro

问题 2：文件引用失败

症状：#[[file:...]] 引用的文件没有被加载

解决方案：

1. 使用相对路径而不是绝对路径
2. 确认引用的文件存在
3. 检查路径中是否有特殊字符
4. 验证文件格式是否支持

问题 3：上下文过大

症状：加载了太多 steering 文件，导致上下文溢出

解决方案：

1. 减少引用的文件数量
2. 拆分大型 steering 文件
3. 只引用必要的部分
4. 使用 inclusion: manual 而不是 auto

9. 高级技巧

1. 条件性 Steering 文件

虽然 Kiro 不直接支持条件逻辑，但你可以创建多个 steering 文件并根据需要选择：

.kiro/steering/
├── translation-strict.md       # 严格模式
├── translation-relaxed.md      # 宽松模式
└── translation-standard.md     # 标准模式

2. 组合多个 Steering 文件

在一个 steering 文件中引用其他 steering 文件的内容：

---
inclusion: manual
---

# 完整翻译工作流

## 基础规则
#[[file:.kiro/steering/translation-base.md]]

## 术语表
#[[file:docs/glossary.yaml]]

## 高级技巧
#[[file:.kiro/steering/translation-advanced.md]]

3. 动态更新

定期审查和更新 steering 文件：

---
inclusion: manual
version: "2.0"
last_updated: "2026-05-12"
next_review: "2026-06-12"
---

# 翻译工作流

## 最近更新
- 添加了新的术语
- 改进了格式规则
- 优化了工作流步骤

写在最后

Steering 文件是 Kiro 中强大的功能，它能够：

✅ 提高效率：一次定义，多次使用
✅ 保证一致性：确保所有输出遵循相同标准
✅ 易于维护：集中管理所有规则
✅ 灵活应用：支持多种触发方式
✅ 可扩展性：支持文件引用和组合

通过合理使用 Steering 文件，你可以将 Kiro 从一个通用 AI 工具转变为一个针对你的项目定制的强大工作流系统。

相关资源

• Kiro 官方文档：Kiro Features