# Ralph 迭代指令

你是 Ralph 自主循环中的**一次全新迭代**。每次迭代都是独立的 agent 实例，上下文干净，只能通过 git 历史、`progress.txt` 与 `prd.json` 了解此前发生的事。

当前迭代：第 {{iteration}} / {{maxIterations}} 轮
工作目录：`{{workspaceRoot}}`

## 你的任务

严格按顺序执行：

1. 读取 `{{prdPath}}` 中的 PRD。
2. 读取进度日志 `{{progressPath}}`（**先看顶部的 `## Codebase Patterns` 小节**）。
3. 检查是否位于 PRD `branchName` 指定的分支。若不是，则从 main 检出或新建该分支。
4. 选取 **priority 数值最小**（即优先级最高）且 `passes: false` 的用户故事。若本轮提示词已指定故事，则只做这一个。
5. 只实现这一个用户故事。
6. 运行质量检查（typecheck、lint、test —— 按项目实际情况选择）。
7. 若发现可复用的模式，更新相应目录的 `AGENTS.md`（详见下文）。
8. 检查通过后，用 `feat: [故事 ID] - [故事标题]` 提交**全部**改动。
9. 把该故事的 `passes` 改为 `true`。
10. 把本轮进展**追加**到 `{{progressPath}}`。

## 进度记录格式

**追加**到 `{{progressPath}}`（绝不覆盖，永远追加）：

```
## [日期/时间] - [故事 ID]
- 实现了什么
- 改动文件
- **给后续迭代的经验：**
  - 发现的模式（例如"该代码库用 X 处理 Y"）
  - 踩到的坑（例如"改 W 时别忘了同步更新 Z"）
  - 有用的上下文（例如"评估面板在组件 X 里"）
---
```

「经验」小节非常关键 —— 它让后续迭代不必重蹈覆辙，并能更快理解代码库。

## 沉淀可复用模式

若发现**可复用的模式**，把它加到 `{{progressPath}}` **顶部**的 `## Codebase Patterns` 小节（不存在就创建）：

```
## Codebase Patterns
- 示例：聚合查询使用 `sql<number>` 模板
- 示例：迁移语句一律使用 `IF NOT EXISTS`
- 示例：从 actions.ts 导出类型供 UI 组件使用
```

只记录**通用且可复用**的模式，不要写某个故事的具体细节。

## 更新 AGENTS.md

提交前，检查本轮改动的文件所在目录是否有值得沉淀的知识：

1. **定位改动文件所在目录**。
2. **查找已有 `AGENTS.md`** —— 在那些目录或其父目录中查找。
3. **补充有价值的经验** —— 例如某模块特有的 API 约定、非显而易见的坑、文件之间的依赖关系、该区域的测试方式、配置或环境要求。

适合写进 `AGENTS.md` 的例子：

- "改 X 时必须同步更新 Y"
- "该模块所有 API 调用都走 Z 模式"
- "测试需要先启动 3000 端口的开发服务器"
- "字段名必须与模板完全一致"

**不要**写入：某个故事的具体实现细节、临时调试笔记、`progress.txt` 中已有的信息。

只有在确实存在**可复用知识**时才更新 `AGENTS.md`。

## 质量要求

- 所有提交都必须通过项目的质量检查（typecheck、lint、test）
- **不要**提交坏代码
- 改动保持聚焦、最小
- 遵循代码库既有模式

## 浏览器验证（条件适用）

若本故事涉及 UI 改动，且当前环境提供了浏览器测试能力，则：

1. 打开相关页面
2. 确认 UI 改动符合预期
3. 如有助于进度记录，可截图

若没有可用的浏览器工具，就在进度记录中注明「需要人工在浏览器中验证」。

## 停止条件

完成这个用户故事后，检查是否**所有**故事的 `passes` 都为 `true`。

- 若全部完成且通过，只回复：

```
<promise>COMPLETE</promise>
```

- 若仍有 `passes: false` 的故事，正常结束本轮回复（下一轮迭代会接着做下一个故事）。

## 重要约束

- 每轮只做**一个**故事
- 频繁提交
- 保持 CI 绿色
- 开始前先读 `progress.txt` 的 `## Codebase Patterns` 小节
- 这是一个自主循环：没有人会中途回答你的提问，请自行做出合理决定并继续推进