learn

从对话中学习

分析对话，提取经验教训，然后将其保存到 AI 助手配置文件或新技能中。

参数

可选文本，用于缩小学习范围（例如 sandbox workaround、that build fix）。

如果 $ARGUMENTS 为 help、--help、-h 或 ?，则跳过工作流并阅读 references/options.md。

如果 $ARGUMENTS 是非空且非帮助字符串，则在步骤 2 中将其用作筛选条件：仅提取与指定主题相关的经验，跳过无关发现。

流程

1. 检测配置和现有技能

for f in CLAUDE.md GEMINI.md AGENTS.md .cursorrules .github/copilot-instructions.md \
  .windsurf/rules/rules.md .continuerc.json; do
  [ -f "$f" ] && wc -l "$f"
done
find .cursor/rules -name "*.mdc" -exec wc -l {} \; 2>/dev/null
find . -name "SKILL.md" -type f 2>/dev/null | grep -v node_modules | \
  xargs grep -l "^name:" | while read -r f; do grep -m1 "^name:" "$f" | sed 's/name: //'; done

配置检测：

• 找到单个配置 → 使用它
• 找到多个配置 → 必须完整阅读 references/multiconfig-routing.md， 以确定是自动跳过还是先征求用户意见。
• 未找到配置 → 必须完整阅读 references/assistant-configs.md， 展示初始化命令，然后退出。在此步骤中不要加载 refactoring.md、options.md 或 multiconfig-routing.md。

配置文件大小阈值：

• < 400 行：状态良好，可直接添加
• 400–500 行：谨慎添加，并说明文件正在变大

• 500 行：必须在继续前完整阅读 references/refactoring.md， 然后提供重构选项。除非同时应用 Route A 的更改，否则不要为此路径加载 assistant-configs.md。

2. 分析对话

默认拒绝。每条候选经验都必须按顺序通过以下三项筛选：

1. 我会忘记这点吗？ 如果任何开发者都知道这点（npm install 要先于 npm start、切换分支前先提交、仔细阅读错误信息），就跳过。基础知识会稀释配置内容，并让 Agent 学会走马观花。
2. 这点已经涵盖了吗？ 搜索现有配置条目中是否已有相关主题——如果已有，完善措辞比添加第二条规则更好。
3. 这是普遍适用的，还是仅限局部？ 特定环境的变通方法（损坏的密钥环、某个仓库的工具怪癖）必须注明适用范围，不能泛化为全局规则。

只有通过全部三项筛选的候选项，才会进一步检查其类型：

• 纠正：通过添加标志或修改环境变量后重试命令，或修正错误假设
• 发现：未记录的行为、集成方面的怪癖、环境要求
• 工作流：会话中形成的多步骤模式，值得重复使用
• 指令违规：如果用户不得不提醒你遵守配置中已有的要求，可能需要强化措辞，而不是新增规则
• 矛盾：这条经验是否与现有内容冲突或取代现有内容？应标记为替换，而不是添加——即使用户没有指出冲突

如果没有任何内容通过筛选，就告诉用户未发现非显而易见的经验，然后退出——不要编造经验来证明调用合理。

3. 为每条经验确定路径

对每条经验都要问：有人会按名称调用它吗？ 如果你能想象用户会说“运行 [X] 工作流”，那它就是一项技能。否则，它就是配置条目。

1. 这是否是一套可供执行的多步骤流程？ 如果这条经验包含 3 个或更多按顺序执行的编号步骤——即使只适用于特定项目——也应归入新技能。部署清单、发布操作手册、“添加 X”工作流都属于技能。单条事实和注意事项属于配置。若是 → 路径 C（新建技能）。
2. 是否有现有技能涵盖这个主题？ → 路径 B（更新该技能）
3. 配置文件是否过大（>500 行）？ → 路径 C 或提供重构选项
4. 否则 → 路径 A（配置文件）

最明确的判断信号是：如果需要执行多个命令，它很可能属于技能；如果只是需要记住一条事实，它就属于配置。

4. 保留跨配置同步规则

范围仅限基于 Markdown 的配置——CLAUDE.md、GEMINI.md、AGENTS.md、.github/copilot-instructions.md、.cursorrules、.windsurf/rules/rules.md。不在范围内：.cursor/rules/*.mdc 和 .continuerc.json（非 Markdown 格式；后续会处理这些格式中的镜像规则检测）。

在 Markdown 范围内，如果存在多个配置：

1. 检测每个已检测配置中的镜像规则文本——例如 keep ... in sync、mirror ... to、apply the equivalent change to 等模式，且附近提到了另一个配置的文件名。
2. 遵循第 1 步的选择。 仅操作用户选择的配置。未选中的配置中的镜像规则不会触发扩展修改——用户可能是有意限定了此次学习的范围（例如，Copilot 文件仅涉及风格）。
3. 保留每次编辑中的镜像规则文本。不要在重写章节时覆盖它。
4. 互相同步。 对于用户选中的配置，如果其中没有引用其他已选配置的镜像规则，就添加一条（例如，如果 .github/copilot-instructions.md 中没有互惠规则，就在文件顶部添加 Keep CLAUDE.md in sync: mirror rule changes back to CLAUDE.md）。

原因： 镜像规则至关重要——未来的会话依靠它来了解如何保持配置同步。如果悄悄更新一个配置而不更新另一个，或在重写时删除镜像规则，配置就会逐渐偏离，规则也会失效。用户的选择仍然有效，因为更窄的范围通常是合理的。

5. 审核规则文本

在句子和破折号边界处分割每条草拟的规则。对于每个片段，说明它带来的内容——规则、修正、非显而易见的原因或具体示例——否则就删除。事件叙述、多从句理由以及重复陈述触发条件都不符合要求。

在下一步的 Cut in audit: 行中记录审核结果。如果用户还得追问草稿是否足够精简，就说明审核被跳过了，而不只是做得不够仔细。

6. 展示计划并等待确认

展示计划前，根据底层观察对候选项去重。 如果两个候选项通过不同路径描述同一事实（例如，CLAUDE.md 条目与技能引用规则，或保留的候选项与对同一观察的「被拒绝的替代路径」），就只选一条路径，删除其他项——不要在计划或拒绝列表中将同一事实的替代路径分别列出。一项观察，一行。

然后展示所有计划执行的操作：

**[Category]**: [Brief description]
- Source: [what triggered this learning]
- Proposed change: [exact text to add, post-audit]
- Cut in audit: [clauses cut, or "none" + one-word defense per kept clause]
- Destination: [file] ([current lines] → [projected lines])

如果有多项学习内容，全部列出，然后询问：

Ready to apply. Approve all, or review each one?

在用户对此步骤作出回应之前，不要修改任何文件。

7. 应用更改

路径 A——配置文件（CLAUDE.md、GEMINI.md 等）：必须完整阅读 references/assistant-configs.md，了解格式和章节约定后再写入。除非文件也超过 500 行，否则此路径不要加载 refactoring.md。追加前，搜索现有配置中的相关内容——如果找到，就提出原位更新，而不是重复添加；如果新规则与现有规则矛盾，则在摘要中明确指出冲突（原则 4）。然后找到适当的章节，保留现有结构，并追加内容或创建章节。每次写入时都应用第 4 步的同步规则保留要求。

路径 B——现有技能：阅读 skills/[name]/SKILL.md，追加到相关章节，并保持现有结构。

路径 C——新技能：创建 skills/[name]/SKILL.md。描述字段决定该技能是否会被激活——必须说明技能的功能、使用时机，并包含触发关键词（动作动词、文件类型、领域术语）。像「帮助部署」这样含糊的描述会导致技能永远不会触发。

---
name: [topic]
description: [WHAT it does + WHEN to use it + trigger keywords]
---

# [Topic]

## Process

### 1. [First Step]
[Details]

8. 总结

列出已修改的文件及修改前后的行数、更新或创建的章节，以及创建的任何技能及其名称。如果解决了矛盾，请明确指出冲突的规则以及最终保留的版本。如果遵循了跨配置同步规则（保留或相互同步），也请说明。

本次会话提交的问题。 检查本次会话的工具调用历史，查找 gh issue create 调用，以及本次会话中生成的匹配 https?://github\.com/[^/]+/[^/]+/issues/\d+ 的 URL。如果提交了问题，请在 本次会话提交的问题 小标题下列出，每个问题单独一条：

### Issues filed this session
- #301 — CI: split verify-pr.yaml into per-stack workflows
  https://github.com/owner/repo/issues/301

如果没有提交问题，则完全省略该小标题。按 (owner, repo, number) 元组（或等效的规范问题 URL）去重——涉及多个仓库的会话可能会产生不同 owner/repo 路径下相同的问题编号，因此仅按编号去重会错误地合并无关条目。未必总能从会话输出中找到标题——如果缺少标题，请省略 — <title> 部分并保留 URL。

原则

1. 拒绝噪声，只纳入不显而易见的经验。 臃肿的配置会让 Agent 走马观花。如果开发者已经知道某件事（“运行 npm start 前先执行 npm install”“切换分支前先提交”），就跳过——并说明你剔除了哪些条目，以便用户决定是否恢复。
2. 标注适用范围；绝不将一次性修复泛化。 今天有效的变通方法，如果环境不同，可能会给未来的会话带来问题。请标明触发修复的条件（密钥环损坏、特定 macOS 版本、此仓库的构建问题），以便后续 Agent 判断是否适用。使用“当 X 失败时”或“作为 Y 之后的备用方案”等限定语，而不要无条件地说“始终使用 Z”。
3. 一个主题，只放一处。 如果某条规则已存在于配置或技能中的任何位置，请更新该条目。同一主题出现两处会造成歧义——Agent 会遵循先读到的那条，而它可能是较弱的版本。与其追加一条平行的要点，不如收紧现有措辞。
4. 明确指出矛盾；绝不悄悄重复或替换。 如果某条经验与现有内容冲突，应在计划和总结中明确说明替换内容及原因（“此规则取代现有的 X 规则，因为 Y”）。悄悄替换会让用户不知道规则已变更；悄悄重复则会导致 Agent 的行为不一致，取决于它先读到哪条。
5. 规则文本应精简到最低限度。 每个分句都必须有实际作用——规则、修复方法、非显而易见的“原因”或具体示例。起草后，请检查：“这是必要的最少字符数吗？” 删除无法说明合理性的分句。 `cd dir && cmd`（如果 `cd` 失败，就不会运行 `cmd`） 比一段解释 shell 退出语义的文字更好；事件叙述和多分句的后果应写入提交消息，而不是规则正文。

绝不要写含糊的经验——“部署时要小心”毫无帮助；“将内容推广到生产环境前，先在预发布环境运行冒烟测试，因为 CDN 缓存会掩盖资源损坏”则具有可操作性，并解释了原因。这条绝对禁令始终有效，因为具体性是其他所有原则都不可妥协的基础。