Kiro Steering 文件 Inclusion 模式详解一、什么是 Steering 文件Steering 文件是 Kiro 的上下文注入机制——通过 Markdown 文件向 Kiro 提供额外的指令、规范和上下文信息影响 Kiro 在对话中的行为方式。它的作用类似于给 Kiro 制定工作手册告诉它在什么场景下、按什么规则、用什么方式来处理任务。存放位置路径作用域.kiro/steering/*.md当前工作区项目级别对当前项目生效~/.kiro/steering/*.md用户级别全局对所有项目生效工作区级别的规则优先级高于用户级别。冲突时以工作区为准。注博客https://blog.csdn.net/badao_liumang_qizhi二、三种 Inclusion 模式Steering 文件通过 front-matterYAML 头部中的inclusion字段来控制何时被加载到 Kiro 的上下文中。2.1 自动加载模式Always配置方式不写inclusion字段或写一个空的 front-matter。--- --- # 你的规范内容行为每次新建会话时Kiro 自动将此文件的内容加载到上下文中。无需任何手动操作。适用场景编码规范命名约定、注释要求接口调用规范认证方式、地址配置项目架构说明模块职责、技术栈团队约定Git 规范、代码审查标准示例——编码规范--- --- # 项目编码规范 ## 命名规则 - 类名使用 PascalCase - 方法名和变量名使用 camelCase - 常量使用 UPPER_SNAKE_CASE - 数据库字段使用 snake_case ## 代码注释 - 注释语言统一使用中文 - 公共方法必须写 JavaDoc - 复杂逻辑需要写行内注释说明意图 ## 异常处理 - 禁止空 catch 块 - 业务异常使用自定义异常类 - 异常信息需包含上下文参数2.2 手动引入模式Manual配置方式--- inclusion: manual --- # 你的规范内容行为不会自动加载。需要用户在聊天输入框中通过#文件名不含.md后缀手动引入。触发方式在聊天中输入#然后选择对应文件名。适用场景偶尔使用的工具说明特定任务的操作指南参考文档不需要每次都看敏感配置不想每次都暴露在上下文中示例——部署流程指南--- inclusion: manual --- # 生产环境部署流程 ## 部署步骤 1. 确保所有测试通过 2. 合并代码到 release 分支 3. 执行 mvn clean package -Pprod 4. 上传到制品库 5. 通过运维平台触发部署 ## 回滚方式 - 制品库中选择上一个版本重新部署 - 数据库回滚脚本位于 docs/rollback/ 目录使用时在聊天中#生产环境部署流程即可激活。2.3 条件匹配模式FileMatch配置方式--- inclusion: fileMatch fileMatchPattern: **/*.java --- # 你的规范内容行为当 Kiro 读取到匹配fileMatchPattern的文件时自动将此 Steering 文件激活并注入上下文。适用场景针对特定文件类型的规范Java 规范、SQL 规范、前端规范特定目录下文件的操作说明读取配置文件时的注意事项fileMatchPattern 语法标准 Glob 语法模式匹配*.java当前目录下的 Java 文件**/*.java所有目录下的 Java 文件src/main/**/*.xmlsrc/main 下所有 XML 文件*Controller.java所有以 Controller 结尾的 Java 文件README*所有 README 开头的文件docker-compose*.yml所有 docker-compose 相关的 yml 文件示例——Java 文件规范--- inclusion: fileMatch fileMatchPattern: **/*.java --- # Java 代码规范 ## 类结构顺序 1. 静态常量 2. 实例变量 3. 构造方法 4. 公共方法 5. 私有方法 ## 方法命名前缀 - 查询: get / find / query / list - 创建: create / add / save - 更新: update / modify - 删除: delete / remove - 校验: check / validate / verify示例——SQL 文件规范--- inclusion: fileMatch fileMatchPattern: **/*.sql --- # SQL 编写规范 ## 命名规则 - 表名使用 snake_case加业务前缀如 t_order_detail - 索引名格式: idx_表名_字段名 - 必须包含 id、create_time、update_time 字段 ## 查询规范 - 禁止 SELECT * - WHERE 条件必须走索引 - 大表查询必须加 LIMIT示例——Docker 相关文件规范--- inclusion: fileMatch fileMatchPattern: Dockerfile* --- # Dockerfile 规范 ## 基本要求 - 基础镜像使用公司内部镜像仓库 - 必须指定镜像版本不用 latest - 使用多阶段构建减小最终镜像大小 - 非 root 用户运行应用三、模式对比一览维度自动加载 (Always)手动引入 (Manual)条件匹配 (FileMatch)配置---\n---或不写inclusion: manualinclusion: fileMatchfileMatchPattern加载时机每个会话自动用户#引用时匹配文件被读入时上下文占用始终占用按需占用条件占用适合内容核心规范、必须遵守的操作手册、参考文档文件类型相关的规范会话间一致性✅ 所有会话一致❌ 需要手动激活✅ 读到匹配文件就激活四、文件引用语法Steering 文件支持引用项目中其他文件作为上下文# API 接口规范 接口设计需要符合以下 OpenAPI 规范 #[[file:docs/openapi.yaml]] 数据库表结构参考 #[[file:docs/schema.sql]]#[[file:相对路径]]语法会把被引用文件的内容嵌入到 Steering 文件中作为 Kiro 的额外上下文。适用场景引用 OpenAPI/Swagger 规范指导接口开发引用 GraphQL Schema 指导查询编写引用数据库 DDL 指导 SQL 编写引用设计文档指导实现五、实用场景示例集5.1 Git 提交规范自动加载--- --- # Git 提交规范 ## Commit Message 格式 - feat: 新功能 - fix: 修复 bug - docs: 文档变更 - refactor: 重构 - test: 测试相关 - chore: 构建/工具链变更 ## 分支命名 - feature/功能描述 - bugfix/问题描述 - hotfix/紧急修复描述 ## 规则 - 提交信息使用中文 - 每次提交只做一件事 - 不要提交 .idea/ 和 target/ 目录5.2 接口调用规范自动加载--- --- # 本地接口测试规范 ## 认证方式 - 认证地址: POST https://auth-server.com/oauth/token - client_id: my_client - client_password: my_password - grant_type: password - username: testuser - password: testpass ## 业务接口 - 基础地址: http://127.0.0.1:8080 - 认证头: Authorization: Bearer access_token ## 流程 1. 先获取 token 2. 带 token 调用业务接口5.3 代码审查清单手动引入--- inclusion: manual --- # 代码审查清单 ## 检查项 - [ ] 是否有未处理的异常 - [ ] 是否有硬编码的配置值 - [ ] 是否有 SQL 注入风险 - [ ] 是否有并发安全问题 - [ ] 新增字段是否更新了文档 - [ ] 是否有性能问题N1 查询、大循环中的 IO - [ ] 日志是否完整入参、出参、异常5.4 前端文件规范条件匹配--- inclusion: fileMatch fileMatchPattern: **/*.tsx --- # React 组件规范 ## 组件结构 - 使用函数组件 Hooks - Props 使用 interface 定义类型 - 组件文件名与组件名一致PascalCase ## 状态管理 - 局部状态用 useState - 跨组件共享用 Context 或状态库 - 异步请求用 useEffect cleanup ## 样式 - 使用 CSS Modules 或 Tailwind - 禁止行内样式5.5 数据库迁移规范条件匹配--- inclusion: fileMatch fileMatchPattern: **/migration/** --- # 数据库迁移规范 ## 文件命名 - 格式: V{版本号}__{描述}.sql - 示例: V20260701__add_user_status_column.sql ## 规则 - 每个迁移文件只做一件事 - DDL 和 DML 不混在一个文件中 - 必须可回滚提供对应的 rollback 脚本 - 大表 ALTER 需要评估锁表影响六、最佳实践核心规范用自动加载——编码规范、接口调用方式、项目约定等每次都需要的内容设为自动加载确保所有会话行为一致。参考文档用手动引入——部署手册、设计文档、不常用的操作指南用 manual 模式避免浪费上下文空间。文件类型规范用条件匹配——Java 规范只在处理 Java 文件时生效SQL 规范只在处理 SQL 时生效精准注入。文件要精简——Steering 文件会占用 Kiro 的上下文窗口。自动加载的文件尽量控制在关键信息不要写成长篇文档。敏感信息注意安全——自动加载的文件每次都会被读取。如果包含密码等敏感信息考虑是否适合自动加载或者将其加入.gitignore避免提交。工作区 用户级别——团队规范放.kiro/steering/随项目走个人偏好放~/.kiro/steering/不影响团队。
