Keep the Why

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

Star 数
★ 163
最近更新
今天
License
MIT
主语言
Python

30 秒速览

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

这个 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)

如何安装或部署这个 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 当前 75 · 表现良好 Agent 插件 / 技能免费 ★ 163 今天 Python Codex · Claude Code
Softaworks Agent Skills 51 · 缺口较多 Agent 插件 / 技能免费 + 模型费 ★ 2.5k 6 个月前 Python Claude Code
上下文工程智能体技能集 49 · 缺口较多 Agent 插件 / 技能免费 + 模型费 ★ 18k 17 天前 Python Codex · Claude Code
Finding-Unknowns Skills 76 · 表现良好 Agent 插件 / 技能免费 ★ 339 今天 Python Claude Code · Claude.ai

FollowAgents 如何评估这个 Agent?

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

权限方面证据扎实:CI 工作流全部声明 contents: read 只读令牌并按 SHA 锁定 action 版本;linter 有专门的 PathConfinement 测试证明拒绝读取项目树之外的路径(../、绝对路径、符号链接逃逸均触发 E009),dashboard 测试同样验证符号链接和外部目录不被读取,故 least_privilege 给 3。写入确认由配置项(capture-confirmation、confirm-when-unsure)支持,但确认流程本身未在源文件中展示,给 2。数据流(纯 Markdown、无数据库无守护进程)和敏感数据处理(anonymize 测试、脚本标签转义、隐藏字符检测)有测试佐证但只覆盖 dashboard 一侧,各给 2。依赖方面 CI 中 black 按版本锁定,但 dashboard 测试中 npm 安装 jsdom@24 未锁定完整版本,且未提供 lockfile,给 2。外部影响限于仓库内文件写入和可选的 PyPI linter 安装(提供询问优先选项),给 2。回滚依赖 Git 本身和 superseded/pinned-version 机制,属合理但间接,给 2。来源归属有 git attribution、.mailmap 合并、Evidence/Source 字段和作者统计测试,给 3。

可靠稳定11 / 14 · 3.9/5

test_version.py 直接测试版本号前三段必须等于 SUPPORTED_SCHEMA 且覆盖所有 schema 门控,自洽性有硬性测试保障,给 3。核心 linter 声称仅用标准库、前端纯函数测试声称无依赖,但完整依赖清单未在提供文件中出现,给 2。失败输出有结构化错误码(E001–E301)和 GITHUB_ACTIONS 注解模式处理,测试声称'never a traceback and never a guess',但这是测试注释的自述而非独立证据,给 2。

适用触发14 / 18 · 3.9/5

面向维护者、团队和遗留项目,四种模式有覆盖,且诚实说明回顾式恢复的局限('history gives back only part'),但场景描述以叙述为主,给 2。能力边界多处明示(未列出的工具'has not been measured, not failed'、eval 有诚实的失败分析),可给 2——未给 3 是因为边界声明多指向站外链接,本仓库内不可直接核对。触发精度有明确设计:技能仅在对话匹配时激活、setup 只能由显式请求触发、hook/入口文件的加载统计(10/10、3/3)有记录但属自报,给 2。环境适配最充分:70+ agent、逐 agent 目录表、共享路径回退、Windows 路径解析的平台差异都有测试覆盖,给 3。

规范维护14 / 18 · 3.9/5

信息架构出色:'Where this fits' 表格划分 README/docs/CHANGELOG/context 各自职责,字母索引骨架有完整 lint 规则(E205/E206),给 3。安装说明覆盖 skills CLI、gh、asm、各插件市场和手动克隆回退,含陷阱说明(不要整仓克隆),给 3。命名稳定性有固定目录名要求和 pinned-version/pinned-path 校验测试,但 legacy 格式迁移仅在测试中出现,给 2。examples/ 目录和多模式走查被引用但内容未在提供文件中,给 2。已知限制有陈述(eval 注意事项、回归限制)但多在站外,给 2。MIT 许可证文件完整且与元数据一致,给 3。版本与变更日志:CHANGELOG 被链接、四段版本方案被测试锁定,但 CHANGELOG 本体未在文件中,给 2。维护责任:具名维护者、48 小时安全响应承诺、按问题一条 issue 的流程,但为单人文档化承诺,给 2。

有效结果9 / 13 · 3.5/5

输出是纯 Markdown + 索引 + 自包含 dashboard 导出(转义脚本标签有测试),可用性好但可用性声明未经执行验证,给 2。边际价值有那个 20 会话对照实验(10/10 不再重复被拒方案)佐证,实验脚本与转录声称在仓库内但未提供,属自报实验,给 2。成本收益论据(推理作为开发副产物、省 token)合理但同样依赖自报测量,给 2。

证据核验5 / 8 · 3.1/5

核心主张指向 experiments/rejected-change/ 的完整转录与评分,可追溯性设计到位但本次审查未取得实验文件本体,给 2。跨源佐证:多个注册表和安全扫描徽章被列出,但其内容未经独立验证,agent 矩阵在站外,给 2。事实与推断分离是产品自身的 schema 要求(Evidence: confirmed/inferred/unknown,E111 强制解释矛盾项),且有测试证明,但作为本仓库自评工具的意义大于对外主张的核验,给 2。

风险与缓解建议
  • 本审查为静态源码审查,未执行任何测试或 eval;所有行为声明(10/10 hook 加载率、20 会话实验)均为仓库自报,置信度低。
  • README 中大量指向 keepthewhy.com 和博客的站外链接承载关键证据(eval 数据、安装细节、安全说明),安装与采用前应在最新修订版中自行核对。
  • linter 会读取 context/ 中的 Markdown;虽然路径封闭有测试保护,但 context/ 内容由 agent 生成,仍可能被注入恶意指令,建议人工评审 context/ 的 PR 变更。
  • 安装方式之一通过 npx skills 拉取,属供应链信任决策;生产环境建议使用精确 release tag 或手动克隆 skills/keep-the-why/。
  • 发布者身份未经 FollowAgents 企业注册表验证;维护者为个人,单点维护风险需自行评估。
证据充分度:低 评估于 2026年9月28日 审查版本 baa35114726e
查看完整评分方法 →

常见问题

需要付费服务或账号吗?
不需要。存储就是仓库里的 Git 和 Markdown,无数据库、无守护进程、无账号;MIT 许可。运行代理本身的模型费用与本项目无关。
对已有仓库也能用吗?
可以,但文档明确说明有限制:git 历史、issue 和代码只能还原部分理由,维护者需补齐其余部分,需要真实投入。
在未列出的代理工具上能用吗?
技能是开放的 SKILL.md 格式,安装路径普遍可用,但"每个会话自动加载"依赖平台钩子或入口文件段,未列出的工具未经过测量,仓库欢迎带验证示例的 PR。
理由写错了怎么办?
条目有 Status 字段(active/superseded/open/needs-review/pending-confirmation)和 Evidence(confirmed/inferred/unknown),维护模式下会解决矛盾、标记被取代条目;linter 只查结构,内容真伪由人判断。
它和会话记忆是一回事吗?
不是。会话记忆记录发生了什么,项目状态记录项目在哪,本项目保存的是"为什么变成这样"这第三层,不是代理活动的转写或日志。
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

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

相关 Agents