AI's tech debt is invisible — even to AI. I solved it at the architecture layer.

The article explains that AI-generated code accumulates a new form of invisible, systemic tech debt because AI models cannot see existing codebase patterns across sessions, leading to inconsistent architecture. The author, an open-source maintainer, solved this by creating "aming-claw," which pins a graph projection of the codebase to every commit, allowing AI to read the project's structure before writing code and alerting users when the graph becomes stale. This structural fix ensures persistent, long-term project memory rather than relying on short-lived context windows or manual hints.

TL;DR— AI repeats your patterns badly, ignores existing services, and forgets every cross-session lesson you taught it. This isn't laziness — it's a new kind of tech debt:invisible,systemic, andarchitectural. Project memory hints don't scale. Bigger context windows don't help. The fix is structural: pin a graph projection of your codebase to every commit, let AI read it before writing, surface "graph stale" prompts when source drifts. Real commit receipts from my own OSS project aming-claw inline. Architects, change my mind in the comments. What is AI tech debt? Let me define this precisely, because it's a different beast from the tech debt you already know. | Dimension | Traditional tech debt | AI tech debt | |---|---|---| | Who creates it | Engineers knowingly | AI unknowingly | | Awareness | Conscious tradeoff | AI doesn't know it's accruing | | Fix lifecycle | Fix once, done | Every new session repeats it | | Visibility | git log shows it | Invisible across sessions | | Scale | Team-bounded | Systemic, AI-generated | The core asymmetry: the more your team uses AI for coding, the more invisible debt accrues — and you have no tool that sees it. 5 symptoms diagnose yourself Run this checklist against your team: - ❌ AI re-implemented a service that already exists - ❌ AI shipped code using a pattern completely inconsistent with everything around it - ❌ AI didn't see the implementation sitting in the next file over - ❌ Every new session repeats the same mistakes you corrected last time - ❌ AI treats a familiar codebase as if it were brand new Three or more? You're accruing AI tech debt. The bigger your team and the more AI you use, the faster it compounds. A real case study: my toolboxclient stateService I'm the maintainer of toolboxclient https://github.com/amingclawdev/toolBoxClient open-source cross-platform AI agent runtime, 274+ stars . I asked AI to add a stateService . The directory server/services/ already contained, in clear sight: TOOLBOXCLIENT/server/services/ ├── fingerPrintService.js ├── memoryService.js ├── providerModelService.js ├── proxyService.js ├── taskService.js ├── toolServiceManager.js ├── walletService.js └── webSocketService.js Roughly a dozen services, all sharing the same HTTP pattern. What AI shipped commit 68487cc https://github.com/amingclawdev/toolBoxClient/commit/68487cc , 2026-03-19 : // AI's version: WebSocket-based StateClient with Proxy class StateClient { constructor agentName { // 🚨 WebSocket, not HTTP — inconsistent with every other service in the folder this.ws = new WebSocket ... this. data = {} this.state = this. createProxy } createProxy { // Proxy traps to broadcast via WebSocket return new Proxy this. data, { ... } } } It used WebSocket instead of HTTP. It used a Proxy-based intercept-and-broadcast pattern unlike anything else in the codebase. It built a parallel architecture next to an established one. This wasn't a code bug. It was a pattern bug. AI literally couldn't see the existing services. The first fix: project memory My first instinct: add a hint to project memory. use existing HTTP services, don't add WebSocket AI refactored cleanly commit bbdf82c https://github.com/amingclawdev/toolBoxClient/commit/bbdf82c , 2026-03-21 : feat: stateService Phase A+B — HTTP CRUD + SSE broadcast Phase A: /api/state/ routes read, write, session CRUD, language pref Phase B: SSE subscribe endpoint with topic filtering + EventBus broadcast 74/74 tests pass. No breaking changes — additive only. WebSocket gone. HTTP CRUD + SSE matching the existing pattern. Clean fix. For about ten seconds, I thought I'd solved it. Why project memory hints don't scale Then I realized something uncomfortable: This catch only worked because I noticed.The next AI session would start with zero memory of this lesson. Every context window starts as a blank slate. This is the systemic nature of AI tech debt: - AI can't see existing patterns when it writes - I see it → I fix it once → the fix doesn't propagate to future sessions - Manual project memory maintenance puts the work back on me, not AI - This doesn't scale — and the failure mode is silent The first insight I stopped trying to fix prompts and started looking at the structural problem: AI agents don't need bigger context windows. They need a persistent structural record of the project that survives across sessions. Context windows are short-term memory. What's missing is long-term, project-level memory — something any AI session can read before writing. This is the insight that turned into aming-claw https://github.com/amingclawdev/aming-claw . Building aming-claw and falling into the next trap The idea: give every AI session a queryable graph of the project. Files, modules, functions, patterns — all of it, machine-readable, persistent. - Scan the codebase → build a graph of all entities and relations - Expose it through an MCP server that any agent can query - AI reads the graph before writing - Graph persists across sessions I built it. It worked. Then it broke — at a higher layer. I had implemented the graph with: - Mutable nodes — agents could edit graph state directly - A patch pipeline — 5-stage mutation flow propose → validate → review → apply → snapshot - A graph editor UI — humans could also edit the graph Within a few weeks, the graph drifted from the actual code . Why? Because I had created a second source of truth : - The real source of truth was source code - But I also let the graph be directly mutated - The two sources inevitably diverged Same trap. Higher layer. The real architectural insight After hitting the same trap twice, the answer crystallized: ~~The graph is something you edit.~~ The graph is a projection of the commit. In concrete terms: Every commit can correspond to one graph git commit modifies source / hints / config ↓ system detects: HEAD ≠ graph's bound commit ↓ ⚠️ "graph stale" prompt user decides when to reconcile ↓ user-triggered fixed algorithm source + hints + config ↓ new graph snapshot ←→ new commit hash 4 key invariants | | Invariant | What it guarantees | |---|---|---| | 1 | Fixed algorithm | Same input → same graph deterministic, no randomness | | 2 | 1:1 binding | Every commit hash maps to exactly one graph snapshot | | 3 | User-triggered | Reconciliation is explicit, not a background git hook | | 4 | Stale prompt | System surfaces drift in dashboard / CLI; user triggers when ready | Why not a git hook? A reasonable question: why not auto-rebuild the graph on every commit via a git hook? Three reasons I deliberately didn't: - Reconciliation is expensive full codebase scan + algorithm - Surprise auto-builds destabilize state — user should control when state changes Batching commits before a single reconcile is often what users want The system shows a graph stale indicator in dashboard and CLI. Users reconcile when they're ready. This is a deliberate design choice, not a limitation. How modification and rollback work | Operation | Implementation | |---|---| | Modify the graph | Modify source / hints / config → trigger reconcile | | Roll back the graph | git revert → trigger reconcile | | Verify consistency | Same commit → same graph replayable | Logic lives in code. The graph is a read-only projection. How this solves AI tech debt Returning to the original problem: AI repeats patterns badly because it can't see the codebase . The architectural fix: - Every AI session starts by querying the graph via MCP - The graph records the full structure — files, functions, modules, patterns - AI sees, for example, existing HTTP service pattern in server/services/ - AI reuses the pattern instead of shipping a parallel WebSocket implementation - After AI makes changes → user commits → system flags graph as stale → user reconciles → next session sees updated patterns Cross-session knowledge transfer happens through the graph, not the prompt. This is what "solved at the architecture layer" means: it's not a smarter prompt, it's a different topology of state. Coming up: the algorithm itself This post covered why the projection model works. The next post covers how the algorithm builds the graph: - in-degree=0 entry detection - DFS 3-color marking - Tarjan SCC for cyclic clusters - 6-signal layer scoring - Cross-language fact pipeline Python + TypeScript Follow me here to catch the next one. Change my mind I claim this architectural pattern solves AI tech debt: every commit corresponds to one graph + user-triggered reconcile + stale-state prompt . Your turn. Two architectural choices: - Treat project state as a single source of truth, commit-bound - Or maintain a separate memory store that AI writes to Which is more robust? Which scales better? Where would you attack my approach? Calibrated invitation: I want senior engineers and AI infra people to push back with specifics. "What about X?" or "Have you considered Y?" lands better than "this won't work." If you've shipped something adjacent, tell me — I want to compare designs.