treasoni maintain-learnings（经验库维护）
让 .learnings/ 保持小而有用：它是发现流程缺陷的雷达，不是永久堆放错误的仓库。重复错误必须优先修源头，验证有效后再清理活跃记录。
Step 1: 审计经验库
先读取：
.learnings/RULES.md.learnings/LEARNINGS.md.learnings/ERRORS.md
然后运行审计脚本。Codex 示例：
python3 .agents/skills/maintain-learnings/scripts/audit_learnings.py --root . --skills-dir .agents/skills --rules-file AGENTS.md --hooks-path .codex/hooks
Claude Code 示例：
python3 .claude/skills/maintain-learnings/scripts/audit_learnings.py --root . --skills-dir .claude/skills --rules-file CLAUDE.md --hooks-path .claude/hooks
Step 2: 选择修复目标
优先处理：
- 活跃记录中同一 skill 出现 2 次及以上。
- 历史归档和活跃记录合计出现 3 次及以上。
- 已写入
RULES.md但仍在ERRORS.md/LEARNINGS.md中复发。 - 活跃文件超过 100 行且包含明显重复主题。
Step 3: 追溯源头
根据审计报告读取对应源文件：
- skill 问题：
<skills-dir>/<skill>/SKILL.md - skill 模板问题：
<skills-dir>/<skill>/references/ - 项目规则问题：
AGENTS.md/CLAUDE.md/ 项目自定义规则文件 - hook 问题：
.codex/hooks//.claude/hooks// 项目自定义 hook - 工具脚本问题：对应
scripts/
Step 4: 修改机制
修复必须落到可执行机制之一：
- 在对应
SKILL.md中加入明确步骤、硬性约束或验证 checklist。 - 修改 reference 模板，使正确格式自然生成。
- 添加或修改校验脚本，让错误能被自动发现。
- 更新项目规则，但只提升跨 skill 的铁律。
不要只把“下次注意”追加到 .learnings/。如果没有源头修改，不能清理对应错误记录。
Step 5: 验证修复
至少验证两件事：
- skill 元数据存在：
python3 -c 'from pathlib import Path; p=Path("<skills-dir>/<skill>/SKILL.md"); t=p.read_text(encoding="utf-8"); assert t.startswith("---\n") and "\n---" in t[4:]; assert "name:" in t and "description:" in t; print("skill metadata ok")'
- 每条待归档记录都能对应到新的步骤、模板或校验逻辑。
Step 6: 双平台同步守护
如果项目同时使用 Codex 和 Claude Code，修改任何共享 skill 后都运行：
python3 .agents/skills/maintain-learnings/scripts/sync_platform_skills.py --root . --skill <skill>
如果另一侧缺失，先 dry-run：
python3 .agents/skills/maintain-learnings/scripts/sync_platform_skills.py --root . --from-platform agents --to-platform claude --skill <skill>
确认后应用：
python3 .agents/skills/maintain-learnings/scripts/sync_platform_skills.py --root . --from-platform agents --to-platform claude --skill <skill> --apply
保留平台专属内容：
- Codex UI 元数据（如
agents/openai.yaml）只留在.agents/。 - Claude Code 的 hooks / settings 只按 Claude Code 规则处理。
- 不用一侧版本覆盖另一侧专属命令、Hook、工具说明和平台限制。
Step 7: 清理活跃 learnings
只处理已经验证修复的记录：
- 在
.learnings/archive/YYYY-MM-DD-maintenance.md追加归档块，包含原记录摘要、修复路径、验证方式、处理结果。 - 从
.learnings/LEARNINGS.md或.learnings/ERRORS.md移除对应详细记录。 - 保留或更新
.learnings/RULES.md中的简短铁律。 - 未修复、未验证或仍需观察的记录继续留在活跃文件中。
禁止行为
- 不要为了“变短”直接清空
.learnings/。 - 不要归档未修复的问题。
- 不要把多个不同根因的错误合并成一条模糊规则。
- 不要把只适用于某个 skill 的细节提升到项目总规则。