如何在不丢失上下文的情况下从 Kiro 迁移到 Codex (2026)

内容迁移了。结构没有。 Kiro 的工作区引导保存在 .kiro/steering/ 中，全局引导保存在 ~/.kiro/steering/ 中，两者都是普通的 .md 文件。Codex 读取 AGENTS.md 文件。正文内容无需修改即可移动；问题在于它落脚在何处。

每个目录一个文件是核心约束。 Codex 的发现机制是一个遍历过程：“从项目根目录（通常是 Git 根目录）开始，Codex 向下遍历到你当前的工作目录……在路径上的每个目录中，它会依次检查 AGENTS.override.md、AGENTS.md，然后是 project_doc_fallback_filenames 中的任何备用名称。Codex 每个目录最多包含一个文件。”

同一路径下的六个引导文件最多会变成一个文件。你要么将它们合并到单个根目录的 AGENTS.md 中，要么将它们分发到它们所管辖的代码目录中——而第二种选择正是 Codex 模型的设计初衷。

全局引导映射，遵循首个文件规则。 在 Codex 的主目录中，“如果存在 AGENTS.override.md，Codex 会读取它。否则，Codex 会读取 AGENTS.md。Codex 在此级别仅使用第一个非空文件。”因此，你存放个人惯例的 ~/.kiro/steering/ 目录将变成 ~/.codex/AGENTS.md 处的一个文件。覆盖文件对于临时切换非常有用：“当你需要临时全局覆盖而不想删除基础文件时，请使用 ~/.codex/AGENTS.override.md。”

合并顺序已明确，这与某些人的假设相反。 “Codex 从根目录向下拼接文件，并用空行连接它们。靠近你当前目录的文件会覆盖先前的指导，因为它们在组合提示词中出现得更晚。”后出现的获胜。这清晰地映射了 Kiro 的直觉，即具体优于通用，但它是通过拼接提示词中的位置来实现的，而不是通过优先级规则。

Kiro 的四种包含模式在 Codex 中都没有等效项。 这是实质性的损失，因此值得列出你放弃了什么。

inclusion: always 是默认设置并直接映射——这些文件在 Kiro 中是无条件的，在 Codex 中也保持无条件。

带有 fileMatchPattern 的 inclusion: fileMatch “仅在处理与指定模式匹配的文件时”加载文件，文档清楚地解释了原因：“这通过仅在需要时加载专业指导来保持上下文的相关性并减少噪音。”Codex 没有模式触发的加载。fileMatch 文件要么变成始终加载，要么变成不加载。

inclusion: manual 文件“可以通过在聊天消息中引用 #steering-file-name 来按需使用”，并且它们“也会作为斜杠命令出现”。Codex 没有按需附加指令的功能。

带有名称和描述的 inclusion: auto 是基于相关性的模式。同样缺失。

Kiro 直接指出这些模式的存在是有原因的：它们有助于“优化性能并确保在需要时提供相关的上下文”。移除它们意味着你保留的每一项内容在每次运行中都需要付出代价。

即使在 Kiro 内部，AGENTS.md 的行为也已经与 Codex 类似。 Kiro 支持该标准，但有一个记录在案的区别：“AGENTS.md 文件不支持包含模式，并且始终包含在内。”如果你的一部分 Kiro 设置已经存在于 AGENTS.md 中，那么该部分就是直接复制，并且你已经习惯了它的无条件加载。

字节上限是没人预料到的失效模式。 “Codex 会跳过空文件，并且一旦合并大小达到 project_doc_max_bytes（默认 32 KiB）定义的限制，就会停止添加文件。”它会停止。它不会发出警告。文档中记录的两种补救措施都可用：“达到上限时，提高限制或将指令拆分到嵌套目录中。”

现在结合这两个事实。Kiro 用户通常比同等 Codex 设置拥有更多的引导文本总量，这恰恰是因为包含模式使得保留大量文本的成本很低。将其扁平化为无条件文件， 32 KiB 的到来会比你想象的要快。这与 为什么 Codex 会跳过你的 AGENTS.md 规则 背后的静默不足属于同一类问题。

Specs（规范）无法迁移。 Kiro 的 specs 是结构化的产物——每个 spec 都会在 .kiro/specs/<name>/ 下生成 requirements.md、design.md 和 tasks.md，用于跟踪用户故事、架构和具体的实现任务。Codex 没有接收它们的 spec 系统。这些文件是 markdown 格式，如果你需要，它们可以保留在仓库中，但它们不再是智能体用来跟踪进度的动态产物。

云端引导有一个值得了解的限制。 如果你在 Web 上使用 Kiro，请注意“‘全局引导’指的是你本地的 ~/.kiro/steering/ 目录，云端沙箱无法读取它”，这就是为什么 Kiro 为云端会话提供配置同步（Configuration Sync）的原因。Codex 的全局文件保存在运行 Codex 的机器上，因此无论你在哪里运行它，都会遇到同类问题。

步骤 1：按位置重构，而不是按主题

克制将所有内容合并到单个根目录 AGENTS.md 中的本能。这是最快的路径，但它会直接让你撞上字节上限。

相反，请根据引导适用的位置对引导文件进行分类，然后将每个文件放入其管辖的目录中。fileMatchPattern 为 "app/api/**/*" 的引导文件将变成 app/api/AGENTS.md。作用域为 "src/components/**/*" 的引导文件将变成 src/components/AGENTS.md。Codex 自己的建议也与之相符：“Codex 一旦到达你当前目录就会停止搜索，因此请将覆盖文件放置在尽可能靠近专业工作的地方。”

这恢复了 fileMatch 所做工作的很大一部分。虽然不是全部——Codex 是在你的工作目录上触发，而不是在智能体读取的文件上触发——但在 app/api 中工作的开发人员会获得 API 指导，而不是组件指导，这正是关键所在。

对于真正通用的内容，保留一个根目录 AGENTS.md 并保持其简短。例如你的技术栈、编码规范、构建和测试命令。将 inclusion: always 文件移到这里，不要放其他内容。

如果嵌套目录需要替换而不是扩展其上方的指导，请在该目录中使用 AGENTS.override.md——Codex 会首先检查它，并采用它而不是同级的 AGENTS.md。

两个实用提示。如果仓库已经使用了不同的文件名，请注册它而不是重命名：在 ~/.codex/config.toml 中设置 project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] 会让 Codex 将这些文件视为指令文件，文档警告说“不在该列表中的文件名在指令发现中会被忽略”。如果你在 GitHub 中使用 Codex 代码审查，审查规则应放在“最靠近规则管辖代码的 AGENTS.md”中的 ## Code Review Rules 部分。

步骤 2：决定如何处理 manual 和 auto 文件，然后衡量结果

你的 inclusion: manual 和 inclusion: auto 文件是那些无家可归的文件。它们是故障排除指南、迁移步骤、“仅偶尔需要的重上下文文档”——这是 Kiro 自己对 manual 模式最适合做什么的描述。

你有三个坦诚的选择和一个糟糕的选择。你可以将它们提升为无条件加载，并在每次运行时为此付出代价。你可以将它们放在嵌套目录中，以便仅在有人在那里工作时才加载。你可以将它们保留为普通的仓库文档，在智能体被要求时读取，这最接近它们原本的行为。糟糕的选择是将它们合并到根文件中，这会导致你撞上 32 KiB 的限制，并开始丢失你真正需要的指导。

然后进行验证。Codex 准确地记录了如何验证，在重构之后，这绝不是一个可以跳过的步骤：

从仓库根目录运行 codex --ask-for-approval never "Summarize the current instructions."，并确认全局和项目文件按优先级顺序出现。运行 codex --cd subdir --ask-for-approval never "Show which instruction files are active." 以确认嵌套覆盖替换了更广泛的规则。要进行完整审计，“通过 codex -c log_dir=./.codex-log 选择加入纯文本 TUI 日志，并检查 ./.codex-log/codex-tui.log”。

有两点让这比听起来更轻松。没有需要对抗的缓存：“Codex 在每次运行（以及每个 TUI 会话开始时）都会重建指令链，因此无需手动清除缓存。”如果指导看起来被截断了，文档直接指出了解决方法——提高 project_doc_max_bytes 或拆分到嵌套目录中。

在配置时，请单独决定是否使用 Codex 自己的记忆层。它确实存在且默认关闭，其自身行为值得独立理解；开启 Codex 的本地记忆 介绍了它保留的内容以及如何控制它。

上述所有内容都是真正的重构，它让你不得不做出 Kiro 从未强迫你做出的权衡：哪些指导值得在每一次运行中都加载。

这种权衡之所以存在，是因为指令和事实被存储在同一个地方。指令是简短且行为导向的——例如“在此处运行 make test-payments”，“在未通知安全部门的情况下绝不轮换密钥”。事实是冗长且参考性的——例如为什么 API 在路径中进行版本控制、某个术语在内部意味着什么、哪个服务拥有哪个队列。Kiro 允许你将两者都保留在引导中，因为包含模式使得事实的成本很低。而 Codex 在每次运行中都会对它们收费，并受限于 32 KiB 的上限。

将它们分开，上限就不再重要了。AGENTS.md 文件保持简短且行为导向；事实保存在一个存储库中，智能体在遇到问题时会读取它。MemoryLake 的设置只需三个步骤。

步骤 1：创建 API 密钥

登录并从你的控制面板生成一个 API 密钥。它不是指令链的一部分，因此它保存的任何内容都不会计入 project_doc_max_bytes，也无需复制到嵌套目录中。

步骤 2：上传你的第一批记忆

这就是你的 manual 和 auto 引导文件该去的地方。故障排除步骤、架构决策及其背后的原因、领域词汇、迁移操作手册，以及你在审查中不断重复的答案。

将行为保留在 AGENTS.md 中。命令、规范以及每次运行都必须适用的规则正是指令链的用途所在。

步骤 3：连接你的 AI 和智能体

将 Codex 指向该存储库。偶尔需要的指导变得可用而无需常驻，你的根文件可以轻松保持在上限以下，而必须始终适用的指导足够简短，可以真正被遵循——这正是 为什么智能体会忽略你的指令文件 的关键所在。

第一个改变是 32 KiB 不再是设计约束。现在，你希望智能体了解的每一个事实都在与你希望它遵循的每一条指令竞争同一个预算。

第二个改变是失去包含模式的代价变小了。fileMatch 可以通过目录放置部分恢复；而 manual 和 auto 则无法恢复，与始终加载的文件相比，存储库更接近“按需提供”的模式。

第三个改变是你的 specs 不再是死胡同。Kiro 的 requirements.md、design.md 和 tasks.md 包含真正的决策和真正的推理。Codex 没有跟踪它们的功能，但其中的决策正是那种值得保持可读的持久知识——正如 将项目文档转化为 AI 记忆 中所阐述的观点。

• 分发，不要合并。 Codex 每个目录最多包含一个文件，因此请将指导放置在它管辖的目录中。
• 保持根文件简短。 只有 inclusion: always 的内容才属于那里。
• 将 fileMatch 转化为位置。 app/api/**/* 的模式将变成 app/api/AGENTS.md。
• 使用 AGENTS.override.md 进行替换，而不是扩展。 Codex 会在同一目录中先于 AGENTS.md 检查它。
• 注册备用文件名而不是重命名。 project_doc_fallback_filenames 会让 Codex 读取它们；未列出的名称将被忽略。
• 刻意关注上限。 加载会在达到 project_doc_max_bytes（默认 32 KiB）时停止，且没有任何警告。提高上限或进行拆分。
• 使用文档中记录的命令进行验证。 使用 codex --ask-for-approval never "Summarize the current instructions." 和 --cd subdir 变体，以及用于审计的 TUI 日志。
• 不要尝试移植 specs。 将这些文件保留为文档；将其中包含的决策提取到智能体真正可以访问的地方。

Codex 的指令模型故意设计得比 Kiro 更简单：遍历树，每个目录获取一个文件，拼接，在 32 KiB 处停止。简单是一项特性，这意味着迁移主要是一个地理位置问题——将每份指导放在它管辖的代码所在的位置。

无法保留的是条件加载，这是需要提前规划而不是事后发现的部分。尽你所能进行分发，使用 Codex 提供的命令进行验证，并将偶尔参考的材料移到不会在每次运行时都对你收费的地方。