Keep the Why

仓库原生的“为什么”记忆层:把代码库背后的决策与被否决的方案,以 Markdown 形式随 Git 版本化保存,避免 AI 代理与人重复提出已被拒绝的方案。

Star 数
★ 240
最近更新
3 天前
License
MIT
主语言
JavaScript

30 秒速览

运行形态
Agent 插件 / 技能命令行工具
可在哪里用
通用 · 跨平台Codex · Claude Code
费用
免费,无需付费服务
上手难度
低 · 几分钟可跑通
开始前需要
Node.js(用于 npx skills CLI)或 GitHub CLI v2.90.0+Shell / 命令行网络访问本地文件系统
典型场景
团队在长寿命代码库上运行编码代理,希望避免每次会话重新争论已定案的架构问题
不适合
  • 想要会话级临时记忆或任务管理工具的团队,本项目不做这些
  • 没有长期维护压力、无需保留决策理由的一次性小项目
  • 不愿在仓库中提交 context/ Markdown 文件的工作流
官网
keepthewhy.com ↗ 来自 GitHub 仓库设置
维护状态
近 30 天有提交最近提交 2026-11-18最新版本 v0.20.3(2026-10-21)

这个 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 历史,含主题引用图与待办队列。

  1. 团队在长寿命代码库上运行编码代理,希望避免每次会话重新争论已定案的架构问题
  2. 接手遗留项目的新维护者或新代理,需要知道某段怪异代码是 Chesterton's Fence 还是可以删除
  3. 资深维护者离职前,用知识交接访谈模式让代理分析代码并针对性提问,把隐性经验落盘
  4. 代理尝试简化某段代码后发现存在真实约束而放弃——无提交无 PR,技能仍记录该理由供后人查证
  5. 希望在 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-why
  • pip 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@latest

Claude Code 插件方式:

bash

claude plugin marketplace add oliver-zehentleitner/keep-the-why --sparse .claude-plugin skills
claude plugin install keep-the-why@keep-the-why

CI 中使用 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?

FollowAgents 源码审查 · FARS-2.1
表现良好
83/ 100 五分制 4.2 / 5
信任安全 21/29
可靠稳定 11/14
适用触发 16/18
规范维护 16/18
有效结果 12/13
证据核验 7/8
查看各维度的扣分理由
信任安全21 / 29 · 3.6/5

证据显示,技能要求把仓库内容当数据而非指令、对不确定理由提问,并为条目区分 confirmed/inferred/unknown;安全文档具体列出路径边界、缓存只读及网络请求。扣分原因:默认 proactive 捕获和自动本地 lint 仍可能写文件或安装并运行 PyPI 包;许可交由宿主 Agent 机制,未提供独立权限层;敏感信息禁令明确,但样本未证明有自动秘密检测。

可靠稳定11 / 14 · 3.9/5

README、技能与安全文档对 Markdown/Git 存储、捕获和维护的核心描述基本一致,且说明结构 lint 不判断理由真假。扣分原因:文档提及许多可选组件和平台,但本包样本未覆盖全部实现;依赖可用性主要依赖外部 Agent、安装器、Git/PyPI 等。CLI 对无项目、无效目录、绑定失败等给出具体错误和退出码,故失败信息得分高。

适用触发16 / 18 · 4.4/5

技能描述连续捕获、回溯恢复、知识访谈和维护四类场景,限定不记录常规实现细节,并明确触发范围;安装文档列出多种 Agent、项目/个人范围及启动方式。扣分原因:适配实际依赖各宿主的技能加载和启动支持,文档也承认未测平台尚未验证,环境一致性不能据此给满分。

规范维护16 / 18 · 4.4/5

样本提供清晰的信息架构、详细安装途径、命令示例、FAQ、明确限制、MIT 许可证及版本化配置说明。扣分原因:版本与更新说明的存在可见,但本样本未包含完整变更记录;SECURITY.md 指定个人维护者并说明披露渠道,却没有展示继任或团队维护安排。

有效结果12 / 13 · 4.6/5

产物将理由保存为可审阅、可检索、随 Git 分发的 Markdown,并提供索引、条目格式及 lint/dashboard 等配套用途;样本也明确说明无相似度搜索,并给出核心效果实验的指向。扣分原因:持续捕获、初始整理和维护仍需 Agent/维护者投入,且实验主张在此静态审查中只能视作仓库所述,不能独立确认成本收益。

证据核验7 / 8 · 4.4/5

条目规范要求 Source、Verification 和证据分类,文档区分结构检查与事实判断,并为实验、eval 和矩阵提供可追踪材料路径。扣分原因:本样本没有附上实验成绩、完整 eval 数据或全部交叉来源,不能把 README 的效果主张当作已独立复核的结果。

风险与缓解建议
  • 默认设置可能允许主动写入 rationale;审阅并确认项目的 capture-confirmation 设置,以及谁可以审阅 context/ 变更。
  • 自动本地 lint 可能从 PyPI 安装并运行程序;检查个人 local-lint 设置,并注意第三方安装器有各自的数据处理策略。
  • 结构检查不能证明记录的理由真实;回溯恢复结果应保留 unknown/inferred 标记并由维护者核实。
证据充分度:低 评估于 2026年11月8日 审查版本 28bfdc94abff 评估后仓库已有新提交,评分可能未覆盖最新改动
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/keep-the-why.svg?lang=zh)](https://followagents.com/zh/agents/keep-the-why)
<a href="https://followagents.com/zh/agents/keep-the-why"><img src="https://followagents.com/badge/keep-the-why.svg?lang=zh" alt="FARS 评测"></a>

最近版本

来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。

  1. v0.20.3
    发布说明摘录
    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 查看 ↗
  2. v0.20.2
    发布说明摘录
    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 查看 ↗
  3. v0.20.1
    发布说明摘录
    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 查看 ↗

常见问题

需要付费服务或账号吗?
不需要。存储就是仓库里的 Git 和 Markdown,无数据库、无守护进程、无账号;MIT 许可。运行代理本身的模型费用与本项目无关。
对已有仓库也能用吗?
可以,但文档明确说明有限制:git 历史、issue 和代码只能还原部分理由,维护者需补齐其余部分,需要真实投入。
在未列出的代理工具上能用吗?
技能是开放的 SKILL.md 格式,安装路径普遍可用,但"每个会话自动加载"依赖平台钩子或入口文件段,未列出的工具未经过测量,仓库欢迎带验证示例的 PR。
理由写错了怎么办?
条目有 Status 字段(active/superseded/open/needs-review/pending-confirmation)和 Evidence(confirmed/inferred/unknown),维护模式下会解决矛盾、标记被取代条目;linter 只查结构,内容真伪由人判断。
它和会话记忆是一回事吗?
不是。会话记忆记录发生了什么,项目状态记录项目在哪,本项目保存的是"为什么变成这样"这第三层,不是代理活动的转写或日志。
Keep the Why 官网是什么?
Keep the Why 的 GitHub 仓库填写的官网是 https://keepthewhy.com。这个链接由仓库作者设置;源码在 GitHub(oliver-zehentleitner/keep-the-why)。
Keep the Why 开源吗?
开源。源码在 GitHub(oliver-zehentleitner/keep-the-why),许可证是 MIT。
Keep the Why 安全吗?
FollowAgents 的 FARS 评审(2026年11月8日)给 Keep the Why 的“信任与安全”打了 21/29 分。评审检查的 8 项安全措施没有完全缺失的。评审之后仓库已有更新。
Keep the Why 还在维护吗?
在维护。GitHub 上最近一次提交是 2026-11-18,在最近 30 天内。最新版本是 v0.20.3(2026-10-21)。
Keep the Why 是谁开发的?
Keep the Why 由 GitHub 账号 oliver-zehentleitner 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念