experience-codifier

name	experience-codifier
description	经验固化协议：将解决问题中发现的最佳实践自动提炼、分类、写入 Agent 规则或 Skill 知识库，并同步上传。 触发关键词: 固化经验, 总结教训, 升级规则, 经验沉淀, codify experience, harness learning, 提炼经验

🧬 Experience Codifier — 经验固化协议

将"遇到问题 → 解决问题"的经验闭环，提炼为可复用的 Agent 规则或 Skill 知识。 核心原则：宁缺毋滥 — 只固化高泛用、长时效、原则级的经验。

执行声明

我将严格按照以下协议评估、分类、写入经验。每条经验必须通过质量门且经人工确认后才会写入。

---

触发条件

自动触发：Agent（PlanPlus / GuidedDev）完成任务后，自动评估本次执行中是否存在以下模式：

• 预期外的问题 → 找到了更好的做法
• 踩坑后发现的隐含规则
• 多次尝试后收敛出的有效模式

手动触发：用户说"固化经验"、"总结教训"等关键词

---

Step 1: 经验提取

从本次执行上下文中提取候选经验，每条包含：

• 场景: 什么情况下会遇到这个问题
• 规则: 正确的做法是什么（祈使句）
• 原因: 为什么这样做有效（一句话）
• 来源: 本次哪个步骤/任务中发现的

一次最多提取 3 条候选。数量不是目标，质量才是。

---

Step 2: 双层质量门

对每条候选经验，依次过门。全部 PASS 才进入提案。

通用经验（→ 工具仓库，惠及所有项目）

#	检查项	PASS 条件	FAIL 后果
G1	泛用性	能覆盖 ≥3 种不同的未来场景（跨项目/跨模块）	降级为项目经验候选
G2	时效性	预期有效期 ≥6 个月（不依赖特定 API 版本/临时 workaround）	丢弃，告知原因
G3	粒度	描述的是原则/模式，而非具体操作步骤	丢弃，告知原因
G4	可验证性	正确性可客观验证（非"感觉更好"）	降级为项目经验候选
G5	非重复性	read_file 目标文件，确认不存在语义等效条目	丢弃，告知已有哪条覆盖

项目经验（→ 当前项目本地，仅本项目受益）

G1 或 G4 不通过时自动降级到此层，只需通过 3 门：

#	检查项	PASS 条件
G2'	时效性	预期有效期 ≥3 个月
G3'	粒度	同 G3
G5'	非重复性	同 G5（检查本地文件）

两层都不通过 → 不固化，向用户说明原因。

---

Step 3: 分类

对通过质量门的经验进行分类（互斥）：

类型	判据	写入目标
A — Agent 方法论	关于 Agent 如何工作（搜索策略、规划思路、工具使用模式、交互方式）	Agent 文件的 <learned_patterns>
B — Skill 域知识	关于某个 Skill 领域的具体陷阱/模式/隐含规则	该 Skill 的 references/experience-notes.md
C — AI 编排方法论	关于"如何写 AI 指令/Skill 本身"的 meta 级经验	docs/AI任务编排经验方法论.md 附加经验区

Type C 额外门槛（meta 级错误代价极大）：

• 必须已在 ≥2 个不同 Skill 或 Agent 中实际验证过
• 不满足 → 降级为 Type A

通用 vs 项目的写入位置：

	通用经验	项目经验
Type A	{{TOOL_REPO_PATH}}/templates/{Agent}.agent.md 的 <learned_patterns>	当前项目 .github/agent-patterns.md
Type B	{{TOOL_REPO_PATH}}/templates/skills/{name}/references/experience-notes.md	当前项目 .github/skills/{name}/references/experience-notes.md

---

Step 4: 容量管控

写入前检查目标文件当前条目数。

容量上限：

位置	上限	原因
Agent <learned_patterns>	15 条	Agent prompt 始终加载，控制上下文
Skill experience-notes.md	20 条/Skill	按需加载，容量可更大

未命中上限 → 直接追加

命中上限 → 整合模式

1. 读取目标文件全部现有条目
2. 生成整合提案，包含以下三类操作：
   • 合并：语义重叠的 2+ 条 → 合并为 1 条更精炼的版本（信息不丢失）
   • 提升：经过 ≥6 个月且多次验证的经验 → 建议提升为 Agent <rules> 的正式规则（腾出 LP 位置）
   • 归档：since 日期超过 6 个月的条目 → 请用户确认是否仍有效，过时则移入 <!-- ARCHIVED --> 注释区
3. 展示整合提案给用户确认（逐条确认/否决）
4. 执行整合后写入新条目

归档格式：<!-- ARCHIVED: LP-{N} (YYYY-MM ~ YYYY-MM) 原因: {原因} | 原内容: {完整内容} -->

---

Step 5: 草拟 & 人工确认

展示提案

向用户展示完整提案（🔴 硬阻断，不可跳过）：

• 每条经验的：场景 / 规则 / 原因 / 来源
• 质量门评判（哪些通过、哪些降级）
• 分类结果 + 目标文件路径
• 如触发整合模式，同时展示整合提案

ask_questions:
  header: "经验固化"
  question: "提炼出以下经验，请确认是否写入：\n\n{经验草案摘要}\n\n目标: {文件路径}\n层级: {通用/项目}"
  options:
    - label: "确认写入"
      recommended: true
    - label: "修改后写入"
      description: "我来调整措辞或分类"
      allowFreeformInput: true
    - label: "放弃"
      description: "本次不固化"

---

Step 6: 写入 & 上传

写入格式

Type A — Agent <learned_patterns>:

### LP-{NNN}: {标题} <since: YYYY-MM>
- **场景**: {何时适用}
- **规则**: {具体做法，祈使句}
- **原因**: {为什么有效，一句话}

Type B — Skill experience-notes.md 表格追加一行：

| YYYY-MM-DD | AI | {场景简述} | {经验规则} | {相关文件} |

Type C — AI 编排方法论 在附加经验区追加：

### {标题}

| 手段 | 用法 | 解决的问题 |
|------|------|------------|
| {手段} | {用法} | {问题} |

上传流程

通用经验 → 同步到工具仓库：

1. 通过 {{TOOL_REPO_PATH}} 定位工具仓库
2. 在终端执行 git -C "{{TOOL_REPO_PATH}}" pull origin master
3. 编辑目标文件（editFiles）
4. 调用 #quick-upload 创建 PR 并通知

项目经验 → 提交到项目仓库（团队共享）：

1. 直接在当前 workspace 编辑目标文件
2. 调用 #quick-upload 创建 PR，提交信息格式：chore(skill): 固化项目经验 — {经验标题}
3. PR 合并后团队成员 pull 即可获得新经验

降级策略

• {{TOOL_REPO_PATH}} 不可用或不存在 → 将经验条目以 Markdown 格式输出到对话中，让用户手动处理
• 项目仓库无 git remote → 将经验写入本地文件，提示用户手动提交
• #quick-upload 失败 → 提示用户手动 git commit + push

---

注意事项

• 每次对话最多固化 3 条经验，避免批量低质量写入
• 经验措辞用祈使句（"先检查本地再调 MCP"），不用描述句（"我们发现先检查本地更好"）
• 不写入任何包含具体 PBI 编号、Bug ID、人名的内容
• 不写入临时 workaround（"MCP v1.3 有 bug 需要这样绕"）
• since 标记用于后续整合时判断时效性，必须填写