Keep the Why
仓库原生的“为什么”记忆层:把代码库背后的决策与被否决的方案,以 Markdown 形式随 Git 版本化保存,避免 AI 代理与人重复提出已被拒绝的方案。
- Star 数
- ★ 163
- 最近更新
- 今天
- License
- MIT
- 主语言
- Python
- FA 评分
- 75/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 免费,无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 团队在长寿命代码库上运行编码代理,希望避免每次会话重新争论已定案的架构问题
- 不适合
- 想要会话级临时记忆或任务管理工具的团队,本项目不做这些
- 没有长期维护压力、无需保留决策理由的一次性小项目
- 不愿在仓库中提交 context/ Markdown 文件的工作流
- 源码审查
- 75/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)
如何安装或部署这个 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 当前 | 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?
查看各维度的扣分理由
权限方面证据扎实: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。
test_version.py 直接测试版本号前三段必须等于 SUPPORTED_SCHEMA 且覆盖所有 schema 门控,自洽性有硬性测试保障,给 3。核心 linter 声称仅用标准库、前端纯函数测试声称无依赖,但完整依赖清单未在提供文件中出现,给 2。失败输出有结构化错误码(E001–E301)和 GITHUB_ACTIONS 注解模式处理,测试声称'never a traceback and never a guess',但这是测试注释的自述而非独立证据,给 2。
面向维护者、团队和遗留项目,四种模式有覆盖,且诚实说明回顾式恢复的局限('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。
信息架构出色:'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。
输出是纯 Markdown + 索引 + 自包含 dashboard 导出(转义脚本标签有测试),可用性好但可用性声明未经执行验证,给 2。边际价值有那个 20 会话对照实验(10/10 不再重复被拒方案)佐证,实验脚本与转录声称在仓库内但未提供,属自报实验,给 2。成本收益论据(推理作为开发副产物、省 token)合理但同样依赖自报测量,给 2。
核心主张指向 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 企业注册表验证;维护者为个人,单点维护风险需自行评估。