gabrielmoreira 🧬 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 | 按需加载，容量可更大 |
未命中上限 → 直接追加
命中上限 → 整合模式
- 读取目标文件全部现有条目
- 生成整合提案，包含以下三类操作：
- 合并：语义重叠的 2+ 条 → 合并为 1 条更精炼的版本（信息不丢失）
- 提升：经过 ≥6 个月且多次验证的经验 → 建议提升为 Agent
<rules>的正式规则（腾出 LP 位置） - 归档：
since日期超过 6 个月的条目 → 请用户确认是否仍有效，过时则移入<!-- ARCHIVED -->注释区
- 展示整合提案给用户确认（逐条确认/否决）
- 执行整合后写入新条目
归档格式：<!-- 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 编排方法论 在附加经验区追加：
### {标题}
| 手段 | 用法 | 解决的问题 |
|------|------|------------|
| {手段} | {用法} | {问题} |
上传流程
通用经验 → 同步到工具仓库：
- 通过
{{TOOL_REPO_PATH}}定位工具仓库 - 在终端执行
git -C "{{TOOL_REPO_PATH}}" pull origin master - 编辑目标文件（
editFiles） - 调用
#quick-upload创建 PR 并通知
项目经验 → 提交到项目仓库（团队共享）：
- 直接在当前 workspace 编辑目标文件
- 调用
#quick-upload创建 PR，提交信息格式：chore(skill): 固化项目经验 — {经验标题} - PR 合并后团队成员 pull 即可获得新经验
降级策略
{{TOOL_REPO_PATH}}不可用或不存在 → 将经验条目以 Markdown 格式输出到对话中，让用户手动处理- 项目仓库无 git remote → 将经验写入本地文件，提示用户手动提交
#quick-upload失败 → 提示用户手动 git commit + push
注意事项
- 每次对话最多固化 3 条经验，避免批量低质量写入
- 经验措辞用祈使句（"先检查本地再调 MCP"），不用描述句（"我们发现先检查本地更好"）
- 不写入任何包含具体 PBI 编号、Bug ID、人名的内容
- 不写入临时 workaround（"MCP v1.3 有 bug 需要这样绕"）
since标记用于后续整合时判断时效性，必须填写