用 Kiro 在示例游戏代码库中修 Bug 并加功能

Kiro 是一款把 AI 代理嵌进日常开发流程的编程工具，它提供 IDE、CLI、Web 与移动端等多种形态。这篇教程不讨论抽象概念，而是围绕一个可运行的开源示例游戏 Spirit of Kiro，把 Kiro 放进真实任务里用一遍：读懂一个陌生代码库、修掉两个刻意留下的 bug、做一次去重重构、实现一个横跨前后端的新功能、用钩子自动化重复劳动，最后用 MCP 扩展它的能力边界。如果你已经会写代码，但还没找到把 AI 代理稳定接入工程流程的方法，这套练习就是为你准备的。想先了解工具本身的能力范围，可以看站内的 Kiro 条目。

Spirit of Kiro 是一个无限合成类游戏：玩家发现随机生成的对象，用「切」「涂」「粘」「附魔」这类模拟交互把它们作用到彼此身上，物品会组合、拆解、变形，成品可以卖给一个 AI 鉴定师。游戏里每个对象由 AI 生成，对象之间的交互同样由 AI 模拟，因此具备近乎无限的重复可玩性。举例来说，玩家手上有两件物品——一把勺子和一罐玻璃瓶装的蔬菜，就可以用勺子从蔬菜里取出一份样本。这个核心循环已经跑通，但游戏远未完工：它有一份内容相当长的路线图，还有几个被故意留在代码里的 bug，专门留给学习者用 Kiro 去修。

整个练习建立在该游戏开源代码的一个挑战分支上。下面按任务顺序展开，每个任务都对应一类在真实项目里会反复遇到的场景。

准备工作

开始之前，先确认下面几项前置条件。这些是练习能够跑通的基础，缺一项都会卡在启动阶段。

一个 AWS 账号。 练习使用 Cognito 用户池做身份认证，因此需要能创建并配置 Cognito 资源的账号权限。
Docker 与 Docker Compose。 游戏整套服务通过一个 Docker Compose 文件构建并启动。
本地可用的 DynamoDB。 启动后需要初始化（bootstrap）DynamoDB 表，游戏数据才能落库。
已安装并可登录的 Kiro。 具体安装方式与登录流程以官网当前信息为准。
该游戏开源代码的挑战分支。 所有任务都在这个分支上完成，不要在主线上操作。

需要说明的是，账号类型、可用模型、配额与计费方式会随时间调整，动手前请以官网当前信息为准，不要依赖任何二手描述里的数字。

操作步骤

第一步：搭建开发环境并启动游戏

这一步的目标很单纯：让游戏在你自己的机器上跑起来，并且你能确认它确实在运行。顺序是固定的——先准备 AWS 账号，再配置 Cognito 用户池用于认证，然后用 Docker Compose 构建并启动整套服务，接着初始化 DynamoDB 表，最后在本地验证游戏可以正常访问和操作。

环境没跑通之前不要急着让 Kiro 改代码。原因很实际：后面每个任务都需要你亲自验证改动是否生效，如果基线本身是坏的，你无法区分「Kiro 改错了」和「环境本来就没起来」。

第二步：写 steering 文件，让 Kiro 理解这个项目

Kiro 的 steering 机制用来向代理提供项目层面的持久上下文。面对一个陌生代码库，代理最容易犯的错不是不会写代码，而是不知道这个项目里什么该做、什么不该做、代码风格是什么、哪些目录是生成物不该碰。steering 文件就是把这些约定提前讲清楚的地方。

这一步的产出有两部分：一是配置好 steering 文件，让 Kiro 对项目结构、技术栈与约定形成完整认识；二是在这个基础上，让 Kiro 动手改进游戏的主页落地页。之所以把「改进首页」放在这里，是因为它是一个范围可控、视觉结果直观的任务，适合用来检验 steering 是否真的起了作用——如果 Kiro 改出来的东西符合项目既有风格，说明上下文喂对了。

第三步：修一个隐蔽的物理 bug

现象是这样的：当玩家把浏览器标签页切走、过一会儿再切回来，游戏的物理表现会失控。

这类 bug 的典型特征是「看起来像玄学」：它依赖时间、依赖页面可见性状态、依赖主循环在后台被节流后的补偿逻辑。让人工去查，往往要在渲染循环、时间步长计算和可见性事件监听之间来回跳。让 Kiro 介入时，关键是把复现路径描述清楚——什么操作、什么时序、期望什么、实际什么。描述得越具体，代理定位问题的效率越高。

第四步：修一个跨文件的交互缺陷

游戏最初那版交互逻辑是「凭感觉写出来的」（vibe coded），结果 AI 漏掉了某些情况。这个任务的价值在于：它要求 Kiro 去纠正它自己同类产物留下的错误，而且问题横跨多个文件。

跨文件问题的难点不在单点修改，而在保持一致性。改了一处的判断条件，另一处的调用方是否还成立？错误处理路径是否被同步更新？这类任务适合让 Kiro 先给出受影响的文件清单与修改思路，你确认范围之后再让它落地，而不是一句话丢过去等结果。

第五步：做一次去重重构

重构和写新功能是两件事。写新功能是加法，重构是在不改变外部行为的前提下做减法。这个任务要求把重复代码收敛掉，也就是常说的 DRY。

让代理做重构时，务必把「行为不变」作为硬约束讲清楚，并要求它说明每一处合并的等价性依据。重复代码往往带着细微差异，盲目合并会把两个本来不同的分支压成一个，bug 就此埋下。

第六步：用 spec 实现一个复杂新功能

游戏目前缺少邮箱验证和密码重置。这个功能看起来普通，实际要同时改动客户端与服务端：前端要有入口与状态反馈，后端要有令牌生成、校验、过期与重发逻辑，还要和已有的 Cognito 认证流程对接。

这正是 Kiro 的 spec（规格）能力该上场的地方。对于这种跨端、多步骤、有明确验收标准的需求，先写规格再实现，比直接让代理改代码可靠得多。规格把「要做什么」和「怎么算做完」固定下来，实现阶段就有了可对照的检查表。素材把这类工作明确归入「用规格处理复杂任务」的范畴，简单改动则不必上规格，否则流程成本高于收益。

第七步：用 agent hooks 自动化素材管理

项目里存在一批样板式的素材管理工作，重复、琐碎、且容易出错。Kiro 的 agent hooks 可以在特定事件触发时自动执行代理动作，把这类工作从「每次手动记得做」变成「条件满足就自动做」。

这一步的练习重点是识别哪些工作值得自动化。判断标准不是「能不能自动」，而是「出错代价高不高、频率高不高」。素材管理恰好两条都占：加一个素材要改多处配置，漏一处就是运行时找不到资源。

第八步：用 MCP 扩展 Kiro

Model Context Protocol（MCP）用来给 Kiro 增加新的上下文来源与行为。前面几步都是在改游戏，这一步改的是工具本身：你可以让 Kiro 接入额外的数据源或能力，使它更贴合你的项目与工作习惯。

换句话说，这个练习有两条并行的收获线——一条是把一个半成品游戏推向完成，另一条是把 Kiro 调教成适合你工作方式的助手。后者在练习结束后仍然持续产生价值。

一个完整示例

把上面八步压缩成一条可执行的主线，就是下面这个顺序。它也是建议的练习路径：每一步都为下一步提供必要的上下文或验证基础。

环境就绪。 准备 AWS 账号 → 配置 Cognito 用户池 → 用 Docker Compose 构建并启动游戏栈 → 初始化 DynamoDB 表 → 在本地确认游戏可玩。
喂上下文。 编写 steering 文件，说明项目结构、技术栈与代码约定。
第一个验证任务。 让 Kiro 改进游戏主页落地页，检查产出是否符合项目风格。
第一个 bug。 描述「切走标签页再切回、物理失控」的复现路径，让 Kiro 定位并修复。
第二个 bug。 处理交互逻辑中 AI 遗漏的跨文件问题，先要影响面清单，再落地修改。
重构。 收敛重复代码，以行为不变为约束，逐处确认等价性。
新功能。 为邮箱验证与密码重置编写 spec，再按规格在客户端与服务端实现。
自动化。 用 agent hooks 接管易错的素材管理样板工作。
扩展。 通过 MCP 为 Kiro 增加新的上下文与行为。

如果时间有限，最小可跑通的闭环是第 1 到第 4 步：环境起来、上下文喂进去、改一个页面、修一个 bug。这四步已经覆盖了「让代理在陌生代码库里干活」的核心循环，后面的重构、规格、钩子与 MCP 都是在这个循环上叠加能力。

注意事项

bug 是故意留的。 游戏代码里的缺陷是练习设计的一部分，不要把它们当成项目质量问题，也不要在主线分支上「顺手修掉」——请始终在挑战分支上操作。
环境验证先于代码修改。 本地跑不起来时，先排查 Cognito 配置、Docker Compose 启动状态与 DynamoDB 表初始化，再考虑是不是代理改坏了什么。
重构要守住行为不变。 重复代码之间常有细微差异，合并前要求代理说明等价性依据，否则容易把两个不同分支压成一个。
复杂需求先写规格。 跨客户端与服务端、涉及认证流程的改动，直接让代理动手风险高；用 spec 固定验收标准后再实现。
自动化要有取舍。 agent hooks 适合高频且易错的样板工作，不适合低频、判断依赖人的任务。
易变信息以官网为准。 账号要求、可用模型、配额、计费与各端功能可用性都可能调整，动手前请核对官网当前信息。

练完这一轮，你手上会有一个能跑的游戏、几个被修掉的真实缺陷、一份可复用的规格写法，以及一套按你习惯配置过的 Kiro。接下来最自然的动作，是回到那份游戏路线图，挑一个你感兴趣的想法，用同样的流程自己走一遍。