---
title: "Discussion on \"The reasoning behind a codebase, as a web you can walk\" | Hashnode"
description: "Discussion on \"The reasoning behind a codebase, as a web you can walk\". Decisions that cite each other across repositories — no graph database, no central index, no account. Just Markdown and Git."
url: "https://hashnode.com/posts/the-reasoning-behind-a-codebase-as-a-web-you-can-walk/6abc0e2fcbb7082b897b890a"
---

[Feed](https://hashnode.com/feed) /

Discussion

# [The reasoning behind a codebase, as a web you can walk](https://blog.technopathy.club/the-reasoning-behind-a-codebase-as-a-web-you-can-walk?utm_source=hashnode&utm_medium=feed)

Decisions that cite each other across repositories — no graph database, no central index, no account. Just Markdown and Git.

Sep 29 · 9 min read · blog.technopathy.club  
Updated Oct 5  
Read the article

-   [#ai](https://hashnode.com/tag/ai)
-   [#agents](https://hashnode.com/tag/agents)
-   [#git](https://hashnode.com/tag/git)
-   [#documentation](https://hashnode.com/tag/documentation)
-   [#developer-tools](https://hashnode.com/tag/developer-tools)
-   [#opensource](https://hashnode.com/tag/opensource)
-   [#keepthewhy](https://hashnode.com/tag/keepthewhy)
-   [#project-memory](https://hashnode.com/tag/project-memory)
-   [#claude-code](https://hashnode.com/tag/claude-code)
-   [#ai-agents](https://hashnode.com/tag/ai-agents)
-   [#ai-tools](https://hashnode.com/tag/ai-tools)

## Written by

[Oliver Zehentleitner](https://hashnode.com/@oliver-zehentleitner)

@oliver-zehentleitner · Vienna, Austria

  
[View profile](https://hashnode.com/@oliver-zehentleitner)

DevSecOps · Python · AI-driven Development · Real-world findings from production systems.

I build systems that work — technically sound, security-first, and actually useful to the people who depend on them. Creator of the UNICORN Binance Suite — six open-source Python libraries with 3.3M+ downloads and 390+ dependent public projects — and Keep the Why, an open-source agent skill that preserves the reasoning behind engineering decisions alongside the code. Currently pioneering AI-driven open-source maintenance: running a controlled AI agent that maintains production code and documenting what this shift means for engineering teams. Vienna, Austria 🇦🇹

## Responses 4

Markdown supported · ⌘↵ to post

[Julian Neagu](https://hashnode.com/@julianneagulab)

[Oct 1](https://hashnode.com/posts/the-reasoning-behind-a-codebase-as-a-web-you-can-walk/6abc0e2fcbb7082b897b890a/comment/6abe2bd955a97e59fb18e222)

I like the idea of letting the links create the graph instead of maintaining a graph itself. Git already has most of the pieces, you’re just making the reasoning easier to follow.

[Oliver Zehentleitner](https://hashnode.com/@oliver-zehentleitner)

[Oct 1](https://hashnode.com/posts/the-reasoning-behind-a-codebase-as-a-web-you-can-walk/6abc0e2fcbb7082b897b890a/comment/6abe2bd955a97e59fb18e222#reply-6abe55d2210e9e4d555d63de)

A global graph with registered repositories ^^: [https://keepthewhy.com/dashboard/live/#globe](https://keepthewhy.com/dashboard/live/#globe)

[Kartik N V J K](https://hashnode.com/@kartik-nvj)

[Sep 30](https://hashnode.com/posts/the-reasoning-behind-a-codebase-as-a-web-you-can-walk/6abc0e2fcbb7082b897b890a/comment/6abd569661c50d763ed9b2b8)

Storing the "why" as Markdown plus a UUID in Git is a clever move, it keeps the decision next to the code and survives the people who made it. The live citation graph is the part I'd worry about maintaining, a decision web is only trustworthy if it decays when the code does. Have you found a way to flag stale reasoning nodes when the underlying code changes out from under them?

[Oliver Zehentleitner](https://hashnode.com/@oliver-zehentleitner)

[Oct 1](https://hashnode.com/posts/the-reasoning-behind-a-codebase-as-a-web-you-can-walk/6abc0e2fcbb7082b897b890a/comment/6abd569661c50d763ed9b2b8#reply-6abdf8a793f62310a4a44556)

Yes, and this is exactly where I think the agent itself has to remain the brain. Keep the Why does not try to infer semantic staleness on its own. A code diff is not enough for that anyway. A decision can survive a complete rewrite, while a tiny configuration change can invalidate it.

KTW gives the agent lifecycle signals instead: Revisit when, evidence, verification, needs-review, supersession, and the surrounding rationale. When the agent works on the project again, it has to reason over those signals and the current codebase. If something no longer fits, it can flag the entry, revise it, or supersede it.

The graph helps with visibility. If one rationale entry becomes questionable, it can show the later entries linked to it and where they live. But it does not claim that they are automatically invalid.

I think that separation is important: Keep the Why stores and connects the reasoning. The agent interprets it.