Keep the Why: Preserve the Reasoning Behind a Codebase

What it addresses

Code usually explains what was built, while tests describe expected behavior. Neither necessarily explains why a design took its current form. Keep the Why targets that missing layer: architectural decisions, rejected alternatives, workarounds, incident learnings, and operational constraints are stored as ordinary Markdown in the repository’s context/ directory and committed with the code.

The project is not presented as a separate knowledge base. Repository metadata describes it as requiring no database, daemon, or account, and lists the MIT License. Its core format is an SKILL.md-based agent skill; the README names environments including Claude Code, Codex CLI, Gemini CLI, and Cursor. For teams already using coding agents, keeping rationale beside source can avoid moving conclusions from conversations into a separate wiki or document system.

Features and suitable users

The README describes four modes. Continuous capture records useful rationale during normal development. Retrospective recovery reconstructs what can be inferred from Git history, issues, and code. A knowledge-transfer interview helps collect information that the code cannot explain from a maintainer who may leave the team. Maintenance keeps existing entries current, resolves contradictions, marks superseded decisions, and splits oversized files.

This makes the project most relevant to maintainers of long-lived codebases, collaborative teams, and projects that regularly work with coding agents. A shared record can help answer questions such as whether an awkward workaround is intentional or whether an apparently attractive approach was already tried and rejected. The README also describes an experiment involving 20 fresh agent sessions and a rejected retry-wrapper simplification. That result is a project-reported experiment, not a general guarantee for every repository.

Limitations before adoption

The tool cannot recreate knowledge that no longer exists. The official README says that history, issues, and code reveal only part of the reasoning in an existing repository, so maintainers must fill in the rest; that takes real effort. The workflow also introduces a documentation responsibility. If important context is missed, or if humans do not correct stale, ambiguous, or incorrect entries, context/ can become another collection of documents that users do not trust.

The integration is also tied to the selected agent and workflow. The README describes installation and use across many agents, but the supplied sources do not establish that every agent has identical behavior. They also do not confirm universal deployment prerequisites, minimum hardware, or performance figures. Before adoption, teams should verify the target agent integration, repository permissions, branch policy, and which internal information may be committed to Git.

Keeping rationale beside code is useful, but it creates governance questions. Teams should define whether sensitive information may enter the repository, who reviews rationale changes, and how superseded decisions are handled. The supplied sources do not support a broad security conclusion, so Keep the Why should not be treated as a secrets-management or security-control system.

Release and deployment considerations

Official release v0.20.2 was published on October 12, 2026. Its notes mention an FAQ on moving an existing ADR folder into context/, plus dashboard, registry-search, and linter updates. A cautious rollout would pin a reviewed version, trial it in a non-critical repository, and document directory conventions, review ownership, and migration rules.

For a new project, rationale can be captured from the beginning. For a legacy project, automatically recovered material should be treated as a draft and reviewed by people who know the system before it is committed. The repository page identifies the project as unarchived, but repository activity and counts can change over time.

Sources

• GitHub repository metadata
• Project README
• Official release
• Official project page

Sources checked: 2026-10-20