ASAASA Standard

The ASA Manifesto

Why an architecture standard for AI-generated code exists.

The ASA Manifesto

Why an architecture standard for AI-generated code exists.

Background

AI coding assistants generate code fast. But without structural rules, each generation adds complexity that compounds over time:

  • New code contradicts existing patterns
  • Business logic spreads across files without clear ownership
  • Dependencies form implicitly between unrelated features
  • Custom implementations get overwritten during regeneration

The result is a codebase that becomes progressively harder to modify, test, and reason about. This is not a tooling problem — it is a structural problem. ASA defines the architectural rules that prevent it.

The Structural Failures ASA Addresses

1. Vendor and Knowledge Lock-In

When architecture is implicit (exists only in developers' heads), switching teams or vendors requires re-learning the entire system. ASA makes architecture explicit: every feature has a human-readable specification and a machine-readable contract. Knowledge lives in the codebase, not in individuals.

2. Development Velocity Decay

Without isolation boundaries, changes in one feature break unrelated features. Research shows low-quality code takes 124% longer to resolve issues and creates 9x more unpredictability in delivery timelines (Tornhill & Borg, 2022). ASA enforces strict feature isolation to prevent cross-contamination.

3. The Full Rewrite Problem

When structural debt accumulates beyond a threshold, incremental improvement becomes impractical and teams face costly rewrites. ASA enables incremental regeneration — individual slices can be rewritten without touching the rest of the system.

What ASA Is

ASA is an architectural standard — a set of rules for how AI-generated code should be organized.

It defines:

  • How features are isolated (Atomic Slices)
  • How they communicate (Explicit Contracts)
  • How they are regenerated safely (Deterministic Regeneration)

ASA is comparable to REST (for APIs) or the Twelve-Factor App (for cloud services). It is a design discipline, not a product.

The Four Core Principles

ASA is built on four non-negotiable principles. See Core Principles for the full specification.

1. Determinism

Every ASA operation produces identical output for identical input. No randomness, no heuristics, no AI inference in the core pipeline.

2. Zero Magic

ASA does exactly what you tell it. No hidden behavior, no automatic assumptions, no context-dependent defaults.

3. Boundary Enforcement

Slices are isolated units. They cannot import from other slices. Cross-domain dependencies are forbidden and caught by the linter.

# FORBIDDEN — cross-slice import
from domains.billing.invoice import calculate_total

# ALLOWED — shared module import
from shared.utils.calculator import calculate_total

4. Marker-Based Preservation

When a specification changes, the slice regenerates predictably. Custom code is preserved via explicit markers:

# === BEGIN USER CODE ===
def execute(self, request: LoginRequest) -> LoginResponse:
    user = self.repo.get_user_by_email(request.email)
    return LoginResponse(jwt_token=generate_jwt(user.id))
# === END USER CODE ===

The structure regenerates. User logic survives.

Slice Structure

Every feature is a self-contained directory with a predictable structure:

domains/auth/login/
├── slice.spec.md        # Human-readable specification
├── slice.contract.json  # Machine-readable contract
├── handler.py           # API endpoint
├── service.py           # Business logic
├── repository.py        # Data access
└── schemas.py           # Data models

One operation = one directory. Everything for login — and nothing else — lives here.

What ASA Does Not Do

ASA does not:

  • Replace developers with AI
  • Automatically generate correct code
  • Eliminate the need for code review
  • Work without human oversight

ASA is a structural safety mechanism. It makes AI-generated code maintainable. It does not make AI infallible.

The Standard vs. Implementations

ASA (the standard) defines the rules — slice structure, boundary enforcement, contract format, regeneration semantics. The standard is language-agnostic.

Implementations are tools that enforce and automate ASA rules for specific languages and frameworks. The specification targets Python (FastAPI/Pydantic). Other implementations can follow the same standard for different stacks.

See the ASA Standard for the specification.

Adoption

ASA is designed for incremental adoption. You do not migrate an existing codebase — you apply ASA rules to new features and gradually extend coverage.

Step 1: Learn the standard

Step 2: Apply to new features

  • Structure new features as atomic slices
  • Define specifications and contracts
  • Enforce import boundaries

Step 3: Extend coverage

  • Refactor existing features into slices incrementally
  • Add boundary enforcement to CI pipeline
  • Monitor structural compliance over time

Design Goals

ASA is designed for a future where:

  • AI generates the majority of new code
  • Developers focus on architecture, business logic, and verification
  • Codebases remain maintainable across years and team changes
  • Switching tools or vendors does not require starting over

This requires architectural standards, not just better tools.

Further Reading

ASA v1.0.2 — An open standard for AI-generated software architecture.

No vendor. No license. No cost.