work-report

在工作树根目录编写工作报告 WORK-REPORT.md：记录差异无法体现的内容，供审阅者或新的会话参考。每棵树一份，每次运行时覆盖，因此内容反映当前状态。适用于任何目录（无论是否为 git 仓库、是否为工作树），以及任何形式的工作（提交、零散编辑、跨仓库更改、编辑器设置）。

按顺序执行以下步骤。只有在路径不可写时才停止；即使缺少 git、不在仓库中或会话没有实际操作，也要生成有效报告。

未经请求，绝不写入

自动触发（用户表示工作已完成，却未提及报告）：用一句话提出建议，等待用户同意。你可以先阅读现有报告，以便在建议中提出 Step 2 的问题。明确调用（/work-report、“write the work report”）即表示同意。

“本次工作”的范围 = 本聊天会话

报告你在本次会话中做了什么。绝不要从 git diff 或 git log 推断：git 已记录这些内容，而重建意图会造成丢失。调用时附带的自由文本说明只用于突出重点（该主题应放在各节开头），不能缩小范围。

详略程度——每条内容保持相同篇幅

目标和嵌套项目符号：1–2 句话。列表项：一句话，可选附带括号补充。不要写段落；方便读者快速浏览。

Step 1 - 定位报告

<root>/WORK-REPORT.md，其中 <root> 由 git rev-parse --show-toplevel 确定；若不在 git 仓库中，则使用当前目录。

Step 2 - 阅读现有报告并在其基础上续写

现有报告（可能由另一个 Agent 编写）或许记录的是其他工作。若其中的 Goal 明显与本次会话无关，或其 session id 和 branch 均与当前不同，请询问用户。session id 相同则不必比较 branch：同一会话可以在多个分支上构建不同变体。其他会话的报告通常是有意留下的交接信息，因此要说明重新开始会丢失什么：“WORK-REPORT.md 可能记录的是其他工作（为 CSV 导出添加重试，分支 feat/export-retry）。要续写，还是创建新报告并舍弃其中 2 个待处理事项和 1 条 [ignored] 记录？” 自动触发时，将此问题融入那一句建议中。用户选择“start new”后，仅根据本次会话编写报告；跳过本步骤其余内容。

否则，续写而非重新生成：保留 Problem → Solution 和 Abandoned 中的条目及其标签；若本次会话扩大了目标，则相应拓宽 Goal；并处理所有沿用的待处理事项（删除已处理事项可避免报告在后续会话中不断膨胀）：

沿用的待处理事项	处理方式
已完成，且涉及改变方向、采用某个分支方案，或差异无法体现的检查（检查流水线运行情况、发送邮件、切换控制台标志）	Problem → Solution
已完成，且所需操作可从差异中还原	删除，不留痕迹
经评估后否决	移入 Abandoned，标记为 [considered]
用户否决，或依据用户设定的规则否决（Step 4，Abandoned）	移入 Abandoned，标记为 [ignored]
仍未处理	原样保留
已过时、目标已变更	删除，不留痕迹

Step 3 - 提议添加 gitignore 条目（仅限仓库中的首次运行）

若不在 git 仓库中，或 Step 2 已找到报告（首次运行检查；拒绝后不再询问），则跳过。否则，使用 Step 1 确定的根目录运行 grep -qxF '/WORK-REPORT.md' <root>/.gitignore。提出建议时：不要说“报告是本地文件”之类的话。若条目不存在，说明报告是本地资料，通常不会纳入分支差异，并询问是否添加；无论用户如何回答，继续执行 Step 4。若用户同意，则将以下内容追加到 <root>/.gitignore（若文件缺少末尾换行，先补上）：

# Work report (work-report skill) - git add -f to commit it
/WORK-REPORT.md

保留开头的斜杠：它会将规则限定在工作树根目录，因此不会忽略更深层目录中同名的文件，同时也适用于所有工作树。

Step 4 - 撰写报告

只记录差异无法体现的内容：意图、理由、验证情况和后续步骤。不要复述提交内容或更改过的文件。引用相关资料（PR/issue URL、文件路径、ADR），不要直接粘贴内容。绝不要复述 API 密钥、密码、令牌、凭据或个人身份信息（PII）的值；只说明其存在及所在位置（其他 Agent 会读取报告，而且报告可能会被提交）。 标头 - 必须精确为 # Work report，然后是两行标识符，每行一个事实，绝不合并。branch = 工作开始时所在的分支：新报告填写当前分支，续写时保持不变。session id = 最后一位写入者。读者会 grep 这两行及其回退值：

# Work report

- **branch:** <on a new report git branch --show-current, `(detached)` on a detached head, `(no git)` outside a repo or with git unavailable>
- **session id:** <printenv CLAUDE_CODE_SESSION_ID, or `unknown` if unset>

然后依次列出五个 ## 标题，始终都要包含，内容为空时在其下方写 - none：

• 目标 - 此项工作旨在完成什么。

• 问题 → 解决方案 - 编号列表。以下情况须记录条目：首次尝试失败并改变了方案；做出了真正的取舍（≥2 个可行选项）；或报告中已有的后续事项已完成（由任何人完成，包括本次会话），且无法从 diff 中还原其收尾过程，或收尾本身涉及取舍。记录问题及可行方案，或取舍及其原因。已完成的后续事项若不符合此标准，只保留在 后续事项 中。将 diff、PR 和 CI 无法体现的验证过程（例如在代理不可用时点击重试路径，检查流水线运行结果）并入其所验证的 解决方案；若所验证的工作没有对应条目，则将检查本身作为独立条目（问题 = 需要验证的内容，解决方案 = 检查及其结果）。测试全部通过不算条目。每次改变方案都要单独列为一个条目，即使它属于更大修复的一部分；失败的尝试也要以 [tried] 记录在 已放弃 中。条目格式：

  1.
      - **Problem:** description
      - **Solution:** description
  

• 后续事项 - 供下一次会话或评审者接手的待办清单，每项都要标注：

  • [question] - 尚未解决的决策或未知事项，须以问题形式表述。
  • [action] - 具体工作，使用祈使语气。认为可行但从未实际验证的内容 = [action]，并注明用于确认的检查方式。可以不指定负责人。

  以下内容绝不能列在此处：

  • 已决定不处理的缺口（已接受的风险、超出平台范围）：记录在 已放弃 中，标记为 [considered]；若是用户或用户设定的规则否决，则标记为 [ignored]。
  • 发布操作（commit、push、PR、merge、tag、release）：这些由用户决定，即使会话结束时尚未提交也是如此。
  • 调用 skill 或斜杠命令：写明结果（[action] 为重试路径添加回归测试），绝不写工具（[action] 运行 /test-writer）。

• 建议的 skills - 仅用于结果导向的后续事项。只有当某个 skill 能推进一项 [action] 时才列出，格式为 /skill - 该 skill 推进的后续事项。

• 已放弃 - 记录下一位 Agent 不应重新探索的内容：已放弃的方案，以及后来被否决的既有后续事项。使用编号，每项为一句话并说明原因：

  1. [tried] implemented or attempted, then reverted - why it was backed out
  2. [considered] evaluated and rejected without building it - why it was rejected
  3. [ignored] dismissed by the user or a rule the user set - the user's reason, "user's call", or the rule and its source
  

[ignored] = 用户否决：之后的运行中绝不重新提出、重新标记或再次提供该事项，只有下文的重新开启检查例外。必须有用户授权，授权方式有以下三种：

• 直接授权：本次会话中明确否决（“忽略这个”“跳过 Safari 的情况”“不用管”）。
• 通过用户在本次会话中陈述或确认的规则（例如“只修复阻塞项”这样的评审标准），或通过仓库说明文件（AGENTS.md、CONTRIBUTING.md）中记载的规则，并将其应用于该事项。注明规则及其来源：- 按照用户“只处理阻塞项”的标准不属于阻塞项（本次会话），或写明文件路径。每项单独记录。
• 从现有报告中沿用。

无法注明来源的规则、用户从未确认的 skill 默认行为，或你自己的否决，都应标记为 [considered] 并说明原因。用户沉默、未回答的 [question]，或延期处理（“现在不处理”“以后再说”）都应继续留在 后续事项 中；已在工单或文档中记录的延期事项不需要单独记录。绝不捏造用户的理由或规则。

用户再次要求处理该工作，或更改或撤回相关规则时，即解除 [ignored] 状态；后一种情况会解除引用该规则的所有条目。重新开启检查：如果本次会话中的缺陷或故障与某个 [ignored] 条目有相同的根本原因或失败场景，则保留该条目并添加 [question] 这个 <缺陷> 是否会重新开启 [ignored] <事项>？。由用户决定。

示例：

# Work report

- **branch:** feat/export-retry
- **session id:** 3f1c9a2e-7b44-4d0e-9c1a-5e8f2b6d7a10

## Goal

Make the CSV export survive a dropped connection by retrying failed chunk uploads.

## Problem → Solution

1.
    - **Problem:** Retrying the whole export duplicated rows already written.
    - **Solution:** Retry per chunk with an idempotency key; verified by killing the proxy mid-export and diffing the output.

## Follow-ups

- [question] Should the retry limit be configurable per tenant?
- [action] Add regression tests for the chunk retry path.

## Suggested skills

- /test-writer - Add regression tests for the chunk retry path.

## Abandoned

1. [tried] Exponential backoff in the HTTP client - it retried non-idempotent POSTs elsewhere in the app.
2. [considered] Streaming the export over websockets - too large a change for the bug.
3. [ignored] Safari download filename encoding - user's call.

第 5 步 - 写入文件并汇报

写入 <root>/WORK-REPORT.md，回复文件路径和一行摘要，并注明任何需要重新处理的 [question]。如果该文件被 Git 忽略（第 3 步），请注明 PR 审核者需要主动执行 git add -f WORK-REPORT.md。