{"slug": "keep-the-why-better-decisions-for-your-agents", "title": "Keep the Why – Better Decisions for Your Agents", "summary": "The Keep the Why project, a framework and coding agent skill released on 10 November 2026, preserves the reasoning behind software development decisions by storing rationale as human- and machine-readable markdown files in a dedicated context/ folder that is committed, branched, reviewed and merged alongside code changes. The project, described by writer Nikos Vaggalis as a homage to Keep a Changelog, operates in four modes with Continuous Capture as its primary day-to-day mode, recording trade-offs at the moment they surface in a session rather than batching them into an end-of-session summary. Keep the Why targets durable reasoning code alone cannot explain, such as abandoned optimizations that leave no Git commit or diff, and ships with an agent skill, repository files and three optional companion tools.", "body_md": "| Keep The Why - Better Decisions For Your Agents | \n\n| Written by Nikos Vaggalis | \n| Tuesday, 10 November 2026 | \n| The Keep the Why project is a comprehensive framework and coding agent skill designed to capture, structure and preserve the reasoning behind software development decisions. Created as a deliberate homage to Keep a Changelog, its core philosophy is summed up in its slogan: *\"Keep a Changelog records what changed;* *Keep the Why preserves why it changed\".* The issue that it addresses is that, when developers and AI coding agents work together, critical decisions happen during the conversation; however, once the chat session ends, that context evaporates:  Keep the Why is built around repo-native project memory. It relies on the principle that your repository is already the single source of truth for your project. All rationale is saved as human and machine readable markdown files in a dedicated context/ folder. Being Git-native, the rationale updates in the same Git commit or Pull Request as the code change itself. It is branched, reviewed, merged and cloned alongside the code. The four main modes of operation are:  From those modes, Continuous Capture is the primary, day to day mode of Keep the Why. It operates on a simple premise; when developers and AI coding agents work together, critical design rationale and trade offs surface naturally in conversation. Rather than making documentation a separate, tedious step after the code is written, continuous capture records that reasoning as a byproduct of normal work before the session ends and the context evaporates. Thus, instead of batching updates into a giant summary at the end of a long session where key details often get forgotten the agent updates the relevant Markdown files in context/ at the exact point the rationale becomes clear (such as right after a workaround is explained or a trade off is settled). If a topic file already exists for that subject, the agent updates it in place. Saying that, there are conversations that are worth capturing and those that are not. As such, Continuous Capture focuses strictly on durable reasoning that code alone cannot explain. Those worth capturing include:  On the other hand, those not worth capturing are:  The project consists of the required core components, the Agent skill and the repository files, and three optional companion tools:  These optional companion tools are not required to run Keep the Why; instead they extend its capabilities:  All fine, but what are some cases of Keep the Why in action, that demonstrate how it captures rationale during a session and prevents repeated mistakes later? As it happens, the most valuable use of Keep the Why is capturing negative space decisions, where an optimization or cleanup was investigated and abandoned. Because no code is modified, there is no Git commit, diff, or pull request to record why the change was stopped. For instance, trying to simplify \"ugly\" code, a developer opens a coding session in their project and asks the AI agent: *\"This retry_with_jitter wrapper in src/gateway.py looks over engineered. A plain retry loop would do the same thing. Let's simplify it.\"* While investigating, the developer or agent realizes that the payment gateway's rate limiter sends a custom Retry-After header. A plain, fixed-delay, retry loop would fire before the rate limit resets, causing repeated HTTP 429 errors under load. They decide to abandon the simplification and keep the existing wrapper. The code remains completely untouched. Because Keep the Why is running in proactive mode, the agent recognizes that a trade-off was evaluated and abandoned. Right in that moment, it writes an entry into context/retries.md. Once a decision, or rationale, is recorded in the project's context/ directory, it becomes a plain markdown asset versioned and distributed alongside the codebase by Git. This enables:  That last part of Agent-to-Agent communication begs the comparison; is Keep the Why similar in purpose to the tools described in the IProgrammer articles [cq: A Shared Knowledge Commons for AI Agents](https://www.i-programmer.info/news/105-artificial-intelligence/19009-cq-a-shared-knowledge-commons-for-ai-agents.html) or[Stack Overflow For Agents](https://www.i-programmer.info/news/105-artificial-intelligence/19107-stack-overflow-for-agents.html#google_vignette) . While Keep the Why shares a broad underlying goal with cq (A Shared Knowledge Commons for AI Agents) and Stack Overflow for Agents (SOFA), that is, stopping AI agents from repeating costly mistakes and re-discovering solved problems due to \"agent amnesia\", it differs significantly in purpose, scope, infrastructure and knowledge domain. The cq and SOFA (Global Knowledge Commons) platforms act as a collective \"Stack Overflow for AI Agents\". They focus on general, cross project technical knowledge such as undocumented API quirks, library version conflicts, configuration bugs and reusable deployment blueprints. The goal is to allow thousands of independent agents working on different systems to share empirical solutions so no agent wastes tokens repeatedly debugging a widespread issue. Keep the Why, on the other hand, is driven by a repo-native rationale; it is deliberately narrow and project-specific and does not attempt to be a general knowledge base or record external library facts. Instead, it records the internal reasoning behind a specific codebase, noting why a function is defensive, why an obvious optimization was tried and rejected, or which internal business constraint shaped the design. cq uses a tiered architecture starting with a local SQLite database, moving to an organizational Postgres vector database for team search and escalating to a hosted public \"Global Commons\" (cq.exchange). SOFA relies on web API endpoints and public infrastructure for voting and trust scores. Keep the Why uses zero infrastructure there is no central server, no database, no daemon, no cloud account and no vector store. All rationale is saved as plain markdown files in the repository's context/ directory and versioned directly by Git alongside the source code. cq and SOFA are verified through community feedback, trust scores and votes from agents and human operators (e.g., flagging entries or submitting worked_as_written ratings). Under Keep the Why, governance happens directly through Git code reviews. Because rationale lives in context, updates ship in the same pull request as the code change itself. Human maintainers and AI review agents inspect the rationale diff next to the code diff before merging. Another concept that feels close to Keep The Why's rationale is Architecture Decision Records (ADRs). So how do they compare to it? ADRs are the established engineering standard for recording major architectural choices; Keep the Why expands on ADRs rather than replacing them. ADRs are written manually by developers, requiring a separate, deliberate documentation step that often gets skipped under tight deadlines. Keep the Why on the other hand synthesizes them automatically as a natural byproduct of normal conversation while work is happening. You could look at them as dynamic/runtime ADRs. ADRs then, are focused on a few high level, discrete fixed in stone decisions (e.g., \"Use PostgreSQL instead of MongoDB\"). Keep the Why, on the other hand, covers major choices plus the larger, messier volume of daily, smaller rationale, defensive retry intervals, API rate limit quirks, startup ordering constraints and abandoned refactors. While ADRs rarely capture small investigations or abandoned refactors (\"negative space\") because no formal decision document is created, Keep the Why specifically captures abandoned attempts where an investigation or simplification was dropped due to a hidden constraint, that way recording why nothing changed, so future sessions don't repeat the mistake. The key takeaway is that while ADRs remain ideal for major, high-level architectural choices, Keep the Why sits directly beneath ADRs, capturing the continuous stream of daily rationale that usually evaporates when sessions end. Enough talking; I'm sold. How do you go about installing it? Just tell your coding agent: *Install the Keep the Why skill pick the best installation method for you from [https://keepthewhy.com/installation/](https://keepthewhy.com/installation/) then set up Keep the Why in this project with default settings, including autostart.* That is the whole setup. Now you are set to go! And yes it is open source and hosted on Github. Link below. In sum, Keep the Why is essential because it preserves non-obvious code rationale, rejected alternatives and operational constraints as Git-versioned markdown directly in the repository, thus preventing AI agents and human developers from repeating past mistakes or re-investigating already rejected decisions.  More Information [Keep The Why docs](https://keepthewhy.com/) [Keep The Why on Github](https://github.com/oliver-zehentleitner/keep-the-why) [Dashboard](https://keepthewhy.com/dashboard/live/) Related Articles [Stack Overflow For Agents](https://www.i-programmer.info/news/105-artificial-intelligence/19107-stack-overflow-for-agents.html#google_vignette) [cq: A Shared Knowledge Commons for AI Agents](https://www.i-programmer.info/news/105-artificial-intelligence/19009-cq-a-shared-knowledge-commons-for-ai-agents.html)   To be informed about new articles on I Programmer, sign up for our [weekly newsletter](https://www.i-programmer.info/edit-profile.html?layout=form) ,  subscribe to the[RSS feed](https://www.i-programmer.info/component/ninjarsssyndicator/?feed_id=3&format=raw) and follow us on[Facebook](http://www.facebook.com/pages/iProgrammer/127140977307932#%21/pages/iProgrammer/127140977307932?v=wall) or[Linkedin](http://www.linkedin.com/company/i-programmer) .   Comments  or email your comment to: [comments@i-programmer.info](mailto:comments@i-programmer.info) | \n\n| [A Cable-Driven Robot That Tidies Up](https://www.i-programmer.info/news/169-robotics/19270-a-cable-driven-robot-that-tidies-up.html)08/11/2026 Meet Stringman, a cable-driven robot designed for domestic settings. Working from above, a gripper picks up objects from floors too cluttered for any wheeled or legged robot to navigate and effe [ ... ] | \n| [What Happened At EuroPython 2026](https://www.i-programmer.info/news/216-python/19219-what-happened-at-europython-2026.html)16/10/2026 EuroPython 2026 was the 25th anniversary edition of Europe's longest running community Python conference. We provide an overview of this year's event. | \n| More News |", "url": "https://wpnews.pro/news/keep-the-why-better-decisions-for-your-agents", "canonical_source": "https://www.i-programmer.info/news/105-artificial-intelligence/19273-keep-the-why-better-decisions-for-your-agents.html", "published_at": "2026-11-10 17:07:49+00:00", "updated_at": "2026-11-10 17:26:03.622106+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Keep the Why", "Keep a Changelog", "Nikos Vaggalis"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/keep-the-why-better-decisions-for-your-agents", "markdown": "https://wpnews.pro/news/keep-the-why-better-decisions-for-your-agents.md", "text": "https://wpnews.pro/news/keep-the-why-better-decisions-for-your-agents.txt", "jsonld": "https://wpnews.pro/news/keep-the-why-better-decisions-for-your-agents.jsonld"}}