# Iteration Work Notes

> Use when a complex task will span turns or sessions and needs structured working notes to survive context compression or handoff; short single-turn work does not trigger it.

- Skill: `peiiii/iteration-work-notes` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add peiiii/iteration-work-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peiiii/iteration-work-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: peiiii (https://skillmd.com/u/peiiii)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/peiiii/iteration-work-notes

---


# Iteration Work Notes

## 概述

这个 skill 用来把复杂任务和复杂 debug 的“易丢失上下文”外部化到当前迭代目录下的 `work/`。

目标不是写第二份 `README.md`，而是保证在以下场景里不会失忆：

- 上下文压缩
- 多次对话
- 长时间等待
- 中途交接
- 多轮实验后需要回看证据

## 何时使用

当任务满足以下任一特征时使用：

- 会跨多个阶段或多次对话
- 复杂 debug / 长链路排查
- 需要较长时间等待构建、发布、回归或线上观察
- 需要记录多条假设、证据、已排除路径与下一步
- 用户明确要求“记笔记”“保留过程”“避免上下文丢失”

以下情况通常不需要：

- 小而直接、单阶段、低风险的改动
- 纯措辞调整、轻量文档修补

## 默认落点

优先使用当前对应迭代目录下的：

`docs/logs/v<semver>-<slug>/work/working-notes.md`

规则：

- 默认先只用一个 `working-notes.md`
- 只有当内容明显分叉或持续膨胀时，才拆出更多文件
- 不要仅为了记笔记提前新建新的迭代目录

如果对应迭代目录已经存在，直接在其下创建或更新 `work/`。

如果对应迭代目录还不存在：

- 用户明确要求提前留痕：可以先建对应迭代目录并开始记
- 用户没有明确要求：先按项目迭代制度判断，不要只为了笔记新开迭代

## 推荐结构

`working-notes.md` 默认至少包含以下模块：

1. `当前目标`
2. `当前事实`
3. `关键约束 / 不变量`
4. `证据 / 观察点`
5. `活跃假设`
6. `已排除项`
7. `关键决策`
8. `下一步`
9. `剩余缺口 / 交接提醒`

其中：

- `当前事实` 只写已经确认的事实，不混入猜测
- `活跃假设` 只保留仍未被证伪的路径
- `已排除项` 用来防止上下文压缩后重复踩同一个坑
- `下一步` 应该足够具体，让下一轮直接接上

## 更新时机

至少在以下时刻更新一次：

- 进入新阶段前
- 做完一轮关键实验后
- 改变主要判断或主要方案后
- 进入长时间等待前
- 结束当前会话前

## 记录原则

- 记录事实、分歧点、决策和下一步，不写流水账
- 优先写“为什么现在相信 X / 不再相信 Y”
- 优先链接文件、路径、命令或结果摘要，不粘贴大段原始输出
- 保持当前真相源，不要让旧结论和新结论混在一起
- 如果某条结论过期，直接改掉或标注失效，不要堆版本噪音

## 何时拆分

只有出现下面情况时再拆更多文件：

- 证据量很大，`working-notes.md` 已明显过长
- 同时存在两个以上稳定子问题域
- 需要把 handoff、evidence、decision log 分开维护

推荐拆分方式：

- `work/evidence.md`
- `work/decision-log.md`
- `work/handoff.md`

拆分后仍要遵循一个原则：

- 当前迭代 `README.md` 必须链接这些文件

## 与任务 owner 的配合

- 本 skill 只负责跨轮事实载体，不反向编排调查或实施流程。
- 复杂多阶段实施：和主方案文档一起用。
- 需要交接：在 `剩余缺口 / 交接提醒` 中留下最小接手上下文。

## 反模式

- 把 `work/` 写成第二份完整迭代 README
- 把原始日志整段粘进去，几百行也不整理
- 只记现象，不记已排除项和下一步
- 关键决策只留在聊天里，不落到 `work/`
- 任务已经转向，但笔记仍停留在旧阶段

## 完成标准

只有满足以下条件，才算这份工作笔记真的有用：

1. 下一轮对话不看历史长聊天，也能快速接上
2. 已排除项和活跃假设是清楚分开的
3. 当前决策与下一步是可执行的
4. `README.md` 能找到这份笔记