ci-iteration
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCI Iteration
CI迭代
Overview
概述
Run the specified CI target and automatically fix any failures. Keep iterating until all checks pass or you get stuck on an issue that requires human intervention.
IMPORTANT: All commands must be run from the repository root directory. The Makefile is located at the root of the repository, not in subdirectories.
make运行指定的CI目标并自动修复所有故障。持续迭代直到所有检查通过，或者遇到需要人工干预的问题无法继续。
重要提示：所有命令必须在仓库根目录下运行。Makefile位于仓库根目录，而非子目录中。
makeSub-Agent Policy
子Agent策略
CRITICAL: When spawning sub-agents to run , , , , , or commands, you MUST use :
makepytesttyruffprettiergtdevrunTask tool with:
- subagent_type: devrun <- MUST be devrun, NEVER general-purposeWhy: devrun has hard tool constraints (no Edit/Write) preventing destructive changes. The parent agent (you) processes reports and applies fixes - sub-agents only report.
FORBIDDEN:
- Spawning general-purpose or other sub-agents for make/pytest/ty/ruff/prettier/gt
- Giving sub-agents prompts like "fix issues" or "iterate until passing"
REQUIRED:
- Sub-agents run ONE command and report results
- Parent agent decides what to fix based on reports
** critical **：当生成子Agent运行、、、、或命令时，必须使用：
makepytesttyruffprettiergtdevrunTask tool with:
- subagent_type: devrun <- MUST be devrun, NEVER general-purpose原因：devrun有严格的工具约束（无编辑/写入权限），可防止破坏性变更。父Agent（即你）负责处理报告并应用修复，子Agent仅负责上报结果。
禁止行为：
- 为运行make/pytest/ty/ruff/prettier/gt生成通用型或其他类型的子Agent
- 给子Agent下发类似"fix issues"或"iterate until passing"的提示
要求：
- 子Agent仅运行单个命令并上报结果
- 父Agent根据报告决定要修复的内容
Core Workflow
核心工作流
1. Initial Run
1. 初始运行
Use the devrun agent to run the specified make target from the repository root:
Task tool with:
- subagent_type: devrun
- description: "Run [make target] from repo root"
- prompt: "Change to repository root and execute: [make target]"使用devrun Agent在仓库根目录下运行指定的make目标：
Task tool with:
- subagent_type: devrun
- description: "Run [make target] from repo root"
- prompt: "Change to repository root and execute: [make target]"2. Parse Failures
2. 解析故障
Analyze the output to identify which check(s) failed:
- Ruff lint failures: "ruff check" errors
- Format failures: "ruff format --check" or files needing reformatting
- Prettier failures: Markdown files needing formatting
- MD-check failures: CLAUDE.md files not properly referencing AGENTS.md
- ty failures: Type errors with file paths and line numbers
- Test failures: pytest failures with test names and assertion errors
分析输出识别哪些检查项失败：
- Ruff lint故障："ruff check"错误
- 格式故障："ruff format --check"错误或存在需要重新格式化的文件
- Prettier故障：存在需要格式化的Markdown文件
- MD-check故障：CLAUDE.md文件未正确引用AGENTS.md
- ty故障：附带文件路径和行号的类型错误
- 测试故障：附带测试名称和断言错误的pytest失败
3. Apply Targeted Fixes
3. 应用定向修复
Based on failure type, apply appropriate fixes:
| Failure Type | Fix Command |
|---|---|
| Ruff lint | |
| Ruff format | |
| Prettier | |
| Sync-Kit | |
| MD-check | Edit CLAUDE.md to contain only |
| ty | Edit files to fix type annotations |
| Tests | Read and edit source/test files |
根据故障类型应用对应的修复方案：
| 故障类型 | 修复命令 |
|---|---|
| Ruff lint | 通过devrun运行 |
| Ruff format | 通过devrun运行 |
| Prettier | 通过devrun运行 |
| Sync-Kit | 直接运行 |
| MD-check | 编辑CLAUDE.md仅保留 |
| ty | 编辑文件修复类型注解 |
| 测试 | 读取并编辑源码/测试文件 |
4. Verify and Repeat
4. 验证并重复
After applying fixes, run the make target again via devrun. Continue the cycle: run -> identify failures -> fix -> verify.
应用修复后，通过devrun再次运行make目标。持续循环：运行→识别故障→修复→验证。
Iteration Control
迭代控制
Safety Limits:
- Maximum iterations: 10 attempts
- Stuck detection: If the same error appears 3 times in a row, stop
- Progress tracking: Use TodoWrite to show iteration progress
安全限制：
- 最大迭代次数：10次尝试
- 卡住检测：如果同一错误连续出现3次，停止迭代
- 进度跟踪：使用TodoWrite展示迭代进度
Progress Reporting
进度上报
Use TodoWrite to track progress:
Iteration 1: Fixing lint errors
Iteration 2: Fixing format errors
Iteration 3: Fixing type errors in src/erk/cli/commands/switch.py
Iteration 4: All checks passed使用TodoWrite跟踪进度：
Iteration 1: Fixing lint errors
Iteration 2: Fixing format errors
Iteration 3: Fixing type errors in src/erk/cli/commands/switch.py
Iteration 4: All checks passedWhen to Stop
停止条件
SUCCESS: Stop when the make target exits with code 0 (all checks passed)
STUCK: Stop and report to user if:
- You've completed 10 iterations without success
- The same error persists after 3 fix attempts
- You encounter an error you cannot automatically fix
成功：当make目标退出码为0（所有检查通过）时停止迭代
卡住：满足以下任一条件时停止并向用户上报：
- 已完成10次迭代仍未成功
- 经过3次修复尝试后同一错误仍然存在
- 遇到无法自动修复的错误
Reporting Formats
上报格式
Success Format
成功格式
markdown
undefinedmarkdown
undefinedFinalization Status: SUCCESS
完成状态：成功
All CI checks passed after N iteration(s):
(check) Lint (ruff check): PASSED
(check) Format (ruff format --check): PASSED
(check) Prettier: PASSED
(check) AGENTS.md Standard (md-check): PASSED
(check) ty: PASSED
(check) Tests: PASSED
(check) Sync-Kit (erk check): PASSED
The code is ready for commit/PR.
**IMPORTANT**: Each check line MUST be separated by a blank line in the markdown output to render properly in the CLI.经过N次迭代后所有CI检查均已通过：
(✓) Lint (ruff check)：已通过
(✓) Format (ruff format --check)：已通过
(✓) Prettier：已通过
(✓) AGENTS.md标准（md-check）：已通过
(✓) ty：已通过
(✓) 测试：已通过
(✓) Sync-Kit（erk check）：已通过
代码已满足提交/PR要求。
**重要提示**：markdown输出中每个检查行之间必须空一行，这样才能在CLI中正常渲染。Stuck Format
卡住格式
markdown
undefinedmarkdown
undefinedFinalization Status: STUCK
完成状态：卡住
I was unable to resolve the following issue after N attempts:
Check: [lint/format/prettier/md-check/ty/test]
Error:
[Exact error message]
File: [file path if applicable]
Attempted Fixes:
- [What you tried first]
- [What you tried second]
- [What you tried third]
Next Steps:
[Suggest what needs to be done manually]
undefined经过N次尝试后我仍无法解决以下问题：
检查项：[lint/format/prettier/md-check/ty/test]
错误信息：
[具体错误内容]
文件：[对应文件路径（如有）]
已尝试的修复方案：
- [第一次尝试的操作]
- [第二次尝试的操作]
- [第三次尝试的操作]
后续步骤：
[建议人工处理的操作]
undefinedGuidelines
指导原则
- Be systematic: Fix one type of error at a time
- Run full CI: Always run the full make target, not individual checks
- Use devrun agent: Always use the Task tool with devrun agent for ALL make commands
- Run from repo root: Always ensure make commands execute from repository root
- Track progress: Use TodoWrite for every iteration
- Don't guess: Read files before making changes
- Follow standards: Adhere to AGENTS.md coding standards
- Fail gracefully: Report clearly when stuck
- Be efficient: Use targeted fixes (don't reformat everything for one lint error)
- 系统化处理：每次仅修复一类错误
- 运行全量CI：始终运行完整的make目标，而非单个检查项
- 使用devrun Agent：所有make命令都必须通过Task工具调用devrun Agent执行
- 在仓库根目录运行：始终确保make命令在仓库根目录下执行
- 跟踪进度：每次迭代都使用TodoWrite记录进度
- 不盲目猜测：修改文件前先读取文件内容
- 遵循规范：遵守AGENTS.md中的编码规范
- 优雅失败：卡住时清晰上报问题
- 高效执行：使用定向修复方案（不要因为单个lint错误就重新格式化所有文件）
Example Flow
示例流程
Iteration 1:
- Use Task tool with devrun agent to run make target from repo root
- Found: 5 lint errors, 2 files need formatting
- Fix: Use Task tool with devrun agent to run make fix, then make format from repo root
- Result: 3 lint errors remain
Iteration 2:
- Use Task tool with devrun agent to run make target from repo root
- Found: 3 lint errors (imports)
- Fix: Edit files to fix import issues
- Result: All lint/format pass, 2 type errors
Iteration 3:
- Use Task tool with devrun agent to run make target from repo root
- Found: 2 ty errors in switch.py:45 and switch.py:67
- Fix: Add type annotations
- Result: All checks pass
SUCCESS迭代1：
- 通过Task工具调用devrun Agent在仓库根目录运行make目标
- 发现：5个lint错误、2个文件需要格式化
- 修复：通过Task工具调用devrun Agent在仓库根目录运行make fix，再运行make format
- 结果：剩余3个lint错误
迭代2：
- 通过Task工具调用devrun Agent在仓库根目录运行make目标
- 发现：3个lint错误（导入相关）
- 修复：编辑文件解决导入问题
- 结果：所有lint/格式检查通过，剩余2个类型错误
迭代3：
- 通过Task工具调用devrun Agent在仓库根目录运行make目标
- 发现：switch.py第45行和第67行存在2个ty错误
- 修复：添加类型注解
- 结果：所有检查通过
成功Important Reminders
重要提醒
- NEVER run pytest/ty/ruff/prettier/make/gt directly via Bash
- Always use the Task tool with subagent_type: devrun
- Covered tools: pytest, ty, ruff, prettier, make, gt
- Always ensure make commands execute from the repository root directory
- 绝对不要通过Bash直接运行pytest/ty/ruff/prettier/make/gt
- 始终使用Task工具指定subagent_type: devrun
- 覆盖工具：pytest、ty、ruff、prettier、make、gt
- 始终确保make命令在仓库根目录下执行