agent 错题集 + 你的能力增强剂。
周一。你用 agent 啃一个 Kafka 消费端背压问题。 你从来没写过消息队列。agent 帮你写了，代码跑通了。
周三。另一个项目，消费又慢了。你打开代码，盯着消费者配置。 上周的代码是你看着 agent 写的，但那些决策—— 为什么信号量挡在入口、auto-commit 为什么是敌人——你没记住。 agent 替你做了判断，你没把判断变成自己的。
agent 把答案给了你，但判断过程没给。
AI 是能力倍增器，但它的支点是你自己的基线。 基线不涨，乘出来的结果永远锁死在那个支点上。
coding-wisdom 做的事情很简单：
① agent 替你跨过去的那个门槛——它自动记下来 ② 你有空时，15 分钟蒸馏成属于你的判断力 ③ 下次再遇到，你不靠 agent 也能做出正确决策
flowchart TD
SRC["agent 解题过程"]
SRC --> INBOX
subgraph SYSTEM[" "]
direction LR
INBOX["<b>inbox/</b><br/>agent 错题集<br/><br/>记录 agent 替你做的每一个判断"]
REFS["<b>references/</b><br/>你的工程判断<br/><br/>记录你吸收了什么<br/>能从 agent 手中带走什么"]
INBOX -->|"蒸馏"| REFS
end
是 agent 错题集：agent 帮你解决了 Kafka rebalance、JWT 续期、分库分表——那些你第一次接触就被推着往前走的时刻，不记下来就永远没了。
是你的增强剂：每周打开 OVERVIEW.md，看一眼知识版图。那个数字不是 agent 有多强——是你吸取了多少判断力。
一个 Kafka 背压问题。时间线相同，结果不同。
flowchart LR
subgraph WITHOUT["WITHOUT coding-wisdom"]
direction TB
w1["agent 帮你搞定了"] --> w2["你 merge 了 PR"] --> w3["两周后，同一个 bug<br/>另一个项目，数据丢了"] --> w4["你又喊 agent 来修<br/>agent 从头给你解释"] --> w5["三个月后<br/>你还是没搞懂背压的本质"] --> w6["下次又丢数据<br/>你永远依赖 agent"]
end
subgraph WITH["WITH coding-wisdom"]
direction TB
b1["agent 帮你搞定了"] --> b2["inbox 自动写了一条：<br/>背压必须在管道入口<br/>不是在出口打补丁"] --> b3["两周后<br/>OVERVIEW.md 检索到：<br/>架构认知 · 背压机制"] --> b4["你花了 30 秒重新加载"] --> b5["你自己改对了<br/>没喊 agent"] --> b6["三个月后<br/>那是你自己的判断力<br/>下次遇到，直接做对"]
end
WITHOUT ~~~ WITH
flowchart TD
SESSION["<b>编码会话</b><br/>重构 · Bug修复 · 模式复现<br/>方案选择 · 技术研究"]
GATE["<b>通用性门禁</b><br/>Q1 双场景测试<br/>Q2 去项目化测试"]
HIGH["<b>inbox/high/</b><br/>复现 · 永不过期"]
LOW["<b>inbox/low/</b><br/>初见/未通过 · 7天后清理"]
REFS["<b>references/</b><br/>架构认知 · 编码技巧<br/>思维方式 · 技术栈认知"]
NEXT["下次编码<br/>agent 主动提醒你"]
SESSION -->|"捕获 (自动)"| GATE
GATE -->|"通过 + 复现"| HIGH
GATE -->|"通过 + 初见"| LOW
GATE -->|"未通过"| LOW
HIGH -->|"蒸馏 (你手动)"| REFS
LOW -->|"蒸馏 (你手动)"| REFS
REFS -->|"检索复用"| NEXT
Agent 安装指引 — 把下面这行发给任意 AI 编码助手（Claude Code、Codex CLI 等），让它自己读协议、自己装，无需人工操作：
请按照 https://github.com/Clannad47/coding-wisdom/blob/main/AGENT_INSTALL.md 安装 coding-wisdom
/plugin marketplace add Clannad47/coding-wisdom
/plugin install coding-wisdom@coding-wisdom
# 安装
npm install -g coding-wisdom # 全局安装，自动部署，一步到位
npx coding-wisdom # 或一键免安装
# 更新
npm update -g coding-wisdom # postinstall 自动重新部署
npx coding-wisdom@latest # npx 方式
# 卸载
coding-wisdom --uninstall # 删除 skill，清空 inbox/references
npm uninstall -g coding-wisdom # 移除 npm 包# macOS / Linux
cp -r coding-wisdom ~/.claude/skills/
# Windows
xcopy /E /I coding-wisdom %USERPROFILE%\.claude\skills\coding-wisdom重启 Claude Code，安装完成。
npm install -g coding-wisdom # install.js 自动检测并部署到 ~/.codex/skills/或通过 Codex 技能安装器：
$skill-installer Clannad47/coding-wisdom
同时支持 Claude Code 和 Codex CLI（Agent Skills 开放标准）。差异仅在配置文件命名：
| 概念 | Claude Code | Codex CLI |
|---|---|---|
| 项目上下文 | CLAUDE.md |
AGENTS.md |
| 跨会话记忆 | MEMORY.md |
.codex/memories/ |
| Skill 路径 | ~/.claude/skills/ |
~/.codex/skills/ |
- Fork 本仓库到你的 GitHub（建议私有，保障数据安全）
- Clone 你的 fork 到
~/.claude/skills/coding-wisdom - 想追踪
references/？删掉.gitignore里对应的两行忽略规则 - 正常编码。agent 写
inbox/（本地，永不追踪），你蒸馏到references/ git commit && git push—— 每一次判断力增长都有版本记录- 更新：
git pull即可获得最新 skill 逻辑，用户数据不受影响
你做你的事。agent 检测到认知裂缝时自动写入 inbox/。
| 触发事件 | 例子 |
|---|---|
| 结构性重构 | 改核心数据结构、拆分模块 |
| 非平凡 Bug 修复 | 逻辑错误、设计缺陷 |
| 跨项目模式复现 | 不同项目里出现相似设计模式 |
| 方案选择 | A vs B 选了 A，放弃 B 有理由 |
| 技术研究 | 深入研究得出非文档直接结论 |
tier 由通用性门禁决定：通过 Q1/Q2 + 复现 →
high，初见或未通过 →low（7 天后清理）
零摩擦——你不需要说"记下来"，它自己发生了。
打开 inbox/high/。挑 2-3 条你觉得最有价值的。补充 ## 泛化——从"这个项目的具体 bug"抽象到"任何系统遇到这个信号时应该检查什么"。更新 _index.md，跑 bash scripts/sync-overview.sh。
下次编码，agent 自动检索 references/。当前场景和你蒸馏过的旧知识相关——它提醒你，你调用的是你自己的判断，不是 agent 的。
核心结构：我以为 → 其实是。记录的是认知裂缝——你之前理解错了什么，现在理解对了。
# TypedDict 是声明式契约，不是类型标注
## 我以为
TypedDict 只是给 dict 加类型提示的工具。
## 其实是
TypedDict 让数据结构成为自文档化的契约——
每个处理步骤声明自己需要什么、产出什么。
## 背景
Insurance Atom Trigger，Pipeline 重构。多步骤数据流需要跨步骤类型一致性。
## 泛化
凡多步骤数据流，入口契约不应散落在自然语言和 if/else 里。coding-wisdom/
├── SKILL.md # agent 指令：捕获规则、噪音过滤、动态加载
├── OVERVIEW.md # 自动生成，你的知识版图全貌（禁止手动编辑）
├── guides/ # 按需加载的深层流程
│ ├── distillation.md # 蒸馏工作流和质量门
│ ├── generalization.md # 泛化四层模型（现象→模式→原则→可操作规则）
│ ├── web-calibration.md # 联网校准策略
│ └── ascii-diagrams.md # ASCII 架构图规范
├── templates/ # 条目模板
│ ├── capture-entry.md # 捕获模板（30 秒写完）
│ └── distilled-entry.md # 蒸馏后的完整形态
├── scripts/
│ ├── sync-overview.sh # 从 _index.md 自动生成 OVERVIEW.md (bash)
│ ├── sync-overview.ps1 # 同上（PowerShell）
│ └── setup-local-worktree.* # 开发者本地隔离脚本
├── inbox/ # 本地个人数据（不受版本控制）
│ ├── high/ # 永不过期
│ └── low/ # 7 天后可清理
└── references/ # 你的个人知识库
├── architecture/ # 架构认知
│ ├── _index.md
│ ├── data-flow/ # 数据流与契约设计
│ └── system-design/ # 系统设计模式
├── coding/ # 编码技巧
│ └── _index.md
├── mindset/ # 思维方式
│ └── _index.md
└── techstack/ # 技术栈深度认知
└── _index.md
_index.md 是单一事实源。OVERVIEW.md 由脚本自动聚合——蒸馏完跑一次 bash scripts/sync-overview.sh，完事。
| 维度 | 你在这里积累什么 |
|---|---|
architecture/ |
系统设计、模块边界、数据流、并发模式 |
coding/ |
语言惯用法、反模式、数据结构选择 |
mindset/ |
好品味、设计哲学、消除特殊情况的直觉 |
techstack/ |
Kafka rebalance、JWT 生命周期、分库分表实战 |
- 吸取判断力，不是记 API — 一条知识应该记录"我被纠正了什么"，不是"我第一次见到了什么"
- 30 秒捕获 > 完美格式 — 能 30 秒写完的才是可持续的
- 变少 > 变多 — 90 天未更新的条目标记陈旧，合并或删除
- 文件名即索引 — 看到
2026-04-30_fix_backpressure-boundary.md就知道内容
Q: 它和 CLAUDE.md / MEMORY.md 有什么区别？
CLAUDE.md：项目级架构约束MEMORY.md：跨会话上下文（你是谁、偏好什么）coding-wisdom：跨项目的个人工程判断增长引擎 — 跟着你走，不跟项目走
Q: inbox 会堆满噪音吗？
触发器只命中 5 种认知裂缝事件。high tier 不过期，low tier 7 天自动消失。
Q: 能不能自动蒸馏？
蒸馏是从"项目具体细节"到"任何系统都适用的原则"——这步需要你的判断力介入。agent 可以帮你补泛化和联网校准，但最终是你决定什么值得保留。
一个人对"好判断力"的定义永远是窄的。 你的使用习惯、蒸馏角度、发现的边界情况——都能让这个 skill 变得更好。
几条具体的贡献路径：
你的位置 你可以做什么
──────── ────────────
用了一段时间，有反馈 → 提 Issue：什么场景捕获太多/太少、什么规则让你烦
发现 bug 或有功能想法 → 提 Issue 或直接开 PR
改了捕获规则/噪音过滤 → PR 到 SKILL.md
写了新的 guide 或改进现有 guide → PR 到 guides/
改进了模板 → PR 到 templates/
写了跨平台脚本 → PR 到 scripts/
翻译 README → PR，新文件 README.zh-CN.md 这种格式
Issue 和 PR 都欢迎。 不确定该走哪条路？先开 Issue 聊聊。
MIT