1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | keep-the-why |
| 作者/维护者 | Oliver Zehentleitner |
| 来源链接 | https://github.com/oliver-zehentleitner/keep-the-why |
| 许可证 | MIT（GitHub API 获取） |
| GitHub Stars | 133（GitHub API 获取） |
| Forks | 12（GitHub API 获取） |
| 最新版本 | 0.6.4（SKILL.md front matter 获取） |
| 安装方式 | npx skills add／gh skill install／手动克隆（README 获取） |
2. 功能介绍与亮点
keep-the-why 是一个“仓库原生”的约定 + agent 技能，专门捕获代码之外、代码本身无法解释的推理过程：架构决策、被否决的替代方案、临时变通、事故复盘、运营约束。它把 Keep a Changelog（记录改了什么）和这份技能（记录为什么改）区分开来。
技能定义了四种工作模式：① 持续捕获——在正常开发对话中，agent 察觉到值得保留的推理就顺手记下来，包括“本想改却发现不该动”这种不会留下提交记录的场景；② 回溯挖掘——针对已有或遗留仓库，从代码、Git 历史、issue 中尽量还原决策脉络；③ 知识转移访谈——在维护者知识即将流失前（如离职、退休），针对代码解释不了的部分做定向提问；④ 维护——消解矛盾条目、标记已过时决策、合并重复内容。
核心原则是“绝不臆造理由”：证据分级为已确认／推断／未知三档，说不清楚就明确标注未知，而不是编造一个听起来合理的答案。文档以 Markdown 形式版本化保存在仓库内，人和 agent 都能读。
亮点：完整的 CI 校验（validate-skill、link-check 工作流）、正式的安全披露政策（SECURITY.md）、专属文档站点（keepthewhy.com），并已被 skills.sh 与 SkillsLLM（含安全核验标记）两个第三方技能目录收录。
3. 适用场景
所属分类：工程效率与代码质量
适合在做架构决策、代码评审、遗留系统交接或新人上手时，需要保留决策原因而非只记录改了什么的开发团队；也适合长期维护同一代码库、厌倦反复向 agent 解释“这里为什么这样写”的个人开发者。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——技能采用标准 SKILL.md 格式，官方文档明确列出 Claude Code，且 evals 用例标注基于 Claude Code 测试
- Codex：✅ 原生支持——官方文档明确列出 Codex CLI
- OpenClaw：❓ 未验证——已抓取材料未点名，仅笼统提及“70+ agents，使用开放 Agent Skills 格式”
- Hermes Agent：❓ 未验证——同上，未在已抓取材料中被点名
5. 推荐理由
在编码过程中自动捕获架构决策的来龙去脉，写入版本化文档供团队与后续 agent 复用，避免“问 Bob”式的知识流失与被否决方案的重复踩坑。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 4 | GitHub 133 stars、12 forks；未检索到第三方平台的具名讨论 |
| 可用性 | 9 | 一条命令安装（npx/gh CLI），文档含 references/examples/evals，最近一次提交为 2026-08-01，无付费依赖 |
| 安全性 | 9 | 纯提示词与文档管理型技能，无脚本执行、无网络外发、无需凭据；有正式 SECURITY.md 披露流程；MIT 许可证清晰；作者是有 3.3M+ 下载量开源项目（UNICORN Binance Suite）背景的独立开发者 |
综合评分：7.3（三项均值）
7. 跟同类 Skills 相比的优势
| Skill | 核心机制 | 与 keep-the-why 的差异 |
|---|---|---|
| documentation-and-adrs（addyosmani/agent-skills） | 系统化的 ADR 撰写方法论与最佳实践指南 | 教你如何写 ADR，不在对话过程中自动侦测并落笔捕获，也不含回溯挖掘与维护者访谈模式 |
| claude-mem | 本地优先的 agent 通用记忆系统，压缩上下文并跨会话检索注入 | 面向 agent 自身的通用上下文/偏好记忆，产出物是内部记忆存储；keep-the-why 专注代码库决策推理，产出物是仓库内版本化、人也能读的 Markdown 文档 |
keep-the-why 的差异化在于：只聚焦“代码解释不了的原因”这一件事，且以证据分级（已确认/推断/未知）约束 agent 不得臆造，同时提供访谈与回溯两种针对遗留项目的专门工作流。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价，已被 skills.sh 与 SkillsLLM 两个技能目录收录展示。
9. 其他补充
技能同时提供 .claude-plugin 打包方式，可作为 Claude Code 插件安装；官方文档站 keepthewhy.com 提供 llms.txt 供 agent 直接查阅项目说明。
10. 安装使用方式
- Skills CLI：
npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why - GitHub CLI（v2.90.0+）：
gh skill install oliver-zehentleitner/keep-the-why keep-the-why@latest - 手动克隆仓库后将
skills/keep-the-why目录复制进对应 agent 的 skills 目录 - 安装范围可选项目级或个人级；安装后无需重启，技能会在符合触发场景的对话中自动介入，或可直接向 agent 说明“检查一下 keep-the-why 是否适用”来手动触发
11. 注意事项
- 项目创建于 2026 年 7 月，上线时间较短，仍处于持续迭代阶段
- 依赖 agent 自身判断“什么值得记录”（技能内称为比例门控），过度捕获或捕获不足都取决于 agent 执行时的判断质量
- 目前主要由单一维护者（配合其自动化提交账号）推进，尚无外部社区贡献者