name: learnings description: “捕获和持久化基于证据的执行学习到 `.learnings.jsonl` 中。触发线索/关键词: `$learnings`、经验教训、要点、总结、交接、提交/PR之前、测试通过后、失败->通过、策略调整、陷阱、重试循环。”

学习记录

概述

在证据出现时立即捕获持久的教训，而不仅限于明确的回顾请求。将每个验证后的学习写成 JSONL，以便未来代理人能快速重用成功模式和避免陷阱。

触发线索

$learnings
“经验教训” / “要点” / “总结” / “交接”
提交/PR/发布之前；证明信号状态变化后（失败->通过）
“策略调整” / “陷阱” / “陷阱” / “重试循环”

操作约定（自动捕获）

允许在实现回合结束时（成功或暂停）和交付边界（提交/PR/交接）自动运行。
尽力而为且非阻塞：永远不要求额外上下文；如果证据薄弱，要么不写入，要么用占位符持久化 review_later。
噪音控制：如果没有捕获检查点发生或没有决策塑造性内容出现，附加 0 条记录；否则优选 1 条记录（最多 3 条）。

捕获检查点

在每次编码回合中，当任何这些检查点发生时至少捕获一次：

验证过渡：信号状态变化（失败->通过、通过->失败、超时->稳定）。
策略调整：方法被放弃、替换或简化。
陷阱发现：观察到隐藏风险、脆弱假设或重复陷阱。
动量发现：模式反复加速实施或调试。
交付边界：立即在提交/PR/最终交接之前。

自动触发规则：如果这些检查点都没有发生且没有决策塑造性内容出现，则不附加任何内容。

工作流程

收集证据。
- 检查更改的表面（git status -sb、git diff --stat、针对性 git diff）。
- 收集执行的验证信号和结果。
- 仅在由命令、日志、差异或测试输出证明时收集失败的尝试。
提炼候选学习。
- 只保留改变未来决策的教训。
- 将叙事转换为规则形式（当 X 时，优选 Y，因为 Z）。
分配语义状态。
- 使用简洁的动作状态，采用 snake_case。
- 当合适时，优选 do_more 或 do_less。
- 需要时选择更精确的状态（例如 investigate_more、codify_now、avoid_for_now）。
立即持久化。
- 将每个接受的学习附加到仓库根目录的 .learnings.jsonl（如果没有符合条件的，0 条记录也有效）。
- 使用 append_learning.py 辅助脚本（通过下面显示的规范主路径解析），而不是手动构建 JSON。
在聊天中报告简洁亮点。
- 总结 1-3 个最高杠杆的学习（或说没有）。
- 引用写入结果（.learnings.jsonl 更新、N 条记录附加，或重复跳过）。

JSONL 约定

每行写一个 JSON 对象：

{
  "id": "lrn-20260207T173422Z-a91f4e2c",
  "captured_at": "2026-02-07T17:34:22Z",
  "status": "do_more",
  "learning": "Boundary parsing eliminated downstream guard duplication.",
  "evidence": [
    "uv run pytest tests/parser_test.py::test_rejects_invalid passed after boundary parse refactor"
  ],
  "application": "Parse and refine request payloads once at API boundaries.",
  "tags": [
    "api",
    "testing"
  ],
  "context": {
    "repo": "owner/repo",
    "branch": "main",
    "paths": [
      "src/parser.py",
      "tests/parser_test.py"
    ]
  },
  "related_ids": [
    "lrn-20260130T120000Z-deadbeef"
  ],
  "supersedes_id": "lrn-20260101T090000Z-cafebabe",
  "source": "skill:learnings",
  "fingerprint": "a91f4e2c6b5d3f10"
}

必需键：

id
captured_at
status
learning
evidence
application
source
fingerprint

可选键：

context
tags
related_ids
supersedes_id

写入过程

每个学习使用一个附加调用：

CODEX_SKILLS_HOME="${CODEX_HOME:-$HOME/.codex}"
CLAUDE_SKILLS_HOME="${CLAUDE_HOME:-$HOME/.claude}"
APPEND_LEARNING_SCRIPT="$CODEX_SKILLS_HOME/skills/learnings/scripts/append_learning.py"
[ -f "$APPEND_LEARNING_SCRIPT" ] || APPEND_LEARNING_SCRIPT="$CLAUDE_SKILLS_HOME/skills/learnings/scripts/append_learning.py"

uv run python "$APPEND_LEARNING_SCRIPT" \
  --status do_more \
  --learning "Boundary parsing eliminated downstream guard duplication." \
  --evidence "uv run pytest tests/parser_test.py::test_rejects_invalid passed after boundary parse refactor" \
  --application "Parse and refine request payloads once at API boundaries." \
  --tag api \
  --tag testing

辅助脚本：

将 status 标准化为 snake_case。
当省略时，默认 status 为 review_later。
用占位符回填缺失的证据/应用，而不是失败。
从 remote.origin.url 捕获尽力的仓库 slug（或回退到仓库目录名）。
在可用时从 git 捕获分支和更改路径。
计算指纹以进行重复检测。
默认附加到仓库根目录的 .learnings.jsonl。

挖掘、召回和固化循环

使用挖掘脚本在任务开始时利用学习（一旦用户提示可用），并将重复项目推广为持久策略。

CLI：

CODEX_SKILLS_HOME="${CODEX_HOME:-$HOME/.codex}"
CLAUDE_SKILLS_HOME="${CLAUDE_HOME:-$HOME/.claude}"
LEARNINGS_SCRIPT="$CODEX_SKILLS_HOME/skills/learnings/scripts/learnings.py"
[ -f "$LEARNINGS_SCRIPT" ] || LEARNINGS_SCRIPT="$CLAUDE_SKILLS_HOME/skills/learnings/scripts/learnings.py"
LEARNINGS_SPECS_DIR="$CODEX_SKILLS_HOME/skills/learnings/specs"
[ -d "$LEARNINGS_SPECS_DIR" ] || LEARNINGS_SPECS_DIR="$CLAUDE_SKILLS_HOME/skills/learnings/specs"

uv run python "$LEARNINGS_SCRIPT" datasets
uv run python "$LEARNINGS_SCRIPT" query --spec "@$LEARNINGS_SPECS_DIR/status-rank.json"
uv run python "$LEARNINGS_SCRIPT" recall --query "fix flaky pre-commit hook" --limit 5
uv run python "$LEARNINGS_SCRIPT" codify-candidates --min-count 3 --limit 20

推广经验法则：

如果一个学习被重复（主题出现 >= 3 次）或状态是 codify_now，将其推广到持久文档中（例如 codex/AGENTS.md 或相关技能文档）。
固化后，附加一个后续学习引用持久锚点（使用 --related-id/--supersedes-id 和 codified 标签）。

护栏

将每个学习建立在观察到的证据上；不要将隐藏原因推断为事实。
不要写纯变更日志要点；写决策塑造规则。
保持 status 以行动为导向，并在语义上适合情况。
避免重复条目；辅助脚本通过指纹跳过完全重复。
- 如果你对现有学习有实质性的新证据，附加一个后续记录（调整 status 和/或使 learning 陈述更具体），或有意使用 --allow-duplicate 重新运行。
- 不要手动编辑现有的 JSONL 行。
如果证据薄弱，用 review_later 和占位符持久化，然后稍后丰富。

name: learnings description: “捕获和持久化基于证据的执行学习到 .learnings.jsonl 中。触发线索/关键词: $learnings、经验教训、要点、总结、交接、提交/PR之前、测试通过后、失败->通过、策略调整、陷阱、重试循环。”