DEV Community

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

Posted on

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

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, and architectural. 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 (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
Enter fullscreen mode Exit fullscreen mode

Roughly a dozen services, all sharing the same HTTP pattern.

What AI shipped (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, { ... })
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

AI refactored cleanly (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.
Enter fullscreen mode Exit fullscreen mode

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.

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Reconciliation is expensive (full codebase scan + algorithm)
  2. Surprise auto-builds destabilize state — user should control when state changes
  3. 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:

  1. Every AI session starts by querying the graph (via MCP)
  2. The graph records the full structure — files, functions, modules, patterns
  3. AI sees, for example, existing HTTP service pattern in server/services/
  4. AI reuses the pattern instead of shipping a parallel WebSocket implementation
  5. 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.

Top comments (1)

Collapse
 
amingin_ai profile image
Aming •

Receipts: