AI-Native_Codebases_-_GIDS.pdf

Transcript

1. AI-Native Codebases Ragunath Jawahar, Founder Legacy Code Labs • legacycode.com
2. 2019 2017
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. What is an AI-Native codebase?
9. An AI-Native codebase is one engineered around coding agents as its primary contributors.
10. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
11. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
12. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
13. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
14. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
15. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
16. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
17. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
18. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
19. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
20. ⚠ These are not levels. They are modes of operation. Where you operate depends on your goals, your organization's goals and available resources.
21. Steve Yegge’s Evolution of the Programmer in 2024–2026 Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
22. Agents x Single Codebase
23. Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
24. 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
25. Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
26. 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
27. 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
28. Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
29. 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
30. 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
31. 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
32. Agents x Multiple Codebases
33. Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
34. 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
35. 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
36. Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
37. 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
38. 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
39. Source: h tt ps://steve-yegge.medium.com/welcome-to-gas-town-4f25ee16dd04
40. 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
41. 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
42. What We Can Talk About: The Foundation 1. Structure 2. Behavior 3. Veri fi cation 4. Topology
43. Structure
44. 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
45. 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
46. Structure: Dependency Graphs
47. 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, }
48. 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, }
49. 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, }
50. 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, }
51. 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, }
52. 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, }
53. types.rs
54. 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 { ... }
55. 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 { ... }
56. 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 { ... }
57. 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 { ... }
58. 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 { ... }
59. 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 { ... }
60. 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 { ... }
61. 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 { ... }
62. library_repository.rs
63. library_repository.rs
64. library_repository.rs
65. library_repository.rs
66. library_repository.rs
67. Structure: File-level Dependency Graphs
68. 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, }
69. types.rs (type-level)
70. types.rs (file-level)
71. 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 { ... }
72. library_repository.rs (type-level)
73. library_repository.rs (file-level)
74. types.rs + library_repository.rs (file-level)
75. 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, }
76. 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
77. 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
78. author.rs + book.rs + library_repository.rs
79. Type-level File-level 5 nodes, 8 edges 3 nodes (-40%), 3 edges (-62.5%)
80. 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
81. What We Can Talk About: The Foundation 1. Structure 2. Behavior 3. Veri fi cation 4. Topology
82. Case Study: Clarity Structure
83. What is Clarity?
84. 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
85. Installation Step 1: brew install LegacyCodeHQ/tap/clarity Step 2: clarity setup
86. 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
87. New Language Support?
88. dependency_graph.go type Graph struct { nodes map[string]bool edges map[string][]string }
89. Structural Problems
90. Refactored Structure
91. Rust Support
92. Case Study: Clarity Behavior + Veri fi cation
93. Behavior • Language Parsing • Dependency Resolution
94. 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
95. 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
96. Work fl ow: Verify Language Support
97. Work fl ow: Verify Language Support
98. 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.
99. Topology Composable repos using git submodules
100. Why? • Agent-agnostic con fi guration • One source of truth • Discoverability across agents
101. 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/
102. 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/
103. 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/
104. What We Can Talk About: The Foundation 1. Structure 2. Behavior 3. Veri fi cation 4. Topology
105. Wrapping up • Modes, not levels • The Pillars of AI-Native Codebases • Structure • Behavior • Veri fi cation • Topology
106. 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.
107. Questions? Ragunath Jawahar • h tt ps://legacycode.com @ragunathjawahar • Twi tt er • LinkedIn • GitHub