Share
Embed
AI-Native Codebases
What does it take to build a codebase engineered around coding agents as first-class contributors? This talk maps the operational modes of AI-assisted development — single agent, multi-agent, and orchestrated hierarchies, across single and multiple codebases — and the four pillars that hold them up: structure, behavior, verification, and topology. Includes a deep dive into file-level dependency graphs as a modeling choice, a case study from building Clarity, and a topology pattern for composable repos using git submodules and symlinks.
Presented at GIDS 2026 on April 21.
Ragunath Jawahar
April 21, 2026
Transcript
107 slides
-
01 Mechanized Comprehension Understand software systems through tooling that extracts
structure, history, meaning, and intent from code at scale. 02 Mechanized Veri fi cation Verify software changes deterministically as they happen. 03 Mechanized Remediation Identify and resolve structural decay and technical debt through tool-assisted intervention over expensive rewrites. 04 Directed Evolution Deliberately evolve software toward new behavior through continuous, traceable, and guided transformation. -
01 Mechanized Comprehension Understand software systems through tooling that extracts
structure, history, meaning, and intent from code at scale. 02 Mechanized Veri fi cation Verify software changes deterministically as they happen. 03 Mechanized Remediation Identify and resolve structural decay and technical debt through tool-assisted intervention over expensive rewrites. 04 Directed Evolution Deliberately evolve software toward new behavior through continuous, traceable, and guided transformation. -
01 Mechanized Comprehension Understand software systems through tooling that extracts
structure, history, meaning, and intent from code at scale. 02 Mechanized Veri fi cation Verify software changes deterministically as they happen. 03 Mechanized Remediation Identify and resolve structural decay and technical debt through tool-assisted intervention over expensive rewrites. 04 Directed Evolution Deliberately evolve software toward new behavior through continuous, traceable, and guided transformation. -
01 Mechanized Comprehension Understand software systems through tooling that extracts
structure, history, meaning, and intent from code at scale. 02 Mechanized Veri fi cation Verify software changes deterministically as they happen. 03 Mechanized Remediation Identify and resolve structural decay and technical debt through tool-assisted intervention over expensive rewrites. 04 Directed Evolution Deliberately evolve software toward new behavior through continuous, traceable, and guided transformation. -
01 Mechanized Comprehension Understand software systems through tooling that extracts
structure, history, meaning, and intent from code at scale. 02 Mechanized Veri fi cation Verify software changes deterministically as they happen. 03 Mechanized Remediation Identify and resolve structural decay and technical debt through tool-assisted intervention over expensive rewrites. 04 Directed Evolution Deliberately evolve software toward new behavior through continuous, traceable, and guided transformation. -
An AI-Native codebase is one engineered around coding agents as
its primary contributors. -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
⚠ These are not levels. They are modes of operation.
Where you operate depends on your goals, your organization's goals and available resources. -
Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h
tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04 -
Single Agent x Single Codebase • Default operation mode for
most teams • Costs are predictable • Bo tt lenecks • Structure • Comprehension • Guardrails: linters, forma tt ers, tests, git hooks, etc., • Fast feedback loops -
Multiple Agents x Single Codebase (1/2) • Everything from “Single
Agent x Single Codebase” are table stakes • Parallelization • Task decomposition and sequencing • Clear boundaries so agents don't step on each other • Codebase must support multiple agents • Safety • Con fl icting changes across agents • Merge coordination -
Multiple Agents x Single Codebase (2/2) • Veri fi cation
• Multiple streams of changes need checking • Becomes a bo tt leneck, not just a step • Context switching • Tracking long-running work across agents • Resumability on failure — can another agent pick up where one left o ff ? • Costs compound • Coordination overhead • Failed runs and duplicated work -
Orchestrated Hierarchy x Single Codebase (1/2) • Everything from “Multiple
Agents x Single Codebase” are table stakes • Backlog becomes a constraint • Who de fi nes the work? • Can work be decomposed fast enough to keep agents fed? • Veri fi cation at scale • Verifying combined output of many agents on interconnected tasks • Not just "does it work" but "is this what we wanted” • Work fl ows with specialized (sub)agents -
Orchestrated Hierarchy x Single Codebase (2/2) • Organization becomes the
bo tt leneck • Decision-making speed • Ownership and accountability • Organizational readiness, not just technical readiness • Costs compound • Orchestrator consumes tokens to understand, decompose, and dispatch • Every subagent consumes tokens • Long-running tasks accumulate spend over hours or days • Failed orchestration runs are expensive -
Orchestrated Hierarchy x Single Codebase (2/2) • Organization becomes the
bo tt leneck • Decision-making speed • Ownership and accountability • Organizational readiness, not just technical readiness • Costs compound • Orchestrator consumes tokens to understand, decompose, and dispatch • Every subagent consumes tokens • Long-running tasks accumulate spend over hours or days • Failed orchestration runs are expensive -
Single Agent x Multiple Codebases (1/2) • Everything from “Single
Agent x Single Codebase” are table stakes • Coherence and topology ma tt er a lot • Agent needs to switch between repos • Costs are predictable but needs careful management • Context loading per repo • Agent spends tokens orienting itself in each codebase -
Single Agent x Multiple Codebases (2/2) • Repo topologies ma
tt er • Monorepo — shared tooling and conventions, but scale challenges • Composable (local) monorepo using git submodules — modular but complex • The topology choice a ff ects what agents can see and do -
Multiple Agents x Multiple Codebases (1/2) • Agent-per-repo or agents-across-repos
• Shared guardrails across codebases • Cross-repo feedback loops • Symlinks for agent-agnostic instructions and skills • One source of truth for agent con fi guration • Di ff erent agents expect di ff erent fi le locations • Symlinks solve this without duplication -
Multiple Agents x Multiple Codebases (2/2) • Costs multiply across
repos • Coordination overhead now spans codebases • A failure in one repo can block work in another -
Orchestrated Hierarchy x Multiple Codebases • Orchestrator must comprehend the
system of systems • Dispatching work across repos, not just across tasks • Every repo must be AI-native independently • Shared protocols for intent, structure, and veri fi cation • Costs compound at the system level • Orchestrator overhead across repos • Veri fi cation across repo boundaries • Failed runs can cascade across codebases -
The Full Picture • Moving across operational modes is not
just a technical shift • It's both a skill and an organizational issue • Shifts in how software is built, maintained, and deployed • Training and evangelism • AI costs (tokens, tooling, platforms) • Organizations must invest in infrastructure • These problems are real and vary organizations -
What We Can Talk About: The Foundation 1. Structure 2.
Behavior 3. Veri fi cation 4. Topology -
Why Structure? • Structure and behavior are both inherent to
software • We've always con fl ated the two • Structure is invisible by default • Behavior can always change — if structure allows it • AI-native codebases aggravate the issue -
Structure & Boundaries • You can't pay a tt ention
to everything • External boundaries • Internal boundaries • Layer boundaries • Feature boundaries • Extension boundaries • Understanding the boundaries is understanding the system -
types.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } -
types.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } -
types.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } -
types.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } -
types.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } -
types.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
types.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } -
library_repository.rs pub trait LibraryRepository { fn find_by_isbn(&self, isbn: &str) ->
Result<Book, RepositoryError>; fn find_by_author(&self, author: &Author) -> Result<Vec<Book>, RepositoryError>; fn save(&self, book: &Book) - > Result<(), RepositoryError>; } #[derive(Debug)] pub enum RepositoryError { . .. } pub struct PostgresLibraryRepository { ... } impl PostgresLibraryRepository { ... } -
types.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } -
author.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } book.rs -
author.rs #[derive(Debug, Clone, PartialEq, Eq)] pub struct Author { pub
id: String, pub name: String, } #[derive(Debug, Clone)] pub struct Book { pub id: String, pub title: String, pub author: Author, pub isbn: String, } book.rs -
Type-level File-level 5 nodes, 8 edges 3 nodes (-40%), 3
edges (-62.5%) -
Choosing The Right Resolution Type-level vs. File-level Dependency Graphs •
Complementary choices, not replacements • Same system, di ff erent questions and answers • File names are the native unit • Fidelity depends on fi le cohesion • Design becomes a veri fi able property • Resolution is a modeling choice, not a reduction -
What We Can Talk About: The Foundation 1. Structure 2.
Behavior 3. Veri fi cation 4. Topology -
What is Clarity? • Clarity is a software design tool
for AI-native developers and coding agents • Generates fi le-level dependency graph • Allows various levels of scoping (working directory, commits, directories, fi les, etc.,) • Supports 15 programming languages • Use Cases • View structural changes in real-time • Comprehend code • Refactor safely • Allow agents to verify their own structural changes -
Structure & Boundaries • You can't pay a tt ention
to everything • External boundaries • Internal boundaries • Layer boundaries • Feature boundaries • Extension boundaries • Understanding the boundaries is understanding the system -
How to verify Rust support? • Run tool against a
real-world codebase • Choose a repository • Select commits for veri fi cation • Run the clarity command to generate dependency graph • Visually inspect the graph for anomalies • Fix discovered bugs • Rebuild and rerun the tool to verify the fi x -
How to verify Rust support? • ⚙ Run tool against
a real-world codebase • ⚙ Choose a repository • ⚙ Select commits for veri fi cation • ⚙ Run the clarity command to generate dependency graph • 👩 Visually inspect the graph for anomalies • ⚙ Fix discovered bugs • ⚙ Rebuild and rerun the tool to verify the fi x -
SKILL.md (truncated) - - - name: verify-language-support description: End-to-end workflow
for validating language support changes in the clarity dependency graph analyzer - - - Use this workflow to validate language support end-to-end in `clarity`. ## Prepare 1. Identify the target language module under `depgraph/<language>/`. 2. Identify affected command output in `cmd/languages/` when maturity level changes. 3. Confirm current local changes with `git status - - short`. ## Validate on a Real Repository (Always Interactive) 1. Pick a representative repo for the language. 2. Clone into `/tmp`. 3. Build a review queue before rendering graphs: - Use non-merge commits only. - Use commits with `5-30` changed files. - Prioritize commits that are mostly about the target language (based on file extensions/paths). - Each selected commit should include at least a few files in the target language (minimum 3 unless unavailable). - Default queue size is 10 commits unless the user requests a different count. 4. Show the queue to the user before starting graph renders. -
Why? • Agent-agnostic con fi guration • One source of
truth • Discoverability across agents -
Directory Structure . ├── .gitmodules ├── AGENTS.md # root-level agent
instructions ├── CLAUDE.md -> AGENTS.md # symlink ├── monorepo.project # signpost │ └── arena/ ├── AGENTS.md ├── CLAUDE.md - > AGENTS.md # symlink ├── arena.project # signpost │ ├── arena-cli/ # git submodule │ ├── AGENTS.md │ ├── CLAUDE.md - > AGENTS.md # symlink │ ├── arena-cli.project # signpost │ ├── Cargo.toml │ └── src/ │ └── arena-core/ # git submodule ├── AGENTS.md ├── CLAUDE.md - > AGENTS.md # symlink ├── arena-core.project # signpost ├── Cargo.toml └── src/ -
Directory Structure (Symlinks) . ├── .gitmodules ├── AGENTS.md # root-level
agent instructions ├── CLAUDE.md -> AGENTS.md # symlink ├── monorepo.project # signpost │ └── arena/ ├── AGENTS.md ├── CLAUDE.md - > AGENTS.md # symlink ├── arena.project # signpost │ ├── arena-cli/ # git submodule │ ├── AGENTS.md │ ├── CLAUDE.md - > AGENTS.md # symlink │ ├── arena-cli.project # signpost │ ├── Cargo.toml │ └── src/ │ └── arena-core/ # git submodule ├── AGENTS.md ├── CLAUDE.md - > AGENTS.md # symlink ├── arena-core.project # signpost ├── Cargo.toml └── src/ -
Directory Structure (Signposts) . ├── .gitmodules ├── AGENTS.md # root-level
agent instructions ├── CLAUDE.md -> AGENTS.md # symlink ├── monorepo.project # signpost │ └── arena/ ├── AGENTS.md ├── CLAUDE.md - > AGENTS.md # symlink ├── arena.project # signpost │ ├── arena-cli/ # git submodule │ ├── AGENTS.md │ ├── CLAUDE.md - > AGENTS.md # symlink │ ├── arena-cli.project # signpost │ ├── Cargo.toml │ └── src/ │ └── arena-core/ # git submodule ├── AGENTS.md ├── CLAUDE.md - > AGENTS.md # symlink ├── arena-core.project # signpost ├── Cargo.toml └── src/ -
What We Can Talk About: The Foundation 1. Structure 2.
Behavior 3. Veri fi cation 4. Topology -
Wrapping up • Modes, not levels • The Pillars of
AI-Native Codebases • Structure • Behavior • Veri fi cation • Topology -
An AI-native codebase isn't a codebase with AI bolted on.
It's a codebase where structure, behavior, veri fi cation, and topology are designed so agents can contribute as fi rst- class collaborators. -
Questions? Ragunath Jawahar • h tt ps://legacycode.com @ragunathjawahar • Twi
tt er • LinkedIn • GitHub