ralph-loop-kiro-specs

Kiro 规格的 Ralph 循环

一种自动化、迭代式 Agent 运行器，可在 Kiro 中驱动基于规格的开发。它将 kiro-cli 封装在 bash 循环中，并向其提供精心设计的提示词，使 Kiro 成为一名严谨、善于自我纠正的实现 Agent——能够从规格中选取任务、加以实现、验证自己的工作，并在多次迭代中吸取经验教训。

鸣谢： 基于 mreferre 的 ralph-loop-kiro-specs，采用 Apache License 2.0 许可。

适用场景

• 通过反复进行 Agent 迭代，自动实现 Kiro 规格中的任务
• 无需逐条手动输入提示词，即可驱动规格从头到尾完成
• 在新项目中设置 Ralph 循环
• 排查卡住或失败的 Ralph 循环运行
• 了解进度跟踪、修正和代码库模式的工作方式
• 生成或解读完成后的摘要仪表板

先决条件

要求	详情
Kiro CLI	必须已安装 kiro-cli，并将其添加到 PATH（kiro.dev/cli）
Kiro IDE	已安装 kiro.dev
Bash	标准 bash shell
Kiro 规格	项目中包含位于 .kiro/specs/<specs_name>/ 下的规格，且至少包含 requirements.md、design.md 和 tasks.md

工作原理

Ralph 会运行一个循环，每次迭代都会向 kiro-cli 发送提示词。该提示词要求 Agent 遵循严格的六阶段循环：

六个阶段

1. 加载上下文 — 阅读引导文件（product.md、structure.md、tech.md）和目标规格（requirements.md、design.md、tasks.md、progress.md）。盘点可用工具。
2. 选取一项任务 — 找出编号最小的未完成顶级任务。记录开始时间。每次迭代绝不能选取多项任务。
3. 实现前先理解 — 阅读相关源文件，研究现有模式，重新阅读 progress.md 中的 Corrections 和 Codebase Patterns 部分，并主动应用所有相关修正。
4. 实现 — 按顺序实现该任务及其所有子任务。运行类型检查和测试。如果失败：修复问题；如果后续迭代可能遇到同样的问题，立即记录修正；然后继续。失败尝试 5 次后，将任务标记为 [F]，并记录尚未解决的阻碍。
5. 验证退出标准 — 重新阅读 requirements.md 中的退出标准和 design.md 中的设计约束。确认每项都已满足后，再将任务标记为完成。
6. 更新跟踪信息 — 在 tasks.md 中将任务标记为 [X]，向 progress.md 追加进度记录，添加新的代码库模式，进行最后一次修正检查，并将耗时记录到 specs_time.md。

自我纠正系统

progress.md 顶部的 Corrections 部分是一个平铺的错误及其修复方案查询表。每次迭代都会在开始任何工作前读取该表，并且绝不能重复其中列出的错误。发生错误时应立即记录修正，而不是等到任务结束。

格式：

- ❌ `python manage.py migrate` → ✅ `python3 manage.py migrate` (system has no `python` alias)
- ❌ Running tests with `npm test` → ✅ `npm run test:unit` (project uses separate test scripts)
- ❌ UNRESOLVED: [description of issue that couldn't be fixed after 5 attempts]

代码库模式

Ralph 会累积实现过程中发现的惯例，例如文件命名、导入模式、错误处理、测试命令等。只记录实际遇到的模式，不记录推测性模式。

完成状态与摘要仪表板

所有任务都标记为 [X] 后，Ralph 会在规格目录中生成一个独立的 summary.html，其中包含：

• 顶部面板：规格名称、状态指示器（绿色/红色）、总耗时、任务数量、日期范围
• 左侧面板：可折叠的任务树，悬停提示会显示进度详情
• 右侧面板：计时表，列出每项任务的开始/结束时间和持续时间

项目结构

运行 Ralph 前，用户的项目结构应如下所示：

your-project/
├── ralph-loop-kiro-specs-prompt.md    # The Ralph agent prompt template
├── ralph-loop-kiro-specs-script.sh    # The loop runner script
└── .kiro/
    ├── steering/
    │   ├── product.md                 # What the product is
    │   ├── structure.md               # Project structure conventions
    │   └── tech.md                    # Tech stack and tooling
    └── specs/
        └── <specs_name>/
            ├── requirements.md        # Requirements and exit criteria
            ├── design.md              # Architecture and design decisions
            ├── tasks.md               # Task checklist
            ├── progress.md            # Auto-created: corrections, patterns, progress log
            ├── specs_time.md          # Auto-created: per-task timing
            └── summary.html           # Auto-generated on completion: visual dashboard

设置说明

要在项目中设置 Ralph Loop：

1. 将脚本和提示词模板复制到项目根目录：
   • ralph-loop-kiro-specs-script.sh — 循环运行脚本（随此技能打包，位于 scripts/ 下）
   • ralph-loop-kiro-specs-prompt.md — Agent 提示词模板（随此技能打包，位于 references/ 下）
2. 将脚本设为可执行：chmod +x ralph-loop-kiro-specs-script.sh
3. 确保项目已在 .kiro/specs/<specs_name>/ 下设置 Kiro 规格，且至少包含 requirements.md、design.md 和 tasks.md
4. 确保 .kiro/steering/ 下存在 steering 文件（product.md、structure.md、tech.md）——这些文件能显著提升输出质量

用法

./ralph-loop-kiro-specs-script.sh <max_iterations> <specs_name>

参数	说明
max_iterations	循环的最大迭代次数（正整数）。每次迭代实现一个任务。设置值至少应等于任务数量，并留出重试余量。
specs_name	.kiro/specs/ 下规格目录的名称。该目录及所需文件必须已存在。

示例

# Run up to 15 iterations on the "auth-feature" spec
./ralph-loop-kiro-specs-script.sh 15 auth-feature

迭代模式

脚本启动时会询问是自动运行还是手动运行：

• 自动 — 连续运行任务，中间不会暂停。适用于定义明确的规格。
• 手动 — 每次迭代后暂停，以便审查。适用于新的或不熟悉的规格。

故障排除

Ralph 卡在某个任务上（标记为 [F]）

手动修复问题，更新 tasks.md 以取消该任务的标记，然后重新运行。失败尝试中的修正仍会保留在 progress.md 中，供下一次迭代参考。

达到最大迭代次数，但尚未完成

增加 max_iterations 并重新运行。Ralph 会从上次进度继续，因为它会读取 tasks.md 来查找下一个未完成的任务。

Agent 每次迭代实现了多个任务

这违反了核心约束。检查是否使用了未经修改的提示词模板。模板顶部有一个关键约束部分，用于确保每次迭代只处理一个任务。

缺少 steering 文件

Ralph 即使没有这些文件也能运行，但提供上下文后效果更好。创建 .kiro/steering/product.md、structure.md 和 tech.md，分别描述产品、项目结构和技术栈。

质量检查清单

运行 Ralph Loop 前，请确认：

• 已安装 kiro-cli，且可通过 PATH 使用
• .kiro/specs/<specs_name>/ 下存在规格目录
• requirements.md 包含带退出条件的编号需求
• design.md 包含架构和设计决策
• tasks.md 包含带子任务的编号任务清单
• .kiro/steering/ 下存在 steering 文件（推荐）
• max_iterations 设置为至少等于任务数量，并留出余量
• 项目根目录中存在提示词模板（ralph-loop-kiro-specs-prompt.md）
• 脚本（ralph-loop-kiro-specs-script.sh）具有可执行权限

随附资源

资源	路径	说明
运行脚本	scripts/ralph-loop-kiro-specs-script.sh	驱动迭代的 bash 循环。复制到项目根目录。
提示词模板	references/ralph-loop-kiro-specs-prompt.md	Agent 提示词模板。复制到项目根目录。

需要了解详细的阶段说明、修正格式、代码库模式类别或摘要仪表板规范时，请阅读提示词模板。

许可证

此技能基于 mreferre 的 ralph-loop-kiro-specs，并依据 Apache License 2.0 授权。

Copyright [mreferre]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.