Decision Ledger：为 Claude Code 追踪架构决策

开发者 Dupflo 在 Hacker News 上开源了名为 Decision Ledger 的实验项目，为 Claude Code 提供三个 Agent 技能（/ledger、/ledger-audit、/ledger-report），用于在 AI 辅助编码过程中持续记录、审计并复盘架构级决策。项目目前处于早期实验阶段，尚未积累使用数据，作者本人先在自己的项目上运行并计划公开结果。

项目要解决的问题

文章将核心问题命名为「comprehension debt」——代码能跑但开发者自己已无法为其辩护的决策。作者指出，两名开发者本周交付同一功能，三周后只有一人还能解释清楚；diff 本身无法告诉我们自己是哪一个。Decision Ledger 试图在每一次结构性决策发生时，强制让 AI 助手追问一句「你为什么这样选」，并把回答沉淀下来。

三个技能的设计

三个技能以 Claude Code 标准技能形式安装到 ~/.claude/skills 下，只有 /ledger 会自动拦截结构性决策，其余两个需手动调用：

• /ledger：在结构性决策点拦截，提问一次后记录立场并继续写代码，不阻塞开发流程；
• /ledger-audit：用于在已有代码库上一次性回填历史决策；
• /ledger-report：在 commit 或 PR 时输出当前项目的「掌握度地图」。

作者用 Next.js 添加鉴权作为示例：技能会先问「session 放 httpOnly cookie 还是客户端 token」，开发者回答 cookie 更安全后，再追问「移动端 API 命中同一选择时怎么办」。若答不上来，技能仍写入 cookie 方案，但把这条决策标记为 partial。

安装与使用

项目提供三种安装路径：

• Claude Code 原生路径：通过 plugin marketplace 安装（/plugin marketplace add Dupflo/decision-ledger）；
• 跨代理路径：通过 skills.sh 目录安装（npx skills add Dupflo/decision-ledger），兼容 Codex、Cursor 等；
• 直接脚本：curl 拉取 install.sh，默认全局安装到 ~/.claude/skills。

安装完成后，需在项目 CLAUDE.md 中追加一段指示，让 Claude 在结构性决策前自动加载该技能；状态文件 .mastery/index.json 默认提交进仓库。作者提醒：若仓库公开，应避免在备注中写出具体的薄弱点位置，只命名决策本身。

局限与作者声明

作者在文中明确将项目状态标注为「early」，强调这是实验而非产品，目前没有使用数据。他在自己的项目上运行后发现 state/decay-scope 这条决策存在未解决的缺陷（半衰期按区域计算会错误地刷新邻近条目的置信度），但选择先记录而不修复，以示范「一个衡量未辩护决策的工具，必须先把自己的未辩护决策公开」。整体而言，Decision Ledger 仍是一项个人探索，尚未对社区产生实质性影响。