DEV Community

Tấn Đạt Trần
Tấn Đạt Trần

Posted on

Why AI Coding Agents Need Knowledge Graphs and Strict TDD

#opensource

Why AI Coding Agents Need Knowledge Graphs and Strict TDD

Most AI coding agents (Claude Code, OpenAI Codex, OpenCode, DeepSeek Harness) write code fast, but they break architectures in large production codebases.

Here are the 3 biggest problems with raw agents:

  1. Blind Refactoring: The agent edits a central "hub" file without knowing that 14 downstream modules depend on it, causing silent breaking changes.
  2. False Confidence: Agents routinely hallucinate that their changes "work" without ever compiling, testing, or verifying actual behavior.
  3. Context Pollution: Multi-file modifications quickly exhaust the agent's context window, degrading reasoning quality.

To fix this, I created Supergraph — an open-source workflow and orchestration engine for AI coding agents.

What Supergraph Does

Supergraph enforces a strict 8-step engineering lifecycle on every task:

scan → analyze → plan → TDD → execute → fix → verify → review

1. Knowledge Graph & Blast Radius

Powered by Codebase Memory MCP (SQLite + ZSTD graph database) and Serena LSP, Supergraph indexes your repository locally. Before proposing a single code change, it calculates the mathematical blast radius. If you attempt to modify a high-degree hub node or bridge node, it flags the risk immediately and halts reckless edits.

2. Enforced Test-Driven Development (TDD)

Supergraph enforces a strict RED → GREEN → REFACTOR cycle:

  • RED Phase: The agent MUST write a failing test first, run it against the test suite, and record verified failing output into the system.
  • GREEN Phase: Only after failure verification is recorded does the agent gain permission to write the minimal production code needed to pass.
  • No more fake claims or untested code!

3. Multi-Agent Git Worktrees (supergraph-team)

For complex features or refactors, Supergraph schedules tasks as a Wave DAG. Each agent worker claims an isolated git worktree branch. Tasks execute in parallel without dirtying your main working tree. A verification gate checks tests and linter before merging back into main, with a live status dashboard running at http://localhost:3333.

4. Autonomous Human Browser QA (browser-agent)

Built on native Rust CDP (agent-browser, zero Playwright bloat). It bypasses anti-bot defenses using real browser profiles, captures token-efficient Accessibility Tree snapshots (@ref), and executes 5-dimension ISTQB test matrices (UI + API + database fault injection).

5. ~75% Token Compression (caveman mode)

Built-in prompt engineering and tool-result pruning strip conversational fluff while keeping code and terminal outputs technically exact, saving token costs across multi-hour sessions.

Cross-Platform Support

Supergraph runs identically across 5 agent platforms:

  • Claude Code (Marketplace / Plugin)
  • OpenAI Codex CLI
  • Google Antigravity
  • OpenCode
  • DeepSeek Harness (DSH) (Native Cordis bundle & preset)

Getting Started

Install in one command (macOS/Linux/WSL):

curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

Or on Windows PowerShell 5.1+:

irm https://raw.githubusercontent.com/datit309/supergraph/master/install.ps1 | iex
Enter fullscreen mode Exit fullscreen mode

Start your session with:

/supergraph:scan       # Ingest graph context
/supergraph:analyze    # Risk & blast radius check
/supergraph:plan       # Generate DAG plan
/supergraph:execute    # Parallel git worktrees execution
Enter fullscreen mode Exit fullscreen mode

Open Source & Contributions

Supergraph is 100% open-source under the MIT license:
⭐ GitHub Repository: https://github.com/datit309/supergraph

If you find this approach useful, please drop a Star on GitHub! Pull requests for new skills, test runners, and platform integrations are warmly welcomed.

Top comments (0)