Keep the Why：把代码背后的理由留在仓库里

它解决什么问题

代码通常能说明“做了什么”，测试能说明“应该怎样运行”，但它们未必能解释“为什么这样做”。Keep the Why 面向这一层缺失的信息：把架构决策、被拒绝的替代方案、变通方案、事故经验和运行约束写入仓库的 context/ 目录，以普通 Markdown 保存，并随 Git 一起提交。这样，理由可以和代码同行，分支、克隆和 pull request 也能保留这部分上下文。

项目的定位不是另建一个知识库。仓库元数据显示，它不需要数据库、守护进程或账户，并采用 MIT License。其核心形态是基于 SKILL.md 的 agent skill，README 列出了 Claude Code、Codex CLI、Gemini CLI、Cursor 等代理环境。对已经把编码代理纳入日常开发的团队来说，这种设计可以减少把对话结论重新整理到 wiki、ADR 或其他系统的额外步骤。

主要功能与适合人群

README 描述了四种工作模式。持续捕获是在开发过程中记录值得保留的理由；回溯恢复则从 Git 历史、issue 和代码中重建已有项目的部分背景；知识转移访谈用于从即将离开团队的维护者处补足代码无法解释的内容；维护模式负责处理矛盾、标记已被取代的条目，并拆分过大的文件。

因此，它更适合维护长期运行代码库的个人维护者、需要多人协作的团队，以及频繁使用编码代理的项目。对于经常遇到“这个奇怪的 workaround 能不能删掉”“这个方案是不是已经试过”的团队，仓库内的理由记录可以成为代理和新贡献者的共同入口。官方 README 还给出了一个拒绝方案实验：在其描述的 20 次新代理会话中，有记录时代理找到了对应条目；不过这属于项目提供的实验结果，不应视为对所有项目的普遍保证。

采用前的限制

首先，工具不能凭空恢复已经消失的知识。官方说明明确指出，既有仓库的历史、issue 和代码只能提供部分理由，维护者仍需补充，而且这需要实际投入。持续记录也要求团队接受新的文档习惯：如果代理没有捕获关键背景，或者人类没有校正错误、过时和含糊的条目，context/ 可能变成另一批难以信任的文档。

其次，项目依赖具体代理环境和工作流。README 展示了多种代理的安装与使用方向，但本文提供的来源没有确认每个代理的功能完全一致，也没有给出统一的部署前提、最低硬件配置或性能数据。引入前应先核对目标代理的集成方式、仓库权限、分支策略以及哪些内部信息适合提交到 Git。

最后，理由与代码一起传播既是优点也是治理问题。团队需要决定敏感信息是否允许进入仓库、谁负责审阅记录，以及如何处理被取代的决策。来源未提供足以作出安全保证的审计结论，因此不能把该项目本身当作机密管理或安全控制方案。

版本与部署考虑

官方 v0.20.2 发布于 2026 年 10 月 12 日，发布说明提到现有 ADR 文件夹迁移至 context/ 的 FAQ，以及 dashboard、注册表搜索和 linter 的更新。采用时应锁定经过验证的版本，先在一个非关键仓库试运行，再明确记录目录约定、审阅流程和迁移策略。对于新项目，可以从一开始建立理由记录；对于遗留项目，则应把自动恢复结果当作草稿，由熟悉系统的维护者确认后再提交。

资料来源

• GitHub repository metadata
• Project README
• Official release
• Official project page

资料核对日期：2026-10-20