Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/ZeroZ-lab/unified-skills --skill maintain-workflow-learnThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
| name | maintain-workflow-learn |
| description | 跨会话学习记忆。当发现项目模式、踩坑经验、偏好需要持久化，或提到"学习""记忆""记住""下次注意" |
| argument-hint | [--list | --add: insight | --clear] |
.claude/learnings.jsonlmaintain-workflow-using-unified 或原调用技能文件：.claude/learnings.jsonl（项目级，必须加入 .gitignore）
每行一个 JSON 对象，追加写入：
{"type":"pitfall","key":"orm-n+1-query","insight":"User.list() 默认加载关联，列表接口必须用 .select() 限制字段","confidence":8,"files":["src/services/user.service.ts"],"source":"manual","ts":"2026-04-24T14:30:52+08:00"}
| 字段 | 类型 | 说明 |
|---|---|---|
type | 枚举 | pattern / pitfall / preference / architecture |
key | 字符串 | 唯一标识，kebab-case。同 key 后写入覆盖前写入（last-write-wins） |
insight | 字符串 | 一句话洞察。具体、可操作，不是泛泛描述 |
confidence | 整数 | 1-10。10 = 确凿证据，1 = 初步观察 |
files | 列表 | 相关文件路径（可为空列表） |
source | 枚举 | auto（技能自动采集）/ manual（人工添加） |
ts | ISO-8601 | 记录时间 |
| type | 用途 | 示例 |
|---|---|---|
pattern | 已验证的模式 | "错误处理统一用 Result 类型，不用 try/catch" |
pitfall | 已踩的坑 | "CI 中不能访问内网服务，测试需要 mock" |
preference | 团队偏好 | "commit message 用 conventional commits 格式" |
architecture | 架构约束 | "事件总线只允许 async 通信，禁止同步调用" |
同 key 后写入覆盖前写入（last-write-wins）。
# 去重方法：按 key 保留最后一条
tac .claude/learnings.jsonl | awk -F'"key":"' '!seen[$2]++' | tac > .claude/learnings.jsonl.tmp && mv .claude/learnings.jsonl.tmp .claude/learnings.jsonl
显示最近 20 条学习，按 type 分组：
Patterns (8):
[conf:9] api-error-handling → 统一用 Result 类型
[conf:7] pagination-cursor → 列表接口用游标分页
Pitfalls (5):
[conf:8] orm-n+1-query → User.list() 默认加载关联
[conf:6] ci-internal-access → CI 中不能访问内网服务
Preferences (4):
[conf:9] commit-convention → conventional commits 格式
Architecture (3):
[conf:10] event-bus-async-only → 事件总线只允许 async 通信
conf 为 confidence 缩写。每个条目一行。
全文搜索 learnings.jsonl：
/learn search auth
在 key 和 insight 字段中搜索匹配项，高亮匹配行。
交互式清理：
files 已不存在的条目标记为过时导出为 markdown（按 type 分组）：
# Learnings
## Patterns
- **api-error-handling** (conf:9) — 统一用 Result 类型
Files: src/utils/result.ts
- **pagination-cursor** (conf:7) — 列表接口用游标分页
Files: src/middleware/pagination.ts
## Pitfalls
- **orm-n+1-query** (conf:8) — User.list() 默认加载关联
Files: src/services/user.service.ts
## Preferences
- **commit-convention** (conf:9) — conventional commits 格式
## Architecture
- **event-bus-async-only** (conf:10) — 事件总线只允许 async 通信
手动添加。必须指定 type、key、insight、confidence：
/learn add type:pitfall key:env-var-case insight:"环境变量用 UPPER_SNAKE_CASE，不用 camelCase" confidence:7 files:"config/env.ts"
缺少必填字段拒绝写入并提示。files 和 ts 可选（ts 默认当前时间）。
其他技能在关键节点调用本技能记录学习。触发场景：
| 场景 | 记录 type | 来源技能 |
|---|---|---|
| 调试发现根因 | pitfall | verify-workflow-debug |
| 采纳新的实现模式 | pattern | build-workflow-execute |
| 确认团队偏好 | preference | verify-workflow-review |
| 做出架构决策 | architecture | build-cognitive-decision-record |
自动记录的 source 为 auto，confidence 默认为 5（待验证）。人工 review 后可提高 confidence。
| 说辞 | 现实 | 后果 |
|---|---|---|
| "学习记了也没用" | 每次重复踩坑的代价远超记录成本。一条 pitfall 避免一次返工就回本。 | 重复踩坑 ×3 次 ×2 小时 = 6 小时浪费；记录成本 = 5 分钟 |
| "让 AI 自己记" | 自动采集是补充不是替代。人工判断价值更高——auto 记录需要人工筛选和提权。 | auto 全部 confidence=5 → 信噪比低 → 有价值的学习被淹没 → prune 成本 ×3 |
| "JSONL 格式太原始" | 原始 = 可 grep、可追加、无依赖。不需要数据库。 | 引入数据库 = 新依赖 + 迁移成本 + 维护负担；JSONL 零依赖 |
| "confidence 主观不靠谱" | 主观但有价值。confidence 7 和 3 的差异传达了确定程度。全标 10 才是问题。 | 全标 10 → 无法区分确凿 vs 初步 → 高 confidence 学习无优先权 → 误导决策 |
| "prune 太麻烦" | 不 prune 更麻烦——过时和矛盾的学习比没有学习更危险。 | 过时学习误导 → 按已废弃的 pattern 实现 → 返工 2-4 小时；prune 只需 10 分钟 |
learnings.jsonl 超过 1000 条 — 需要 prune。1000+ 条意味着过时条目未清理，信噪比下降。auto source 少 manual — 缺乏人工筛选。auto 记录的 confidence 默认 5，需要人工 review。| 验证项 | 失败表现 | 处理方式 |
|---|---|---|
| JSONL 格式错误 | 非有效 JSON 或多行对象 | 逐行验证；修复格式或删除损坏行 |
| type 不在枚举范围 | 使用了非标准 type | 映射到最接近的标准 type；无法映射则拒绝写入 |
| confidence 超出范围 | < 1 或 > 10 | 截断到 1-10；全标 10 的条目需人工降权 |
| key 非 kebab-case | 使用 camelCase 或含空格 | 转换为 kebab-case；去重后保留最新条目 |
| 条目超过 1000 条 | learnings.jsonl 过长 | 执行 prune：清理过时、矛盾、低 confidence 条目 |
{"type":"pitfall","key":"orm-n+1-query","insight":"User.list() 默认加载关联，列表接口必须用 .select() 限制字段","confidence":8,"files":["src/services/user.service.ts"],"source":"manual","ts":"2026-04-24T14:30:52+08:00"}
{"type":"pitfall","key":"ORM Problem","insight":"ORM sometimes has performance issues when loading too much data and this can cause slow queries in production environments especially on list endpoints","confidence":10,"files":[],"source":"auto","ts":"2026-04-24T14:30:52+08:00"}
学习记录完成：
操作: [add / list / search / prune / export]
条目数: [N] (add 时 = 1)
新增条目 (add):
type: [pattern/pitfall/preference/architecture]
key: [kebab-case]
insight: [一句话]
confidence: [1-10]
files: [相关路径列表]
source: [auto/manual]
列表摘要 (list):
Patterns: [N] 条 (avg conf: [X])
Pitfalls: [N] 条 (avg conf: [X])
Preferences: [N] 条 (avg conf: [X])
Architecture: [N] 条 (avg conf: [X])
修剪结果 (prune):
已删除: [N] 条 (过时/矛盾/低 conf)
保留: [N] 条
Based on SOC occupation classification
