AI Native Slides Architectural Evolution
Analyzing AI-Native Systems
GRADUATE LEVEL
UNIT 1.1
The Context Paradox
Traditional Clean
Decoupled via abstractions (Interfaces, DI)
Optimized for human "chunking"
Problem: High indirection increases token hops
AI-Native
Coupled for context (High Cohesion)
Optimized for the "Context Window"
Goal: Minimal semantic distance per prompt
The Token Wall
Why "Good" Architecture kills "Vibe" Productivity
Indirection Hell
Tracing a feature requires loading 15 tiny files. The LLM loses the 'Global State' before reaching the logic.
Boilerplate Bloat
Factories, Mappers, and DTOs consume 40% of the context window. The "actual" logic gets truncated.
Hallucinated Imports
Deep folder nesting leads the LLM to 'guess' relative paths, creating non-existent modules.
Case Study: The 10k Monolith
A fintech startup abandoned Microservices for a "Logical Monolith" to improve Cursor.ai performance. The result? A 300% increase in feature velocity, but a massive spike in technical debt.
24h Lead Time
128k Context Target
Zero Manual Docs
New Principles
01
Semantic Proximity
Keep code that changes together in the same physical file, regardless of "layer" conventions.
02
Declarative Boundaries
Use explicit schemas (Zod, Protobuf) as the only way to communicate between modules.
03
Flat is better than Nested
Reduce directory depth to minimize the path-string token overhead in the file tree.
Architecture Post Mortem Architecture Post-Mortem
Case Analysis: The Indirection Death Spiral
REF: AI-ARCH-1.1
NAME: __________________________
Scenario: "Clean Code" vs. The Agent
An enterprise team migrates their legacy Java Spring Boot application to a modern "Agentic" development environment (Cursor/Windsurf). The application follows strict SOLID principles and Hexagonal Architecture . However, the AI agent consistently fails to implement features correctly, despite the "clean" nature of the code.
File Depth: Avg 6 levels deepAvg File Size: 40 linesAbstraction: 3 Interfaces per Service
Agent Failure Rate: 72%Tokens per Feature Trace: 22k (Exceeds local window)Common Error: Circular Dependencies
1. The Cognitive Load Gap
Humans prefer many small files to reduce local complexity. Explain why this architectural pattern acts as an "anti-pattern" for an LLM with an 8k-32k token attention span.
2. Semantic Distance Analysis
In Hexagonal Architecture, the 'Domain' is isolated from 'Infrastructure'. List three ways this physical isolation creates "hallucination risk" when an AI is asked to "Add a new database field and expose it in the UI."
Risk A:
Risk B:
Risk C:
3. Redesign Proposal: Context-Optimized Architecture (COA)
Redesign the file structure for a "User Billing" module. Instead of horizontal layers (Controller, Service, Repository), propose a vertical "AI-Native" structure that minimizes token hops.
TRADITIONAL (DEEP)
📁 src
📁 main
📁 controller
📄 BillingController.java
📁 service
📄 IBillingService.java
📄 BillingServiceImpl.java
📁 model
📄 Invoice.java
AI-NATIVE (FLAT/VERTICAL)
Draw or list your proposed structure here:
4. Discussion Prompt: The "Abstaction Tax"
As a graduate architect, defend or refute the following statement: "In the era of vibe coding, code readability for humans is secondary to code compressibility for machines."
Architectural Failure Guide Teacher Facilitation Guide
Lesson 1: Analyzing AI-Native Architectures
Instructional Objectives
Differentiate between Human-Centric and AI-Centric architectural patterns.
Identify failure modes in traditional "Clean Architecture" when processed by LLMs.
Define the "Context-Optimized Architecture" (COA) paradigm.
The Hook: The "Context Wall" Exercise
Begin by showing a slide of a standard Spring Boot or React folder structure (highly nested). Ask students: "If you had to explain this whole feature to someone who could only see 5 pages of text at a time, how much time would you waste just telling them where things are?"
Key Insight:
Every level of directory nesting and every 'Interface' is a 'Token Tax'. In Vibe Coding, we want to maximize the 'Signal-to-Token' ratio.
Case Study Discussion Points
1. The Cognitive Load Gap
Why does 'Clean Code' fail agents?
Answer Guidance: Agents use Attention Mechanisms. High indirection (going from Controller → Service → Interface → Impl → Repository) forces the agent to keep 5+ file contents in memory. If those files are 100 lines each, that's fine. If they are 500 lines, the agent "forgets" the Controller's original intent by the time it reaches the Repository.
2. Semantic Proximity
The move from Horizontal to Vertical slicing.
Encourage students to discuss Feature Folders . In an AI-native world, `user-billing.ts` containing the DB schema, the API logic, and the UI component is actually *better* than having them in three separate folders, as the agent can see the "whole truth" in one shot.
Common Misconceptions
Misconception Reality "Messy code is fine for LLMs." Messy code increases token noise. LLMs need High-Density Signal , not just "anything goes." "Big context windows fix everything." Longer contexts suffer from "Lost in the Middle" phenomena. Shorter, relevant chunks are always superior.
Contextual Modularity Slides Contextual Modularity
Solving the Token-Budget Constraint
Session 02
Unit 1: Structure
The 8k Token Budget
Constraint Driven Design
📦
Input Space
User Prompt + Instructions
~1,500t
🌲
The codebase
Target Files + Context
~4,500t
🚀
Output Space
Generated Code + Thinking
~2,000t
Total Limit: 8,192 Tokens (Standard Agentic Window)
The Context-First Rule
AVOID
Micro-Files (Atomic Components)
Splitting a component into 10 tiny files creates "Context Fragmentation." The agent spends tokens just parsing the file tree and import paths.
ADOPT
Macro-Modules (High Cohesion)
Bundle logic, types, and schemas into "Logical Sovereignties." Ensure any single feature can be fully "seen" in < 5,000 tokens.
Dependency Management
The Web Effect
One `import { utils } from './common'` often pulls in the entire common folder context.
// BAD: Recursive context bloat
The Solution
Explicit individual imports
"Shell" files for global types
Zero-dependency core logic
Live Workshop
The "Context Budgeter" Challenge
You are building a "Real-time Crypto Trading Dashboard." Design a file structure where any single feature implementation (e.g., "Add New Exchange Support") requires loading exactly THREE files total.
The Context Budgeter The Context Budgeter
Design Optimization Workshop: 8k Token Ceiling
REF: VIBE-ARCH-02
BUDGET: 8192 TOKENS
CORE CHALLENGE
Objective: Zero-Fragmentation Architecture
You are architecting a "Generative Travel Planner" . When the AI agent works on a feature (e.g., "Implement Trip Cost Calculation"), it must be able to 'see' every relevant piece of logic, type definition, and validation schema without exceeding the 8,000 token limit .
Part 1: The Token Audit
Estimate the "Context Cost" (in tokens) of including the following elements in an LLM prompt. Assume standard English/Code tokenization (~4 chars per token).
200-Line Typescript File
~______ t
Full NPM `package-lock.json`
~______ t
A Recursive Directory Tree (10 deep)
~______ t
Part 2: Vertical Slicing
Traditional architecture splits the app by LAYER . You must redesign it by FEATURE DOMAIN . Propose a file structure where a single feature implementation requires only two files.
❌ Bad (Horizontal/Fragmented)
📁 src/api/trips.ts (400t)
📁 src/types/itinerary.d.ts (200t)
📁 src/components/TripCard.tsx (800t)
📁 src/hooks/usePricing.ts (300t)
📁 src/utils/currency.ts (150t)
Trace Hops: 5 Files
✅ Good (Vertical/Consolidated)
1. /features/booking/_____________________.ts
2. /features/booking/_____________________.tsx
Why is this structure more "Agent-Optimized"?
Part 3: The Dependency Pruning Strategy
Large LLMs often "hallucinate" functions when they see large utility imports. Draft a Rule of Context that you would put in a `.cursorrules` or `.clinerules` file to prevent the agent from bloating its own context.
// .cursorrules
# RULE: Context Management
2. If a file exceeds ______ tokens, you MUST ______________________
3. Never import from ________________ because it __________________
Final Reflection: The Human Cost
As you optimize the codebase for AI context windows, you might find that the code becomes harder for a human to navigate (e.g., giant files instead of clean folders). How do you balance this? Which "user" is more important in 2026: The Human Maintainer or the AI Generator?
Engineering Determinism Slides Engineering Determinism
Building Steel Bridges with Probability
Session 03
Reliability Engineering
The Stochastic Gap
PROBABILISTIC
LLM Output
"It usually works. Sometimes it hallucinates a variable. Occasionally it ignores a type constraint."
➔
DETERMINISTIC
Production Runtime
System crashes if a single null is unhandled. Types must be absolute. State must be predictable.
Bridging the Gap via Static Guardrails
Layer 1: Runtime Validation
Zod / Pydantic
Don't trust the AI's "Type" comments. Trust the code that crashes if the data is wrong at the boundary.
Schema-First Development
The agent doesn't write logic; it fills in the holes of a rigid schema you defined.
// The "Contract" for the AI
const UserSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
role: z.enum(['admin', 'user']),
age: z.number().min(18)
});
If the AI tries to pass 'guest' as role, the system refuses to even compile.
Layer 2: The Lint Loop
1
Pre-commit Hooks
No "vibe" code reaches the repo without passing `eslint` and `prettier`. Standards are machine-enforced.
2
Strict Typing
`no-explicit-any` is non-negotiable. Force the AI to solve the type puzzle, don't let it cheat.
3
Architecture Tests
Use tools like `ArchUnit` to ensure the AI doesn't cross module boundaries or create cycles.
Verification > Trust
"In vibe coding, the developer's role shifts from 'Author' to 'Editor-in-Chief' and 'Chief Safety Inspector'."
Workshop: Guardrail Setup
Refining Schema Contracts
Logic Guardrails Worksheet Logic Guardrails
Constraint-Based Engineering for Probabilistic Output
LAB: REL-03
STATUS: UNVERIFIED
The "Contract-First" Mandate
When coding with an LLM, the greatest risk is "Logical Drift" —where the AI produces code that looks correct but violates business invariants. To solve this, we define Static Constraints that the AI cannot ignore without causing a compile-time or runtime crash.
Part 1: Schema Hardening (Zod/Pydantic)
Convert the following vague natural language requirements into a Hard Schema . Ensure the AI cannot pass invalid data through this boundary.
"We need a system for handling Support Tickets. Each ticket must have a unique ID, a priority level (Low, Med, High), and an optional list of attached file URLs. The description cannot be empty."
Target Area
import { z } from 'zod';
export const TicketSchema = z.object({
// 1. Define ID constraint
// 2. Define Priority Enum
// 3. Define Description (min 1 char)
// 4. Define Optional URL list
});
Reflect:
How does this schema protect the system if the LLM decides to hallucinate a "Critical" priority level that our backend doesn't support?
Part 2: The "Linter as a Lever"
In "Vibe Coding," the Linter is your best friend. Propose two custom ESLint rules or Static Analysis checks that specifically target "AI Hallucinations."
01
Rule Name: __________________________________________
Purpose (e.g., prevents importing from the wrong module layer):
02
Rule Name: __________________________________________
Purpose (e.g., mandates JSDoc on all exported functions for better agent context):
Critical Analysis: The "Rigid Bridge" Metaphor
The lesson hook asked: "How do you build a rigid steel bridge using a material that changes shape every time you look at it?"
Based on our exploration of Schemas and Static Analysis, describe the "Steel Frame" of a modern AI-Native application. What parts of the code should NEVER be written by an AI without human verification?
1. ________________________________________________________________
2. ________________________________________________________________
3. ________________________________________________________________
Agentic Interfaces Slides Agentic Interfaces
Designing APIs for Non-Human Consumption
Session 04
Schema Architecture
The Shift in API Consumption
Human Consumer
Reads PDF/Wiki Documentation
Uses Postman to test
Interprets vague error messages
AI Agent Consumer
Reads OpenAPI / JSON Schema
Discovers via "Function Calling"
Hallucinates if schema is vague
LLM Discoverability Rules
01
The "Description" is Code
In an Agentic API, the description field in your OpenAPI spec is the most important piece of logic. It is the agent's prompt.
02
Semantic Naming
/update-p vs /update-user-profile-visibility. The latter provides context for free. Don't be concise; be descriptive.
03
Narrow Types over Strings
Use Enums and regex patterns for strings. If you leave it as type: string, the agent will hallucinate garbage data.
Anatomy of a Hallucination
A banking API has a field currency. It doesn't specify an enum.
Agent A tries: "USD"
Agent B tries: "United States Dollar"
Agent C tries: "$"
Result: 400 Bad Request. Task Failed.
// AGENT-OPTIMIZED SCHEMA
currency: {
type: "string",
enum: ["USD", "EUR", "GBP"],
description: "Must be a 3-letter
ISO 4217 currency code in
all caps."
}
Workshop: The Agentic Schema
You will design an API for a "Smart Home Robot" that allows an AI to perform complex, multi-step actions without a single human intervention.
Start Lab
Agentic Schema Lab Agentic Schema Design
Lab: Designing Interfaces for Non-Deterministic Consumers
LAB: API-04
CONSUMER: AI AGENT
SCENARIO
Project: Autonomous Warehouse Robot API
You are building the backend for a fleet of AI-driven warehouse robots. The robots use an LLM to decide which actions to take based on your API's OpenAPI specification . If your schema is vague, the robots might drop cargo or navigate into restricted zones.
Task: Redesign the `move_cargo` endpoint to be "Hallucination-Proof."
Part 1: The Description as a Prompt
Compare the two schema definitions below. Explain why the "Agent-Optimized" version reduces the likelihood of the robot moving to the wrong coordinate system.
// TRADITIONAL
endpoint: "/move"
params:
x: { type: "integer" }
y: { type: "integer" }
// AGENT-OPTIMIZED
endpoint: "/robot/execute-movement-to-coordinate"
params:
target_x: {
type: "integer",
description: "The horizontal grid index from 0-100."
}
Part 2: Multi-Step Transaction Schema
Design a JSON Schema for a transfer_inventory action. This action requires a source_bin, a destination_bin, and a priority_level. Use Enums to prevent the AI from making up bin names.
{
Why is required more important for an AI agent than for a human developer using a Swagger UI?
Part 3: Error Messages as "Feedback Loops"
When an AI agent fails to call an API correctly, it can often "self-correct" if the error message is descriptive. Redesign this error response to help an AI fix its own hallucination.
❌ Bad Error (Human-Only)
400 Bad Request: "Invalid Input"
✅ Good Error (Agent-Friendly)
"Error: Invalid 'priority' value. You provided 'urgent' but only 'standard' or 'express' are allowed. Please re-try with a valid enum value."
Reflection: The Death of the PDF?
If 99% of your API consumers are AI agents, do you still need a developer documentation website? Why or why not?
Lifecycle Maintenance Slides Lifecycle Maintenance
When the Prompt is the Source Code
Session 05
Evolutionary Strategy
The Maintenance Paradox
Traditional: Code Patching
A bug occurs. A human manually edits lines 45-52. The codebase diverges from the original intent over time.
Vibe Coding: Re-Prompting
A bug occurs. The developer updates the System Instructions or Prompt . The AI regenerates the entire module.
The Loop
Prompt -> Generate -> Validate -> Repeat
"Prompt as Source"
If the prompt generates the code, then the prompt is the Source of Truth.
Version your prompts in Git
Use `.cursorrules` as documentation
Code is a disposable artifact
Strategy
Don't fix the code. Fix the Prompt.
"Every manual edit you make to AI-generated code is a piece of technical debt that the AI will likely overwrite in the next generation cycle. Resist the urge to touch the code. "
Managing Architectural Drift
How do we prevent the AI from slowly turning our clean architecture into a bowl of spaghetti over 6 months?
Constraint Files
Keep a ARCHITECTURE.md that the agent MUST read before every task. Define what it CANNOT do.
Snapshot Testing
Test the *structure* of the code, not just the output. Ensure the file tree hasn't changed unexpectedly.
Agent-Led Refactors
Schedule periodic "Refactor Prompts" where the agent's only goal is to reduce token complexity.
The Maintenance Manifesto
"I will treat code as a fleeting manifestation of my architectural intent. I will invest my time in the logic of my prompts and the rigidity of my schemas , not the lines of my implementation."
End of Sequence
The Vibe Manifesto Worksheet The Vibe Manifesto
Final Project: Defining the Long-Term Architecture Strategy
REF: VIBE-FINAL-05
VERSION: 2026.01
The Maintenance Crossroads
In the final stage of this sequence, you must define the Governance Model for an AI-native codebase. When a feature breaks in production six months from now, your organization needs a clear protocol: Do you fix the code, or do you fix the prompt?
Part 1: Drafting the Protocol
Define the step-by-step procedure for a developer who encounters a logic error in an AI-generated component.
STEP 1:
Example: Analyze the existing Prompt and Schema for ambiguities...
STEP 2:
STEP 3:
STEP 4:
Part 2: Managing Architectural Drift
Describe three "Guardrail Documents" that should be kept in the root of the repository to ensure the AI's generations remain consistent over a multi-year project lifecycle.
Document A
Name: .rules/________________
Role: To prevent the AI from...
Document B
Name: SCHEMA_REGISTRY.md
Role: To ensure that...
Document C
Name: _____________________
Role: To define the...
Final Essay: The Prompt as the Primary Artifact
"If we treat the prompt as the source code and the code as a build artifact (like a binary), what happens to Git and traditional Pull Requests?"
Propose a new way of doing Code Review in a world where the code is 10,000 lines of AI-generated noise, but the change was only a 3-line adjustment to a system prompt. What should the senior architect actually be reviewing?
Congrats on completing "Architecting for LLMs." Remember: In the age of Vibe Coding, your architecture is only as strong as your constraints.
