为什么同一个 steering 文件在不同界面上的表现不同
Kiro 的 steering 页面以一个功能矩阵表开篇，其中的行设计代表了整体架构。“工作区 steering（.kiro/steering/）”在 IDE、CLI、Web 和移动端均可用。“全局 steering（~/.kiro/steering/）”在 IDE 和 CLI 中可用，但在 Web 和移动端被标记为不可用。“在 Web 设置中管理的云端 steering”仅限 Web。 “通过 UI 生成基础文件”仅限 IDE。“引入模式（always、fileMatch、manual）”则被标记为在所有四个界面中均可用。
最后一行正是困惑的源头，因为页面下方更详细的说明对其进行了限制：CLI 目前不支持引入模式，在 CLI 中，目录中的所有内容都会自动加载。因此，正确的思维模型不是“我的规则会跟随我到任何地方”，而是更接近于：文件会跟随您，但限制条件不会。
全局目录也有其自身的边界，文档中同样有所提及：“在 Web 上，‘全局 steering’指的是您本地的 ~/.kiro/steering/ 目录，云端沙箱无法读取该目录。”文档中给出的解决路径是配置同步（Configuration Sync）：“要在跨云会话中重用个人 steering，请通过配置同步上传它；随后云端副本将应用于每个云端会话。”
还有第四种情况，会让那些开始构建自己的自定义智能体的人措手不及。文档指出：“使用自定义智能体时，不会自动包含 steering 文件。您必须显式将它们添加到智能体的 resources 配置中，以加载 steering 上下文。”在智能体的 resources 中添加类似 file://.kiro/steering/**/*.md 的 glob 匹配，才能将它们重新引入。
此外，有一个文件名完全不受限制规则的影响。Kiro 支持 AGENTS.md 标准，但页面上有一个警告：“AGENTS.md 文件不支持引入模式，并且始终会被包含。”如果您在仓库根目录下保留一个跨工具共享的文件，那么根据定义，它就是一个“始终启用”的文件，无论您在其他地方对前置元数据的控制有多么严格。
人们尝试的其他替代方案
删除前置元数据并重新开始。 当条件文件表现异常时，人们的直觉往往是认为 YAML 写错了。通常并非如此。文档确实警告过“引入配置必须是文件中的第一项内容——前面不能有空行或内容”，这值得检查一次——但如果该文件在 IDE 中工作正常，而在 CLI 中不正常，那么前置元数据没有问题，变量在于运行界面。
将所有内容移入三个基础文件中。 product.md、tech.md 和 structure.md 是真实且有用的，文档指出“默认情况下，这些基础文件会包含在每次交互中，构成 Kiro 对项目理解的基线。”这里的失败模式在于将其视为合并的许可：您折叠进去的每一项内容都会在所有地方始终启用，而这恰恰是您想要避免的结果。
将个人偏好放入全局目录并假设它们会同步。 它们确实会同步到 IDE 和 CLI。但文档记录了云端沙箱无法读取该目录，因此这些偏好在 Web 会话中会悄无声息地失效——并且没有任何提示。
精简目录直到 CLI 表现正常。 这确实有效，因为加载的文件变少了。但它也剥夺了 IDE 中使其表现优异的条件性引导。您最终通过降低一个界面的体验来调整另一个界面。
假设这与其他地方的规则触发模式是同一个问题。 它们看起来很相似，但失败的本质不同。当一个工具在所有地方都支持触发模式而规则仍未触发时，问题在于您选择了哪种模式，这在如何选择 Windsurf 规则触发模式中有所讨论。而在本文的情况中，模式是正确的，只是运行界面忽略了它。
解决方案：按各界面必须加载的内容对 steering 进行分类，并限制其余内容
步骤 1：将目录拆分为“始终启用”层和“受限”层
将 .kiro/steering/ 中的所有内容根据一个问题分类到两个堆中：如果这个文件在每个界面上的每个任务中都永久加载，是否可以接受？
“可以接受”的一堆是您的“始终启用”层——包括基础文件以及任何真正通用的内容。Kiro 自身的描述是一个很好的过滤器：product.md “定义您的产品目的、目标用户、关键功能和业务目标”，tech.md “记录您选择的框架、库、开发工具和技术限制”，以及 structure.md “概述文件组织、命名规范、导入模式和架构决策”。刻意保持这一层足够小，因为在 CLI 上，这是唯一存在的层。
“不可接受”的一堆是您的“受限”层：特定于框架的规范、迁移步骤、故障排除指南以及任何篇幅较长的内容。这些文件需要添加前置元数据——并且您需要接受它们在 CLI 上仍然会被加载，这也是防止这一堆文件无限制增长的原因。
在此过程中，请遵循命名建议。文档建议使用能够表明范围的名称，例如 api-rest-conventions.md、testing-unit-patterns.md 和 components-form-validation.md，并遵循“一个文件一个领域”的原则。在这里，名称比平时更重要，因为在所有内容都会加载的界面上，文件名是判断文件用途的唯一信号。
步骤 2：选择与文件引入方式匹配的引入模式
文档中记录了四种模式，它们不可互换。
inclusion: always 是默认模式，不需要前置元数据即可生效。inclusion: fileMatch 接受一个 fileMatchPattern，它可以是单个 glob 匹配（如 components/**/*.tsx）或一个数组（如 ["**/*.ts", "**/*.tsx", "**/tsconfig.*.json"]）。inclusion: manual 使文件“在您的聊天消息中通过使用 #steering-file-name 引用来按需提供”，文档指出“手动 steering 文件也会作为斜杠命令出现——在聊天中输入 / 即可查看并选择它们。” inclusion: auto 需要两个字段——name（“steering 文件的标识符，用于显示和匹配”）和 description（“何时包含此文件。Kiro 会将其与您的请求进行匹配”）——并且该文件会在“您的请求与描述匹配时”被拉取。
记录的用例非常值得遵循，而不是重新发明。手动模式“最适合：专业工作流、故障排除指南、迁移步骤或仅偶尔需要且包含大量上下文的文档。”自动模式“最适合：仅在相关时才应加载的包含大量上下文的引导——例如专业领域知识、复杂工作流或会使始终启用的 steering 载荷过重的详细参考资料。”
这里还涉及另一个机制。与其将规范粘贴到 steering 文件中，不如使用 #[[file:<relative_file_name>]] 引用实时文件——文档给出了 #[[file:api/openapi.yaml]]、#[[file:components/ui/button.tsx]] 和 #[[file:.env.example]] 作为示例。指针能保持最新，而粘贴的内容从您编写的那天起就开始产生偏差。同样的道理也适用于通过路径而非文字来限定指令范围，正如在如何将 Amp 指令限定到文件中所讨论的那样。
步骤 3：按界面放置每个文件，然后在您实际使用的界面上进行验证
现在，根据功能矩阵表而非习惯来决定每个文件的物理存放位置。
仓库标准放入 .kiro/steering/ 并提交。个人偏好放入 ~/.kiro/steering/，冲突规则在文档中已有说明：“如果全局 steering 和工作区 steering 的指令发生冲突，Kiro 将优先采用工作区 steering 指令。”对于云端会话，请从 Kiro Web 的“设置与同步”中上传个人 steering，然后在“设置与 Steering”下创建或编辑云端副本。
团队也有记录在册的路径：“全局 steering 功能可用于定义适用于整个团队的集中式 steering 文件。团队 steering 文件可以通过 MDM 解决方案或组策略推送到用户的电脑，或者由用户从中央仓库下载到他们的电脑，并放入 ~/.kiro/steering 文件夹中。”
然后在关键的地方进行验证。打开您日常使用时间最长的界面，运行一个不应该触发受限文件的任务，以及一个应该触发的任务。在 CLI 上，预期工作区目录中的所有内容都会加载；这种预期本身就是验证。如果您使用自定义智能体，请确认 resources glob 匹配存在，因为没有它，该智能体根本不会加载 steering 上下文。
在 MemoryLake 中进行设置
steering 文件是常驻的简报——规范、技术栈、结构。但它们不太适合承载项目知识的另一半：您做出了什么决定、何时做出的，以及为什么拒绝了替代方案。那一半知识需要能够按需检索，而不是在每个任务中都加载，并且它不应该因为您打开的是 IDE 还是终端而改变形态。一个您有目的地写入 MemoryLake 条目的存储库可以将这些记录保存在一个地方。您可以用自己的语言亲自编写这些条目。您的 Kiro 目录中不会有任何内容被读取、写入或删除。
步骤 1：创建 API 密钥
登录并从您的工作区设置中生成一个 API 密钥。这是您的智能体和集成所使用的凭据，因此在开始移动任何内容之前，请先创建它。
步骤 2：上传您的第一批记忆
从您的 steering 文件暗示但从未明说的决定开始：为什么选择这个技术栈、您拒绝了哪种方法以及基于什么理由、哪个约束的存在是因为没人记得的原因。将每个决定写成简短的独立笔记，以便可以单独检索。
步骤 3：连接您的 AI 和智能体
连接您使用的助手和智能体。然后，这些记录将跟随您跨越不同的界面和工具，而不再依赖于特定会话可以读取哪个目录。
这在实践中带来了什么改变
您的“始终启用”层变成了一种预算，而不仅仅是一个文件夹。一旦您接受了某个界面会加载所有内容，该目录的大小就成了您有意识做出的决定，而不是任其累积。该预算会直接影响到在漫长的会话后期还剩下多少空间，这与在 Kiro 压缩中保留什么中所探讨的权衡是一样的。
评审获得了第二条渠道。在 Kiro Web 上，对拉取请求（PR）的反馈会变成 steering：使用诸如“始终使用我们的标准错误处理”之类的引导进行评论，“智能体会学习并将这些模式应用到您所有仓库的未来工作中。”文档中同时声明了一个重要的限制——“只有您的反馈（创建任务的用户）会影响智能体的学习。其他评审人员的评论不会影响智能体的学习。”资深评审人员对其他人任务的评论不会教给智能体任何东西。
跨工具文件不再是免费的午餐。根目录下的 AGENTS.md 很方便且始终会被包含，这意味着它属于您的“始终启用”预算，而不是预算之外。如果您在多个智能体之间维护同一个文件，每个工具的加载契约都不同，而共享文件的作用仅取决于限制最少的那个读取器。
在工具之间迁移变得更容易规划。当限制条件存在于前置元数据中，而不是存在于特定于工具的 UI 中时，您可以一目了然地看到哪些内容需要在其他地方重新表达——这是如何从 Kiro 迁移到 Claude Code的实用部分。
跨界面 steering 的最佳实践
将界面假设写入文件中。在受限文件的顶部写上一行“预期仅在 src/components 中加载”不需要任何成本，却能告诉下一个人当它在其他地方出现时该检查什么。
定期审查“始终启用”层。这是在每个界面的每个任务上都会产生开销的一层，也是最容易意外膨胀的一层。
优先使用文件引用，而不是粘贴内容。指向实时规范的 #[[file:...]] 指针不会像复制的片段那样过时。
为自动引入文件提供读起来像触发器而非摘要的描述。该字段在文档中的职责是“何时包含此文件”，因此表述为条件的描述——“在创建或修改 API 端点时使用”——比主题标签能发挥更大的作用。共享上下文文件在其他工具中的行为方式相同，如Cursor 项目如何共享上下文文件中所述。
审计实际可用的内容，而不是凭记忆编写的内容。目录列表并不等同于加载列表，两者之间的差距正是如何查找目录中缺失的 Zed 技能中所描述的同一个问题。
结论
Kiro 为您提供了四种引入模式、两个目录以及跨越五个界面的同一个智能体——并且它清晰地记录了限制在何处适用，在何处不适用。CLI 会加载工作区目录中的所有内容。云端沙箱无法读取您的全局目录。自定义智能体除非您在 resources 中列出，否则不会加载任何 steering。根目录下的 AGENTS.md 始终会被包含。
将您的文件分类为在任何地方都可以接受的“始终启用”层，以及刻意保持精简的“受限”层，将个人偏好放在您实际使用的界面能够读取的地方，并在该界面上进行验证，而不是在它碰巧最先正常工作的界面上。然后，将这些规范背后的决定保存在可检索的地方，以便在下一次文件布局发生变化时，这些推理依然能够留存。