Communitygithub.com

m1nga/experience-pack

项目经验教训代理技能:在 EXPERIENCE.md 账本中记录事件,提炼可复用的教训,并防止陈旧决策污染项目记忆。

experience-pack 是什么?

Experience Pack 是一个为 AI 代理设计的中立技能,帮助开发项目系统地记录、提炼和复用经验教训。它基于一个双层模型:项目级账本(EXPERIENCE.md)和可移植的经验层(如 LESSONS.md)。账本用于在项目内部记录具体的事件、成本和过程经验,而可移植层则通过严格的边界测试(替代测试、机制与选择测试、重新推导测试等)剥离所有项目特定名词,仅保留可在不同项目间安全传递的抽象教训。该技能支持多种输入方式(打字或语音),并能处理混乱、口语化的描述。它适用于任何 AI 代理运行时,包括 Claude Code、Cursor 和 Codex。核心价值在于防止项目记忆污染:策略和产品决策留在原项目,只有经过验证的过程经验才能传承,从而避免新项目被旧决策的无意识影响所束缚。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add m1nga/experience-pack

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Experience Pack

一句话:每个项目都有自己的经验账本;边界测试提炼出可移植的部分;只有可移植的部分才能在项目之间传递。

支持打字或语音输入:对于“刚才什么地方出了问题”的凌乱、口语化、混合语言描述——这些都是账本条目的有效原材料——技能会将其结构化为条目,用户只需确认。

两个层次

层次文件所有者内容规则
账本项目根目录下的 EXPERIENCE.md项目带日期、具体、允许项目细节;仅限过程经验——绝不包含产品事实,也绝不作为决策记录
可移植层项目的可移植教训文件(例如 LESSONS.md)和/或本技能的参考包可移植抽象、不含产品名词、在另一个由陌生人阅读的不同项目中仍然成立

流程:某事发生 → 记入账本(当天,趁痛感还在)→ 定期提炼 → 可移植教训。策略和产品决策绝不传递:经验继承,决策消亡。

协议 A — 记录(账本)

先确定根目录。 账本存放在项目根目录——因此在写入前务必确认存在项目根目录。如果当前工作目录是 home 目录、桌面、下载或任何其他非项目位置,请询问此经验属于哪个项目,并在该项目的根目录下写入账本。切勿在 home 目录或桌面目录下创建 EXPERIENCE.md。如果无法确定项目目录,或目标目录不可写,请不要静默丢弃该条目:而是将完整的格式化条目输出为可复制文本,并告知用户它最终应存放在哪里。

在第一天(或首次使用时)在项目根目录创建 EXPERIENCE.md。当发生以下任一情况时追加条目:事件造成了实际的时间/金钱/信任损失;某种方法明显奏效;独立审查者发现了作者遗漏的问题;协作模式成功或失败;用户纠正了代理的方向。

条目格式:

### YYYY-MM-DD — 标题
**发生了什么:** 事实,具体。
**我们做了什么:** 应对措施,具体。
**什么有效 / 什么失败:** 诚实记录两者。
**成本:** 时间 / token / 信任 / 返工。
**可移植?** 是 → <教训-slug> | 尚未 | 否(项目特有)。

规则:记录过程经验,而非产品事实;如果工作区有污染卫生规则(禁用名词),账本必须遵守;绝不回溯日期或重写旧条目——追加更正作为新条目。账本条目使用项目所使用的语言编写(遵循用户现有习惯;如果不清楚,询问一次)。

约束规则(提炼自本技能采纳者的项目):

  • 记录是完成的一部分。 事件修复在账本条目创建之前不得视为完成——账本是门禁,而非日记。(一位早期采用者一天内补录了 8 条记录,因为事件发生时没有任何强制写入机制;紧急情况从来不会留出时间写日记。)
  • 批量导入是合法的,静默回溯日期则不是。 当在一个有历史的项目中采用本技能时:每条条目按其事件日期标注日期,并在账本顶部添加一条带日期的注释声明导入。任何未声明导入的过去日期条目均属伪造。
  • 分发卫生。 账本包含项目内部信息。在拥有公共远程仓库的仓库中,默认将 EXPERIENCE.md 加入 gitignore;仅发布经过边界测试的可移植层。
  • 可发现性。 在项目的主要真相文件(CLAUDE.md / AGENTS.md / 系统映射 / 状态文档)中添加一行指向账本的指示,以便零上下文的代理能够找到账本;不可发现的账本在下一次会话中不会记录任何内容。
  • 被 gitignore 的账本需要声明的逃生路线。 将账本加入 gitignore(上一条规则)也意味着它从克隆/推送恢复中移除。被 gitignore 的账本必须有声明过的备份或同步通道——私有仓库或分支、同步文件夹、定时复制;由用户选择——记录在账本头部注释的一行中。缺少此设置,机器更换或重新克隆将静默擦除项目记忆:换机器变成失忆症,而没有人会注意到,直到下一次事件重复发生。

协议 B — 提炼(边界测试)

对于每个标记为“可移植?是/尚未”的账本条目,按顺序执行以下测试:

  1. 替代测试——移除所有专有名词和具体数字。该陈述是否仍能传授某种知识?如果坍缩成为空话 → 它是决策,舍弃。
  2. 机制与选择测试——它说的是事物如何运作或失败(机制 → 继承),还是谁/什么/花了多少(选择 → 舍弃)?
  3. 重新推导测试——一个聪明的陌生人能否从新项目的自身上下文重新推导出这条内容?如果只能来自旧项目的策略,那就是旧策略在说话——舍弃。
  4. 沉没成本测试——它的唯一价值就是曾经投入了精力吗?舍弃。
  5. 可验证性测试——验证它是否需要某个已经消亡的名词?将其抽象化,或者舍弃。

幸存者被改写为一条抽象的祈使句 + 理由 + 应用方法,并标记溯源(“先前项目,已提炼 · 日期”)。可移植层用英文(或双语)编写:账本可以使用项目使用的任何语言,但可移植教训会传递给陌生人——项目特有的行话会束缚它们。不确定的条目默认舍弃——账本保留它们,以便后续轮次再次尝试。降级(罕见):一个策略形状的工件只有在作为带有重新验证条件的显式假设,且由用户决定时,才能重新进入另一个项目——绝不允许静默进行。

协议 C — 分享 / 应用(另一个项目从本项目学习)

  1. 在接收项目中:读取 references/rebuild-experience-pack.md(本技能的打包叙事)和/或源项目的可移植教训文件——绝不要读取源项目的账本、真相文件或策略。
  2. 启动接收项目自身的 EXPERIENCE.md(协议 A,包括根目录判定)。
  3. 将本技能的五条建议作为设置清单执行;采纳适用的部分;将偏差记录为接收项目的第一条账本条目。
  4. 采纳的教训以带溯源的方式进入接收项目;它们是工程约束,而非用户决策——用户可以重新分类其中任何一条。

边界——本技能从不做的事

  • 绝不在项目之间复制策略、产品事实、用户画像、定价、渠道、客户名称或账户身份——无论方向。
  • 绝不以账本作为决策记录;决策存放在项目自身的真相/决策文件中,并使用它们自己的溯源规则。
  • 绝不编辑其他技能或用户的全局配置。
  • 绝不阅读项目的隔离/归档材料来“丰富”包;提炼输入仅限于账本和实时文件。

与相邻技能的关系

  • conclude-rounds——回顾当前对话的轮次。用户说“复盘”或“let's review”并指代当前对话时,属于该技能;本技能拥有超越对话的项目级事后复盘。
  • iteration-close——关闭一个持续方向的一次迭代(提炼、删除包袱、标记、播种)。如果两个技能都安装了,运行 experience-pack 的协议 B 作为其中的一部分;iteration-close 拥有关闭仪式。两个技能都必须遵守的注意事项: “git 历史就是存档”仅适用于跟踪的文件。未跟踪/被 gitignore 的材料(公共仓库中的私有 IP)没有存档——在清理之前,需要在明确的本地规则下隔离(例如 _retired/);删除它们是永久性丢失,而非清理。
  • diagnose-project-rebuild——当一个方向被替换时,这里的边界测试与用于决定哪些内容幸存的是同一个测试;rebuild 技能拥有诊断和清理机制,并且只将本技能的可移植层作为输入。
  • 本技能是产品无关的,并且必须保持这种状态:如果项目的名词出现在这个文件或其引用中,那是一个缺陷——将其移除。

引擎说明

这里不依赖任何供应商的运行时。“新会话”和“零上下文探测”意味着任何在没有先前上下文的情况下启动的代理实例——一个新聊天、一个子代理或第二个工具。如果某个技能运行时不存在,请手动应用协议:上述文件格式和测试即技能本身。

参考

references/rebuild-experience-pack.md——来自真实五次重构污染叙事的打包、无名词经验:六扇污染之门、源锁定重置方法、三探针验证栈、多 AI 协作协议以及五条预防建议。

相关技能