Yongwoo Yu (me@yowu.dev) / 2026.02.26
As LLM-based code generation tools become ubiquitous, AI agents are emerging as primary developers rather than mere assistants. However, established architectural principles — SOLID, DRY, and Clean Architecture — are optimized for human cognitive models and fail to account for LLM-specific constraints such as limited context windows and hallucination tendencies. Through reverse engineering of an industrial project (Project-ST, a production e-commerce event application for a major platform), we identify and formalize five AI-Native architectural principles: (1) Blast Radius Minimization, (2) Intentional Duplication over Reference, (3) Zero-Context Principle, (4) Contract as Metadata, and (5) Spec as AI Working Memory. We further introduce prompt-based architecture governance, where AI workflow skills enforce principle adherence — a mechanism complementary to traditional static analysis. We propose five quantitative metrics for measuring principle achievement. Our case study reveals an average achievement rate of 74%, with directory isolation (95%) and intentional duplication (90%) showing high conformance, while Spec as source of truth (40%) exposes fundamental tensions between documentation and runtime coupling. We discuss conditions under which these principles apply and their tradeoffs with established software engineering wisdom.
Keywords: AI-Native Architecture, LLM-Driven Development, Software Design Principles, Architecture Governance, Prompt Engineering
The landscape of software development is undergoing a fundamental transformation. Large Language Models (LLMs) have evolved from experimental curiosities into practical code generation engines embedded in mainstream development workflows. Tools such as GitHub Copilot, Cursor, and Claude Code now participate in substantial portions of code authorship across the industry [Peng et al., 2023; Vaithilingam et al., 2022]. Early empirical studies report productivity gains ranging from 26% to 55% when developers use AI-assisted coding tools [Peng et al., 2023], and industry surveys indicate that 84% of professional developers are using or planning to use AI coding tools, with a majority (51%) using them daily [Stack Overflow, 2025; GitHub, 2023].
Yet a critical question remains largely unexamined: as AI agents assume an increasingly central role in code generation, do the architectural principles that have guided software design for decades remain appropriate? Principles such as SOLID [Martin, 2003], DRY (Don't Repeat Yourself) [Hunt and Thomas, 1999], and Clean Architecture [Martin, 2017] were formulated to manage the cognitive limitations of human developers — bounded working memory, difficulty tracing long dependency chains, and the high cost of writing and maintaining code. These principles implicitly assume a human developer who reads, comprehends, and modifies code within the constraints of human cognition.
LLM-based AI agents operate under a fundamentally different cognitive model. Their "working memory" is a fixed-size context window, typically ranging from 8K to 200K tokens, within which attention degrades for information positioned in the middle of the input [Liu et al., 2024]. They are prone to hallucination — generating plausible but incorrect code — particularly when required to reason across multiple files and abstraction layers [Ji et al., 2023]. Conversely, their marginal cost of code generation approaches zero, making strategies such as code duplication economically viable in ways that would be prohibitive for human developers.
These differences suggest that an architectural paradigm optimized for human cognition may be suboptimal — or even counterproductive — when the primary developer is an AI agent. Consider the DRY principle: eliminating code duplication reduces maintenance burden for humans who must manually propagate changes, but for an AI agent, the act of tracing shared dependencies across a codebase consumes precious context window capacity and increases the probability of hallucination. In such an environment, intentionally duplicating code to achieve module isolation may yield superior outcomes.
This paper introduces the concept of AI-Native Software Architecture — a set of design principles explicitly optimized for environments where AI agents serve as the primary code generation and modification agents. We define AI-Native Architecture as a software architecture principle system designed under the premise that AI agents are the primary agents of code generation and modification, optimizing for LLM-specific constraints including context window bounds, hallucination tendencies, and near-zero code generation cost. We derive these principles through reverse engineering of Project-ST, a production e-commerce event application developed for a major e-commerce platform using an AI-agent-centric workflow. The analysis reveals five principles that collectively prioritize context isolation, change safety, and AI-comprehensible metadata over the traditional virtues of code reuse, abstraction, and human readability.
Specifically, this paper addresses the following research questions:
These principles constitute an early-stage theoretical framework valid under the explicit preconditions stated in Section 7.1, maintaining a scope of claims proportionate to the level of evidence, and requiring validation and refinement through additional cases.
Our contributions are fourfold:
The remainder of this paper is organized as follows. Section 2 surveys background and related work across software architecture principles, AI-assisted software engineering, and LLM cognitive characteristics. Section 3 presents the five AI-Native principles with formal definitions and inter-principle dependency analysis. Section 4 describes the skill-based governance mechanism. Section 5 reports the Project-ST case study. Section 6 defines the proposed metrics. Section 7 discusses applicability conditions and tradeoffs. Section 8 addresses threats to validity. Section 9 concludes with directions for future work.
This section surveys four streams of related work that collectively frame the research gap addressed by this paper: the evolution of software architecture principles (Section 2.1), AI-assisted software engineering (Section 2.2), architecture governance and conformance checking (Section 2.3), and the cognitive characteristics of LLMs relevant to code generation (Section 2.4).
The discipline of software architecture has produced a rich body of design principles aimed at managing complexity in large-scale systems. The SOLID principles — Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion — formalized by Martin [2003] represent perhaps the most widely adopted set of object-oriented design guidelines. These principles collectively aim to produce systems that are modular, extensible, and maintainable by human development teams.
The DRY (Don't Repeat Yourself) principle, articulated by Hunt and Thomas [1999], asserts that "every piece of knowledge must have a single, unambiguous, authoritative representation within a system." DRY has become so deeply embedded in software engineering culture that code duplication is routinely flagged as a code smell [Fowler, 2018] and targeted by automated refactoring tools. The underlying economic rationale is straightforward: when humans must manually propagate changes across duplicated code, the maintenance cost scales linearly with the number of copies, and the probability of inconsistency increases.
Clean Architecture [Martin, 2017] and Hexagonal Architecture [Cockburn, 2005] extend these principles into system-level organization, prescribing concentric layers of abstraction with strict dependency rules. Domain-Driven Design (DDD) [Evans, 2003] further emphasizes bounded contexts and ubiquitous language as mechanisms for managing complexity in large domains. Bass et al. [2021] provide a comprehensive treatment of software architecture quality attributes, establishing the vocabulary of modifiability, testability, and deployability that continues to dominate architectural reasoning.
A common thread across these frameworks is their implicit optimization target: the human developer's cognitive capacity. SOLID reduces the mental burden of understanding class responsibilities. DRY ensures that a developer need only look in one place to understand a piece of logic. Clean Architecture provides a mental model for navigating system structure. These are sound principles when humans are the primary agents of code comprehension and modification.
However, the assumption that the primary consumer of architectural decisions is a human developer is increasingly challenged by the rise of AI-agent-driven development. When the entity reading, comprehending, and modifying code is an LLM with a fundamentally different cognitive profile, the optimization target shifts, and principles designed for human cognition may require re-examination.
The integration of AI into software development has progressed through three distinct phases, each representing a qualitative shift in the role of AI within the development workflow.
Phase 1: Code Completion (2020--2022). Early work focused on neural code completion, where AI models predicted the next tokens or lines of code within a developer's editor [Svyatkovskiy et al., 2020]. GitHub Copilot [Chen et al., 2021], built on the Codex model [Chen et al., 2021], exemplifies this phase. The developer remains the sole decision-maker; AI provides suggestions that the developer accepts, modifies, or rejects. Empirical evaluations demonstrated measurable productivity improvements: Peng et al. [2023] reported a 55.8% faster task completion rate in a controlled experiment, while Ziegler et al. [2022] found that developers accepted approximately 30% of Copilot suggestions.
Phase 2: Conversational Assistance (2022--2024). The advent of ChatGPT and similar conversational AI systems introduced a dialogue-based interaction model. Developers describe tasks in natural language and receive code blocks, explanations, or architectural suggestions. Vaithilingam et al. [2022] provided a nuanced perspective on this phase, finding that while AI tools accelerated initial code production, they sometimes introduced subtle bugs that required additional debugging time. In this phase, the developer retains full control over the codebase; AI assists but does not independently navigate or modify project files.
Phase 3: Autonomous Agent Development (2024--present). Most recently, the paradigm has shifted to AI as an autonomous development agent. Systems such as Devin [Cognition, 2024], SWE-Agent [Yang et al., 2024], and Claude Code [Anthropic, 2025] can independently navigate codebases, read and write files, execute shell commands, run tests, and produce complete implementations with minimal human intervention. We define this phase operationally: AI-as-primary-developer refers to a development mode in which the AI agent autonomously determines which files to read, generates or modifies code across multiple files, and executes verification steps, with the human developer serving primarily as a reviewer and architectural decision-maker rather than as the direct author of code.
This three-phase progression is significant because it represents a shift not merely in tooling but in the fundamental relationship between the developer and the codebase. In Phases 1 and 2, architectural principles need only accommodate human cognition, as the AI operates within the developer's cognitive frame. In Phase 3, the AI agent independently interprets the codebase structure, and its cognitive characteristics — not the human's — become the binding constraint on effective code generation.
Despite this trajectory, the existing literature on AI-assisted software engineering has focused predominantly on productivity metrics, code quality, and developer experience. The question of how software architecture should be designed to optimize AI agent performance remains largely unexplored. Ross et al. [2023] touched on the topic by observing that AI agents perform better on well-structured codebases, but did not propose specific architectural principles. This gap — between the recognition that AI agents are becoming primary developers and the formulation of architectural principles suited to their characteristics — is the central motivation of this paper.
Architecture governance encompasses the processes and tools that ensure implemented systems conform to intended architectural designs. The fundamental challenge is bridging the gap between architectural intent (as expressed in design documents, decisions, and conventions) and implemented reality (as manifested in source code). Traditional approaches address this gap through static analysis tools that encode architectural rules as structural constraints.
Knodel and Popescu [2007] provided a comprehensive comparison of static architecture compliance checking approaches, identifying three primary mechanisms: (1) reflexion models, which compare a high-level architectural model against extracted source-code dependencies; (2) dependency structure matrices (DSMs), which visualize and constrain module-level coupling; and (3) architectural constraint languages, which allow architects to declare prohibited or required dependency patterns.
Tools such as ArchLint [Terra et al., 2015], SAVE [Knodel et al., 2006], and Sonargraph implement these mechanisms as automated checks integrated into build pipelines. They detect violations such as unauthorized layer crossings, cyclic dependencies, and interface bypasses. While effective for structural constraints, these tools share three fundamental limitations in the context of AI-driven development:
First, they operate exclusively on produced artifacts — they can verify that generated code conforms to structural rules but cannot influence the generation process itself. When a human developer writes code, the feedback loop between static analysis warnings and code modification is mediated by human comprehension. When an AI agent generates code, this feedback loop is either absent (the agent does not read linter output) or requires an additional orchestration layer.
Second, traditional governance tools encode rules at the code-structural level (module dependencies, class hierarchies, package boundaries) and cannot express behavioral or intentional constraints such as "read the specification file before modifying this module" or "limit your changes to the target directory." These process-level constraints are precisely the type of governance most relevant to AI agents.
Third, static analysis tools assume a stable architectural model against which code is checked. In AI-driven development, where the AI agent may rapidly generate and restructure code, the architectural model itself may need to be communicated to the agent as part of its operating context rather than enforced post-hoc.
The emergence of AI-driven development thus introduces a new dimension to architecture governance. When an AI agent generates code, it operates within the behavioral boundaries defined by its prompt, system instructions, and workflow definitions. This observation suggests a novel governance mechanism: encoding architectural constraints not in static analysis rules but in the natural language directives that guide AI agent behavior. We term this approach prompt-based architecture governance and develop it in Section 4.
Prompt-based governance is not a replacement for static analysis but a complementary layer operating at a different point in the development lifecycle. Static analysis verifies structural properties of the produced artifact (post-hoc verification); prompt-based governance constrains the generative process itself (in-process control). This distinction parallels the difference between quality inspection (testing finished products) and process control (constraining how products are manufactured) in manufacturing engineering. The combination of both layers — prompt-based governance to guide generation and static analysis to verify output — provides a more comprehensive governance framework for AI-driven development environments.
Understanding why traditional architectural principles may be suboptimal for AI agents requires an examination of the cognitive characteristics of LLMs that are relevant to code generation tasks.
Context Window as Working Memory. LLMs process input within a fixed-size context window, analogous to — but fundamentally different from — human working memory. Current models support context windows ranging from 8K tokens (earlier GPT-3.5 variants) to 200K tokens (e.g., Claude 3, GPT-4 Turbo) and beyond. However, effective utilization of this window is not uniform. Liu et al. [2024] demonstrated the "Lost in the Middle" phenomenon: LLMs exhibit significantly degraded performance when relevant information is positioned in the middle of long contexts, with a U-shaped attention curve favoring information at the beginning and end. This finding has direct implications for software architecture: a codebase structure that requires the AI agent to load many files into its context window risks placing critical information in the degraded attention zone.
Hallucination in Code Generation. Hallucination — the generation of plausible but factually incorrect output — is a well-documented limitation of LLMs [Ji et al., 2023]. In code generation, hallucination manifests as references to non-existent APIs, incorrect parameter types, or fabricated library functions. The probability of hallucination increases with the complexity of the reasoning required [Huang et al., 2023], which suggests that architectural structures requiring cross-file reasoning (deep inheritance hierarchies, complex dependency injection graphs) may elevate hallucination risk.
Near-Zero Marginal Cost of Code Generation. Unlike human developers, for whom writing code is a time-intensive activity, LLMs generate code at near-zero marginal cost. This economic shift inverts traditional cost-benefit analyses. Under DRY, the cost of duplication (manual propagation of changes) exceeds the cost of abstraction (creating and maintaining shared code). When an AI agent can regenerate duplicated code on demand, the cost of duplication drops dramatically, while the cost of abstraction (loading shared dependencies into context, tracing cross-file references) remains constant or increases. This inversion creates conditions under which intentional duplication becomes economically rational.
Sensitivity to Prompt Structure. LLM performance is highly sensitive to the structure and content of input prompts [Wei et al., 2022; Brown et al., 2020]. Well-structured, explicit instructions with clear boundaries produce significantly better outputs than ambiguous or implicit specifications. This sensitivity has architectural implications: codebases that provide explicit, self-contained specifications (rather than relying on implicit conventions distributed across files) are more conducive to high-quality AI code generation.
These four characteristics — bounded context windows with non-uniform attention, hallucination tendencies, near-zero generation cost, and prompt sensitivity — collectively define the "cognitive model" of LLM-based development agents. The five AI-Native architectural principles presented in Section 3 are each motivated by one or more of these characteristics, as summarized in Table 1 of that section.
This section presents the five AI-Native architectural principles derived from our analysis of the Project-ST project and grounded in the LLM cognitive characteristics described in Section 2.4. We present each principle with a formal definition comprising four elements: (1) a statement of purpose, (2) an invariant condition that the principle seeks to maintain, (3) the LLM characteristics that motivate the principle, and (4) the tradeoff with established software engineering principles.
The principles are numbered 1 through 5 in the order of presentation, chosen for pedagogical clarity: we begin with Blast Radius Minimization, the most intuitive and empirically validated principle (95% achievement in our case study), and proceed toward Spec as AI Working Memory, the most aspirational principle with the lowest observed achievement (40%). This ordering allows the reader to build confidence in the framework through well-evidenced principles before engaging with more speculative ones. We adopt this presentation-order numbering throughout the paper; readers should note that this numbering reflects expository sequence, not priority ranking.
Table 1. Mapping of LLM Cognitive Characteristics to AI-Native Principles
| LLM Characteristic | Motivated Principles |
|---|---|
| Bounded context window | Blast Radius Minimization, Zero-Context Principle |
| Non-uniform attention (Lost in the Middle) | Zero-Context Principle, Spec as AI Working Memory |
| Hallucination tendency | Blast Radius Minimization, Intentional Duplication, Contract as Metadata |
| Near-zero generation cost | Intentional Duplication over Reference |
| Prompt sensitivity | Contract as Metadata, Spec as AI Working Memory |
Purpose. Ensure that any single code modification affects the smallest possible scope within the system, ideally confined to a single directory.
Invariant. For any change task T targeting feature F, the set of files modified to complete T should be contained within a single directory D(F), such that |affected_directories(T)| = 1.
Motivation. This principle is motivated primarily by the bounded context window and hallucination characteristics of LLMs. When a code change requires modifications across multiple directories or modules, the AI agent must load files from each affected location into its context window. Each additional file increases the total token count, reduces the proportion of context devoted to the primary task, and elevates the probability of hallucination due to cross-file reasoning. By constraining the blast radius to a single directory, the principle minimizes the context required for any given change and thereby reduces the opportunity for errors.
Formal definition. Let C be a codebase organized into directories D = {d_1, d_2, ..., d_n}. For a change task T, define blast_radius(T) = |{d in D : files_modified(T) intersect files(d) != empty}|. The Blast Radius Minimization principle requires that the architecture be designed such that, for the expected set of change tasks, E[blast_radius(T)] approaches 1.
Tradeoff with established principles. Blast Radius Minimization is broadly compatible with the Single Responsibility Principle (SRP) and the bounded context concept from Domain-Driven Design, but it operates at a different granularity. SRP prescribes that a class should have only one reason to change; Blast Radius Minimization prescribes that a change should affect only one directory. The distinction is significant: SRP is a design-time principle about class decomposition, while Blast Radius Minimization is an architecture-time principle about directory organization. In practice, achieving a blast radius of one directory often requires co-locating files that SRP might place in separate packages (e.g., a route handler, its service logic, and its data access layer within a single feature directory rather than in separate layers). The distinction from Vertical Slice Architecture [Bogard, 2018] should also be clarified: vertical slice is a feature-unit decomposition that cuts across UI-business-data layers, targeting human developers' comprehension of features. Blast Radius Minimization targets the optimization of AI agents' context windows and imposes constraints extending to the physical directory structure, thereby demanding a stronger degree of isolation.
Relationship to other principles. Blast Radius Minimization is the foundational principle from which the others derive much of their motivation. Intentional Duplication (Principle 2) is the primary mechanism by which blast radius containment is achieved — shared dependencies are duplicated into each feature directory to eliminate cross-directory coupling. Zero-Context (Principle 3) is an emergent property that becomes achievable when blast radius is successfully minimized.
Achievement in Project-ST. In our case study, 95% of change tasks could be completed by modifying files within a single API or page directory. The 5% of tasks that exceeded a single-directory blast radius involved cross-cutting concerns such as shared authentication middleware and global configuration changes. (Detailed measurement procedure in Section 5.3.)
Purpose. When isolation between modules is required, prefer duplicating shared code into each module over maintaining a single shared reference, accepting the DRY violation as a deliberate architectural choice.
Invariant. For any shared utility or library function U used by modules M_1, M_2, ..., M_k, if the modification of U in the context of M_i should not affect M_j (where i != j), then each module should contain its own copy U_i that can evolve independently.
Motivation. This principle directly addresses the near-zero marginal cost of code generation and the bounded context window characteristics of LLMs. The traditional DRY principle is predicated on the economic assumption that the cost of writing code is high relative to the cost of maintaining references. When AI agents generate code at near-zero marginal cost, this assumption is inverted. Furthermore, shared references impose a context-loading burden: to understand or modify code that references a shared utility, the AI agent must locate and load the shared file, understand its interface and behavior, and reason about the implications of any changes on all consumers. Each of these steps consumes context window capacity and introduces hallucination risk.
Formal definition. Let U be a code unit (function, class, or module) referenced by modules M_1, ..., M_k. Define the coupling cost of shared reference as C_ref(U) = sum over i of context_load_cost(U, M_i) + hallucination_risk(cross_file_reasoning). Define the duplication cost as C_dup(U) = k * sync_cost(U) + k * storage_cost(U). The Intentional Duplication principle recommends duplication when C_dup(U) < C_ref(U), which holds when (a) sync_cost is low (AI can regenerate), (b) k is moderate (not hundreds of copies), and (c) cross_file_reasoning cost is high (LLM context constraints).
Tradeoff with established principles. This principle stands in direct opposition to DRY, one of the most deeply held tenets of software engineering. The resolution lies in recognizing that DRY and Intentional Duplication optimize for different cost functions. DRY minimizes the human cost of change propagation; Intentional Duplication minimizes the AI cost of context loading and cross-file reasoning. Neither is universally superior — the optimal choice depends on whether the primary developer is a human or an AI agent. We note that this tradeoff has a temporal dimension: as LLM context windows expand and hallucination rates decrease, the balance may shift back toward shared references. The principle should therefore be understood as conditional on the current state of LLM capabilities.
Boundary conditions. Intentional Duplication is not a blanket endorsement of all code duplication. Three constraints bound its applicability. First, it applies specifically to utility code that serves module isolation, not to domain logic that should be authoritative. Second, the principle has a scale threshold: when k (the number of copies) reaches the order of hundreds, the cumulative synchronization burden may exceed the context-loading cost of a shared reference. Third, duplication of security-critical code is prohibited in principle, as inconsistencies between copies may introduce vulnerabilities that are harder to audit.
We concretize these three constraints by presenting Table 1-1, which specifies the duplication eligibility and recommended synchronization cadence for each code type.
Table 1-1. Duplication Decision Criteria: Eligibility and Recommended Synchronization Cadence by Code Type
| Code Type | Duplication Eligible | Recommended Sync Cadence (Example) | Rationale |
|---|---|---|---|
| Infrastructure utilities (HTTP wrappers, loggers, formatters) | Eligible | 1--2 weeks | Per-module independent configuration possible; inconsistency impact is local |
| Per-module configuration/adapters | Eligible | 1--2 weeks | Independently modifiable per module |
| LLM prompt wrappers | Eligible | No limit | Independent evolution per module is intentional |
| Core business logic rules | Prohibited | -- | Global consistency is mandatory |
| Authentication/authorization logic | Prohibited | 0 days (immediate) | Security inconsistency directly yields vulnerabilities |
| Settlement/pricing calculations | Prohibited | -- | Legal/financial consistency is mandatory |
| Security policies (encryption, input validation) | Prohibited | 0 days (immediate) | Risk of unauditable vulnerabilities |
The application of these criteria is structured as a two-step decision process. First, "Can this code be independently modified per module?" — if yes, it is a duplication candidate. Second, "Could inconsistency in this code cause a security or integrity incident?" — if yes, duplication is absolutely prohibited. The recommended synchronization cadences are operational heuristics adjustable to project context; they should be understood as a judgment framework rather than normative thresholds.
Worked example. To concretely illustrate the effect of Intentional Duplication, consider the following. Before duplication, Project-ST's six APIs imported shared/utils/llm-client.ts via shared references — whenever the AI agent modified any API, context loading of this shared file was required. After duplication, a local copy was placed in each API directory (e.g., apis/recommend/llm-client.ts, apis/ranking/llm-client.ts), enabling the AI agent to complete modifications using only files within the target directory. This structural change became the foundation for each API's LLM client to independently evolve with endpoint-specific retry logic and timeout configurations.
Achievement in Project-ST. In our case study, the project maintained six independent copies of an LLM client wrapper (llm-client.ts), each configured for a specific API endpoint. Analysis of the version history revealed that these copies had diverged over time, with endpoint-specific retry logic, timeout configurations, and error handling — confirming that the duplication was not redundant but served genuine isolation purposes. The overall achievement rate was 90%, with the remaining 10% representing cases where shared utilities (primarily authentication middleware) were referenced rather than duplicated, creating residual cross-module coupling.
Purpose. Design the codebase such that an AI agent can fully comprehend and modify any feature by reading only the files within that feature's directory, without requiring knowledge of external files, global configurations, or cross-cutting abstractions.
Invariant. For any feature directory D(F), the files within D(F) should be sufficient for an AI agent to (a) understand the feature's purpose and behavior, (b) identify all dependencies and constraints, and (c) implement modifications without consulting files outside D(F).
Motivation. The Zero-Context Principle is motivated by all four LLM cognitive characteristics identified in Section 2.4, making it the most comprehensively motivated of the five principles. The bounded context window makes it desirable to minimize the number of files loaded; the Lost in the Middle phenomenon makes it important that critical information be present in the immediate working set rather than scattered across distant files; hallucination risk increases with cross-file reasoning; and prompt sensitivity means that self-contained, explicitly structured directories serve as more effective "prompts" for the AI agent than implicit conventions requiring global knowledge.
Formal definition. Let D(F) be the directory for feature F, and let files(D(F)) be the set of files in that directory. For an individual feature, define ZCS(F) = 1 if an AI agent can complete a representative modification task on F by reading only files(D(F)), and ZCS(F) = 0 otherwise. Note that ZCS(F) is binary for each individual feature — a given feature either achieves zero-context or it does not. The Zero-Context Score for the entire codebase is then the proportion of features that achieve zero-context: ZCS(C) = (1/n) * sum over F of ZCS(F), where n is the number of features. This aggregation produces a continuous value in [0, 1]; for example, a ZCS(C) = 0.75 indicates that 75% of features are fully self-contained while 25% require external context.
Relationship to Principles 1 and 2. Zero-Context is not an independent principle but rather an emergent property that arises from the successful application of Blast Radius Minimization and Intentional Duplication. When the blast radius is confined to a single directory (Principle 1) and shared dependencies are duplicated into each directory (Principle 2), the result is a directory that contains all information necessary for the AI agent to operate — i.e., zero external context is required.
The inter-principle dependency structure forms a directed acyclic graph with three layers. At the foundation layer, Blast Radius Minimization and Intentional Duplication operate independently but synergistically — duplication is the primary mechanism that enables blast radius containment. At the emergent layer, Zero-Context arises as a consequence when both foundation principles are achieved: directory isolation (from Blast Radius Minimization) combined with local code completeness (from Intentional Duplication) yields self-contained feature directories. At the enhancement layer, Contract as Metadata and Spec as Working Memory further enrich zero-context directories by providing structured metadata that improves the quality of the AI agent's context loading, without being prerequisites for Zero-Context itself.
Tradeoff with established principles. Zero-Context trades global coherence for local completeness. In Clean Architecture, a developer navigates from outer layers to inner layers following dependency rules, building a global mental model of the system. Zero-Context inverts this: each directory is a self-contained unit that can be understood without the global model. This is advantageous for AI agents, which do not maintain persistent mental models across tasks, but it may reduce the system's conceptual integrity — a quality attribute valued by Bass et al. [2021] as essential for long-term maintainability by human teams. The distinction from Package-by-Feature [Richardson, 2018] should also be clarified: package-by-feature is an organizational principle for package structure that permits external dependencies. Zero-Context targets the complete elimination of external context, accepting even Intentional Duplication (Principle 2) to this end, thereby demanding a qualitatively different level of isolation.
Achievement in Project-ST. The Zero-Context Score was measured at 75%. For 10 of the 13 API endpoints, an AI agent could complete modification tasks using only the files within the API's directory (spec.ts, service.ts, route handler, and local utilities). The remaining 25% required external context due to: (a) shared authentication middleware that was referenced rather than duplicated, (b) global environment configuration that affected API behavior, and (c) complex data pipelines where understanding upstream transformations was necessary to correctly modify downstream logic.
Purpose. Encode inter-module dependencies and interface contracts as explicit, machine-readable metadata within each module, rather than relying on implicit conventions, runtime discovery, or documentation external to the codebase.
Invariant. For any module M that depends on external service S, the contract with S (expected interface, data schema, behavioral constraints) should be declared as structured metadata within M's directory, and this metadata should include an explicit usedBy annotation identifying all consumers.
Motivation. This principle addresses the hallucination tendency and prompt sensitivity characteristics of LLMs. When an AI agent must generate code that interacts with an external service, it needs accurate information about the service's interface. If this information is not explicitly present in the module's directory, the agent must either search the broader codebase (consuming context window capacity) or infer the interface from usage patterns (risking hallucination). By encoding contracts as explicit metadata — for example, as TypeScript type definitions within a spec file — the principle provides the AI agent with authoritative reference material that can be loaded into context alongside the implementation files.
Formal definition. Let deps(M) be the set of external dependencies of module M, and let contracts(M) be the set of explicitly declared contracts in M's directory. Define Contract Completeness as CC(M) = |contracts(M) intersect deps(M)| / |deps(M)|. The principle requires that CC(M) approach 1.0 for all modules. Furthermore, for each contract c in contracts(M), define usedBy(c) as the set of declared consumers. The bidirectional traceability invariant requires that for every actual consumer M' of contract c, M' appears in usedBy(c).
Tradeoff with established principles. Contract as Metadata shares the spirit of Design by Contract [Meyer, 1992] and Interface Segregation (the 'I' in SOLID), but differs in its emphasis on location and format. Traditional Design by Contract embeds preconditions and postconditions in the implementation; Contract as Metadata externalizes them as standalone metadata files co-located with the consuming module. This externalization introduces a synchronization challenge — the metadata may drift from the actual implementation — but provides the AI agent with a concise, authoritative reference that can be prioritized in context loading. The principle thus trades the consistency guarantee of embedded contracts for the accessibility advantage of externalized, AI-readable metadata.
Distinction from existing API specification standards. Contract as Metadata may appear superficially similar to established API specification formats such as OpenAPI/Swagger [SmartBear, 2021] or Protocol Buffers [Google, 2008]. However, it differs in two critical respects. First, location: OpenAPI specifications are typically centralized (a single openapi.yaml at the project root or served from a documentation endpoint), whereas Contract as Metadata requires that contract information be co-located within each consuming module's directory, ensuring it is immediately available in the AI agent's local context. Second, purpose: OpenAPI serves documentation, client generation, and testing; Contract as Metadata serves AI agent context initialization — providing the agent with the minimal, authoritative information needed to understand and modify a specific module without navigating to external specification files. The two approaches are complementary: an OpenAPI specification may serve as the source of truth from which module-local contract metadata is derived, but the act of co-locating this metadata within each module is the architectural decision that distinguishes Contract as Metadata.
The synchronization challenge. A fundamental tension exists within this principle: the very act of externalizing contract information creates a potential for drift between the contract metadata and the actual service behavior. This tension is not unique to AI-Native Architecture — it echoes the long-standing challenge of keeping documentation synchronized with code — but it is particularly acute because the AI agent may treat outdated metadata as authoritative, producing code that conforms to a stale contract. Section 5.4 discusses observed instances of this drift in the Project-ST case study.
Achievement in Project-ST. Contract Completeness was measured at 70%. The project's spec.ts files declared type definitions and interface contracts for most external dependencies, including explicit usedBy annotations linking APIs to their consuming pages. However, 30% of actual dependencies were not reflected in the metadata, primarily involving: (a) transitive dependencies through shared middleware, (b) runtime-discovered dependencies (e.g., feature flags that conditionally activated integrations), and (c) recently added integrations where the spec had not been updated — instances of the spec-runtime drift discussed above.
Purpose. Designate a specification file (e.g., spec.ts) within each feature directory as the authoritative entry point for AI agents — a structured document that serves as the AI agent's "working memory initialization" by providing a complete summary of the feature's purpose, interface, dependencies, and constraints.
Invariant. For any feature directory D(F), a specification file spec(F) should exist such that reading spec(F) alone provides the AI agent with sufficient context to (a) understand what the feature does, (b) identify its inputs and outputs, (c) enumerate its dependencies, and (d) recognize constraints and invariants that must be preserved during modification. In Project-ST, spec.ts contained the following structured fields: method/path (HTTP interface), summary (feature synopsis), flow (sequential description of execution steps), tables: { reads, writes } (database dependencies), externalAPIs (external API contract references and consumed endpoints), and cautions (edge cases and constraints that the AI agent must observe during modification). This field structure was designed so that an AI agent could immediately grasp a feature's purpose, data flow, external dependencies, and caveats from a single file, and it illustrates the concrete form that "structured metadata" takes in practice.
Motivation. This principle is primarily motivated by the prompt sensitivity and non-uniform attention characteristics of LLMs. Research on prompt engineering has demonstrated that providing structured, explicit context at the beginning of an input significantly improves LLM output quality [Wei et al., 2022]. The spec file operationalizes this finding at the architectural level: by placing a structured summary at the entry point of each feature directory, the principle ensures that the most critical information occupies the privileged position at the start of the AI agent's context window, where attention is strongest [Liu et al., 2024].
Formal definition. Let spec(F) be the specification file for feature F, and let knowledge(F) be the complete set of facts necessary to understand and modify F. Define the Spec Coverage as SC(F) = |facts_in(spec(F)) intersect knowledge(F)| / |knowledge(F)|. Define the Spec-Runtime Drift Rate as SRDR(F) = |facts_in(spec(F)) minus facts_true_at_runtime(F)| / |facts_in(spec(F))|. The principle requires high SC(F) (comprehensive coverage) and low SRDR(F) (accurate coverage).
The working memory analogy. The term "working memory" is used as a deliberate analogy to the cognitive science concept [Baddeley, 2000], not as a claim of functional equivalence. Human working memory serves as a temporary store for information relevant to the current task; the spec file serves an analogous role for the AI agent by providing a curated subset of the codebase's knowledge that is relevant to the current feature. The analogy is imperfect — human working memory is dynamically updated during task execution, while the spec file is a static document — but it captures the essential function: providing immediate, task-relevant context without requiring global search.
Tradeoff with established principles. Spec as Working Memory introduces a form of documentation-as-architecture that is uncommon in mainstream software engineering. The dominant practice is that "the code is the documentation" — a principle advocated by proponents of Clean Code [Martin, 2008] and Agile methodologies. Spec as Working Memory partially reverses this by creating a structured metadata layer that summarizes and indexes the code. The cost is maintenance: the spec must be kept synchronized with the implementation, and any drift degrades the principle's effectiveness. The benefit is AI-readability: a well-maintained spec provides the AI agent with a high-signal, low-noise entry point that is far more effective than parsing raw implementation files.
Relationship to other principles. Spec as Working Memory enhances both Zero-Context (Principle 3) and Contract as Metadata (Principle 4). The spec file is the vehicle through which contract metadata is exposed to the AI agent, and its presence within the feature directory contributes to zero-context achievability by consolidating essential information in a single, structured file.
Achievement pathway and current implementation status. While we maintain the theoretical standing of Principle 5, the current implementation in Project-ST constitutes an initial operationalization rather than full operationalization. Three operationalization pathways are identified: (a) manual maintenance (the current Project-ST approach, yielding low achievement), (b) code-generation-based (the AI automatically regenerates the spec from the implementation), and (c) hybrid (skeleton maintained manually, details auto-generated). The limitations of the manual maintenance approach reflect the immaturity of the current implementation strategy rather than a deficiency in the principle itself.
Achievement in Project-ST. This principle had the lowest achievement rate at 40%. While all 13 API directories contained spec.ts files, the quality and completeness of these specifications varied significantly. The primary deficiencies were: (a) spec-runtime drift, where the spec declared interfaces that had been modified in implementation without corresponding spec updates (observed in 4 of 13 APIs); (b) incomplete dependency enumeration, where the spec omitted transitive or conditional dependencies; and (c) absence of behavioral constraints, where the spec described data types but not business rules or invariants. The 40% achievement rate reflects the assessment that fewer than half of the spec files were sufficiently complete and accurate to serve as reliable working memory initialization for an AI agent. This low achievement reveals a fundamental tension: maintaining a parallel specification layer requires discipline that is difficult to sustain, even — or especially — in an AI-driven workflow where the speed of code generation outpaces documentation updates. This low achievement appears to be partly structural (the principle demands a level of spec-code coupling that current tooling does not automate) and partly procedural (the development team did not consistently enforce spec-first workflows). Disentangling these two factors — whether the principle is inherently difficult to achieve or merely under-implemented in this case — is a question we return to in Section 7.
The five principles are not independent design choices but form a hierarchical dependency structure. Understanding this hierarchy is essential for practitioners seeking to adopt the framework incrementally.
Foundation layer: Blast Radius Minimization and Intentional Duplication. These two principles form the structural foundation. Blast Radius Minimization defines the goal (single-directory change containment), and Intentional Duplication provides the primary mechanism for achieving it (eliminating cross-directory coupling through code duplication). An organization adopting AI-Native Architecture should implement these principles first.
Emergent layer: Zero-Context. When Principles 1 and 2 are successfully implemented, Zero-Context emerges as a natural consequence. If each change is contained within one directory and all necessary code is locally present, the directory becomes self-contained — requiring zero external context. Zero-Context is therefore not a principle to be implemented directly but a quality to be measured as an indicator of Principles 1 and 2's effectiveness.
Enhancement layer: Contract as Metadata and Spec as Working Memory. These principles enhance the quality of the zero-context environment by adding structured metadata. Contract as Metadata ensures that external dependencies are explicitly declared; Spec as Working Memory provides a structured entry point for AI agents. These principles can be adopted incrementally and independently of each other, though they are most effective in combination.
This layered structure has practical implications for adoption. Organizations need not implement all five principles simultaneously; they can begin with the foundation layer (achieving immediate blast radius reduction through directory-based modularization and selective duplication) and progressively add the enhancement layer as their AI-Native practices mature.
Section 2.3 identified the limitations of traditional static analysis tools in governing AI-driven development and introduced the concept of prompt-based architecture governance. This section develops that concept in detail, using the skill system observed in the Project-ST project as the basis for analysis.
In AI-agent-driven development, a skill is a structured natural language directive that defines an AI agent's workflow for a specific class of tasks. Each skill specifies the sequence of actions the agent must follow, the files it must read, the constraints it must observe, and the verification steps it must perform upon completion. Skills are not code — they are prompt templates that shape the agent's behavior during code generation and modification tasks.
In the Project-ST project, nine skills were identified through reverse engineering of the development workflow. These skills can be classified into three categories by their governance function:
Generative skills govern the creation of new architectural units. The new-api skill directs the AI agent to create a new API endpoint by first reading an existing API directory as a template, then generating a spec.ts, service.ts, route handler, and associated files in a new directory following the established pattern. The new-page skill performs the analogous function for frontend pages. By encoding the expected directory structure and file composition in the skill definition, generative skills ensure that newly created modules conform to the architectural pattern from inception.
Modificatory skills govern changes to existing architectural units. The modify-api and modify-page skills direct the agent to read the target module's spec.ts before making changes, constrain modifications to the target directory, and require verification that changes do not affect other modules. Figure 1 illustrates the core structure of the modify-api skill.
Figure 1. Core Structure of the modify-api Skill Definition (Excerpt)
Preconditions:
"Read the target API's spec.ts first to ascertain the current interface and dependencies. The types and contracts declared in spec.ts serve as the starting point for modification."Invariants:
"Constrain modifications to files within the target API directory. Do not modify files in other directories. Adhere to the type contracts declared in spec.ts."Postconditions:
"Execute build verification. Confirm that the interface declarations in spec.ts are consistent with the modified implementation; if inconsistent, update spec.ts."
Cases were observed where spec-runtime drift occurred in commits that bypassed skills and modified code directly (Section 5.4), illustrating that the absence of skill-based process governance can accelerate architectural drift. The api-change, external-change, and schema-change skills handle cross-cutting modifications that require coordinated changes across multiple modules. Notably, even these cross-cutting skills decompose the task into per-directory sub-tasks, preserving the Blast Radius Minimization principle wherever possible.
Verification skills govern the detection and correction of architectural drift. The sync-contracts skill directs the AI agent to compare spec.ts declarations against actual implementation code and flag discrepancies. The sync-page-contracts skill performs the analogous check for frontend page contracts. These skills operationalize the Contract Completeness (CC) and Spec-Runtime Drift Rate (SRDR) metrics defined in Section 6.
Each skill encodes enforcement of one or more AI-Native principles. Table 2 presents the mapping between skills and the principles they enforce.
Table 2. Skill-Principle Enforcement Matrix
| Skill | P1: Blast Radius | P2: Duplication | P3: Zero-Context | P4: Contract | P5: Spec |
|---|---|---|---|---|---|
| new-api | Enforced | Enforced | Enforced | Enforced | Enforced |
| new-page | Enforced | Enforced | Enforced | Enforced | Enforced |
| modify-api | Enforced | -- | Enforced | Verified | Required |
| modify-page | Enforced | -- | Enforced | Verified | Required |
| api-change | Partial | -- | Partial | Updated | Required |
| external-change | Partial | -- | Partial | Updated | Required |
| schema-change | Partial | -- | Partial | Updated | Required |
| sync-contracts | -- | -- | -- | Verified | Verified |
| sync-page-contracts | -- | -- | -- | Verified | Verified |
In this matrix, "Enforced" indicates that the skill's workflow structurally prevents violation of the principle; "Required" indicates that the skill mandates a specific action related to the principle (e.g., reading the spec file); "Verified" indicates that the skill includes a verification step that detects violations; and "--" indicates that the skill does not directly address the principle. "Partial" requires further elaboration: the cross-cutting skills (api-change, external-change, schema-change) enforce blast radius containment and zero-context within each sub-task, but the task itself inherently spans multiple directories. For example, the schema-change skill decomposes a database schema modification into per-API update sub-tasks, each constrained to one directory — but the overall task affects multiple directories by definition. Thus, the principle is enforced at the sub-task level while being necessarily violated at the task level.
The governance mechanism of skills can be formally characterized using the precondition-invariant-postcondition framework familiar from Design by Contract [Meyer, 1992], adapted to the AI agent context.
Preconditions are the files and information that the skill requires the AI agent to read before beginning code generation. The most critical precondition across all skills is the spec-first requirement: the agent must read the target module's spec.ts file before modifying any implementation files. This precondition ensures that the agent's context is initialized with the authoritative metadata for the module, directly supporting Principle 5 (Spec as Working Memory).
Invariants are constraints that must be maintained throughout the skill's execution. The most fundamental invariant is directory isolation: modifications should be confined to the target directory unless the skill explicitly authorizes cross-directory changes. This invariant directly enforces Principle 1 (Blast Radius Minimization). Additional invariants include type consistency (modified code must conform to the types declared in spec.ts) and contract preservation (usedBy annotations must remain accurate after modification).
Postconditions are verification steps that the skill requires the agent to perform after completing code generation. These include: (a) build verification — the modified code must compile/transpile without errors; (b) contract synchronization check — any changes to interfaces must be reflected in spec.ts; and (c) blast radius audit — the agent must confirm that no files outside the target directory were modified (for single-module skills).
Execution scenario example: modify-api skill. To illustrate the concrete workflow, consider the task "Add a sort-criteria field to the recommend API response." The AI agent executes as follows: (1) Precondition — read POST_recommend_items/spec.ts to ascertain the current response schema, external API dependencies (externalAPIs), and caveats (cautions). (2) Implementation — add the new field to types.ts, modify service.ts to compute the relevant value, and update the response mapping in handler.ts. All modifications are confined to the POST_recommend_items/ directory (directory isolation invariant). (3) Postcondition — execute build verification, then update the response schema description in spec.ts to preserve spec-runtime consistency. This scenario illustrates how the precondition-invariant-postcondition triad respectively enforces Principle 5 (spec-first), Principle 1 (blast radius containment), and Principle 4 (contract synchronization).
Prompt-based governance through skills offers several advantages over traditional static analysis for AI-driven development:
Behavioral constraint expressiveness. Skills can encode constraints that are impossible to express in static analysis rules. "Read the spec file before modifying the service" is a process constraint on the agent's behavior, not a structural property of the code. Static analysis can verify that a spec file exists but cannot enforce that the agent consulted it before generating modifications.
Natural language flexibility. Architectural rules expressed in natural language can accommodate nuance and context that formal constraint languages cannot. A skill can specify "if the change affects the response schema, update the usedBy annotations in all consuming page specs" — a conditional, semantic instruction that would require sophisticated program analysis to encode as a static rule.
Co-evolution with the codebase. Skills can be updated as architectural patterns evolve, without modifying the codebase or the static analysis toolchain. This is particularly valuable in rapidly evolving AI-Native projects where architectural norms are still being established.
However, prompt-based governance has significant limitations that must be acknowledged:
Non-deterministic enforcement. Unlike static analysis, which produces deterministic pass/fail results, prompt-based governance operates through the probabilistic behavior of an LLM. The agent may misinterpret a skill directive, skip a required step, or fail to recognize a violation. Enforcement is therefore probabilistic rather than guaranteed.
No compile-time enforcement. Skills operate at the workflow level, not the language level. There is no mechanism analogous to a compiler error that would prevent the agent from committing code that violates a skill-encoded constraint. Violations are detected only if the skill includes explicit postcondition checks.
Circumventability. An AI agent (or a human developer) can bypass skills entirely by performing tasks without invoking the relevant skill. Skills are conventions, not guardrails. This limitation parallels the distinction between coding standards (advisory) and type systems (enforced): skills provide the former but not the latter.
Opacity of compliance. It is difficult to audit whether a given code change was produced in compliance with the relevant skill. Unlike static analysis, which leaves an audit trail (passed/failed checks), skill compliance is visible only through indirect evidence (e.g., the presence of updated spec.ts files, the absence of cross-directory modifications).
These limitations suggest that prompt-based governance should be deployed in conjunction with, not as a replacement for, traditional verification mechanisms. The combination of skill-based process governance and automated postcondition verification provides a more robust governance framework than either mechanism alone.
Complementary governance layers. In practice, a complete AI-Native architecture governance requires a three-layer complementary structure. Layer 1 (pre-generation guidance): Skills constrain the generative process — the core contribution of this paper. Layer 2 (in-process verification): CI guardrails automatically verify generated artifacts. Two key examples are presented: (a) cross-boundary change detection — a commit hook or CI pipeline step that automatically flags file modifications crossing module directory boundaries for review, serving as a runtime enforcement mechanism for Principle 1 (Blast Radius Minimization); (b) spec drift fail-fast check — a build-time check that detects structural inconsistencies between spec files and actual exports/types, failing the build upon mismatch, serving as a runtime enforcement mechanism for Principle 5 (Spec as AI Working Memory). Layer 3 (post-hoc measurement): Metrics (BRI, ZCS, CC, SRDR) periodically compute architectural conformance — another core contribution of this paper. While the core contributions of this paper are Layers 1 and 3, we include an overview and key examples of Layer 2 for practical completeness.
This section presents a detailed case study of Project-ST, a production e-commerce event application developed for a major e-commerce platform, from which the five AI-Native architectural principles were derived. We describe the project context (Section 5.1), the reverse engineering methodology (Section 5.2), principle-by-principle achievement measurements (Section 5.3), identified problems and architectural tensions (Section 5.4), and an observation regarding the two-level AI structure that emerged during development (Section 5.5).
Project-ST is a gamified event application for a major e-commerce platform, designed to drive merchant engagement through store management simulation gameplay. The application was developed using an AI-agent-centric workflow, where a Claude-based AI agent served as the primary code author under the direction of a human architect.
Technical characteristics:
The project represents a specific category of software: a time-bounded event application with moderate complexity, a well-defined feature set, and a small development team (one human architect plus AI agent). This context is important for understanding both the applicability and the limitations of the principles derived from this case study (see Section 8 for threats to validity).
The five AI-Native principles were not designed a priori but rather emerged through systematic reverse engineering of the Project-ST codebase after the project's completion. Our analysis followed a three-axis methodology:
Axis 1: Codebase Structure Analysis. We performed a systematic examination of the directory structure, file organization patterns, and dependency relationships across the entire codebase. This analysis revealed the feature-based directory organization, the pattern of duplicated utility files, and the presence of spec.ts files as module entry points. Quantitative measures included: directory count, files per directory, cross-directory import frequency, and duplicated file identification.
Axis 2: Development Workflow Reconstruction. We reconstructed the development workflow by analyzing the AI agent's skill definitions, examining the git commit history to understand the temporal sequence of development activities, and reviewing the human architect's design documents (Confluence pages). This axis revealed the skill-based governance mechanism and the spec-first development pattern.
Axis 3: Principle Extraction and Validation. From the patterns identified in Axes 1 and 2, we extracted candidate architectural principles through a process of analytical generalization [Yin, 2018]. Each candidate principle was validated against three criteria: (a) observability — the principle must be manifest in the codebase structure, not merely intended; (b) motivation — the principle must be traceable to one or more LLM cognitive characteristics; and (c) distinctiveness — the principle must represent a departure from or refinement of established software engineering principles. Five principles met all three criteria and are presented in Section 3.
For each of the five principles, we measured the degree of achievement using the metrics defined in Section 6 (presented here in summary form; full metric definitions follow in Section 6).
Measurement procedure. All measurements were performed by the first author through manual analysis of the codebase and its git history, supplemented by automated scripts for dependency extraction and diff analysis. To ensure replicability, we describe the specific procedure for each metric below. We acknowledge that single-rater measurement introduces subjectivity risk; inter-rater reliability assessment is planned for the multi-case extension of this study.
Skill-usage commit identification criteria. To analyze the indirect effects of skill-based governance, we defined operational criteria for distinguishing commits generated through skill invocation from those that were not. The primary identifier is the commit message: commits generated through skill invocation follow specific message patterns (containing the skill name or matching an agent-auto-generated format), and commits matching these patterns were classified as "skill-usage commits." The secondary identifier is the agent session log: where commit messages alone were ambiguous, we cross-referenced skill invocation records against commit timestamps for confirmation. Commits that could not be classified by either identifier were treated as "unclassified," excluded from the analysis, and the unclassified proportion is reported alongside results to ensure transparency.
Principle 1: Blast Radius Minimization (BRI = 1.05, Achievement: 95%). We analyzed the complete git commit history (142 total commits) and selected 60 commits that represented distinct feature-level changes, excluding merge commits, documentation-only changes, and configuration file updates. The selection criterion was operational: a commit was included if it modified at least one TypeScript source file in an API or page directory. For each selected commit, we counted the number of distinct feature directories containing modified files. Of the 60 analyzed commits, 57 modified files within a single directory (BRI = 1.0). The three exceptions involved: (a) a global authentication middleware update that required changes in the shared middleware directory and one API directory; (b) a database schema migration affecting the schema directory and two API directories; and (c) a cross-API data pipeline modification. The resulting mean BRI of 1.05 closely approaches the ideal of 1.0.
Principle 2: Intentional Duplication (DIR = 0.35, Achievement: 90%). We identified six instances of the llm-client.ts utility duplicated across API directories. Pairwise diff analysis revealed an average code divergence of 35% (DIR = 0.35), indicating that the copies had evolved independently with endpoint-specific configurations. Of the 13 API directories, 12 contained all necessary utility code locally; one API directory relied on a shared authentication module, representing the 10% non-achievement.
Principle 3: Zero-Context (ZCS = 0.75, Achievement: 75%). We operationalized ZCS by having the AI agent (Claude 3.5 Sonnet) attempt one representative modification task per API endpoint, totaling 13 trials. Each task was a single-field addition: adding a new response field to an existing API, requiring the agent to understand the current data schema, modify the service logic, and update the route handler. The agent was constrained to reading only files within the target directory (no access to files outside that directory). A task was scored as successful (ZCS = 1) if the generated code compiled without errors and produced the correct response; it was scored as failed (ZCS = 0) if the agent required external files or produced incorrect code due to missing context. The agent successfully completed tasks for 10 of 13 APIs without requiring external context. The three failures involved: an API dependent on shared middleware logic, an API requiring understanding of an upstream data pipeline, and an API whose behavior was conditionally modified by global feature flags.
Principle 4: Contract as Metadata (CC = 0.70, Achievement: 70%). We manually audited each spec.ts file, comparing declared dependencies and interface contracts against actual runtime dependencies identified through static import analysis and dynamic call tracing. Of 47 actual external dependencies across all modules, 33 were accurately declared in spec.ts files (CC = 0.70). The 14 undeclared dependencies fell into three categories: transitive middleware dependencies (6), feature-flag-conditional integrations (4), and recently added integrations with outdated specs (4).
Principle 5: Spec as Working Memory (SRDR = 0.23, Achievement: 40%). We measured both Spec Coverage and Spec-Runtime Drift Rate. Spec Coverage averaged 55% — specs described data types and primary interfaces but omitted behavioral constraints, error handling specifications, and performance requirements. SRDR was 0.23, meaning that 23% of facts declared in spec files were inaccurate relative to the current implementation. The combined achievement of 40% reflects the assessment that fewer than half of the spec files were sufficiently complete and accurate to serve as reliable working memory initialization for an AI agent.
Table 3. Summary of Principle Achievement in Project-ST
| Principle | Primary Metric | Ideal | Observed | Achievement |
|---|---|---|---|---|
| P1: Blast Radius Minimization | BRI | 1.0 | 1.05 | 95% |
| P2: Intentional Duplication | DIR | 0.2--0.5 | 0.35 | 90% |
| P3: Zero-Context | ZCS | 1.0 | 0.75 | 75% |
| P4: Contract as Metadata | CC | 1.0 | 0.70 | 70% |
| P5: Spec as Working Memory | SRDR | 0.0 | 0.23 | 40% |
| Overall Average | -- | -- | -- | 74% |
Indirect compliance indicators. To indirectly assess the effectiveness of skill-based governance, we propose two proxy indicators that can be computed from available data. First, the proportion of modify-api skill-usage commits in which spec.ts was also updated can serve as a proxy for spec-first compliance. Second, the proportion of single-module skill (modify-api, modify-page) usage commits that modified only a single directory can serve as a proxy for isolation invariant compliance. In this study, systematic cross-referencing of commit message patterns and agent session logs was not completed, and we therefore do not report specific figures; the actual computation and interpretation of these indicators are left as future work.
Operational metric observations. Beyond the achievement metrics, we observed operational-level indicators from the git history. Reinterpreting the BRI data, 95% of changes were completed within a single directory — an operational indicator that AI agent change scope aligned with architectural intent. Additionally, the average time to add a new API endpoint, derivable from the time intervals between new-api skill-usage commits, was identified as an operational metric that can be extracted in future work. However, we explicitly acknowledge that in the absence of a comparison baseline (a project not applying AI-Native principles), these observations constitute exploratory description rather than absolute effect measurement.
The reverse engineering analysis revealed several problems that illuminate the tensions inherent in AI-Native Architecture.
Butterfly-API drift. One API endpoint (nicknamed "butterfly-api" by the development team due to its wide-reaching effects) exhibited a pattern of escalating cross-module dependencies over time. Initially conforming to the single-directory isolation pattern, this API gradually accumulated references to other modules' data models and utility functions as the business logic grew in complexity. The butterfly-api's blast radius expanded from 1 directory in the initial implementation to 4 directories by the project's end, demonstrating that blast radius containment requires ongoing vigilance and is not automatically preserved as features evolve.
Spec-runtime divergence acceleration. An unexpected finding was that spec-runtime drift accelerated over the project lifecycle. Early in development, when features were being created (often using the new-api skill), specs were generated alongside implementation code and were highly accurate. As the project entered the modification and iteration phase, implementation changes were frequently made without corresponding spec updates. The AI agent, when invoking the modify-api skill, would read the spec first as directed — but the spec it read was increasingly stale. This created a paradoxical situation: the governance mechanism (spec-first reading) was faithfully followed, but the governed artifact (the spec) had degraded, leading to code generation based on outdated assumptions.
Complex pipeline pressure on Zero-Context. Three API endpoints participated in a multi-stage data pipeline where the output of one API served as the input to another. For these endpoints, true zero-context was unachievable: understanding the data format required knowledge of the upstream transformation, which was defined in a different directory. This observation suggests that the Zero-Context Principle has an inherent limitation in data pipeline architectures where sequential dependencies create irreducible cross-module information requirements.
Duplication synchronization gap. While the six duplicated llm-client.ts files had evolved independently (as intended), one instance was discovered where a critical bug fix in one copy was not propagated to the others. The bug — an incorrect retry backoff calculation — was fixed in the first API directory where it was discovered but remained in the other five copies for two weeks until a manual audit detected it. Re-evaluating against the recommended synchronization cadences in Table 1-1, the observed two-week delay falls within the acceptable range for the infrastructure utility category; however, had the code in question involved security-related logic, the delay would have exceeded the recommended cadence. This observation suggests the need for three mitigation mechanisms: (a) a sync-duplicates verification skill that detects semantic diffs across duplicated files, (b) git-hook-based notifications upon duplicated file modification, and (c) a duplication registry metadata tracking which files were duplicated from where. This incident illustrates the maintenance risk that Intentional Duplication introduces — even when architecturally justified — and the need for automated tooling to manage it systematically.
An unexpected finding from the case study was the emergence of a two-level AI architecture that was not part of the original design intent.
Level 1: Service AI. The Project-ST application itself uses LLM-based AI as part of its runtime functionality — generating personalized game content, crafting merchant recommendations, and producing dynamic event descriptions. This is the "AI in the product" layer, where LLM API calls are embedded in the application's service logic.
Level 2: Development AI. Separately, the application was developed using an AI agent (Claude) as the primary code author. This is the "AI as the developer" layer, where the LLM generates and modifies the application's source code.
The architectural implications of this two-level structure are noteworthy. The spec.ts files in Project-ST served a dual purpose: they documented the API interface for the development AI (supporting Principle 5) while also defining the LLM prompt templates used by the service AI (supporting runtime functionality). This dual role created a coupling between architectural governance and runtime behavior — changes to the spec for governance purposes could inadvertently affect the application's runtime LLM interactions, and vice versa.
This dual-purpose coupling may have contributed to the low achievement rate of Principle 5 (Spec as Working Memory, 40%). When spec.ts served both as governance metadata for the development AI and as a runtime artifact for the service AI, modifications motivated by runtime requirements (e.g., adjusting LLM prompt templates for better game content) could introduce spec-runtime drift from the development governance perspective, and vice versa. The competing demands of these two roles made it difficult to maintain the spec as a reliable source of truth for either purpose.
Furthermore, a tentative observation was that the complexity of the service AI may constrain the achievability of architectural principles for the development AI. The character/generate API consisted of a three-stage pipeline — 6 parallel VLM calls, 1 LLM consolidation generation, and 1 ImageGen final generation — requiring more than 10 files within a single directory (pipeline.ts, prompt-builder.ts, vlm-client.ts, llm-client.ts, image-generation-client.ts, etc.). The inherent complexity of this service AI pipeline acted as a factor inhibiting the achievement of the Zero-Context Principle — one of the three failures that limited ZCS to 75% occurred at this API. While this is a tentative observation from a single case, it raises the possibility of an inverse relationship between service AI complexity and architectural conformance for the development AI.
Additionally, on the frontend side, a parallel observation was made. Pages consuming AI-generated content (e.g., O-TYP test results, recommended items) had their UI complexity driven by the richness of service AI outputs, requiring additional components and state management within the page directory.
This observation suggests that as AI becomes simultaneously embedded in products and development processes, a new class of architectural concerns arises around the separation (or deliberate integration) of these two AI layers. Three tentative separation strategies are identified: (a) explicit separation of development-use and runtime-use sections within spec.ts (via section markers or file splitting), (b) isolating runtime prompt templates into a separate file while keeping spec.ts exclusively for development governance, and (c) a build-time pipeline that auto-generates one from the other. We record the validation of these separation strategies, including the frontend-side observations, as areas for future investigation.
The five principles presented in Section 3 require quantitative metrics to enable objective measurement of architectural conformance. This section defines five metrics — one primary metric per principle — specifying the operational measurement procedure, interpretation criteria, ideal values, and known limitations for each.
Definition. ZCS measures the proportion of feature modules in a codebase for which an AI agent can complete a representative modification task using only files within the module's directory.
Measurement procedure. (1) Enumerate all feature directories D(F_1), ..., D(F_n) in the codebase. (2) For each feature F_i, define a representative modification task T_i — a task of moderate complexity that requires understanding the feature's data model, service logic, and interface (e.g., adding a response field, modifying a validation rule, or changing a data transformation). (3) Instruct the AI agent to complete T_i with access restricted to files(D(F_i)) only. (4) Score ZCS(F_i) = 1 if the agent produces a correct, compilable modification; ZCS(F_i) = 0 otherwise. (5) Compute ZCS(C) = (1/n) * sum of ZCS(F_i).
Interpretation. ZCS(C) = 1.0 indicates perfect zero-context: every feature is fully self-contained. Values below 1.0 indicate features that require external context. A score of 0.75, as observed in Project-ST, indicates that one in four features has irreducible external dependencies.
Ideal value. 1.0 (all features self-contained).
Limitations. ZCS is sensitive to the choice of representative task — a trivial task (e.g., changing a string constant) may achieve ZCS = 1 even for poorly isolated modules, while an overly complex task may fail for reasons unrelated to isolation. The metric also depends on the specific AI agent used, as different models have different context utilization capabilities. We recommend using tasks of moderate complexity and reporting the agent model and version alongside ZCS values.
Practical approximation. We propose the External Import Ratio (EIR = number of imports from outside the directory / total number of imports) as an independent indicator readily usable in practice. EIR is immediately computable via static analysis and can be integrated into CI pipelines for automated tracking. EIR is not a complete substitute for ZCS but rather a meaningful practical indicator in its own right — modules with low EIR have fewer external dependencies and are more amenable to local modification by AI agents. Validation of the correlation with the precise metric (ZCS) is left as future work.
Definition. BRI measures the average number of directories affected per change task, reflecting the degree of change containment achieved by the architecture.
Measurement procedure. (1) Extract the git commit history for the analysis period. (2) Filter commits to include only those representing feature-level changes (exclude merges, documentation, and configuration-only commits). (3) For each qualifying commit T_j, count the number of distinct feature directories containing modified source files: blast_radius(T_j). (4) Compute BRI(C) = (1/m) * sum of blast_radius(T_j), where m is the number of qualifying commits.
Interpretation. BRI = 1.0 indicates perfect blast radius containment: every change is confined to a single directory. Values above 1.0 indicate the average degree of cross-directory impact. A BRI = 1.05, as observed in Project-ST, indicates that the vast majority of changes are single-directory, with rare exceptions.
Ideal value. 1.0 (single-directory containment for all changes). BRI can be automatically computed via a git log --stat parsing script, making it the least costly to automate among the proposed metrics.
Limitations. BRI is influenced by commit granularity — a developer who makes atomic commits (one logical change per commit) will produce different BRI values than one who bundles multiple changes. BRI also does not distinguish between necessary cross-directory changes (e.g., schema migrations that inherently affect multiple modules) and avoidable ones. We recommend computing BRI with a documented commit selection criterion, as described in Section 5.3.
Definition. DIR measures the degree to which intentionally duplicated code has evolved independently across modules, thereby validating the isolation purpose of the duplication.
Measurement procedure. (1) Identify all sets of duplicated files in the codebase — files that share a common origin but reside in different feature directories. (2) For each duplicated set {U_1, ..., U_k}, compute pairwise code similarity using a diff-based metric: similarity(U_i, U_j) = 1 - (edit_distance(U_i, U_j) / max(|U_i|, |U_j|)). (3) Compute the divergence for the set: divergence = 1 - mean(similarity(U_i, U_j)) for all pairs. (4) Compute DIR(C) = mean(divergence) across all duplicated sets.
Interpretation. DIR = 0 indicates that all duplicated files are identical (no independent evolution, suggesting the duplication may be unnecessary). DIR > 0.3 suggests meaningful independent evolution, validating the isolation purpose. Very high DIR values (> 0.7) may indicate that the files have diverged so significantly that they are no longer meaningfully "duplicated" but rather independently developed modules that happen to share a historical origin.
Ideal value. Context-dependent. A DIR in the range [0.2, 0.5] suggests healthy intentional duplication — enough divergence to justify isolation, but sufficient commonality to indicate a shared architectural pattern. Values near 0 suggest unnecessary duplication; values near 1.0 suggest the "duplication" label is no longer apt.
Limitations. DIR is a retrospective metric — it measures whether duplication was justified after the fact, not whether the decision to duplicate was correct at the time it was made. A DIR of 0 does not necessarily mean duplication was wrong; the copies may simply not yet have had occasion to diverge. Additionally, DIR does not account for the semantic significance of differences — a single-line configuration change may be more architecturally meaningful than a large block of reformatted code.
Definition. CC measures the proportion of actual external dependencies that are explicitly declared as contract metadata within each module's directory.
Measurement procedure. (1) For each module M, enumerate the set of actual external dependencies deps(M) through a combination of static import analysis (extracting all import statements referencing external modules) and manual identification of runtime dependencies (API calls, database queries, external service invocations). (2) Enumerate the set of declared contracts contracts(M) by parsing the module's specification file (e.g., spec.ts). (3) Compute CC(M) = |contracts(M) intersect deps(M)| / |deps(M)|. (4) Compute CC(C) = (1/n) * sum of CC(M_i).
Interpretation. CC = 1.0 indicates that every external dependency is explicitly declared in the module's contract metadata. Values below 1.0 indicate undeclared dependencies — gaps in the metadata that may cause the AI agent to generate code with incorrect assumptions about external interfaces.
Ideal value. 1.0 (all dependencies declared).
Limitations. CC depends on the definition of "external dependency," which can range from narrow (only cross-service API calls) to broad (any import from outside the module directory). The metric is also sensitive to granularity: should each individual function imported from an external module count as a separate dependency, or should the module-level dependency count as one? We recommend using module-level dependency counting and documenting the dependency definition used.
Definition. SRDR measures the proportion of facts declared in a module's specification file that are inaccurate relative to the current runtime implementation, reflecting the degree of drift between the spec and the code.
Measurement procedure. (1) For each module M, enumerate all factual assertions in spec(M) — type definitions, interface signatures, dependency declarations, behavioral constraints. Denote this set facts(spec(M)). (2) For each fact f in facts(spec(M)), verify whether f is consistent with the current implementation by examining the corresponding source files. (3) Classify each fact as accurate (consistent with implementation) or drifted (inconsistent). (4) Compute SRDR(M) = |drifted facts| / |facts(spec(M))|. (5) Compute SRDR(C) = (1/n) * sum of SRDR(M_i).
Interpretation. SRDR = 0 indicates perfect spec-runtime consistency. Higher values indicate greater drift. An SRDR = 0.23, as observed in Project-ST, means that approximately one in four spec assertions was inaccurate — a level of drift that can cause an AI agent to generate code based on incorrect assumptions in roughly one-quarter of its context loading.
Ideal value. 0.0 (no drift).
Limitations. SRDR is the most labor-intensive metric to measure, as it requires manual comparison of spec assertions against implementation code. Automating this measurement is possible for structural facts (type signatures, function parameters) but remains challenging for behavioral facts (business rules, error handling policies). The metric is also binary per fact (accurate or drifted), losing nuance about the severity of drift — a minor type annotation discrepancy is weighted equally with a fundamentally incorrect interface declaration.
Practical approximation. Structural facts (type signatures, function parameters) can be automatically detected via AST comparison between the TypeScript type definitions in spec.ts and the actual exported types, thereby reducing the scope of manual audit required for behavioral facts.
The five metrics are not independent. BRI and DIR jointly indicate the effectiveness of the foundation layer (Principles 1 and 2); ZCS serves as an aggregate indicator of the emergent layer (Principle 3); CC and SRDR assess the enhancement layer (Principles 4 and 5). A codebase with high BRI (close to 1.0) and high DIR (above 0.3) but low ZCS may indicate that blast radius containment and duplication are present but that other factors (shared middleware, global configuration) undermine zero-context. Low SRDR combined with high CC indicates a well-maintained contract metadata layer, while high SRDR regardless of CC indicates systemic spec-runtime drift.
Two-tier measurement strategy. For practical adoption, we propose a measurement strategy that categorizes metrics into two tiers by automability. Tier 1 (CI-integrated, automated): BRI (git log parsing), EIR (static import analysis), CC approximation (spec file existence + declared-to-external-import ratio), DIR (file hash comparison + diff line count), SRDR structural approximation (AST comparison between spec.ts type definitions and actual exported types) — these can be integrated into CI pipelines for automatic computation on every build. Tier 2 (periodic audit, semi-automated): ZCS (sandboxed AI agent trials), SRDR behavioral facts (manual audit of business rules and error handling policies) — these are measured periodically on a sprint or release cycle cadence. Tier 1 measurements alone are sufficient for practical assessment of architectural compliance; Tier 2 serves deeper quality audits.
We propose the AI-Native Architecture Conformance Index (ANACI) as a weighted composite: ANACI = w_1 * BRI_norm + w_2 * DIR_norm + w_3 * ZCS + w_4 * CC + w_5 * (1 - SRDR), where BRI_norm = max(0, 2 - BRI) clamps the BRI contribution to [0, 1] (yielding 1.0 at the ideal BRI = 1.0 and 0.0 when BRI >= 2.0), DIR_norm normalizes DIR to [0, 1] based on the ideal range [0.2, 0.5], and w_1, ..., w_5 are weights summing to 1. The max(0, 2 - BRI) normalization avoids the numerical instability of an inverse transform while providing a linear, interpretable mapping: each additional directory in the average blast radius reduces the BRI contribution by 1.0. We do not prescribe specific weights, as these should reflect the organization's priority among the principles. In the Project-ST case, an equal-weight ANACI yields approximately 0.76.
This section examines the broader implications of the AI-Native architectural principles, addressing their applicability conditions, relationship with established principles, economic considerations, and limitations.
The five AI-Native principles were derived from a specific project context — a time-bounded event application of moderate complexity, developed by a single human architect with an AI agent. It is essential to delineate the conditions under which these principles are likely to be beneficial versus those where they may be inapplicable or counterproductive.
Favorable conditions. The principles are most applicable to projects exhibiting the following characteristics: (a) AI-primary development, where the AI agent generates the majority of code and the human serves as architect and reviewer; (b) feature-based decomposability, where the system can be organized into relatively independent feature modules with bounded interfaces; (c) moderate scale, where the number of feature modules is in the range of tens to low hundreds, keeping the duplication strategy manageable; and (d) rapid iteration cadence, where the cost of cross-module coordination is amplified by frequent changes.
Service architecture condition: AI-API-centric rather than DB-centric structure. A favorable condition observed in the Project-ST case was that the service architecture was AI-API-centric rather than database-centric (DB-centric). In the spec.ts files of the 13 API endpoints, tables: { reads: [], writes: [] } — indicating no database dependencies — constituted the majority, with MongoDB serving only as lightweight storage for user profiles and generated results. The core business logic consisted of orchestrating external AI API calls (LLM, VLM, image generation). This structural characteristic was observed as a favorable condition that facilitated principle adoption in Project-ST: in traditional DB-centric systems where database transactions and integrity constraints are the primary source of cross-module coupling, directory isolation and intentional duplication may be constrained by transaction boundaries and data integrity requirements. Consequently, AI-Native architectural principles apply more naturally to services where AI API calls constitute the core logic and databases play a secondary role; applicability to DB-centric systems requires further investigation.
Unfavorable conditions. The principles are less applicable to: (a) large-scale enterprise systems with hundreds of tightly coupled services, where the duplication strategy (Principle 2) would generate unmanageable synchronization overhead; (b) safety-critical systems where the consistency guarantees of shared code are essential and the probabilistic nature of AI-generated code is unacceptable; (c) human-primary development where AI serves as an assistant rather than the primary author, making human cognitive optimization more relevant than LLM context optimization; and (d) algorithmically complex domains where deep abstraction hierarchies reflect genuine domain complexity that cannot be flattened without loss of expressiveness.
Incremental adoption in existing codebases. Although the principles in this paper were derived from a greenfield project, the majority of real-world projects are existing codebases (brownfield). The recommended starting point is a "new module isolation" strategy: when adding new feature modules, structure only those modules according to AI-Native principles (especially P1 directory isolation + P3 Zero-Context). A three-phase incremental expansion path is proposed: (1) Develop new features as isolated directories, minimizing dependencies without touching existing code (transition criterion: EIR for new modules is stably low). (2) Apply P4 contract metadata to new modules, making interfaces between new and existing modules explicit (transition criterion: interface calls between new and existing modules begin to occur). (3) Refactor the most frequently AI-agent-modified existing modules for P1 compliance (transition criterion: the module's monthly modification frequency ranks in the upper quartile) — modules with high modification frequency yield the greatest return on investment. This strategy connects naturally with the dual-mode architecture discussed in Section 7.2: existing code coexists as the "human-governed layer" while new modules constitute the "AI-governed layer" in a transitional form.
The generalizability of this framework must be validated through additional case studies; claims at the current stage are bounded by the preconditions met by Project-ST.
A central question raised by this work is whether AI-Native principles replace or complement established principles such as SOLID and DRY. Our analysis suggests a nuanced answer: conditional complementarity.
The AI-Native principles do not invalidate SOLID or DRY in absolute terms. Rather, they identify conditions under which the cost-benefit calculus of these principles shifts. DRY remains optimal when human developers are the primary code maintainers, when code duplication creates genuine consistency risks in domain logic, and when the system is expected to outlive the current AI tooling generation. Intentional Duplication becomes preferable when AI agents are the primary developers, when the duplicated code is infrastructure-level utility code (not domain logic), and when module isolation is a higher priority than code reuse.
This suggests a dual-mode architecture as a pragmatic path forward: organizations can maintain DRY principles for core domain logic and shared business rules (the "human-governed" layer) while adopting Intentional Duplication and Zero-Context principles for feature-level infrastructure code (the "AI-governed" layer). The boundary between these layers becomes an explicit architectural decision — one that should be documented and governed by the skill system.
Collateral effect on human code review. The Intentional Duplication strategy in AI-Native Architecture introduces a tension unique to human-AI collaboration processes. When AI agents perform security patches or batch modifications on duplicated utility code, they generate similar-but-not-identical changes across multiple directories, which can increase review fatigue for human code reviewers. Batch modifications that are low-cost for AI agents may impose repetitive, attention-dispersing review tasks on human reviewers. This asymmetry illustrates how AI-Native Architecture can shift collaboration costs to humans, suggesting the need for review support automation such as semantic diff summarization tools for duplicated files.
The economic viability of Intentional Duplication depends on a cost crossover: the point at which the cost of maintaining duplicated code (synchronization burden) exceeds the cost of maintaining shared references (context loading burden for AI agents). Several factors influence this crossover:
AI code generation cost trajectory. As LLM inference costs continue to decline (a trend that shows no sign of reversing), the cost of regenerating duplicated code approaches zero asymptotically. This trend favors duplication.
Context window expansion. As context windows expand from 200K to 1M+ tokens, the context loading cost of shared references decreases, potentially shifting the balance back toward shared code. However, the "Lost in the Middle" phenomenon [Liu et al., 2024] suggests that larger context windows do not automatically translate to better utilization — the degradation of attention in long contexts may persist even with expanded windows.
Hallucination rate reduction. As LLMs become more reliable, the hallucination cost of cross-file reasoning decreases, weakening the case for isolation through duplication. We anticipate that if hallucination rates drop below a critical threshold (which we cannot currently quantify), the Zero-Context Principle may become unnecessary for well-structured codebases.
Synchronization tooling. The development of automated synchronization tools — AI-driven utilities that detect and propagate changes across duplicated files — could dramatically reduce the cost of the duplication strategy. As observed in Section 5.4, the two-week delay in bug fix propagation across duplicated files concretely illustrates the need for such tools. Such tools would transform Intentional Duplication from an "accept the maintenance cost" strategy to an "automate the maintenance cost" strategy.
We acknowledge that the current study lacks sufficient quantitative evidence regarding the cost of code duplication; precise measurement of the cost crossover point remains an open empirical question. We propose these factors as variables in a cost model that practitioners can evaluate for their specific context, rather than prescribing a universal answer.
The low achievement rate of Principle 5 (40%) warrants deeper analysis. Two competing explanations exist:
Structural explanation. Maintaining a parallel specification layer that accurately reflects the runtime implementation is fundamentally difficult because it creates a synchronization problem with no automated enforcement mechanism. Unlike type systems, which the compiler enforces, or test suites, which CI pipelines verify, spec accuracy has no automated checkpoint. This explanation suggests that the principle is inherently limited without tooling investment.
Procedural explanation. The Project-ST team did not consistently enforce spec-first workflows, particularly during the modification phase of development. The spec-runtime drift was not inevitable but resulted from workflow discipline failures. This explanation suggests that the principle is achievable with better process enforcement.
Our analysis suggests that both factors contributed, but the structural factor is dominant. Even with perfect workflow discipline, the speed of AI-driven code generation creates a fundamental tension: the AI agent modifies implementation code faster than the spec can be updated (even if the spec update is part of the same workflow), because implementation changes often have cascading effects that the spec structure cannot anticipate. A promising mitigation is spec generation from code — inverting the spec-first pattern to have the AI agent automatically regenerate the spec from the current implementation after each modification cycle. This approach sacrifices the spec's role as a prescriptive document (what the code should do) but preserves its role as a descriptive entry point (what the code currently does), which may be sufficient for the working memory function. As a concrete implementation candidate, we suggest a pipeline that automatically extracts module-local contract slices from existing API specifications such as OpenAPI/Protocol Buffers and reflects the generated summaries in each module's spec file.
We organize threats to validity following the framework of Yin [2018] for case study research, supplemented by the guidelines of Wohlin et al. [2012] for software engineering experimentation.
Reverse engineering bias. The five principles were extracted through reverse engineering of a completed project by the first author, who was also involved in the project's architectural decisions. This dual role creates a risk of confirmation bias — the analyst may have identified patterns that confirm pre-existing beliefs about AI-Native Architecture rather than objectively characterizing the codebase structure. Mitigation: We cross-validated the extracted principles against the project's original design documents (Confluence design proposals). However, we acknowledge that these design documents were authored by members of the same team, limiting the independence of this validation. The cross-validation confirms intentionality of design choices but does not eliminate the risk that both the design and the reverse engineering share the same analytical blind spots. A stronger mitigation — independent replication by researchers not involved in the project — is planned for the multi-case extension. Additionally, each principle was required to meet the three validation criteria described in Section 5.2 (observability, motivation, distinctiveness).
Achievement measurement subjectivity. The achievement percentages (95%, 90%, 75%, 70%, 40%) involve qualitative judgment, particularly for ZCS (deciding whether a task was "successfully" completed) and SRDR (deciding whether a spec assertion is "accurate"). Mitigation: We defined operational measurement procedures (Section 5.3) and reported the specific criteria used. However, single-rater measurement remains a limitation. A planned multi-case extension will include inter-rater reliability assessment.
Causal inference limitation. The case study establishes correlation between the AI-Native principles and observed codebase properties but cannot establish causation. We cannot determine whether the principles caused improved AI agent performance or whether other factors (small project scale, experienced architect, specific AI model capabilities) were responsible. Mitigation: We propose controlled experiments (hypotheses H1, H2, H3) as future work to establish causal relationships. The current paper's contribution is the identification and formalization of the principles, not the proof of their causal efficacy.
Single-case generalization. The most significant threat to external validity is the derivation of a five-principle framework from a single case study. Project-ST is a small-to-medium event application with specific characteristics (time-bounded, moderate complexity, single-architect team) that may not generalize to other project types. Mitigation: We employ analytical generalization [Yin, 2018] rather than statistical generalization — the principles are proposed as a theoretical framework with explicitly stated preconditions, not as universal laws. Validating principles at a small scale before expanding is a normal path for establishing architectural principles. The Gang of Four design patterns originated in the Smalltalk ecosystem and became enterprise-system standards; microservices architecture began as an internal experiment at Netflix and proliferated across the industry. The single case in this study represents the first step on such an expansion path. We further delineate applicability conditions in Section 7.1 and plan additional case studies to strengthen generalizability.
Absence of comparison baseline. We explicitly acknowledge the absence of a comparison baseline. Project-ST was developed with AI-Native principles applied from the outset, so no pre-application state exists; before-and-after comparisons are planned for future controlled experiments.
Technology stack specificity. The case study is based on TypeScript/Fastify, a specific technology stack that may have influenced the observed patterns. The directory-based organization that enables Zero-Context may be more natural in TypeScript/Node.js ecosystems than in languages with package-based namespacing (e.g., Java, Kotlin). Mitigation: The principles are defined at the architectural level, not the language level. We hypothesize that they are applicable across technology stacks but acknowledge that the specific mechanisms for achieving them may vary.
AI model specificity. The case study was developed using Claude as the primary AI agent. Different LLM architectures may exhibit different cognitive characteristics (e.g., different context window utilization patterns, different hallucination tendencies), potentially affecting the relevance of specific principles. Mitigation: The principles are motivated by general LLM characteristics (context windows, hallucination, generation cost) shared across current foundation models, not by Claude-specific behaviors. However, we acknowledge that the quantitative achievement rates may vary across models.
Temporal validity. LLM capabilities are evolving rapidly. Advances in context window size (1M+ tokens), hallucination reduction, and agentic reasoning may alter the cost-benefit calculus underlying the principles. In particular, Principle 2 (Intentional Duplication) is most vulnerable to obsolescence if context windows become effectively unlimited and hallucination rates approach zero. Mitigation: We explicitly discuss this temporal dimension in Section 7.3 and frame the principles as conditional on the current state of LLM technology rather than as permanent prescriptions.
AI-Native terminology. The term "AI-Native Architecture" is not established in the academic literature. Our operational definition (Section 1) may not align with how the term comes to be understood by the broader community. Mitigation: We provide an explicit operational definition and avoid relying on intuitive interpretations of the term.
Metric construct validity. The proposed metrics (ZCS, BRI, DIR, CC, SRDR) are novel and have not been validated against external criteria. We cannot be certain that, for example, ZCS truly measures the "zero-context-ness" of a codebase rather than some confounded property such as module simplicity. Mitigation: We define each metric operationally and acknowledge the need for construct validation through convergent and discriminant validity analysis in future work.
Working memory analogy. The use of "working memory" to describe the spec file's function (Principle 5) is an analogy, not a theoretical claim. Human working memory [Baddeley, 2000] is a dynamic, capacity-limited cognitive system; the spec file is a static document. Over-interpreting this analogy could lead to design choices based on false parallels. Mitigation: We explicitly acknowledge the limitations of the analogy in Section 3.5 and use it solely as an explanatory device for the spec file's function of providing immediate, task-relevant context.
This paper has presented five architectural principles for AI-Native software development — Blast Radius Minimization, Intentional Duplication over Reference, Zero-Context Principle, Contract as Metadata, and Spec as AI Working Memory — derived through reverse engineering of an industrial project and grounded in the cognitive characteristics of LLM-based development agents.
We now revisit the four research questions posed in Section 1:
RQ1: Which aspects of established architectural principles become inadequate in AI-primary environments? Our analysis identifies three specific inadequacies. DRY's elimination of code duplication forces AI agents to trace cross-file references, consuming context window capacity and increasing hallucination risk (Section 3.2). Clean Architecture's layered abstractions require global mental model construction, which AI agents — lacking persistent memory across tasks — cannot perform (Section 3.3). Traditional architecture governance through static analysis operates on produced artifacts rather than the generative process, leaving AI agent behavior unconstrained (Section 4.4).
RQ2: How can AI-Native principles be formally defined, and what tradeoffs do they hold with established principles? We formalized five principles, each defined by purpose, invariant, motivation, and tradeoff (Section 3). The principles form a hierarchical dependency structure — a foundation layer (Blast Radius, Duplication), an emergent layer (Zero-Context), and an enhancement layer (Contract, Spec) — and stand in conditional complementarity with established principles rather than absolute opposition (Section 7.2).
RQ3: Can prompt-based workflows serve as an architecture governance mechanism? Our case study demonstrates that skills effectively encode and partially enforce architectural constraints through preconditions, invariants, and postconditions (Section 4.3). However, their enforcement is non-deterministic and circumventable, making them complementary to — not a replacement for — static analysis and automated verification (Section 4.4).
RQ4: What metrics can quantitatively measure AI-Native architectural conformance? We proposed five metrics (ZCS, BRI, DIR, CC, SRDR) with operational measurement procedures and a composite index (ANACI). Application to the Project-ST case yielded an overall conformance of 74%, demonstrating that the metrics are computable and interpretable for real codebases, though further validation across multiple cases is needed (Section 6).
Returning to our contributions: (1) the formalization of five principles with formal definitions and inter-principle dependencies (Section 3); (2) the introduction of prompt-based architecture governance with a skill-principle mapping matrix (Section 4); (3) an empirical case study with quantitative achievement measurements across all five principles (Section 5); and (4) five quantitative metrics with operational definitions and a composite conformance index (Section 6). Each contribution has been delivered, though all are conditioned on the single-case study limitation discussed in Section 8.
The case study of Project-ST provides empirical grounding, with an average principle achievement rate of 74%. The high achievement rates for Blast Radius Minimization (95%) and Intentional Duplication (90%) suggest that these foundational principles are both practically achievable and naturally emergent in AI-driven development. The lower achievement for Spec as Working Memory (40%) reveals a fundamental tension between the speed of AI code generation and the discipline required to maintain parallel specification layers — a tension that current tooling does not adequately address.
The introduction of prompt-based architecture governance through skills represents a novel contribution to the governance literature. While limited by non-deterministic enforcement and circumventability, skills provide a governance mechanism that operates at the process level — constraining how code is generated, not merely verifying what was generated — filling a gap that traditional static analysis cannot address.
We identify four directions for future research:
Multi-case validation. The most immediate priority is to validate the five principles across additional case studies spanning different project scales (enterprise systems), technology stacks (Kotlin/Spring Boot, Python/FastAPI), and AI agent models (GPT-4, Gemini). A minimum of three additional cases is needed to support cross-case analysis [Yin, 2018].
Controlled experiments. The three hypotheses proposed in this paper (H1: Context Isolation, H2: Duplication-Isolation Tradeoff, H3: Metadata-Driven Governance) require controlled experiments to establish causal relationships. We plan experiments where AI agents perform identical tasks on codebases structured according to AI-Native principles versus traditional architectures, measuring code quality, hallucination rate, and task completion accuracy.
Automated metric tooling. The current metrics require substantial manual measurement effort. Developing automated tools for computing ZCS (through sandboxed AI agent trials), BRI (through git log analysis), and CC/SRDR (through spec-code comparison scripts) would enable longitudinal tracking of AI-Native architectural conformance.
Spec generation from code. As discussed in Section 7.4, the low achievement of Principle 5 suggests the need for tooling that automatically generates or updates spec files from implementation code. This inversion of the spec-first pattern — from prescriptive to descriptive specifications — could preserve the working memory function while eliminating the synchronization burden. Integrating such generation into the skill-based governance workflow is a promising avenue. Furthermore, the complete implementation and empirical validation of the three-layer governance framework (skills + CI guardrails + metrics) is also planned as future work.
Systematic measurement of skill compliance rates. Given the non-deterministic nature of skill-based governance, a framework for systematically measuring the concordance between skill directives and actual agent behavior is needed. This would provide the foundation for quantitatively assessing the reliability of prompt-based governance.
The transition to AI-primary software development is accelerating. As this transition progresses, the architectural principles that guide software design must evolve accordingly. We offer the five AI-Native principles and the accompanying metrics as a starting point for this evolution — a framework to be tested, refined, and extended as the community accumulates experience with AI-driven development at scale.
Anthropic. 2025. Claude Code overview. Official Product Documentation. https://docs.anthropic.com/en/docs/claude-code/overview
Baddeley, A. 2000. The Episodic Buffer: A New Component of Working Memory? Trends in Cognitive Sciences 4, 11 (2000), 417--423.
Bass, L., Clements, P., and Kazman, R. 2021. Software Architecture in Practice (4th ed.). Addison-Wesley.
Bogard, J. 2018. Vertical Slice Architecture. https://www.jimmybogard.com/vertical-slice-architecture/
Brown, T.B., Mann, B., Ryder, N., et al. 2020. Language Models are Few-Shot Learners. In Advances in Neural Information Processing Systems (NeurIPS) 33, 1877--1901.
Chen, M., Tworek, J., Jun, H., et al. 2021. Evaluating Large Language Models Trained on Code. arXiv preprint arXiv:2107.03374.
Cockburn, A. 2005. Hexagonal Architecture. https://alistair.cockburn.us/hexagonal-architecture/
Cognition. 2024. Introducing Devin, the First AI Software Engineer. Cognition Labs Technical Blog.
Evans, E. 2003. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley.
Fowler, M. 2018. Refactoring: Improving the Design of Existing Code (2nd ed.). Addison-Wesley.
GitHub. 2023. The State of the Octoverse 2023. GitHub Annual Report.
Google. 2008. Protocol Buffers: Developer Guide. https://protobuf.dev/
Huang, L., Yu, W., Ma, W., et al. 2023. A Survey on Hallucination in Large Language Models: Principles, Taxonomy, Challenges, and Open Questions. arXiv preprint arXiv:2311.05232.
Hunt, A. and Thomas, D. 1999. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley.
Ji, Z., Lee, N., Frieske, R., et al. 2023. Survey of Hallucination in Natural Language Generation. ACM Computing Surveys 55, 12 (2023), 1--38.
Knodel, J. and Popescu, D. 2007. A Comparison of Static Architecture Compliance Checking Approaches. In Proceedings of the 6th Working IEEE/IFIP Conference on Software Architecture (WICSA), 12--21.
Knodel, J., Muthig, D., Haury, U., and Meier, G. 2006. Architecture Compliance Checking -- Experiences from Successful Technology Transfer to Industry. In Proceedings of the 12th European Conference on Software Maintenance and Reengineering (CSMR), 117--126.
Liu, N.F., Lin, K., Hewitt, J., et al. 2024. Lost in the Middle: How Language Models Use Long Contexts. Transactions of the Association for Computational Linguistics 12 (2024), 157--173.
Martin, R.C. 2003. Agile Software Development: Principles, Patterns, and Practices. Prentice Hall.
Martin, R.C. 2008. Clean Code: A Handbook of Agile Software Craftsmanship. Prentice Hall.
Martin, R.C. 2017. Clean Architecture: A Craftsman's Guide to Software Structure and Design. Prentice Hall.
Meyer, B. 1992. Applying "Design by Contract." Computer 25, 10 (1992), 40--51.
Millett, S. 2015. Patterns, Principles, and Practices of Domain-Driven Design. Wrox.
Peng, S., Kalliamvakou, E., Cihon, P., and Demirer, M. 2023. The Impact of AI on Developer Productivity: Evidence from GitHub Copilot. arXiv preprint arXiv:2302.06590.
Richardson, C. 2018. Microservices Patterns: With Examples in Java. Manning.
Ross, S.I., Martinez, F., Houde, S., et al. 2023. The Programmer's Assistant: Conversational Interaction with a Large Language Model for Software Development. In Proceedings of the 28th International Conference on Intelligent User Interfaces (IUI), 491--514.
SmartBear. 2021. OpenAPI Specification v3.1.0. https://spec.openapis.org/oas/v3.1.0
Stack Overflow. 2025. 2025 Developer Survey. https://survey.stackoverflow.co/2025/
Svyatkovskiy, A., Deng, S.K., Fu, S., and Sundaresan, N. 2020. IntelliCode Compose: Code Generation Using Transformer. In Proceedings of the 28th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering (ESEC/FSE), 1433--1443.
Terra, R., Valente, M.T., Czarnecki, K., and Bigonha, R.S. 2015. Recommending Refactorings to Reverse Software Architecture Erosion. In Proceedings of the 16th European Conference on Software Maintenance and Reengineering (CSMR), 335--340.
Vaithilingam, P., Zhang, T., and Glassman, E.L. 2022. Expectation vs. Experience: Evaluating the Usability of Code Generation Tools Powered by Large Language Models. In Proceedings of the CHI Conference on Human Factors in Computing Systems Extended Abstracts (CHI EA), 1--7.
Wei, J., Wang, X., Schuurmans, D., et al. 2022. Chain-of-Thought Prompting Elicits Reasoning in Large Language Models. In Advances in Neural Information Processing Systems (NeurIPS) 35, 24824--24837.
Wohlin, C., Runeson, P., Host, M., Ohlsson, M.C., Regnell, B., and Wesslen, A. 2012. Experimentation in Software Engineering. Springer.
Yang, J., Jimenez, C.E., Wettig, A., et al. 2024. SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering. arXiv preprint arXiv:2405.15793.
Yin, R.K. 2018. Case Study Research and Applications: Design and Methods (6th ed.). SAGE Publications.
Ziegler, A., Kalliamvakou, E., Li, X.A., et al. 2022. Productivity Assessment of Neural Code Completion. In Proceedings of the 6th ACM SIGPLAN International Symposium on Machine Programming (MAPS), 21--29.