feedback-learning

反馈学习

当用户明确纠正实现或设计方案、否定某种模式，或要求 Agent 从反馈中学习时，使用此技能；但用户触发字面内容 learn! 的情况除外。

字面内容 learn! 请求仅由 .github/instructions/learnings.instructions.md 管理，不属于此技能的范围。不要替换或重新解释该指令。

目标

将可复用的知识保存在最小且权威的文档中。一次纠正不会自动成为永久规则。

工作流

1. 识别纠正内容

   • 哪里错了？
   • 为什么错了？
   • 用户更倾向于哪种做法？
   • 会影响哪些路径或子系统？

2. 写入前先搜索

   • 检查适用的指令、技能、设计文档、测试和限定范围的学习文件。
   • 更新现有规则，而不是添加重复内容。

3. 对反馈分类

   反馈类型	目标位置
   任务特定偏好或一次性调整	不要持久化
   不得回归的具体行为	回归测试
   稳定的子系统架构或产品不变量	相关设计／规范文档
   通用仓库规则	适用的指令文件
   可复用但尚未成熟或验证的指导	.github/learnings/<area>.md
   由工具驱动的工作流	相关技能

4. 谨慎归纳

   • 保留原则，而不是事件经过。
   • 除非临时符号名称、行号或实现细节定义了持久契约，否则不要包含这些内容。
   • 没有更广泛的依据时，不要将一次对某种实现的否定转化为通用禁令。

5. 只记录一次

   • 设计文档和测试具有权威性。
   • 学习收件箱条目是临时内容。晋升条目时，在同一次更改中移除收件箱条目。
   • 永远不要在技能、指令和设计文档中重复同一规则。
   • 添加收件箱条目之前，先按照下方维护规则精简目标文件。

6. 验证

   • 确认目标位置适用于受影响的路径。
   • 检查链接，并移除已被取代或相互矛盾的指导内容。

学习收件箱格式

使用以下格式创建或更新 .github/learnings/<area>.md：

# Area learning inbox

Last reviewed: YYYY-MM-DD

## Short topic

- **Scope:** `affected/path/**`
- **Learning:** Generalized guidance in one or two sentences.
- **Evidence:** Why this is reusable beyond the current task.
- **Disposition:** Candidate for `<design document, instruction, skill, or test>`.

条目应简洁。每个领域的收件箱最多包含 10 个主题，大小不超过 8 KB。如果新增条目会超过任一限制，请先晋升、合并或移除现有条目，再决定是否值得持久化这条新反馈。

阅读学习内容

不要在每项任务中都注入学习收件箱内容。先搜索相关文件的标题和 Scope 字段，然后只阅读匹配的条目。学习收件箱用于补充源代码、测试和设计文档；它并非无关工作的前提，也不能凌驾于这些内容之上。

精简与垃圾回收

每次写入前都要精简收件箱。如果收件箱达到任一上限，或读取时发现其 Last reviewed 日期已超过 90 天，也要进行全面审查。审查期间：

• 将稳定的架构指导晋升到负责维护该内容的规范中；
• 在测试中明确具体行为；
• 将重叠条目合并为一条通用原则；
• 移除过时、相矛盾、已晋升或依据薄弱的条目；
• 根据当前源代码和权威文档检查所有保留条目后，更新 Last reviewed。

收件箱可以缩减至零条目。不要仅仅因为某条学习将来可能有用，就将其保留。