DEV Community: vibecodiq

Delivery Slowdown in AI-Generated Codebases — Why Every Sprint Takes Longer Than the Last

vibecodiq — Fri, 10 Apr 2026 16:15:12 +0000

"Six months ago, we shipped features in two days. Now a single change takes two weeks."

If you've built an application with AI tools — Cursor, Lovable, Bolt.new, Replit, v0 — and you're past the first few months of development, there's a good chance your delivery speed has declined. Not gradually. Sharply.

This is not a team problem. It's a structural one.

The Mechanism: Verification Debt

Every AI session optimizes for the immediate task. "Fix the checkout bug" — the fix goes where the symptom is. "Add email notification on purchase" — added inline in the payment handler.

Each session is locally correct. But none of them maintain awareness of the broader codebase structure.

The result: files that started as single-purpose now handle multiple concerns. Business logic scattered across layers. A dependency graph where everything is connected to everything.

This creates verification debt — the growing cost of verifying that a change doesn't break something unexpected.

VERIFICATION DEBT COMPOUND CURVE

  Time per feature (days)
  |
  10|                                    *  *
   8|                               *
   6|                          *
   5|                     *
   4|                *
   3|           *
   2|      *
   1|  *
   0+--+--+--+--+--+--+--+--+--+--+--+-
    M1 M2 M3 M4 M5 M6 M7 M8 M9 M10

  Each new feature adds coupling.
  Each coupling point adds verification overhead
  to every future change.

Why It Compounds

The compound rate is approximately 30-40% per quarter in structurally uncoupled codebases. Here's why:

Month 1-3: Small codebase. Blast radius is obvious. One developer ships independently. Features take 1-2 days.

Month 4-6: Codebase has grown. Files are shared across features. Every change requires checking what else it affects. PR review time doubles because reviewers can't predict side effects. Features take 3-5 days.

Month 7-9: Team grows to handle the backlog. But more developers in a coupled codebase doesn't create parallelism — it creates coordination overhead. Two developers modify the same 600-line utility file in the same sprint. Merge conflicts. Re-reviews. Features take 5-10 days.

Month 10+: The team has doubled. Total output has dropped. 40% of developer time goes to merge conflicts, coordination meetings, and verifying side effects.

Measure It

1. File churn concentration

git log --since="30 days ago" --pretty=format:"%H" | while read hash; do
  git diff-tree --no-commit-id --name-only -r $hash
done | sort | uniq -c | sort -rn | head -10

If the same files appear in every commit, your codebase is structurally coupled. Changes can't be isolated because domain boundaries don't exist.

2. Coupling density

git log --since="30 days ago" --pretty=format:"%H" | while read hash; do
  git diff-tree --no-commit-id --name-only -r $hash | wc -l
done | awk '{sum+=$1; n++} END {print "Avg files per commit:", sum/n}'

Healthy: 2-4 files per commit (changes stay within one domain).
Warning: 5-8 files (cross-domain coupling).
Critical: 8+ files (no structural boundaries exist).

3. Verification bottleneck files

find src/ -name "*.ts" -o -name "*.tsx" | xargs wc -l | \
  awk '$1 > 300 {print}' | sort -rn | head -10

Files above 300 lines are verification bottlenecks. Every change to a large file requires reviewing the entire file because the internal blast radius is the whole file.

4. PR review time trend

If you use GitHub:

gh pr list --state merged --limit 50 --json createdAt,mergedAt | \
  jq '.[] | {days: (((.mergedAt | fromdateiso8601) - (.createdAt | fromdateiso8601)) / 86400)}'

Compare the average from your first 25 merged PRs vs your last 25. If review time has increased significantly, verification debt is compounding.

The Myth: "We Just Need More Developers"

Adding developers to a structurally coupled codebase makes delivery slower, not faster. Each new developer adds coordination overhead without reducing verification debt.

The research confirms it: PR review times in AI-generated codebases increase by 91% between month 3 and month 9. The cause is not team size — it's structural coupling.

The Structural Fix

The fix is not process improvement, better planning, or more standups. It's structural:

Bounded domain isolation — each business domain owns its files. Cross-domain imports are forbidden by automated rules.
Enforced import boundaries — a boundary linter prevents one domain from reaching into another. Violations are caught before merge, not after.
Known blast radius — when domains are isolated, every change has a predictable scope. PR reviews become fast because the reviewer knows exactly what could be affected.
Parallel delivery — isolated domains mean developers work independently. No merge conflicts on shared files. No coordination meetings about who's touching what.

The goal: delivery time stays flat as the codebase grows. Not because of better developers — because of better structure.

Based on ASA (Atomic Slice Architecture) — an open architecture standard for AI-generated software that enforces these boundaries automatically.

Architecture Drift in AI-Generated Codebases — How Clean Layers Dissolve One Prompt at a Time

vibecodiq — Fri, 03 Apr 2026 16:58:21 +0000

"The architecture changed. Nobody decided it should."

Architecture drift is the #1 root cause of structural failure in AI-generated codebases. It happens silently, one prompt at a time, and by the time it's visible, the cost of fixing it has compounded significantly.

The Mechanism

Each AI session optimizes for the immediate task without maintaining awareness of the broader architecture.

BOUNDARY EROSION TIMELINE

  Month 1:  API --> Business --> Data
            (clean layers, clear direction)

  Month 4:  API <-> Business <-> Data
            (boundaries crossed, bidirectional)

  Month 8:  API <-> Business <-> Data
              \      |  X  |      /
               \---> UI <---/
            (boundaries dissolved, spaghetti)

Session 1: "Create a user service" — clean module with clear boundaries.
Session 15: "Fix the checkout bug" — fix goes in the route handler because that's where the symptom is.
Session 30: "Add email on purchase" — notification logic added inline in the payment handler.
Session 50: Business logic lives in 5 layers. Nobody can draw the architecture from memory.

Detection

1. Layer Violation Check

# Database queries in UI components (should be 0)
grep -rn "prisma\|supabase\|\.from(" --include="*.tsx" src/components/ src/app/ | wc -l

# Business logic in route handlers (should be minimal)
grep -rn "if.*price\|calculate\|validate" --include="*.ts" src/app/api/ | wc -l

2. Import Direction Analysis

# Files with the most imports (potential boundary violators)
grep -rn "import.*from" --include="*.ts" --include="*.tsx" src/ | \
  awk -F: '{print $1}' | sort | uniq -c | sort -rn | head -10

In a clean architecture, import counts should be low and directional (API imports Business, Business imports Data, never the reverse).

3. Business Logic Scattering

# Where does "payment" logic live?
grep -rln "payment\|stripe\|checkout\|price" \
  --include="*.ts" --include="*.tsx" src/ | \
  awk -F/ '{print $1"/"$2}' | sort | uniq -c | sort -rn

If a single business concept appears in 4+ directories, the architecture has drifted.

4. Convention Drift

# Check for inconsistent patterns
grep -rn "export default function\|export function\|export const" \
  --include="*.ts" --include="*.tsx" src/ | \
  awk -F: '{print $3}' | sort | uniq -c | sort -rn

Multiple export patterns suggest the AI changed conventions mid-project.

The Compounding Cost

Feature delivery cost over time:

  Month 1:  2 days   (clean architecture)
  Month 4:  4 days   (50% archaeology)
  Month 8:  8 days   (75% archaeology)
  Month 12: 12+ days (mostly archaeology)

For a 3-person team at $150/hour, the velocity difference between month 1 and month 8 represents ~$36,000/month in wasted capacity.

Why Sprints Don't Fix This

Architecture drift is a compound structural condition. Sprints are time-boxed delivery cycles. They operate at different scales:

Sprint: "Fix this module" — fixes surface symptoms
Structural intervention: "Re-establish all boundaries" — fixes root cause

Without enforcement, the next sprint re-introduces the same violations.

The Structural Fix

Step 1: Map Current State

# Generate dependency graph
npx madge --image graph.svg --extensions ts,tsx src/

# List all circular dependencies
npx madge --circular --extensions ts,tsx src/

Step 2: Define Target Architecture

Document the intended layer structure:

src/
  app/           # Routing only (Next.js pages/API routes)
  modules/       # Business logic (one module per domain)
    auth/
    payments/
    users/
    notifications/
  shared/        # Cross-cutting utilities
    types/
    utils/
    lib/

Rule: app/ imports modules/. modules/ imports shared/. Never the reverse.

Step 3: Migrate Incrementally

For each layer violation:

Identify the misplaced logic
Create the correct target module
Move the logic
Update imports
Verify no regressions

Step 4: Enforce Boundaries

// eslint.config.js — import boundary enforcement
export default [
  {
    rules: {
      'import/no-restricted-paths': ['error', {
        zones: [
          // modules/ cannot import from app/
          { target: './src/modules', from: './src/app' },
          // shared/ cannot import from modules/ or app/
          { target: './src/shared', from: './src/modules' },
          { target: './src/shared', from: './src/app' },
        ]
      }]
    }
  }
];

Step 5: CI/CD Enforcement

# .github/workflows/architecture.yml
name: Architecture Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: Circular dependency check
        run: npx madge --circular --extensions ts,tsx src/ && echo "PASS" || (echo "FAIL: circular deps" && exit 1)
      - name: Lint (includes boundary rules)
        run: npm run lint

The Result

After structural intervention + enforcement:

Layer violations: blocked at CI
Circular dependencies: prevented
Business logic: centralized in domain modules
Feature delivery: predictable again (back to ~2 days for standard features)

Architecture drift is the root cause. Boundary enforcement is the structural fix.

This is part of the AI Chaos series — a structural analysis of failure patterns in AI-generated codebases. Based on ASA (Atomic Slice Architecture) — an open architecture standard for AI-generated software.

Resources

ASA Standard — the open specification
GitHub — source, examples, documentation
Vibecodiq — structural diagnostics for AI-built apps

Regression Fear in AI-Generated Codebases — Why Every PR Feels Like a Gamble

vibecodiq — Sat, 28 Mar 2026 09:31:35 +0000

"Every PR is a gamble. We just don't know what it'll break."

If your team has stopped merging on Fridays — or Thursdays — you're experiencing regression fear. Not a psychological problem. A structural one.

This post explains the mechanism, how to measure it, and the fix.

The Mechanism: Unbounded Blast Radius

In a well-structured codebase, a change in module A affects module A and its direct dependents. The blast radius is bounded and predictable.

In most AI-generated codebases past month 3, the blast radius is unbounded:

BLAST RADIUS MAP

  Change: update pricing display

  PREDICTED impact:        ACTUAL impact:
  pricing/ui.tsx           pricing/ui.tsx
                           payments/checkout.ts
                           users/dashboard.tsx
                           notifications/email.ts

  predicted: 1 file        actual: 4 files
  blast radius: unbounded

The mechanism: AI generates code that works by taking the shortest path. That shortest path often creates implicit dependencies — shared state, cross-module imports, business logic in unexpected places. Each implicit dependency extends the blast radius of every future change.

Detection: Three Measurements

1. Regression Ratio

# Total commits in last 30 days
TOTAL=$(git log --oneline --since="30 days ago" | wc -l)

# Fix/revert commits
FIXES=$(git log --oneline --since="30 days ago" \
  --grep="fix\|revert\|hotfix\|broken\|rollback" | wc -l)

echo "Regression ratio: $(( FIXES * 100 / TOTAL ))%"

What the number means:

0-10%: Normal. Minor regressions caught early.
10-20%: Warning. Coupling is growing.
20%+: Critical. One in five commits fixes something a previous commit broke.

2. Cursed Files

git log --since="90 days ago" --pretty=format: --name-only \
  | sort | uniq -c | sort -rn | head -10

These are the files that appear in the most commits. In AI-generated codebases, the top 3 files are usually:

The largest files (500+ lines, multiple domains)
The files where regressions originate
The files nobody wants to touch

3. Merge Velocity Trend

# Commits per week for last 12 weeks
for i in $(seq 0 11); do
  START=$(date -d "$((i+1)) weeks ago" +%Y-%m-%d)
  END=$(date -d "$i weeks ago" +%Y-%m-%d)
  COUNT=$(git log --oneline --since="$START" --until="$END" | wc -l)
  echo "Week -$i: $COUNT commits"
done

A declining trend means the team is merging less frequently — not because they're doing less work, but because each merge is riskier.

Why "More QA" Doesn't Fix This

QA catches regressions after they happen. It does not prevent the architectural condition that causes them.

The regression cycle:

Developer ships change. Passes unit tests.
QA finds regression in unrelated area. Files bug.
Developer context-switches back. Debugs for hours.
Fix introduces new side effect. Cycle repeats.

Adding more QA people makes the cycle faster — not shorter. The root cause remains: unbounded blast radius.

The Cost

A team of three developers at $150/hour loaded:

30% of features cause regressions = 2.4/month
6 hours average to find, diagnose, fix each
$2,160/month = $25,920/year in regression costs alone

Plus velocity decay:

Month 3:  8 features/month (productive)
Month 6:  5 features/month (fear + overhead)
Month 9:  3 features/month (regression management dominates)

The Structural Fix: Bounded Blast Radius

Step 1: Identify Cursed Files

Run the cursed files detection above. The top 3 files are your decomposition targets.

Step 2: Map Implicit Dependencies

For each cursed file, trace what depends on it:

# Find all files that import from the cursed file
grep -rln "from.*cursedFile\|require.*cursedFile" \
  --include="*.ts" --include="*.tsx" src/

Step 3: Decompose by Domain

Split cursed files by business domain. Each new file has one responsibility and explicit imports.

Step 4: Enforce One-Directional Dependencies

# Verify no circular dependencies exist
npx madge --circular --extensions ts,tsx src/

After decomposition, the dependency graph should be a tree, not a web.

Step 5: Add Regression Tests for Boundaries

For each module boundary, add a test that verifies the contract:

// Test that pricing module doesn't depend on notification module
import { getPrice } from '@/modules/pricing';

test('getPrice returns number without side effects', () => {
  const result = getPrice({ plan: 'pro', period: 'monthly' });
  expect(typeof result).toBe('number');
  // No notifications sent, no user state changed
});

Step 6: CI/CD Enforcement

Block merges that:

Introduce circular dependencies
Exceed file size thresholds
Miss test coverage on boundary contracts

The Result

After structural enforcement, the blast radius of every change is bounded and predictable. QA becomes verification — confirming bounded changes work as expected — not discovery of unrelated breakage.

Regression fear disappears. Not because the team is braver. Because the architecture makes cross-module leakage structurally impossible.

Resources

ASA Standard — the open specification
GitHub — source, examples, documentation
Vibecodiq — structural diagnostics for AI-built apps

Hidden Technical Debt in AI-Generated Codebases — Why Working Code Gets Expensive to Change

vibecodiq — Fri, 20 Mar 2026 18:27:11 +0000

"It worked fine for six months. Then every change became expensive."

Your AI-generated app is live. Customers are paying. The dashboard looks fine. But every feature takes 2-3x longer than it should, and nobody can explain why.

This post explains what hidden technical debt looks like in AI-generated codebases, how to detect it, and the structural decomposition that fixes it.

What Makes AI-Generated Debt "Hidden"

Traditional technical debt is visible — you know you're cutting corners. AI-generated technical debt is invisible — the shortcuts happen at generation time and nobody notices.

Here's the mechanism:

Session 1:  User service created (clean, 80 lines)
Session 15: Pricing logic added to user service ("it needs user data")
Session 30: Notification logic added to pricing flow ("notify on purchase")
Session 45: User service is now 600 lines, handles 4 domains
Session 60: "Why does adding a referral system take 3 weeks?"

Each session makes a locally reasonable decision. The AI puts code where the context is closest. Nobody checks whether the global architecture remains coherent.

DOMAIN SCATTERING MAP

  userService.ts (620 lines)
    - user logic         ████████░░  40%
    - pricing logic      ████░░░░░░  20%
    - notifications      ███░░░░░░░  15%
    - audit logging      ███░░░░░░░  15%
    - shared state       ██░░░░░░░░  10%

  AFTER DECOMPOSITION:
    users/userService.ts          (120 lines)
    pricing/priceCalculator.ts    (90 lines)
    notifications/notifier.ts     (70 lines)
    billing/auditLogger.ts        (60 lines)

  1 file x 5 domains --> 4 files x 1 domain each

Detection: Three Measurements

1. File Size Distribution

find src -name "*.ts" -o -name "*.tsx" | xargs wc -l | sort -rn | head -20

What to look for:

Files over 500 lines = almost certainly multi-domain
Files over 800 lines = critical structural risk
If your top 10 files average over 400 lines, the architecture has drifted

2. Domain Scattering

Pick a core business concept (e.g., "pricing"). Count how many files contain it:

grep -rln "price\|pricing\|amount\|cost\|subscription\|billing" \
  --include="*.ts" --include="*.tsx" src/ | wc -l

What the number means:

1-3 files: Clean. Pricing logic is centralized.
4-7 files: Warning. Logic is scattering.
8+ files: Critical. Pricing decisions happen everywhere.

3. Shared Mutable State

# Count module-level mutable variables
grep -rn "^let \|^var \|export let\|export var" \
  --include="*.ts" --include="*.tsx" src/ | wc -l

Each one is a hidden coupling point. A change in one function silently affects every other function that reads or writes the same variable.

4. Feature Estimate Accuracy

Look at your last 10 features or bug fixes. Calculate:

accuracy = (actual_time / estimated_time)

If the average is above 2.0, the architecture is fighting you. Hidden dependencies are making scope unpredictable.

Why "Refactor Later" Doesn't Work

Technical debt has interest rates. AI-generated codebases have higher interest rates because:

Shortcuts are invisible. Nobody chose to put pricing logic in the user service. The AI did it because that's where the context was.
Coupling compounds. Every feature added on top of a coupled module increases the coupling. By month 6, you can't change pricing without touching users, notifications, and payments.
The window closes. Refactoring in month 3 is a focused sprint. Refactoring in month 9 is a rewrite. The complexity grows faster than capacity.

Month 3:  Refactoring cost = 2-3 days
Month 6:  Refactoring cost = 2-3 weeks
Month 9:  Refactoring cost = "we need to rewrite"
Month 12: "We're stuck"

The Structural Fix: Decomposition + Enforcement

Step 1: Domain Audit

Map every file to its primary business domain:

# Create a domain map
for file in $(find src -name "*.ts" -o -name "*.tsx"); do
  echo "$file: $(head -5 $file | grep -o 'import.*from' | head -3)"
done

Identify files that serve multiple domains (these are the decomposition targets).

Step 2: Extract Domain Modules

For each multi-domain file:

Identify the distinct responsibilities
Create separate module files for each domain
Move logic to the appropriate module
Update imports

// BEFORE: src/services/userService.ts (600 lines, 4 domains)
export function getUser() { ... }
export function calculatePrice() { ... }    // pricing domain
export function sendNotification() { ... }  // notification domain
export function generateInvoice() { ... }   // billing domain

// AFTER: 4 focused modules
// src/modules/users/userService.ts
// src/modules/pricing/priceCalculator.ts
// src/modules/notifications/notificationService.ts
// src/modules/billing/invoiceGenerator.ts

Step 3: Eliminate Shared Mutable State

Replace module-level mutable variables with:

Function parameters (explicit data flow)
Immutable state containers
Event-based communication between modules

// BEFORE: shared mutable state
let currentUser: User | null = null;

export function setUser(user: User) { currentUser = user; }
export function getPrice() { return currentUser?.plan.price; } // hidden dependency

// AFTER: explicit data flow
export function getPrice(user: User): number {
  return user.plan.price;
}

Step 4: Enforce Boundaries

Add automated checks that prevent re-coupling:

// package.json script
{
  "scripts": {
    "check:boundaries": "npx madge --circular --extensions ts,tsx src/",
    "check:size": "find src -name '*.ts' | xargs wc -l | awk '$1 > 500 {print \"WARN:\", $0}'",
    "precommit": "npm run check:boundaries && npm run check:size"
  }
}

Step 5: Monitor Trend

Track these metrics weekly:

Number of files over 500 lines (should decrease or stay flat)
Number of circular dependencies (should be 0)
Feature estimate accuracy (should improve toward 1.0-1.5x)

The Result

After structural decomposition, the cost of change becomes predictable. Adding a referral system touches the referral module — not pricing, users, notifications, and billing. Feature estimates become accurate because scope is bounded.

Hidden technical debt doesn't require a rewrite. It requires structural decomposition and ongoing enforcement.

Resources

ASA Standard — the open specification
GitHub — source, examples, documentation
Vibecodiq — structural diagnostics for AI-built apps

Security Debt in AI-Generated Codebases — A Structural Problem, Not a Tooling Problem

vibecodiq — Fri, 13 Mar 2026 15:54:46 +0000

"We passed the security review. Six weeks later, we found auth bypasses in three endpoints."

Research shows 45% of AI-generated code contains security vulnerabilities. Not because AI is malicious — because security is a system-level property, and AI generates code at the function level.

This post breaks down the structural mechanism behind security debt in AI-generated codebases, how to detect it, and the enforcement model that prevents it.

The Structural Mechanism

AI produces code that works. "Works" means it handles expected input correctly. It does not mean it handles unexpected input safely.

Authentication, authorization, input validation — these are constraints that must be enforced globally, not function by function.

Here's what happens in practice:

Session 1:  Auth middleware created for /api/users
Session 12: New route /api/billing added — no auth middleware applied
Session 25: Frontend validation added — backend accepts raw input
Session 38: API key hardcoded in utils/stripe.ts for "quick fix"
Session 50: Three unprotected endpoints, no input validation on backend

Each session solves the immediate problem. Nobody checks whether the global security constraints are maintained.

ROUTE COVERAGE MAP

  /api/users       [AUTH]  protected
  /api/billing     [AUTH]  protected
  /api/webhooks    [    ]  UNPROTECTED
  /api/reports     [    ]  UNPROTECTED
  /api/admin       [AUTH]  protected
  /api/export      [    ]  UNPROTECTED
  /api/settings    [    ]  UNPROTECTED

  coverage: 3/7 routes = 43%
  structural gap: 4 unprotected endpoints
  attack surface: growing with every AI session

Detection Scripts

1. Security-Related TODOs

grep -rn "TODO\|FIXME\|HACK" --include="*.ts" --include="*.tsx" src/ \
  | grep -i "auth\|token\|valid\|secur\|password\|api.key\|secret"

These are security decisions the AI deferred. Each one is a structural gap.

2. Auth Middleware Coverage

Count your routes:

grep -rn "router\.\|app\.get\|app\.post\|app\.put\|app\.delete\|export.*GET\|export.*POST\|export.*PUT\|export.*DELETE" \
  --include="*.ts" --include="*.tsx" src/ | wc -l

Count your auth references:

grep -rn "middleware\|protect\|auth\|guard\|requireAuth\|withAuth" \
  --include="*.ts" --include="*.tsx" src/ | wc -l

If routes significantly exceed auth references, some endpoints are unprotected.

3. Hardcoded Secrets

grep -rn "sk_live\|sk_test\|api_key\|apiKey\|secret\|password" \
  --include="*.ts" --include="*.tsx" --include="*.env*" src/ \
  | grep -v "node_modules\|\.env\.example"

Any match outside .env files is a structural vulnerability.

4. Frontend-Only Validation

# Find validation in frontend components
grep -rn "required\|pattern=\|minLength\|maxLength\|validate" \
  --include="*.tsx" src/components/ src/app/ | wc -l

# Find validation in API routes/handlers
grep -rn "zod\|yup\|joi\|validate\|sanitize\|escape" \
  --include="*.ts" src/api/ src/server/ src/lib/ | wc -l

If frontend validation count >> backend validation count, input reaches the server unvalidated.

Why "Better Prompts" Don't Fix This

"Just tell the AI to write secure code" sounds reasonable. It doesn't work structurally.

The AI can generate a secure authentication middleware. But it doesn't enforce that middleware globally. The next session adds a new route without it. The session after that adds frontend validation but skips the backend.

Security is an architecture property. It requires global enforcement — every route, every input, every dependency. AI optimizes locally. The gap between "works" and "secure" grows with every session.

The Structural Fix: Enforcement Model

Step 1: Middleware-First Architecture

Every route is protected by default. Exceptions are explicitly declared.

// middleware.ts — applies to ALL routes
export function middleware(request: NextRequest) {
  const publicPaths = ['/api/health', '/api/auth/login'];

  if (publicPaths.includes(request.nextUrl.pathname)) {
    return NextResponse.next();
  }

  const token = request.headers.get('authorization');
  if (!token || !verifyToken(token)) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/api/:path*',
};

The key: protection is the default. Public access is the exception that must be explicitly declared.

Step 2: Input Validation at the Boundary

Every API endpoint validates input before processing:

import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  role: z.enum(['user', 'admin']),
});

export async function POST(request: NextRequest) {
  const body = await request.json();
  const parsed = CreateUserSchema.safeParse(body);

  if (!parsed.success) {
    return NextResponse.json(
      { error: 'Invalid input', details: parsed.error.issues },
      { status: 400 }
    );
  }

  // Only validated data reaches business logic
  return createUser(parsed.data);
}

Step 3: Automated Enforcement

Add CI/CD checks that block insecure code from merging:

# .github/workflows/security.yml
name: Security Checks
on: [pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Check for hardcoded secrets
      - name: Secret scan
        run: |
          if grep -rn "sk_live\|sk_test\|apiKey.*=.*['\"]" \
            --include="*.ts" --include="*.tsx" src/; then
            echo "FAIL: Hardcoded secrets detected"
            exit 1
          fi

      # Check for unprotected routes
      - name: Auth coverage check
        run: |
          ROUTES=$(grep -rn "export.*GET\|export.*POST" \
            --include="*.ts" src/app/api/ | wc -l)
          AUTH=$(grep -rn "requireAuth\|withAuth\|middleware" \
            --include="*.ts" src/app/api/ | wc -l)
          echo "Routes: $ROUTES, Auth refs: $AUTH"

      # Dependency audit
      - name: Dependency vulnerability check
        run: npm audit --production --audit-level=high

Step 4: Dependency Audit

npm audit --production

Run this on every merge. AI pulls in dependencies because they solve the immediate problem — not because they're security-reviewed.

The Result

After structural enforcement, security becomes a system property rather than a per-developer responsibility. New routes are protected by default. Input is validated at the boundary. Secrets never reach the codebase. Dependencies are audited automatically.

Security debt is a structural condition. The fix is structural enforcement.

Resources

ASA Standard — the open specification
GitHub — source, examples, documentation
Vibecodiq — structural diagnostics for AI-built apps

Comprehension Debt — When Your AI-Generated Codebase Outgrows Your Understanding

vibecodiq — Fri, 06 Mar 2026 14:11:37 +0000

"I'm running a SaaS on code I don't fully understand."

A founder told us this during our first call. Not ashamed. Just honest. The product had 80 paying users, revenue was growing, and the AI had built most of the codebase across 70+ sessions.

But when a customer reported a billing error, nobody could trace where pricing logic actually lived.

This post explains what comprehension debt is, how to measure it, and how to fix it structurally.

What Is Comprehension Debt

Comprehension debt is what happens when code is generated faster than it can be understood.

AI produces working software. But "working" and "understood" are not the same thing. Each AI session solves the immediate task without asking whether the solution is structurally coherent with what came before.

By month 4, the codebase has implicit conventions that nobody explicitly chose:

Naming patterns that shifted mid-project
Business logic in unexpected locations
Functions that do three things
Files that nobody can summarize in one sentence

GENERATION SPEED vs COMPREHENSION SPEED

  Session 1   ████░░░░░░░░  ████░░░░░░░░
  Session 15  ████████░░░░  █████░░░░░░░
  Session 30  ████████████  ██████░░░░░░
  Session 50  ████████████  ██████░░░░░░
              ████████████

              gap = comprehension debt

How to Measure Comprehension Debt

Test 1: The Explanation Test

Pick any file over 300 lines in your project. Can you explain what it does — without reading the code line by line?

If not, you have comprehension debt.

Test 2: The Three Questions Test

find src -name "*.ts" -o -name "*.tsx" | xargs wc -l | sort -rn | head -20

For your top 10 files, ask:

What domain does this file belong to? (auth, payments, users, etc.)
What happens if I delete it? (what breaks, what depends on it)
Who is responsible for it? (which team member, which module)

If you can't answer all three for most files, the codebase has outgrown your ability to reason about it.

Test 3: The TODO Audit

grep -rn "TODO\|FIXME\|HACK\|XXX" src/ | wc -l

A high number means the AI left breadcrumbs it never cleaned up. Each one is a comprehension gap — a place where the AI deferred a decision that nobody came back to.

Test 4: The Convention Drift Check

# Check for inconsistent naming patterns
grep -rn "export default function\|export function\|export const" src/ --include="*.ts" --include="*.tsx" | head -30

Look at the first 30 exports. Are they consistent? default function vs named export vs const arrow function? If you see all three patterns, the AI shifted conventions mid-project.

Why Documentation Doesn't Fix This

"We'll add documentation later" is the default response. It's also the wrong fix applied at the wrong layer.

Documentation describes what the code does. It does not change what the code does.

If the architecture is incoherent — business logic in three places, naming conventions that shift mid-project, files that mix four domains — documentation just describes the mess. It's the equivalent of labeling every room in a building with no floor plan.

Worse: the AI that wrote the code will generate plausible-sounding documentation. But "plausible" and "accurate" diverge when the architecture has drifted.

The Structural Fix

Comprehension debt is not a knowledge problem. It's a structure problem. The fix sequence:

Step 1: Domain Mapping

List every business domain in your application (auth, users, payments, notifications, etc.). Then map which files contain logic for which domain.

# Find all files that reference "price" or "payment"
grep -rln "price\|payment\|stripe\|checkout" src/ --include="*.ts" --include="*.tsx"

If pricing logic lives in more than 2-3 files, it's scattered.

Step 2: Module Boundaries

Create explicit module boundaries:

src/
  modules/
    auth/          -- everything authentication
    payments/      -- everything pricing and billing
    users/         -- everything user management
    notifications/ -- everything notifications
  shared/
    types/         -- shared type definitions
    utils/         -- pure utility functions

The rule: each module owns one domain. No file crosses domain boundaries.

Step 3: Self-Documenting Naming

Enforce consistent naming conventions:

Files named by what they do, not how they're implemented
Functions named by their business purpose
No abbreviations that require domain knowledge to decode

Step 4: Convention Enforcement

Add linting rules that enforce:

Consistent export patterns
File size limits (flag files over 300 lines)
Import boundaries (modules can only import from allowed modules)

// Example: eslint boundary rule
{
  "rules": {
    "import/no-restricted-paths": [{
      "zones": [{
        "target": "./src/modules/auth",
        "from": "./src/modules/payments"
      }]
    }]
  }
}

The Result

After structural reorganization, the codebase becomes self-evident. You can navigate by structure instead of by searching. A new team member can understand the architecture from the folder structure alone. The explanation test becomes trivial — because each file does one thing in one domain.

Comprehension debt doesn't require more documentation. It requires more structure.

Resources

ASA Standard — the open specification
GitHub — source, examples, documentation
Vibecodiq — structural diagnostics for AI-built apps

Why AI-Generated Apps Break After Every Change — The Structural Mechanism

vibecodiq — Wed, 25 Feb 2026 15:22:05 +0000

"Every time we add something, something else breaks."

If you've built an application with AI tools — Cursor, Lovable, Bolt.new, Replit, v0 — and you're past the first few months of development, there's a good chance you've heard this sentence. Maybe you've said it yourself.

This post breaks down the structural mechanism behind this pattern, how to detect it in your own codebase, and what the fix actually looks like.

The Pattern

Here's what we typically see in AI-generated codebases past month 3:

Files that have grown past 500–800 lines
Circular dependency chains between modules
Business logic in unexpected places (route handlers, UI components, utility files)
Less than 10% test coverage
Every "simple" change requires extensive manual testing

This isn't bad code. It's structurally incoherent code.

The Mechanism: Architecture Drift

AI-assisted development optimizes locally. Each prompt solves the immediate problem without awareness of the broader architecture.

Session 1 establishes a clean boundary between your API routes and your business logic. Session 47 erodes it — because the fastest way to fix a bug is to put the fix where the symptoms are, not where the root cause lives.

Session 1:  Clean boundary between modules
Session 15: First shortcut across boundary
Session 30: Business logic in route handlers
Session 47: Circular dependency chain forms
Session 60: "Every change breaks something else"

By month 6, a change in module A breaks module B because they share internal state that nobody intended to share. The dependency graph has become a web rather than a tree:

LOCAL OPTIMIZATION              STRUCTURAL ENFORCEMENT

  A <-> B                         A
  |  X  |                         |
  C <-> D                         B --> C
  |  X  |                               |
  E <-> F                         D --> E

  circular chains: 4              circular chains: 0
  blast radius: unknown           blast radius: bounded
  change cost: unpredictable      change cost: predictable

Detection: Two Commands

1. Circular Dependencies

npx madge --circular --extensions ts,tsx src/

What the number means:

0 chains: Clean. Your modules can change independently.
1–2 chains: Warning. Coupling is forming.
3+ chains: Critical. Isolation is structurally impossible.

2. Oversized Files

find src -name "*.ts" -o -name "*.tsx" | xargs wc -l | awk '$1 > 500' | sort -rn

In AI-generated codebases, files over 500 lines usually contain logic from multiple domains. They are where "unrelated" breakage originates.

3. Test Coverage

npx jest --coverage --coverageReporters=text-summary 2>/dev/null | grep "Statements"

Less than 10% means the feedback loop between code changes and correctness verification is absent.

Why "Just Add Tests" Doesn't Fix This

Tests detect that a regression happened. They do not prevent the architectural condition that causes it.

If your architecture allows a pricing change to break authentication, tests will catch the failure — after the fact. But no amount of test coverage prevents the coupling itself. The change still leaks across boundaries because the boundaries don't exist.

The Structural Fix

The fix is not a rewrite. It's boundary enforcement — applied in sequence:

Step 1: Map the Current State

Run the detection commands above. Document:

How many circular dependency chains exist
Which files exceed 500 lines
Where business logic actually lives vs. where it should live

Step 2: Establish Boundaries

Define which module owns which logic. The rule is simple:

One module = one domain = one direction of dependency

A pricing module can depend on a user module. A user module cannot depend on a pricing module. If they both need shared data, extract it into a shared types module that both can depend on.

Step 3: Break Circular Chains

For each circular dependency:

Identify the shared state or logic that creates the cycle
Extract it into a separate module
Update both modules to depend on the extracted module instead of each other

Step 4: Decompose Oversized Files

Files over 500 lines get split by domain responsibility:

Route handlers contain only routing logic
Business logic lives in domain modules
Shared utilities contain only pure functions

Step 5: Add Test Baseline

Once boundaries exist, tests become meaningful. Each test covers a bounded module, not the entire system. Focus on:

Critical business paths (payments, auth, core workflows)
Boundary contracts (what each module exports)
Regression triggers (the specific changes that caused past breakage)

Step 6: Enforce Automatically

Set up CI/CD gates that block:

New circular dependencies
Files exceeding size thresholds
Merges without test coverage on critical paths

This turns the architecture from "trust-based" to "enforcement-based." Changes that violate boundaries are caught before they reach production.

The Result

After structural stabilization, the blast radius of every change becomes predictable. A change in the pricing module affects pricing. A change in authentication affects authentication. "Every time we add something, something else breaks" disappears — not because the team is more careful, but because the architecture makes cross-module leakage structurally impossible.

Resources

ASA Standard — the open specification
GitHub — source, examples, documentation
Vibecodiq — structural diagnostics for AI-built apps

Taming the 5–10% Instability Rule: Using ASA for Deterministic Regeneration

vibecodiq — Tue, 09 Dec 2025 15:21:27 +0000

If you use AI coding tools daily, you've probably seen this:

You ask the assistant to "update this endpoint", and the PR comes back with a lot more than that:

The service changed
A helper was "cleaned up"
A test file got rewritten
An unrelated import moved somewhere else

Nothing looks obviously wrong, but over time you accumulate a growing zone of "I don't know why this changed."

That's what I call the 5–10% instability rule:

Every regeneration quietly destabilizes ~5–10% of your codebase through unrequested changes.

In this post, I'll show how ASA v1.0 (a deterministic CLI for slice‑based architecture) turns regeneration from a risky operation into a fully controlled, local, repeatable process.

The concrete pain: AI touching more than you asked for

Typical flow today:

You change requirements for login (extra field, new error).
You ask AI: "Update the login endpoint, service and tests."
The assistant edits 5–10 files — some relevant, some "for consistency."
The diff includes signature changes, helper refactors, and test rewrites.

As an engineer, you now have three problems:

Unclear blast radius — what else did we just change?
Architecture erosion — a "small cleanup" breaks a domain boundary.
Fear of regeneration — doing this again might overwrite business logic.

You can try to tighten the prompt, but the real issue is that nothing in your project structure encodes strict boundaries plus regeneration rules.

ASA's core idea is: encode them.

ASA in 30 seconds

ASA v1.0 is a Python CLI that works on Slices: vertical feature units that colocate everything for one use‑case:

domains/auth/login/
├── slice.spec.md        # Human spec
├── slice.contract.json  # Machine contract
├── handler.py           # FastAPI endpoint
├── service.py           # Business logic
├── repository.py        # Data access
├── schemas.py           # Pydantic models
└── tests/

The pipeline is deterministic:

slice.spec.md → slice.contract.json → skeleton → your implementation

Key points:

Slices give you local, vertical boundaries.
Specs & contracts are the single source of truth.
Markers preserve your implementation across regeneration.
Linter enforces domain boundaries with AST checks.

Before vs After: Changing a Slice

Let's walk through a real change: adding ip_address to login for security logging.

Before ASA: free‑form codebase

You might have something like:

# auth/routes.py
@router.post("/login")
def login(payload: dict):
    user = user_repo.get_by_email(payload["email"])
    if not user or not verify_password(payload["password"], user.password_hash):
        raise HTTPException(status_code=401)
    token = generate_jwt(user.id)
    audit_login(user.id)  # logging somewhere else
    return {"token": token}

Now product asks: "Also store the IP address and make it available to an analytics job."

With AI, your prompt is vague by definition:

"Update login to accept ip_address, store it, and keep tests passing."

The assistant might:

Change this handler
Rewrite some helper called audit_login
Adjust a couple of tests
Maybe "simplify" a repository interface on the way

You get your feature — and another 5–10% of "not sure what changed".

After ASA: slice‑based, deterministic workflow

In ASA, login lives in its own Slice:

domains/auth/login/
  slice.spec.md
  slice.contract.json
  handler.py
  service.py
  repository.py
  schemas.py
  tests/

Step 1 — Update the Spec (domains/auth/login/slice.spec.md):

# Purpose
User logs in with email and password. Returns JWT token.

## Inputs
- email: string
- password: string
- ip_address: string

## Outputs
- jwt_token: string
- expires_in: int

## Behaviour
- Verify user exists.
- Verify password.
- Generate JWT token.
- Log IP address for security.

## Errors
- INVALID_CREDENTIALS: Invalid email or password.

## Side Effects
- Logs login attempt with IP address.

## Dependencies
None

Step 2 — Regenerate contract + skeleton:

asa generate-contract auth/login
asa regenerate-slice auth/login

generate-contract updates slice.contract.json from the spec.
regenerate-slice then reads the contract and updates the Python files:

schemas.py (adds ip_address)
handler/service/repository structure
tests skeleton

Step 3 — Verify your implementation survived

Business logic in service.py is wrapped by markers:

from .repository import LoginRepository
from .schemas import LoginRequest, LoginResponse

class LoginService:
    def __init__(self) -> None:
        self.repo = LoginRepository()

    # === BEGIN USER CODE ===
    def execute(self, request: LoginRequest) -> LoginResponse:
        user = self.repo.get_user_by_email(request.email)
        if not user:
            raise ValueError("USER_NOT_FOUND")
        if not self.repo.verify_password(user, request.password):
            raise ValueError("INVALID_CREDENTIALS")

        token = generate_jwt(user.id)
        self.repo.log_login(user.id, request.ip_address)

        return LoginResponse(jwt_token=token, expires_in=3600)
    # === END USER CODE ===

ASA regenerates the file around this block and then reinserts your function body exactly as written.

You get:

Updated schemas and contracts
Same business logic
No surprise changes in unrelated slices

Step 4 — Run the linter:

asa lint auth/login

If AI tried to sneak in a cross‑domain import (e.g. directly calling domains.analytics), the linter fails and tells you exactly where.

Minimal CLI workflow to adopt ASA

To start using ASA on a new feature, you typically do:

# 1) Create a slice
asa create-slice auth/login

# 2) Write the spec (manual or with AI help)
#    edit domains/auth/login/slice.spec.md

# 3) Generate contract + skeleton
asa generate-contract auth/login
asa generate-skeleton auth/login

# 4) Implement your logic between markers in service.py/repository.py

# 5) Lint before committing
asa lint auth/login

From then on, any change to login flows through:

asa generate-contract auth/login
asa regenerate-slice auth/login
asa lint auth/login

Regeneration becomes a routine operation, not a roll of the dice.

Why this kills the 5–10% instability rule

The 5–10% rule thrives on three things:

Global, shared helpers
Fuzzy boundaries ("we try not to import that…")
Non‑deterministic generation

ASA attacks all three:

Slices encourage local duplication of business helpers instead of sharing them across domains.
Domain rules are enforced by an AST linter, not just by code review.
The CLI is deterministic — same spec, same skeleton, every time.

AI is still in the loop, but its freedom is constrained by contracts, markers and lint rules.

You keep the speed. You lose the architectural roulette.

If you want to see the full starter kit and CLI in action, check out:

Source code & starter kit: https://github.com/vibecodiq/asa-starter-kit

Stop Letting AI Delete Your Code: Deterministic Regeneration with ASA v1.0

vibecodiq — Fri, 05 Dec 2025 11:26:45 +0000

AI coding tools are great at one thing: rewriting lots of code very fast.

That’s also exactly how they break your system.

If you’ve ever:

Asked an AI to “update this schema” and lost a hand‑written edge case
Let a tool “clean up this service” and watched a subtle validation vanish
Tried to regenerate a scaffolded module and ended up diffing walls of code

…then this post is for you.

In this guide, we’ll look at how ASA v1.0 lets you regenerate Python slices safely – preserving your business logic byte‑for‑byte while still letting AI help with the boring parts.

The Pain: Regeneration Fear

A typical AI‑assisted workflow today:

Use your favourite tool (Cursor, Copilot, etc.) to scaffold a FastAPI endpoint.
Add some custom behaviour on top – edge cases, extra validation, domain rules.
A week later, requirements change. You need a new field or different error semantics.
You ask AI to “regenerate the handler and service to match the new schema”.

What comes back is a brand‑new version of the file.

It may be cleaner. It may even pass tests. But it almost certainly:

Rewrote parts of your manually added logic
Changed error types or messages
Modified behaviour in ways the AI can’t explain

After this happens once or twice, you learn a new instinct:

“Never regenerate a file you’ve touched.”

Congratulations – your “AI‑generated” scaffolding just became zombie code.

ASA’s View: Separate Intent from Implementation

Agentic‑Sliced Architecture (ASA) starts from a different assumption:

Specs should be regenerated. Business logic should not.

So it separates your flow into three layers:

Spec (slice.spec.md) – a human‑readable Markdown description of a feature: purpose, inputs, outputs, behaviour, errors, side‑effects, dependencies.
Contract (slice.contract.json) – a strict, machine‑readable JSON version of that spec.
Generated code skeleton – FastAPI router + service + repository + schemas + tests.

The important bit: all of this lives inside a Slice – a vertical feature unit like domains/auth/login/ instead of being scattered across folders.

You create it with:

asa create-slice auth/login

Then you fill in domains/auth/login/slice.spec.md with your feature description.

From Spec to Code: The Deterministic Pipeline

Once your spec is ready, ASA v1.0 runs a deterministic pipeline:

asa generate-contract auth/login
asa generate-skeleton auth/login

Behind the scenes, this does:

Parse the Markdown spec
Emit a JSON contract with inputs/outputs/behaviour/errors/side‑effects
Generate Python modules that match that contract

The generated folder looks like this:

domains/auth/login/
├── slice.spec.md
├── slice.contract.json
├── handler.py
├── service.py
├── repository.py
├── schemas.py
└── tests/
    └── test_slice.py

Given the same spec, you’ll always get the same contract and skeleton files. No randomness, no “almost the same but slightly different” diffs.

So where does your custom logic live?

Markers: Where Your Logic Lives (and Survives)

ASA reserves explicit regions in generated files for your implementation.

For example, in service.py you’ll see:

from .repository import LoginRepository
from .schemas import LoginRequest, LoginResponse

class LoginService:
    def __init__(self) -> None:
        self.repo = LoginRepository()

    # === BEGIN USER CODE ===
    def execute(self, request: LoginRequest) -> LoginResponse:
        # Your implementation here
        user = self.repo.get_user_by_email(request.email)
        if not user:
            raise ValueError("USER_NOT_FOUND")

        if not self.repo.verify_password(user, request.password):
            raise ValueError("INVALID_CREDENTIALS")

        token = generate_jwt(user.id)
        return LoginResponse(jwt_token=token, expires_in=3600)
    # === END USER CODE ===

Everything between BEGIN USER CODE and END USER CODE is your territory.

You can:

Hand‑write it
Ask an AI assistant to generate it
Refine it over time

ASA will never overwrite this region during regeneration.

The Magic Trick: Regenerate Without Losing Logic

Now imagine you extend the feature:

Add ip_address: string to the inputs
Log login attempts for security
Maybe enrich the response with an extra field

You update slice.spec.md to reflect the new behaviour, then run:

asa generate-contract auth/login
asa regenerate-slice auth/login

Here’s what happens:

ASA re‑parses slice.spec.md and updates slice.contract.json.
It regenerates the skeleton files (schemas, handler signatures, test stubs, etc.).
For files that contain user markers, it extracts your code, regenerates the structure, and injects your code back into the new version.

Your execute() implementation is preserved exactly, but now:

The LoginRequest model includes ip_address
The handler signature matches the new contract
Tests and scaffolding are up to date

You’ve just updated your feature end‑to‑end without manually touching any glue code – and without losing a single line of business logic.

Keeping Architecture Clean: Linting Boundaries

Overwriting logic is one problem. Eroding architecture is another.

When AI tries to “help”, it often reaches for the nearest import that makes the code compile, even if it breaks your domain boundaries.

ASA ships with a linter that understands Slices and performs AST‑based checks:

asa lint auth/login

It verifies that:

All required files exist and contracts are valid
Slice structure is consistent
Imports don’t cross domains in illegal ways

If a repository in auth/login tries to import something like domains.billing.invoice, the linter fails and tells you exactly where the violation happened.

This makes it much harder for “just make it work” AI changes to quietly turn your codebase into spaghetti.

Using ASA with AI in Practice

ASA v1.0 is a Python CLI, not a black‑box SaaS.

You can plug it into whatever workflow you already have:

Use an LLM to generate specs (slice.spec.md) from product requirements.
Let ASA turn those specs into contracts and skeletons.
Use AI again to help implement the logic inside marker regions.
Regenerate safely whenever the spec changes.
Run asa lint in CI to enforce boundaries before merge.

The more agents and tools you add, the more you’ll appreciate that spec → contract → code is deterministic and repeatable.

When to Reach for ASA

You probably don’t need ASA for throwaway prototypes.

You almost certainly need it if:

You are building a long‑lived product with an AI‑heavy dev loop
Multiple agents or tools will touch the same backend
You’re already afraid to regenerate code you generated a month ago
You care about domain boundaries and want them enforced, not just drawn on a diagram

In that world, “just trust the AI” is not a strategy.

You want an architecture that:

Treats specs as the source of truth
Makes regeneration safe by design
Protects business logic with explicit markers
Guards your boundaries with a linter

That’s what ASA v1.0 is designed to do.

If you want to see it in action, check out the regeneration demo https://vibecodiq.com/demo/ and docs on the ASA starter kit repo https://github.com/vibecodiq/asa-starter-kit.

Deterministic Regeneration with ASA Core v1.0

vibecodiq — Wed, 03 Dec 2025 15:54:40 +0000

Most AI-powered coding tools are excellent at generating code once…
But they struggle — sometimes catastrophically — when asked to generate the same feature again.

You update the spec, click "regenerate," and suddenly:

Your custom logic disappears
Your validation rules vanish
Your test structure no longer matches
Your handlers and models drift apart

This is the regeneration trap.
ASA Core v1.0 was built specifically to escape it.

In this article, we'll break down:

Why regeneration fails in traditional tools
How ASA's deterministic pipeline prevents code loss
The slice-based architecture that eliminates drift
A real example showing safe regeneration
Why determinism is essential for multi-agent AI workflows

1. The Pain: Regeneration as a Full Rewrite

Here is the typical lifecycle developers experience with most generators:

Day 1: Generate scaffolding → looks great
Day 2: Implement business logic → feels great
Day 3: Requirement changes → regenerate → everything is gone

The generator doesn't know what you wrote.
It only knows how to produce a new skeleton.

This leads to:

Lost developer time
Fear of touching generators
Divergent specs & code
Architecture decay

You don't just lose code — you lose trust.

2. ASA's Model: Slices, Specs, and Contracts

ASA uses three layers to create a deterministic, AI-safe workflow:

1. Slices

Self-contained vertical feature units:

domains/auth/login/
├── slice.spec.md
├── slice.contract.json
├── handler.py
├── service.py
├── repository.py
├── schemas.py
└── tests/

2. Specs (Human-readable)

Seven required sections: Purpose, Inputs, Outputs, Behaviour, Errors, Side Effects, Dependencies.

3. Contracts (Machine-readable)

JSON schema generated from the spec:

{
  "inputs": { "email": "string", "password": "string" },
  "outputs": { "jwt_token": "string", "expires_in": "int" }
}

ASA then uses deterministic templates to generate code.

No randomness.
No heuristics.
No AI in the core pipeline.

3. Marker-Based Code Preservation (ASA's Key Feature)

Instead of trying to guess what is "your code" vs "generated code", ASA explicitly marks regions to preserve:

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

During regeneration, ASA:

Extracts everything inside the markers
Regenerates the structure around it
Inserts your code back exactly where it belongs

This is a 100% deterministic round trip.

Your code can never be overwritten by accident.

4. Example: Login Slice with New Requirements

You have a working login slice.

Later, security wants to log ip_address.

In most tools:

Regenerate → code loss → manual merge → bugs.

In ASA:

Update slice.spec.md:

- email: string
- password: string
- ip_address: string # new

Regenerate safely:

asa generate-contract auth/login
asa regenerate-slice auth/login

ASA updates:

Models
Handler signature
Tests
Contract

Your logic remains intact.

5. Determinism Enables AI-First Engineering

In AI-assisted development, regeneration must be safe because:

Multiple agents may touch the same slice
Specs may change daily
Contracts evolve quickly
Automated workflows need predictable behavior
CI needs to regenerate and lint without human supervision

ASA ensures:

Same spec → same contract
Same contract → same files
No surprises in diffs
No accidental overwrite of logic

This is architecture built for the AI era.

6. Why Teams Adopt ASA

ASA Core v1.0 is perfect for:

Long-lived backends
Multi-agent coding environments
Fast-evolving feature sets
Teams tired of code drift
Organizations needing deterministic output
Anyone building with LLMs at the center

ASA allows you to embrace regeneration — not fear it.

Conclusion

Regeneration should NOT feel like:

rm -rf my_code

It should feel like:

safely update the structure while preserving my logic

ASA Core v1.0 makes that possible using:

Slice colocation
Deterministic templates
Machine-readable contracts
Marker-based preservation
Boundary enforcement via linter

If you want a backend architecture that can keep up with AI-driven development — ASA is it.

Source code & starter kit: https://github.com/vibecodiq/asa-starter-kit

How I Stopped AI Codebases From Collapsing: Architecture Drift vs. Deterministic Slices

vibecodiq — Mon, 01 Dec 2025 21:23:07 +0000

AI coding tools are amazing… until they silently break your architecture.

This article shows exactly why drift happens — and how ASA Core v1.0 fixes it with deterministic slice-based generation.

1. The Real Pain: AI Code Is Not Deterministic

Run the same instruction twice and you get different outputs:

# Version 1
class LoginService:
    def execute(self): ...

# Version 2
class Login:
    def run(self): ...

Same prompt → different structure → instant drift.

2. Drift Gets Worse When Specs Change

Traditional workflow:

edit spec
↓
Regenerate
↓
💀 Custom code overwritten

So engineers stop regenerating.
Schemas drift from implementation.
Tests no longer match the API.

3. ASA Core v1.0: Deterministic Pipeline

ASA uses a strict 3-step flow:

slice.spec.md → slice.contract.json → skeleton code

Every step is deterministic — no randomness, no inference.

4. Before vs After (Real ASA Behavior)

❌ Before (traditional generation)

# Business logic gets overwritten when spec changes
def execute(self, req):
    # custom logic

Change the spec → overwrite → cry.

✅ After (ASA regeneration)

You write logic ONLY between markers:

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

Change the spec:

asa generate-contract auth/login
asa regenerate-slice auth/login

ASA regenerates the file structure and injects your preserved logic back in.

This is guaranteed — documented and implemented in Core.

5. Boundary Violations Stop Instantly

ASA lints with AST analysis:

$ asa lint auth/login

❌ [LINT FAIL] Boundary violation in repository.py:
   Line 1: Illegal import 'domains.billing.invoice'
   -> Cannot import from other domains.

Same-domain imports are fully allowed; cross-domain imports are forbidden.

6. Quick Reproducible Workflow

pip install -e ".[dev]"

asa create-slice auth/login

# edit slice.spec.md

asa generate-contract auth/login
asa generate-skeleton auth/login

# implement logic between markers

asa lint auth/login

And when specs change:

asa generate-contract auth/login
asa regenerate-slice auth/login

Zero drift. Zero overwrite. Fully deterministic.

7. Why This Matters

Clean architecture + deterministic regeneration =
AI codebases that don’t collapse.

This is the foundation for stable AI-assisted engineering.

Source code & starter kit:
https://github.com/vibecodiq/asa-starter-kit

ASA: The First Architecture Built for the AI-Coding Era

vibecodiq — Sat, 29 Nov 2025 20:12:50 +0000

🧩 The Problem: AI Development Is in Chaos

Over the last two years, AI has become the most powerful coding tool ever created.
But it also introduced a new category of problems that traditional architectures were never meant to handle:

❌ Generated code is unstable (drift)
❌ Small changes break unrelated modules
❌ Multi-agent workflows conflict
❌ Regeneration overwrites human logic

This is no longer a tooling issue.
It’s a systemic architectural problem — and systemic problems require architectural solutions.

🧠 The Origin: Why We Needed ASA

Across multiple AI-driven projects, the same destructive pattern kept appearing:

AI could generate code
...but couldn’t preserve architecture
Small spec changes broke unrelated modules
Agents overwrote each other’s logic

Eventually it became undeniable:

We cannot build AI-generated software on architectures designed before AI existed.

That realization led to the creation of ASA — the AI-Sliced Architecture.

🔍 What Is ASA?

ASA introduces vertical slices, deterministic scaffolding, and regeneration safety.
It ensures:

AI cannot break the architecture.
Developers can iterate safely.
Only deterministic scaffold regions regenerate.
Human-written logic stays intact.

ASA transforms AI development from "creative chaos" into deterministic engineering.

📂 ASA Slice Structure (v1.0)

A slice contains everything needed for a single feature: handler, service logic, schemas, repository, contract, spec, and tests.

src/
└── domains/
    └── auth/
        └── slices/
            └── login/
                ├── __init__.py
                ├── handler.py          # AI-managed entry point
                ├── repository.py       # Data layer
                ├── schemas.py          # Pydantic models (I/O)
                ├── service.py          # Human-written logic (Protected 🔒)
                ├── slice.contract.json # Generated from slice spec
                ├── slice.spec.md       # Human-written slice definition
                └── tests/              # Deterministic test scaffold

This structure is deterministic, stable, and regeneration-safe.

🔒 The “Sandwich Pattern”: AI Code Around Human Logic

ASA enforces a strict separation between AI-generated and human-written regions.

Example (service.py):

`python

src/domains/auth/slices/login/service.py

✅ THIS FILE IS SAFELISTED.

AI regenerates scaffolding around it, but never touches this logic.

def login_user(ctx: LoginContext):
if not ctx.user_exists:
raise UserNotFound()

return {"token": generate_token(ctx.user)}

Your logic is never overwritten, even when you regenerate the slice 50 times.

⚡ Why Traditional Architectures Struggle in the AI Era

Clean Architecture, DDD, and Hexagonal Architecture were created for a world where:

Humans wrote 100% of the code
Refactoring was manual
Boundaries were conventions
Regeneration didn’t exist

In modern AI workflows, regeneration happens daily and AI frequently violates invisible boundaries.
ASA doesn’t replace Clean Architecture — it stabilizes it and makes it safe for AI.

🚀 The 3 ASA Gamechangers

01 // Regeneration Without Destruction

Update the spec → ASA regenerates only deterministic regions.
Your custom logic stays untouched.

02 // The Boundary Guardian

ASA blocks cross-slice imports, domain leaks, and architecture drift.
AI agents can no longer "accidentally" break the system.

03 // Structural Determinism

Same input → same output.
No hallucinated folders, no random files.
ASA behaves like a compiler, not a creative assistant.

🧪 Try ASA in Practice (8-Minute Demo)

Live demo: vibecodiq.com/demo/

`bash

1. Define a slice

mkdir -p domains/auth/slices/login_demo

2. Generate contract

asa generate-contract auth/login_demo

3. Generate skeleton

asa generate-skeleton auth/login_demo

4. Regenerate safely

asa regenerate-slice auth/login_demo
`

🔮 What’s Next?

This is Part 1 of the ASA series.
Coming next:

The Boundary Guardian — AST-Backed Enforcement
Zero-Hallucination Scaffolding
Safe Multi-Agent Workflows

Follow me here or on LinkedIn https://www.linkedin.com/in/voldan/ to join the discussion.