iterating

迭代

通过在 Work Logs 中持久化状态，在多个会话间保持上下文。

环境检测

检测环境并加载相应的参考文档：

if [ "$CLAUDE_CODE_REMOTE" = "true" ]; then
  # Claude Code on the Web (CCotw) - writes to GitHub
  # Read: references/ccotw-environment.md
elif [ -n "$CLAUDE_CODE_REMOTE" ]; then
  # Claude Code CLI - writes to local filesystem
  # Read: references/codecli-environment.md
elif [ -x "$(command -v osascript)" ] && [ -d "/Applications/Claude.app" ]; then
  # Claude Desktop - may write to disk OR output for download
  # Read: references/desktop-environment.md
else
  # Claude.ai (web/chat/native app) - outputs for download
  # Read: references/chat-environment.md
fi

有关持久化和检索的详细信息，请参阅特定环境的参考文档。

检查点模式

迭代技能采用检查点并保存的模式，以防止工作丢失：

1. 创建/更新 WorkLog → 向用户输出 → 停止
2. 用户将 WorkLog 保存到项目知识库（可在对话长度限制之后继续使用）
3. 用户说“继续”（同一对话或新对话均可）
4. 针对一项进行增量推进 → 更新 WorkLog → 停止
5. 重复

这很重要，因为不同对话不会自动共享上下文： 跳过“停止”步骤（“全程瀑布式”）会导致用户尚未看到或无法调整的工作， 而且如果对话在检查点生成前结束，所有工作都可能丢失。

WorkLog 格式

---
version: v1
status: in_progress
---

# [Project Name] Work Log

## v1 | YYYY-MM-DD HH:MM | Title

**Prev:** [previous context OR "Starting new work"]
**Now:** [current goal]

**Progress:** [X% complete OR milestone status]

**Files:**
- `path/to/file.ext` (Why this file matters)
  - L45-67: [What to examine/change here]
  - L123-145: [Another area, specific issue]

**Work:**
+: [additions with file:line]
~: [changes with file:line]
!: [fixes with file:line]

**Decisions:**
- [what]: [why] (vs [alternatives])

**Works:** [effective approaches]
**Fails:** [ineffective approaches, why]

**Blockers:** [None OR specific blocker with owner/ETA]

**Next:**
- [HIGH] [Critical action item]
- [MED] [Important but not urgent]
- [LOW] [Nice to have]

**Open:** [questions needing answers]

核心工作流

开始新工作：

1. 检测环境
2. 创建 WorkLog v1，写明任务目标、决策、文件引用和后续步骤
3. 使用特定环境的方法进行持久化
4. 停止 — 向用户展示 WorkLog
   • 说明计划内容
   • 告诉用户将 WorkLog 保存到项目知识库
   • 等待用户说“继续”后再开始工作

继续工作：

1. 检测环境
2. 使用特定环境的方法检索 WorkLog，或识别用户粘贴的 WorkLog
3. 解析最新版本和状态
4. 确认：“根据 WorkLog vN，状态：[状态]。进度：[X%]。正在处理：[具体的 HIGH 项]”
5. 执行一项 HIGH 优先级事项。
6. 更新 WorkLog，版本号递增
7. 使用特定环境的方法进行持久化
8. 停止 — 向用户展示更新后的 WorkLog
   • 总结已完成的工作
   • 告诉用户保存更新后的 WorkLog
   • 等待用户说“继续”后再处理下一项

识别用户粘贴的 WorkLog： 如果用户在对话开始时粘贴了带有 WorkLog frontmatter 的内容：

1. 从 YAML 中解析版本和状态
2. 确认：“根据 WorkLog vN，状态：[状态]。任务：[目标]。下一步：[HIGH 项]”
3. 从上方第 5 步继续工作流

版本管理

• 简单递增：v1 → v2 → v3
• Frontmatter：version: vN（必填）
• 文件名：WorkLog vN.md（可选）
• 多个文件：使用版本号最高的文件

状态

• in_progress：工作正在进行
• blocked：等待外部依赖或决策
• needs_review：可供人工检查
• completed：任务已完成

优先级系统

后续步骤必须按优先级排序：

• [HIGH]：阻碍其他工作的关键事项
• [MED]：重要但不紧急
• [LOW]：锦上添花的改进

除非另有指示，否则 Claude 每次迭代只处理一项 HIGH 优先级事项（见上方核心工作流）——这样每个检查点都便于审查，而不是把多项更改打包进一次 WorkLog 更新。

文件引用

使用相对于项目根目录的路径，并注明行范围：

**Files:**
- `src/auth/oauth.ts` (OAuth implementation needs refactoring)
  - L45-67: Current token validation logic
  - L123-145: Refresh token handling (race condition on L134)

重要： 使用相对路径，不要使用 /home/claude/ 这类绝对路径（每个会话都会使用新的计算环境）。

进度跟踪

始终包含进度指示（令牌或配额限制可能导致计划无法全部完成）：

**Progress:** 60% complete

较长的项目也可以使用：

**Progress:** Phase 2/3 | Auth ✅ | Payments 50% 🔄 | UI ⏳

记录内容

应包括：

• 关键决策及其理由和备选方案
• 有效和无效的方法
• 重要发现
• 带行范围的文件引用
• 标注优先级的后续步骤
• 进度指示
• 注明负责人和预计完成时间的阻碍事项

不要包括：

• 次要代码更改（使用 git）
• 显而易见的信息
• 原始数据转储
• 实现细节（使用代码注释）

用户沟通

创建 WorkLog 后：

• “已创建 WorkLog v1。请将其保存到项目知识库。”
• “准备就绪，请说‘继续’即可开始。”

完成一项后：

• “已完成 [item]。已将 WorkLog 更新至 vN。”
• “请将更新后的 WorkLog 保存到项目知识库。”
• “准备好进行下一项，请说‘继续’即可开始。”

继续时：

• “根据 WorkLog vN，状态：[status]。进度：[X%]。”
• “正在处理：[specific HIGH item]”

状态变更时：

• “已将 WorkLog 状态更新为 [new_status]：[reason]”
• “请保存更新后的 WorkLog。”

高级模式

遇到以下情况时，请阅读 references/advanced-patterns.md：

• 项目持续 5 个以上会话
• 用户提及“调试策略”、“假设跟踪”或“决策演变”
• 管理多个并行工作流
• 用户询问长期项目模式
• 遇到复杂问题，受阻并需要系统性方法

否则请跳过——对于大多数情况，上述基本工作流已足够。

参考文档

• references/chat-environment.md - Claude.ai（网页/聊天/原生应用）
• references/desktop-environment.md - Claude Desktop
• references/codecli-environment.md - Claude Code CLI
• references/ccotw-environment.md - Claude Code on the Web