keep-the-why

Keep the Why

Keep a Changelog records what changed. Keep the Why preserves why it changed.

Keep the Why is the why layer of repo-native project memory: your repository already holds what the project is, how it works and what changed; this is the agent skill, and the file convention it maintains, that preserve the one thing it was missing — the reasoning behind a codebase — architecture decisions, rejected alternatives, workarounds, incident learnings, operational constraints that the code alone can't explain — in the repo. That memory is plain Markdown in context/, committed with the code, so Git already provides the storage, the history and the distribution: it travels with every clone, branch and fork, and a pull request shows the reasoning diff beside the code diff. It captures that reasoning as a byproduct of working with your agent, so every later session can use it. Your agent, and every other agent that works in the repository, understands not just the code but everything around it: why it is the way it is, what was tried and rejected, which constraints the source doesn't show. So does the next person. Onboarding gets faster, legacy projects become tractable again. It works continuously as you develop, where the reasoning comes for free.

It pays off most where re-debated decisions, forgotten workarounds and departed knowledge cost the most: maintainers and teams running coding agents on long-lived codebases. Starting on an existing repository works too, within limits — history, issues and code give back only part of the why, a maintainer has to fill in the rest, and that takes real effort. It is never too late to begin, though.

The payoff, made concrete: a new hire, or an AI agent that's never touched the codebase before, doesn't have to track down whoever wrote the original code — and doesn't just repeat what was already tried and rejected. That part is measured: twenty fresh agent sessions, the same codebase, the same request to simplify a retry wrapper. Without a recorded reason, seven of ten offered the already-rejected simplification again; with one context/ entry, all ten found it and none did (the experiment, transcripts and grades). Every wrong turn the agent doesn't take is work nobody has to do and undo — it saves time, money in tokens, and nerves. The same context makes changes safer across the board — no more guessing whether an odd piece of code is a Chesterton's Fence worth keeping or just cruft nobody got around to removing — turning a legacy project back into something tractable instead of a black box only one person ever understood. "Ask Bob" stops being the fallback.

Documentation is normally extra work that happens after the code is done — reload the reasoning from memory, write it down again, file it somewhere else: a wiki, an ADR, a PR description nobody reopens. That's exactly why it so often doesn't happen. When an agent is already how you work — deciding, weighing trade-offs, explaining itself in the same conversation that produces the change — the reasoning shows up for free, as a byproduct of that conversation, not separate effort. Keep the Why's actual job is narrower than it sounds: don't let that reasoning get thrown away.

Tested with: Claude Code, opencode, Pi, Hermes, and more — see the full eval suite and the agent × model matrix for what's actually been run against what, and how.

Installable with one command on Claude Code, Codex, GitHub Copilot, Cursor, OpenClaw, Hermes Agent, Cline, OpenCode, Pi, Antigravity and 60+ more agents.

Website: https://keepthewhy.com · llms.txt for AI agents/assistants looking up this project

The problem

Important project knowledge gets created in conversation — with a teammate, or with an AI coding agent — and then evaporates once the conversation ends. The code shows what was built. It rarely shows why. Tests preserve expected behavior; they don't preserve the reasoning behind it — a project can be fully tested and still hard to maintain because nobody can explain why any of it works the way it does. Missing reasoning costs you in four concrete ways:

• Re-debate — the same architecture question gets re-litigated because nobody remembers it was already settled.
• Silent regression — someone "cleans up" a workaround that looks unnecessary, not knowing it's the fix for a bug that then comes back.
• Onboarding stall — new contributors (human or AI) don't touch code they don't understand, so progress slows out of caution.
• Repeated agent mistakes — a fresh AI session, with no memory of the last one, proposes or re-implements something already tried and rejected, because nothing on disk records that it was.

How it works

Keep the Why's agent skill is SKILL.md-based — an open, cross-agent format (Claude Code, Codex CLI, Gemini CLI, Cursor, and others). It operates in four modes:

1. Continuous capture — during normal development, the agent notices rationale worth keeping and records it alongside the code as it happens.
2. Retrospective recovery — pointed at an existing or legacy repository, the agent reconstructs what it can from git history, issues, and code, and is explicit about what it couldn't.
3. Knowledge-transfer interview — before a maintainer's knowledge becomes unavailable (leaving, retiring, changing teams), the agent analyzes the codebase first, then either asks targeted questions about exactly what the code couldn't explain, or — for someone whose knowledge is broad and tacit after many years on one system — just listens while they narrate freely and extracts the rationale from that instead.
4. Maintenance — existing rationale docs get kept current: contradictions resolved, superseded entries marked, oversized files split.

What you do: tell your agent to install it and set up the project — one sentence, for any of 70+ agents; "default settings" is a complete answer. Then work as usual. The defaults are the fully integrated setup: capture is proactive, the agent writes when the reasoning is clear and asks only when it is genuinely unsure, and the project carries its own start path, so every later session in that directory loads the skill by itself. You never have to tell it what to write down, and a project that was set up once stays set up: the start path is committed with it, so everyone who works in that directory gets the skill loaded — a new collaborator answers one short list of personal preferences the first time, and that is all. The longer version, with what that changes for pull requests and for teams: Keep the Why is not another workflow.

Works for autonomous agents too, with no human in the loop. Declare the session unattended and the agent doesn't ask into the void or drop what it found: it writes the entry and flags it pending-confirmation — recorded now, confirmed by the next person who looks.