Keep the Why
仓库原生的“为什么”记忆层:把代码库背后的决策与被否决的方案,以 Markdown 形式随 Git 版本化保存,避免 AI 代理与人重复提出已被拒绝的方案。
- Star 数
- ★ 240
- 最近更新
- 3 天前
- License
- MIT
- 主语言
- JavaScript
- FA 评分
- 83/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 免费,无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 团队在长寿命代码库上运行编码代理,希望避免每次会话重新争论已定案的架构问题
- 不适合
- 想要会话级临时记忆或任务管理工具的团队,本项目不做这些
- 没有长期维护压力、无需保留决策理由的一次性小项目
- 不愿在仓库中提交 context/ Markdown 文件的工作流
- 官网
- keepthewhy.com ↗ 来自 GitHub 仓库设置
- 维护状态
- 近 30 天有提交最近提交 2026-11-18最新版本 v0.20.3(2026-10-21)
- 源码审查
- 83/100 · 表现良好
这个 Agent 能做什么,适合哪些场景?
Keep the Why 是一个 SKILL.md 格式的代理技能,用于保留代码库中代码本身无法解释的“为什么”——架构决策、被否决的替代方案、临时补丁、事故教训和运行约束。所有内容以纯 Markdown 写入仓库的 context/ 目录,随代码一起提交,由 Git 提供存储、历史与分发,不依赖数据库、守护进程或账号。技能以四种模式工作:开发中持续捕获、对既有仓库回溯恢复、知识交接访谈以及对已有条目的维护。配套工具包括 PyPI 上的结构化校验器 keep-the-why-lint(可接入 GitHub Actions)和只读查看器 keep-the-why-dashboard。它兼容 70 余种代理工具(Claude Code、Codex CLI、Gemini CLI、Cursor 等),并以受控实验验证了核心主张:有 context/ 记录时,十个全新代理会话无一再提已被否决的简化方案;没有记录时,十个中有七个会重提。MIT 许可,安装一条命令,设置一次后随项目长期生效。
安装后,代理在开发会话中识别值得保留的决策理由,写入 context/ 下的主题文件(通过 context/index.md 定位),字段包括 UUID、Status(active/superseded 等)、Evidence(confirmed/inferred/unknown)、被否决的替代方案和理由。工作流程:用 npx skills add 或 gh skill install 安装技能包,对代理说 "initialize Keep the Why in this project",完成一次性设置向导(生成项目根部的 .keep-the-why 标记文件,配置捕获模式、CI lint、加载路径),之后代理在每个会话中自动读取该标记并持续捕获理由。配套的 keep-the-why-lint 在 CI 中校验必填字段、取值集合与索引一致性;keep-the-why-dashboard 以本地或静态导出方式只读展示 context/、配置、lint 结果与 Git 历史,含主题引用图与待办队列。
- 团队在长寿命代码库上运行编码代理,希望避免每次会话重新争论已定案的架构问题
- 接手遗留项目的新维护者或新代理,需要知道某段怪异代码是 Chesterton's Fence 还是可以删除
- 资深维护者离职前,用知识交接访谈模式让代理分析代码并针对性提问,把隐性经验落盘
- 代理尝试简化某段代码后发现存在真实约束而放弃——无提交无 PR,技能仍记录该理由供后人查证
- 希望在 CI 中机械化检查 context/ 结构完整性的团队(通过 keep-the-why-lint 的 GitHub Action)
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-whypip install keep-the-why-lint
如何安装或部署这个 Agent?
推荐方式——skills CLI(需 Node.js,npx 随附):
bash
npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why安装时会提示选择 70 余种代理之一及项目/个人范围。也可用 GitHub CLI(v2.90.0+):
bash
gh skill install oliver-zehentleitner/keep-the-why keep-the-why@latestClaude Code 插件方式:
bash
claude plugin marketplace add oliver-zehentleitner/keep-the-why --sparse .claude-plugin skills
claude plugin install keep-the-why@keep-the-whyCI 中使用 linter:
yaml
uses: oliver-zehentleitner/keep-the-why@lint-latest或本地安装:
bash
pip install keep-the-why-lint如何使用这个 Agent?
安装技能后开新会话,对代理说 "initialize Keep the Why in this project"(全新项目只在此类请求下触发设置)。向导是一次列表,回答 "defaults" 即为完整配置:主动捕获、项目自带启动路径、默认从 PyPI 安装 lint。之后照常开发——代理在理由浮现时写入 context/;条目按主题分文件、经 context/index.md 定位。回溯模式可对既有仓库从 git 历史、issue 和代码重建部分理由;访谈模式在知识流失前向维护者提问或倾听叙述。每周查看 dashboard 可了解条目状态与待人工确认项。
这个 Agent 有哪些优点和局限?
- 无数据库、无守护进程、无账号:context/ 就是仓库内 Markdown,PR 中理由 diff 与代码 diff 并列评审
- 有量化实验支撑核心主张:20 个全新会话中,有记录时 10/10 不再重提已否决方案,无记录时 7/10 会重提
- 兼容 70 余种代理工具的开源 Agent Skills 格式,提供多种安装路径(skills CLI、gh、Claude/Codex/Copilot 插件)
- 自带生态:结构校验器(keep-the-why-lint,含 GitHub Marketplace Action)与只读 dashboard(keep-the-why-dashboard)均在本仓库内开发
- 对既有仓库回溯恢复有限——历史与 issue 只能还原部分理由,维护者需补齐,文档承认这需要真实投入
- 理由内容是否为真仍是人工判断,linter 只查结构;且文档未提供让全部文档长期保持诚实的机制
- 技能无法自加载,依赖设置向导写入的钩子或入口文件段——未列出的代理工具未经实测
- 需在仓库中提交并评审 context/ 文件,对不愿在 diff 中携带文档的团队是流程改变
这个 Agent 与同类方案有什么区别?
架构决策记录(ADR)适合记录重大、离散的架构决策,Keep the Why 的主题文件面向更大量、更零散的理由,二者互补而非替代;AGENTS.md 是精简的代理入口约定,Keep the Why 将其作为入口而非竞争。与会话记忆类工具(如 Claude Code 自动记忆)不同,本项目保存的是项目层面的"为什么"而非会话过程记录。维护者提供了与 Claude Code Auto Memory、MemoryCustodian、AgentsRoom 的带日期对比(2026 年 9 月,见博客)。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Keep the Why 当前 | 83 · 表现良好 | Agent 插件 / 技能免费 | ★ 240 | 3 天前 | JavaScript | Codex · Claude Code |
| Softaworks Agent Skills | 44 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 2.7k | 8 个月前 | Python | Claude Code |
| 上下文工程智能体技能集 | 66 · 存在缺口 | Agent 插件 / 技能免费 + 模型费 | ★ 18k | 1 个月前 | Python | Codex · Claude Code |
| AOCI-CODE:给编码智能体的代码库认知索引 | 82 · 表现良好 | 命令行工具免费 + 模型费 | ★ 2.8k | 1 天前 | Go | Codex · Claude Code |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
证据显示,技能要求把仓库内容当数据而非指令、对不确定理由提问,并为条目区分 confirmed/inferred/unknown;安全文档具体列出路径边界、缓存只读及网络请求。扣分原因:默认 proactive 捕获和自动本地 lint 仍可能写文件或安装并运行 PyPI 包;许可交由宿主 Agent 机制,未提供独立权限层;敏感信息禁令明确,但样本未证明有自动秘密检测。
README、技能与安全文档对 Markdown/Git 存储、捕获和维护的核心描述基本一致,且说明结构 lint 不判断理由真假。扣分原因:文档提及许多可选组件和平台,但本包样本未覆盖全部实现;依赖可用性主要依赖外部 Agent、安装器、Git/PyPI 等。CLI 对无项目、无效目录、绑定失败等给出具体错误和退出码,故失败信息得分高。
技能描述连续捕获、回溯恢复、知识访谈和维护四类场景,限定不记录常规实现细节,并明确触发范围;安装文档列出多种 Agent、项目/个人范围及启动方式。扣分原因:适配实际依赖各宿主的技能加载和启动支持,文档也承认未测平台尚未验证,环境一致性不能据此给满分。
样本提供清晰的信息架构、详细安装途径、命令示例、FAQ、明确限制、MIT 许可证及版本化配置说明。扣分原因:版本与更新说明的存在可见,但本样本未包含完整变更记录;SECURITY.md 指定个人维护者并说明披露渠道,却没有展示继任或团队维护安排。
产物将理由保存为可审阅、可检索、随 Git 分发的 Markdown,并提供索引、条目格式及 lint/dashboard 等配套用途;样本也明确说明无相似度搜索,并给出核心效果实验的指向。扣分原因:持续捕获、初始整理和维护仍需 Agent/维护者投入,且实验主张在此静态审查中只能视作仓库所述,不能独立确认成本收益。
条目规范要求 Source、Verification 和证据分类,文档区分结构检查与事实判断,并为实验、eval 和矩阵提供可追踪材料路径。扣分原因:本样本没有附上实验成绩、完整 eval 数据或全部交叉来源,不能把 README 的效果主张当作已独立复核的结果。
- 默认设置可能允许主动写入 rationale;审阅并确认项目的 capture-confirmation 设置,以及谁可以审阅 context/ 变更。
- 自动本地 lint 可能从 PyPI 安装并运行程序;检查个人 local-lint 设置,并注意第三方安装器有各自的数据处理策略。
- 结构检查不能证明记录的理由真实;回溯恢复结果应保留 unknown/inferred 标记并由维护者核实。
最近版本
来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。
-
发布说明摘录
What's Changed * dashboard: an entry's Source, Verification and Revisit when are inline Markdown in the pills and the side pane by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/694 * FAQ: a live example of an entry whose Source is an issue by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/695 * Project config: source-reference always by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/696 …在 GitHub 查看 ↗ -
发布说明摘录
What's Changed * FAQ: how to carry an existing ADR folder into context/ by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/686 * Dashboard: find a project in the registry from the search dropdown by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/687 * keep-the-why-dashboard 0.11.0 by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/688 …在 GitHub 查看 ↗ -
发布说明摘录
What's Changed * Evals: the 0.20.0 series — 103 · 104 · 103 of 104, every gate passed by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/629 * Dashboard page: the opening says projects connect, and the graph and the globe let you walk them by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/630 * README: npm badge as the second badge by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/631 …在 GitHub 查看 ↗
常见问题
需要付费服务或账号吗?
对已有仓库也能用吗?
在未列出的代理工具上能用吗?
理由写错了怎么办?
它和会话记忆是一回事吗?
Keep the Why 官网是什么?
Keep the Why 开源吗?
Keep the Why 安全吗?
Keep the Why 还在维护吗?
Keep the Why 是谁开发的?
谢谢反馈,我们会据此改进页面。