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>`**:

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

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

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

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

```markdown
### {标题}

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

### 上传流程

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

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` 标记用于后续整合时判断时效性，必须填写