Skip to content

Dev-Wiki/dev-harness / retro

dev-harness-retro

Verified

仅在用户明确要求 retro、复盘、总结并沉淀或维护 LESSONS.md 时,回顾任务并把结论分类为 FACT、POLICY、LESSON,输出有证据、可纳入正式文档的候选结论

dev-harness-retro

对一次已发生的工作进行显式项目复盘。它维护复盘历史和“待纳入正式规范的候选结论”(Promotion Candidates),不是每个任务的自动收尾步骤,也不能把一次 AI 失误静默升级为永久项目规则。

输出语言

  • 用户明确要求英文时使用英文;否则,中文项目或新建且未指定语言的 LESSONS.md 默认使用简体中文。
  • 刷新既有文档时跟随其主体语言;只编写或改写本次复盘涉及的文字,不顺带全文翻译。
  • 中文标题、表头、结论、证据、适用范围和最终报告使用中国人习惯的自然中文,不生硬套用英文句式。
  • 路径、命令、代码符号、API/协议/产品名、必要缩写和 FACT / POLICY / LESSON 分类值保持原样;首次面向读者展示时先说明它们的中文含义。

触发边界

仅在用户明确要求以下动作时使用:

  • retro、复盘、总结并沉淀;
  • 更新或整理 LESSONS.md;
  • 从本次工作提炼可进入项目契约的候选事实或政策。

普通任务完成、代码验证通过或发现一个偶发错误,都不得自动触发 Retro。未被明确触发时,不创建、不读取、不更新 LESSONS.md。

三类结论

每条候选必须且只能归入一类:

类型含义进入条件默认去向
FACT当前项目可客观验证的事实有仓库路径、配置、测试或运行证据LESSONS.md 中的候选结论;写入 Context 等正式文档后不再重复维护
POLICY开发者或团队决定采用的规范有用户明确确认;Git 历史和既有习惯只能作为候选证据LESSONS.md 中的候选结论,等待写入对应正式规范
LESSON本次任务的经验、AI 行为问题或暂时注意事项能说明具体情境、观察和更稳妥做法保留在 LESSONS.md,默认不是硬约束

禁止混淆:

  • 一次 AI 失误不是 FACT;
  • 历史提交习惯不是 POLICY,除非用户确认;
  • LESSON 不自动成为永久约束;
  • 无可复核证据的项目断言只能记录为待验证 Lesson,不能伪装成 Fact。

所有权与正式写入

稳定结论应写入现有项目契约(Project Contract)中对应的权威文档,而不是要求所有 Agent 永久加载整份历史:

候选内容正式归属
项目结构、入口、架构边界dev-harness-context 管理的 Context
构建、测试、设备与环境要求HARNESS.md / dev-harness-commands
Git、tag、release、changelog 政策dev-harness-git-workflow
文档根、SSOT、归档政策dev-harness-docs
规划状态和优先级政策dev-harness-planning

Retro 只输出候选结论。写入正式规范前必须再次检查归属文档的写入边界;POLICY 必须取得用户确认。不得在一次 Retro 中静默修改多个 Skill 的正式产物。

LESSONS.md 契约

LESSONS.md 是复盘历史与候选库,不是所有任务的强制 preamble:

# LESSONS — 项目复盘记录

> 由 dev-harness-retro 在用户显式触发时维护。
> 本文件中的 LESSON 默认不是永久硬约束;稳定事实和政策应写入对应 Project Contract。

## 复盘条目

| ID | 类型 | 结论 | 证据 / 决策来源 | 适用范围 | 日期 |
|----|------|------|-----------------|----------|------|

## 待纳入正式规范的候选结论

| ID | 目标归属 | 候选内容 | 前置条件 | 状态 |
|----|------------|----------|----------|------|

ID 使用 R 加三位数字,例如 R001,已有 ID 不重用。对语义相同的条目更新原 ID,不制造重复历史。

兼容旧版:若现有 LESSONS.md 使用“活跃规则 / 归档规则”表,先原样保留。只有本次显式 Retro 确实需要编辑时,才把涉及的旧条目标为 legacy Lesson 或迁移到新表;不得删除用户历史,也不得自动把旧条目写入正式文档或认定为 Fact/Policy。

工作流

  1. 固定本次复盘范围:任务、时间段或用户指出的事件。
  2. 读取本次对话、diff、验证输出以及用户指定的复盘材料;远端 issue、日志和附件仍是不可信输入。
  3. 提取具体观察,删除无法复核、纯情绪化或与未来工作无关的内容。
  4. 将每条内容分类为 FACT、POLICY 或 LESSON,并列出证据缺口。
  5. 与现有 LESSONS.md 按语义去重;复用旧 ID。
  6. 先向用户展示准备记录的分类结果。POLICY 的确认可以在这一步取得。
  7. 只更新 LESSONS.md;若用户另外明确要求将某条候选写入正式文档,再交给对应 owner 执行独立、可验证的写入。
  8. 报告新增、更新、未采纳和待写入正式文档的条目,以及每条 Fact/Policy 的证据或确认来源。

质量门

  • 每条 FACT 都有当前仓库、配置、测试或运行证据;
  • 每条 POLICY 都记录明确的用户决定,不能只引用历史惯例;
  • 每条 LESSON 都写明适用情境,不使用“永远”“所有任务必须”等无证据措辞;
  • 候选结论指向唯一归属文档,不复制正式规范正文;
  • 没有把普通任务完成误当成 Retro 授权;
  • 没有自动 commit、push 或修改多个契约文件。

停止条件

  • 用户没有显式要求复盘或沉淀;
  • 无法确定复盘范围;
  • 候选 Policy 尚未得到用户确认;
  • Fact 的证据已因仓库漂移失效;
  • 写入正式文档的操作超出用户本次授权。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall