knowledge-capture

知识捕获

概述

每次实质性的交互都会带来有价值的信息。一次调试会话会揭示代码库中隐藏的惯例。用户的一次纠正会透露其偏好。一次失败的计划会暴露盲点。记录这些观察并非额外负担，而是能力的复利增长。

核心原则： 解决难题却不记录所得，意味着下次还得从零开始。

没有例外。没有变通办法。没有捷径。

首要准则

EXTRACT INSIGHT FROM EVERY MEANINGFUL INTERACTION

一次未经过反思便结束的交互，就是一笔白白浪费的投入。你掌握了上下文，找到了答案，也观察到了哪些做法奏效——然后却把这一切都丢弃了。

不要找借口：

• 不要因为任务感觉“很常规”就跳过记录
• 不要因为“马上要切换上下文”就跳过记录
• 不要因为教训看起来“显而易见”就跳过记录
• 在上下文完整时感觉显而易见的东西，冷启动时就会变得无迹可寻

反思。提炼。持久化。仅此而已。

使用时机

以下情况后必须执行：

• 交付复杂功能（哪些模式证明有效？）
• 解决顽固缺陷（根因特征是什么？）
• 收到揭示问题的评审反馈（下次应该有哪些不同？）
• 被用户纠正（发现了什么新偏好？）
• 大幅修改计划（哪些判断有误？）
• 通过反复尝试发现代码库惯例（别让下次会话再经历一遍）

例外情况（请与用户确认）：

• 一行代码的简单修复
• 未产生新信息的交互
• 用户明确拒绝时

如果你正想“这里没什么值得记录的”，请停下来。这是在找理由。

记录流程

AFTER completing any meaningful task:

1. REFLECT: What succeeded? What failed? What was unexpected?
2. DISTILL: What generalizable pattern or insight emerges?
3. DEDUPLICATE: Is this already recorded? Does it contradict something stored?
4. PERSIST: Write it to the appropriate memory file with date and context
5. PRUNE: Remove any prior entries that newer evidence invalidates

Omit any step = insight permanently lost

记录生命周期

digraph capture_lifecycle {
    rankdir=TB;
    node [shape=box style=filled];

    task [label="Meaningful Task\nCompleted" fillcolor=lightyellow shape=doublecircle];

    reflect [label="REFLECT\nWhat occurred?\nWhat surprised me?" fillcolor="#ccccff"];
    distill [label="DISTILL\nAbstract the insight\nfrom the specifics" fillcolor="#ccccff"];
    exists [label="Already\nrecorded?" shape=diamond fillcolor="#fff3e0"];
    conflicts [label="Contradicts\nan existing entry?" shape=diamond fillcolor="#fff3e0"];
    persist [label="PERSIST\nSave to memory\nwith date + context" fillcolor="#ccffcc"];
    prune [label="PRUNE\nRemove outdated\nentry" fillcolor="#ffcccc"];
    cluster [label="CLUSTER\n3+ related insights?\nForm a conviction" fillcolor="#ccffcc"];
    promote [label="PROMOTE\nHigh-confidence conviction\n-> CLAUDE.md rule" fillcolor="#e8f5e9"];
    skip [label="Skip\n(already known)" fillcolor="#eeeeee"];

    task -> reflect;
    reflect -> distill;
    distill -> exists;
    exists -> skip [label="yes, identical"];
    exists -> conflicts [label="no"];
    conflicts -> prune [label="yes"];
    prune -> persist;
    conflicts -> persist [label="no"];
    persist -> cluster;
    cluster -> promote [label="3+ confirmations"];
    cluster -> task [label="await further\nevidence" style=dashed];
}

洞见类别

有效模式

带来良好结果的代码实现方式、调试策略和架构选择。这些都是值得强化的正面信号。

Sample entry:
  Date: 2025-04-10
  Context: Built retry logic for third-party webhook delivery
  Insight: Exponential backoff with random jitter eliminated thundering-herd spikes
  Confidence: medium (validated once)

失败及其补救措施

哪些地方出了问题、如何解决，以及如何防止再次发生。失败往往能带来信号最强的教训。

Sample entry:
  Date: 2025-04-12
  Context: Logging middleware silently swallowed request bodies after refactor
  Insight: Any change to middleware ordering demands a full integration test pass -- blast radius is total
  Confidence: high (validated by production incident)

用户偏好

用户遵循的风格选择、工具偏好和惯例。通过纠正和直接陈述发现。

Sample entry:
  Date: 2025-04-13
  Context: User corrected my naming approach
  Insight: User requires camelCase for variables, PascalCase for types, and no abbreviations anywhere
  Confidence: high (direct correction)

项目专属知识

架构细节、隐藏的陷阱、关键文件，以及文档中没有记录的团队经验。

Sample entry:
  Date: 2025-04-14
  Context: Spent 15 minutes searching for runtime config
  Insight: All runtime configuration lives in src/config/runtime.ts, not in .env files
  Confidence: high (verified in source)

存储机制

利用 Claude Code 的记忆系统：~/.claude/projects/[project]/memory/

记忆文件分类

文件	用途	示例条目
effective-patterns.md	能够带来良好结果的代码实现方式和策略	"在 API 边界使用 Zod schema，可在错误数据传播之前捕获它们"
failure-analysis.md	根因模式和诊断技巧	"测试在本地通过却在 CI 中失败，通常说明存在时区或区域设置假设"
project-map.md	架构、关键文件和代码库惯例	"数据库迁移文件位于 db/migrations/，并通过 pnpm db:migrate 执行"
human-preferences.md	用户坚持的风格选择、工具偏好和惯例	"用户要求显式错误类型；不接受基于字符串的错误"

条目结构

每条捕获的洞见都必须包含：

### [Concise title]
- **Date:** YYYY-MM-DD
- **Context:** What was happening when this was discovered
- **Insight:** The generalized takeaway
- **Confidence:** low / medium / high
- **Confirmations:** Number of times this has been validated

去重流程

写入新条目前，先检查目标记忆文件。如果洞见已经存在：

• 洞见相同、置信度相同 -> 完全跳过
• 洞见相同、置信度提高 -> 更新置信度并增加确认次数
• 洞见矛盾 -> 替换旧条目，并注明矛盾之处

成熟周期

孤立的洞见汇聚起来，便会形成有力的确信。

从洞见到确信

Insight 1: "This project validates forms with zod" (medium confidence)
Insight 2: "API route handlers also validate payloads with zod" (medium confidence)
Insight 3: "User corrected me for using manual validation instead of zod" (high confidence)

    Converge into conviction

Conviction: "This project ALWAYS validates at every boundary using zod"
Confidence: high (confirmed across 3 interactions)

从信念到规则

当一条信念达到高置信度（在 3 次以上交互中得到确认）时，即可晋升为项目 CLAUDE.md 规则：

Conviction: "This project always validates with zod"
  -> Confirmed 3+ times
  -> Propose to user: "I have observed that this project consistently
    uses zod for validation. Should I codify this as a project rule in CLAUDE.md?"
  -> User approves -> add to CLAUDE.md

绝不自动晋升。 向 CLAUDE.md 添加条目前，务必征得用户同意。人类对永久规则拥有最终决定权。

会话开始时的审查

在项目中开始新会话时：

1. 阅读该项目的所有记忆文件
2. 找出尚未综合整理的相关洞见簇
3. 标记可能已过时的条目（日期较早、置信度较低、从未再次确认）
4. 提出可晋升的信念

置信度等级

等级	含义	来源	操作
低	暂定信号	单次出现，未经确认	记录，并留意是否得到确认
中	可能的模式	确认过两次，或有一个强烈指标	记录，并在相关时应用
高	已确立的事实	确认过 3 次以上，或用户明确声明	记录、一贯应用，并考虑晋升

认知陷阱

合理化说辞	事实
“这里没什么值得记录的”	每项任务都会产生信号。只是你观察得还不够仔细。
“我自然会记得”	你不会。下次会话开始时，你将一无所知。记忆文件让你保持连续性。
“太琐碎了，不值得记录”	细微的洞见会逐渐累积。三个小观察就能汇成一条强有力的信念。
“这是不言自明的”	现在上下文完整时，对你而言不言自明。下周冷启动时就未必了。
“记录太费时间”	写下一条记录只需 30 秒；重新发现同一洞见却要 30 分钟。
“用户没有要求这样做”	用户要求的是质量。从经验中学习正是质量随时间提升的方式。
“记忆文件越来越杂乱”	这是修剪问题，不是记录问题。多做修剪，绝不要停止记录。
“这只适用于这一个项目”	项目专属知识是最有价值的类型。这正是它按项目存储的原因。

防护措施

禁止操作：

• 在艰难的调试会话后跳过复盘
• 存储缺少日期和上下文的条目（未注明日期的洞见会逐渐失效）
• 未经用户批准就自动向 CLAUDE.md 添加规则
• 未去重就重复记录同一洞见
• 保留与较新证据相矛盾的条目
• 记录实现细节，而不是可推广的模式

必须执行：

• 完成任何重要工作后进行复盘
• 持久化前检查记忆（去重）
• 为每条记录标注置信度
• 将信念晋升为 CLAUDE.md 规则前征得用户同意
• 修剪被较新证据推翻的条目
• 按主题组织条目，而非按时间顺序排列

集成

此技能为其他技能提供支持：

• godmode:fault-diagnosis —— 历史故障分析为当前排查提供参考
• godmode:pattern-matching —— 已记录的约定有助于保持代码一致性
• godmode:test-first —— 过去的测试失败会影响未来的测试策略
• godmode:task-planning —— 过去的计划失败有助于避免重复误判
• godmode:quality-enforcement —— 已记录的质量模式有助于提高基线

此技能从其他技能获取信息：

• godmode:review-response —— 评审反馈会转化为已记录的洞见
• godmode:completion-gate —— 验证失败会转化为已记录的经验教训
• godmode:comprehension-check —— 演练发现会转化为已存储的观察结果
• godmode:task-runner —— 计划执行会揭示哪些方法有效、哪些无效

良性循环：

Work -> Capture -> Persist -> Apply -> Work better -> Capture more