DEV Community

Marwan Chawa
Marwan Chawa

Posted on Edited on

Managing Architectural Context and Spec Drift for AI Coding Agents with Eidos

#ai #python #architecture #opensource

When a team uses AI coding agents (Claude Code, Cursor, Antigravity, Copilot, Aider, Cline, OpenCode, Codex) on a growing codebase, a few practical problems usually show up:

  1. Fragmented rules across multiple agent tools. On most teams, different engineers use different harnesses—one person uses Claude Code, another uses Cursor or Copilot, and CI runs another agent. Maintaining separate, drifting rule files (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, etc.) quickly breaks down.
  2. High token costs from unscoped context. A single monolithic instruction file works for a small project, but as a repository grows, stuffing every domain rule, container boundary, and contract into every prompt wastes tokens—or forces agents to run expensive, blind grep and file-read loops across the repo.
  3. ADRs drift from the code. Architecture Decision Records are useful when written, but over time it becomes difficult for both humans and agents to tell which decisions are still active and which parts of the codebase they govern.
  4. Unchecked boundary violations. An agent can make all existing unit tests pass while still introducing coupling across containers or breaking an architectural assumption that wasn't explicitly tested.

Eidos (eidos-ai) was built to address these problems by combining established software engineering practices into a single, opinionated workflow designed for both human engineers and AI coding agents:

  • Built for Both Humans and AI: Every specification combines machine-validated YAML frontmatter (queried by AI agents via CLI/JSON) with readable AsciiDoc narrative and an interactive web portal (explored by engineers, architects, and product/design teams).
  • Unified Business, Architecture, and Design Specs: Rather than treating backend code in isolation, Eidos links the full system across three connected layers:
    • Business & Product (DDD): Bounded domains (DOM-*), capabilities (CAP-*), personas (PER-*), and system-wide policies (POL-*).
    • Technical Architecture (Arc42 & C4): System context (SYS-*, ARCH-*), containers (CNT-*), components (CMP-*), interface contracts (CTR-*), and in-place design decisions (DEC-*).
    • UI & Design Systems: Multi-brand design systems (DS-*), W3C design tokens, UI component contracts (UIC-*), client manifests (CLT-*), screen states (SCR-*), and user flows (FLOW-*).
  • Git as the Single Source of Truth: Specifications, architecture, design systems, and code live together in the repository—not scattered across external wikis, Figma comments, or ticketing tools.
  • Multi-Tool Alignment (eidos plugin install all): Teams don't have to standardize on a single AI coding tool. Eidos installs a unified set of skills and hooks across all major agent harnesses (Claude Code, Cursor, Antigravity, Copilot, Aider, Cline, OpenCode, Codex), all querying the same underlying specification graph.
  • Lower Token Cost via Precision Context Slicing: Instead of loading massive markdown files or letting agents read dozens of files to orient themselves, Eidos serves compact, token-budgeted context slices (anchor, guardrails, or deep) and AST repo maps—giving the agent harness the exact business, architectural, or UI context it needs for a specific file or task.
  • 100% Local, Zero API Keys Required: Eidos runs entirely on your machine. Indexing, context slicing, semantic search (via local ONNX), validation, and drift detection do not call external LLMs or require any cloud API keys.
  • Opinionated Engineering Methodology:
    • Spec-Driven Development (SDD): Specifications are treated as executable schemas that co-evolve with code rather than static afterthoughts.
    • Test-Driven Development (TDD): Every capability and policy invariant (INV-*) binds directly to an automated test function (file::func).
    • Kanban Lifecycle (SpecDelta & Explorations): Architectural changes and technical spikes move through explicit lifecycle states (EXP-* explorations and DLT-* SpecDeltas from draft → proposed → verified → applied), visualized on a Kanban board in the static portal.

Eidos is also used to specify and validate itself—you can browse its own specifications in the eidos/ directory or view the generated C4 Architecture Portal.

How It Works

Instead of keeping architecture notes in external wikis or append-only ADR folders, Eidos stores specifications as AsciiDoc files with structured YAML frontmatter inside the repository (CNT-* Containers, CMP-* Components, CTR-* Contracts, CAP-* Capabilities).

                    ┌───────────────────────────────────┐
                    │   Living Specifications (eidos/)  │
                    │  CNT-* │ CMP-* │ CTR-* │ CAP/INV  │
                    └─────────────────┬─────────────────┘
                                      │
                      ┌───────────────┴───────────────┐
                      ▼ (SQLite + AST Graph)          ▼ (eidos portal)
            ┌───────────────────┐           ┌───────────────────┐
            │  AI Coding Agents │           │  Human Engineers  │
            │ (eidos context &  │           │   (C4 Explorer    │
            │   Agent Skills)   │           │  & Blast Radius)  │
            └─────────┬─────────┘           └─────────┬─────────┘
                      │                               │
                      └───────────────┬───────────────┘
                                      ▼
                    ┌───────────────────────────────────┐
                    │   Codebase & Polyglot Test Suite  │
                    │   Checked by: eidos drift / hook  │
                    └───────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

1. In-Place Decisions and SpecDelta Transitions

Rather than maintaining separate ADR files, Eidos records design decisions (DEC-*) directly inside the frontmatter of the container, component, or contract they apply to—along with the rationale and rejected alternatives.

When making larger cross-container changes, you can define a SpecDelta (DLT-*) that describes the planned architectural transition, verify it against the codebase, and apply it when the change lands.

2. Scoped Context via a Local SQLite + AST + Semantic Graph

Before modifying a file, an engineer or coding agent can query the local index (eidos/.cache/index.db). Eidos combines SQLite FTS5 BM25 search, recursive CTE graph traversal, polyglot AST symbol indexing, and optional offline Hybrid RRF semantic search (using a local quantized microsoft/harrier-oss-v1-0.6b ONNX model):

# Generate an AST-based structural outline of the repository
eidos index repo-map --max-tokens 1500

# Find a code symbol's exact file:line location and owning C4 component
eidos index find-symbol "ArchitecturalIndex" --json

# Pull a token-budgeted context slice (anchor, guardrails, or deep) for a file
eidos context -f src/eidos/core/index/builder.py

# Check upstream and downstream dependencies before modifying a component
eidos index blast-radius CNT-EIDOS-CORE --depth 2
Enter fullscreen mode Exit fullscreen mode

Instead of reading unrelated specs or grepping across the entire repo, eidos context returns only the owning container/component, relevant contracts, recorded decisions (DEC-*), and active invariants (INV-*) for that file or task—cutting down unnecessary file reads and token usage across every agent turn.

3. Linking Invariants to Automated Tests (eidos drift)

Each capability or policy invariant (INV-*) in Eidos can bind directly to a test function (file::func) across Python, TypeScript/JavaScript, Go, Rust, Java, or Kotlin:

invariants:
  - id: INV-IDX-001
    statement: "Knowledge graph synchronization must complete deterministically without network calls."
    severity: critical
    verification_method: automated-test
    test_binding: "tests/test_index.py::test_offline_deterministic_sync"
Enter fullscreen mode Exit fullscreen mode

Running eidos drift checks the working tree against the specification graph:

  • Were public symbols or contract files modified without updating the corresponding specification?
  • Does every bound test function exist and reference the invariant ID it verifies?
  • Do all YAML frontmatter schemas and x-eidos-ref links resolve cleanly?

Eidos also provides a Stop hook (eidos hook) that coding agents can run automatically at the end of a turn to catch and fix drift before finishing a task.

4. Static C4 Architecture Portal

Because the specifications are structured, eidos portal serve (or eidos portal build) generates a self-contained static web viewer from the repository without requiring a Node.js runtime:

eidos portal serve --path eidos --port 8080
Enter fullscreen mode Exit fullscreen mode

It lets you inspect C4 containers and components, view contracts and design tokens, simulate blast radius across the dependency graph, and review SpecDeltas. You can see what the output looks like on Eidos's own repo here: mchawa.github.io/eidos/portal/.

Getting Started

Eidos is distributed as a standalone Python CLI on PyPI (eidos-ai) and includes a skill bundle (eidos plugin install all) for Claude Code, Cursor, Antigravity, GitHub Copilot, Aider, Cline, OpenCode, and Codex.

# Install with uv (or pipx)
uv tool install eidos-ai

# Initialize in a repository
eidos init

# Install agent skills for your editor/CLI agent
eidos plugin install all

# Build the local index and run validation + drift checks
eidos index sync
eidos validate eidos && eidos drift
Enter fullscreen mode Exit fullscreen mode

Links & Feedback

Note: While eidos plugin install generates adapters for Cursor, Copilot, Aider, Cline, OpenCode, and Codex, the agent workflow has primarily been tested with Claude Code and Google Antigravity so far. Feedback, bug reports, and testing from users on other agent harnesses are very welcome!

Top comments (0)