AI Code Review Patterns That Actually Catch Architecture Violations

Most teams use AI for surface-level code reviews—formatting, naming conventions, simple linting. They're missing the real value: catching architecture violations before they compound into technical debt.

Research shows manual code reviews catch only 40% of architecture violations. AI-assisted reviews, when configured correctly, catch 75%+ of violations. The difference isn't the AI itself—it's how you use it.

Here's what you'll learn: 5 specific patterns for AI code reviews, implementation steps for each, and real metrics from teams that made this work.

Why Manual Reviews Miss Architecture Violations

The Cognitive Load Problem

When you review a pull request, your brain prioritizes what's easy to spot: variable names, formatting issues, obvious bugs. Architecture violations—like improper service coupling or domain boundary leaks—require deeper analysis that doesn't happen when you're reviewing the fifth PR of the day.

The Context Switching Cost

Reviewing code in Service A while understanding its relationship to Services B, C, and D requires holding the entire system in your head. Most reviewers don't have that context readily available. They might catch that a function works, but miss that it violates your microservices boundaries.

The Inconsistency Problem

Sarah catches domain boundary violations. Mike focuses on performance. Alex is great at security. No single reviewer catches everything consistently. Your architecture guardrails only work if everyone enforces them the same way.

Time Pressure Reality

Deep architectural analysis takes 2-3x longer than surface-level review. When you're under deadline pressure, which review do you think happens? The quick one. Architecture violations slip through because teams don't have time for thorough review.

The Compound Effect

One team I worked with had a simple rule: "Payment service should never directly call User service." Over six months, without automated enforcement, this violation appeared in 23 different places. Each violation made the next one easier to justify. "Well, we already do it over here..."

Architecture violations compound. One leak becomes permission for more. Before you know it, your microservices are a distributed monolith.

The 5 AI Code Review Patterns That Work

Pattern 1: Domain Boundary Violation Detection

What It Catches

Cross-domain dependencies, leaky abstractions, improper service coupling, bounded context violations.

Why It Matters

I've seen a 12-service architecture turn into spaghetti because no one enforced domain boundaries. Service A called Service B's database directly "just this once." Six months later, you can't change Service B's schema without coordinating with 4 other teams.

How to Implement

Step 1: Define Your Domain Boundaries

Create .github/copilot-instructions.md (or equivalent context file):

# Domain Boundaries

## Payment Domain
- Owns: payment processing, refunds, transaction history
- Exposes: REST API for payment operations
- Never accesses: User database, Order database directly
- Communication: Publishes PaymentCompleted, PaymentFailed events

## Order Domain  
- Owns: order management, order status, cart operations
- Exposes: REST API for order operations
- Never accesses: Payment internals, User database directly
- Communication: Subscribes to PaymentCompleted events

## User Domain
- Owns: user profiles, authentication, preferences
- Exposes: REST API for user operations
- Never accesses: Payment database, Order database directly

## CRITICAL RULES
- Services communicate via REST APIs or events, NEVER direct database access
- No circular dependencies between domains
- Shared code goes in commons library, not copied between services

Step 2: Configure AI to Scan for Violations

Add to your code review workflow (GitHub Actions example):

- name: AI Architecture Review
  run: |
    gh pr diff | analyze-with-ai --context .github/copilot-instructions.md \
      --check "domain boundary violations"

Step 3: Use Specific Prompts

When reviewing PRs manually with AI assistance:

Analyze this PR for domain boundary violations based on our architecture rules:

[Paste architecture rules from copilot-instructions.md]

PR Changes:
[Paste git diff]

Check for:
1. Direct database access across service boundaries
2. Circular dependencies between domains  
3. Improper service-to-service calls
4. Shared code that should be in commons library

For each violation found, explain:
- What rule it violates
- Why this is problematic
- Suggested fix

Real Example

Before AI Review:

// In Order Service - VIOLATION
import { UserRepository } from '@user-service/repositories';

export class OrderProcessor {
  async createOrder(userId: string, items: OrderItem[]) {
    // Directly accessing User database from Order service
    const user = await UserRepository.findById(userId);
    
    if (user.preferences.marketingOptIn) {
      // Send marketing email
    }
    
    return this.orderRepo.create({ userId, items });
  }
}

AI Detection:

🚫 Domain Boundary Violation Detected

File: order-processor.ts
Line: 5

Violation: Order Service is directly importing and using UserRepository 
from User Service's internal repository layer.

Architecture Rule Violated:
"Services communicate via REST APIs or events, NEVER direct database access"

Why This Is Problematic:
1. Creates tight coupling between Order and User services
2. Order service can break if User database schema changes
3. Prevents independent deployment of User service
4. Violates microservices isolation principle

Suggested Fix:
Call User Service's REST API instead:

const user = await this.userServiceClient.getUser(userId);

Or if this is part of order flow, consider:
- Caching user preferences in Order service (eventually consistent)
- Including necessary user data in order creation request
- Using event-driven approach (UserPreferencesUpdated event)

After Fix:

// In Order Service - CORRECTED
import { UserServiceClient } from '@shared/clients';

export class OrderProcessor {
  constructor(private userService: UserServiceClient) {}

  async createOrder(userId: string, items: OrderItem[]) {
    // Call User Service API - proper boundary respect
    const user = await this.userService.getUser(userId);
    
    if (user.preferences.marketingOptIn) {
      // Send marketing email
    }
    
    return this.orderRepo.create({ userId, items });
  }
}

Success Metrics from Real Team

A 50-person engineering team implemented this pattern:

• Month 1: AI flagged 18 domain boundary violations in existing PRs
• Month 2: Violations dropped to 3 per month as team learned
• Month 6: Team reduced cross-service coupling by 65%
• Side benefit: New engineers learned architecture boundaries faster by seeing AI feedback

Pattern 2: Performance Anti-Pattern Scanning

What It Catches

N+1 queries, blocking I/O in async contexts, memory leaks, inefficient algorithms, missing indexes, unoptimized database queries.

Why It Matters

Performance issues are expensive to fix in production. A team I advised spent 3 weeks fixing an N+1 query that could have been caught in code review. The query worked fine in dev (10 users) but brought production to its knees (100K users).

How to Implement

Step 1: Document Performance Patterns

Add to your architecture context:

# Performance Patterns & Anti-Patterns

## Database Access
✅ GOOD: Fetch related data with JOINs or eager loading
❌ BAD: Loop through results making individual queries (N+1)

✅ GOOD: Use pagination for large result sets  
❌ BAD: Load all records into memory

✅ GOOD: Add indexes for frequently queried fields
❌ BAD: Query unindexed fields in WHERE clauses

## Async/Await
✅ GOOD: await in async functions, Promise.all for parallel ops
❌ BAD: Blocking I/O in async context (fs.readFileSync)
❌ BAD: Sequential awaits when operations can be parallel

## Memory Management
✅ GOOD: Stream large files, process in chunks
❌ BAD: Load entire file into memory
❌ BAD: Growing arrays without bounds

## Algorithms
✅ GOOD: O(log n) or O(n) for operations on large datasets
❌ BAD: O(n²) or worse for operations on potentially large data

Step 2: Create Performance Review Prompt

Review this code for performance anti-patterns:

Performance Context:
- Expected data volume: [e.g., 10K users, 1M orders]
- Latency target: [e.g., p95 < 200ms]
- Memory constraints: [e.g., lambda 512MB]

Code:
[Paste code]

Check for:
1. N+1 query patterns
2. Missing database indexes  
3. Blocking operations in async context
4. Algorithm complexity issues for expected data volumes
5. Memory leaks or unbounded growth
6. Missing pagination on large result sets

For each issue:
- Explain performance impact at scale
- Estimate performance degradation
- Provide optimized alternative

Real Example: N+1 Query Detection

Before AI Review:

// API endpoint to get users with their orders
async getUsersWithOrders() {
  const users = await this.db.query('SELECT * FROM users');
  
  // N+1 QUERY PROBLEM - one query per user
  const usersWithOrders = await Promise.all(
    users.map(async (user) => {
      const orders = await this.db.query(
        'SELECT * FROM orders WHERE user_id = ?',
        [user.id]
      );
      return { ...user, orders };
    })
  );
  
  return usersWithOrders;
}

AI Detection:

⚠️ Performance Anti-Pattern: N+1 Query

File: user-controller.ts
Lines: 5-12

Problem: This code makes 1 query to fetch all users, then N additional 
queries (one per user) to fetch their orders.

Performance Impact:
- 100 users = 101 database queries
- 10,000 users = 10,001 database queries
- At ~5ms per query, 10K users = ~50 seconds

Latency Estimate:
- Current: O(n) database queries → 50+ seconds for 10K users
- Optimized: O(1) query → <100ms for 10K users

Optimized Solution:

async getUsersWithOrders() {
  // Single query with JOIN - much faster
  const result = await this.db.query(`
    SELECT 
      users.*,
      orders.id as order_id,
      orders.total,
      orders.status,
      orders.created_at as order_date
    FROM users
    LEFT JOIN orders ON orders.user_id = users.id
    ORDER BY users.id, orders.created_at DESC
  `);
  
  // Group orders by user in application code
  return this.groupOrdersByUser(result);
}

Alternative if using ORM:

async getUsersWithOrders() {
  return await this.userRepo.find({
    relations: ['orders'], // Eager load in single query
  });
}

Real Example: Async Anti-Pattern

Before AI Review:

async processUploadedFiles(files: File[]) {
  const results = [];
  
  // Processing sequentially - slow!
  for (const file of files) {
    const content = await this.readFile(file);
    const processed = await this.processContent(content);
    const saved = await this.saveToStorage(processed);
    results.push(saved);
  }
  
  return results;
}

AI Detection:

⚠️ Performance Issue: Sequential Async Operations

File: file-processor.ts  
Lines: 5-11

Problem: Files are processed sequentially. Each file waits for the 
previous one to complete, even though operations are independent.

Performance Impact:
- 10 files × 2 seconds each = 20 seconds total
- Files could process in parallel → ~2 seconds total
- 10x slower than necessary

Optimized Solution:

async processUploadedFiles(files: File[]) {
  // Process all files in parallel
  const results = await Promise.all(
    files.map(async (file) => {
      const content = await this.readFile(file);
      const processed = await this.processContent(content);
      return await this.saveToStorage(processed);
    })
  );
  
  return results;
}

// For very large batches, use controlled concurrency:
async processUploadedFiles(files: File[]) {
  const BATCH_SIZE = 10;
  const results = [];
  
  for (let i = 0; i < files.length; i += BATCH_SIZE) {
    const batch = files.slice(i, i + BATCH_SIZE);
    const batchResults = await Promise.all(
      batch.map(file => this.processFile(file))
    );
    results.push(...batchResults);
  }
  
  return results;
}

Success Metrics

Team B (e-commerce platform, 15 engineers):

• Baseline: 8 performance-related production issues per quarter
• After AI Performance Review: 2 issues per quarter (75% reduction)
• Specific wins:
  • Caught N+1 query that would have affected 500K users
  • Identified missing index before launch (would have caused 5s query times)
  • Found memory leak in file processing that would have crashed lambdas

ROI: $40K saved in one quarter (reduced production incidents, avoided customer impact)

Pattern 3: Security Vulnerability Pre-Screening

What It Catches

SQL injection risks, XSS vulnerabilities, authentication bypasses, exposed secrets, insecure data handling, authorization gaps.

Why It Matters

Security issues are the most expensive bugs. One team I consulted for had an authentication bypass reach production. Cost: 2 weeks of all-hands incident response, regulatory reporting, customer communications. Could have been caught in code review.

How to Implement

Step 1: Define Security Context

# Security Requirements

## Authentication
- All API endpoints require JWT token (except /login, /register, /health)
- JWTs must be verified with RS256 algorithm
- Token expiry must be validated
- Refresh tokens stored in httpOnly cookies

## Authorization  
- Check user permissions before any data access
- Use row-level security for multi-tenant data
- Never trust client-side role/permission checks

## Input Validation
- Sanitize all user input
- Use parameterized queries (NEVER string concatenation)
- Validate file uploads (type, size, content)
- Escape output in templates (XSS prevention)

## Secrets Management
- Never hardcode API keys, passwords, tokens
- Use environment variables or secret manager
- Rotate secrets regularly
- Different secrets per environment

## Data Protection
- Encrypt sensitive data at rest (PII, payment info)
- Use HTTPS for all communications
- Hash passwords with bcrypt (cost factor 12+)
- Mask sensitive data in logs

Step 2: Security Review Prompt

Security review this PR:

Security Context:
[Paste your security requirements]

PR Changes:
[Paste diff]

Check for:
1. SQL injection vulnerabilities (string concatenation in queries)
2. XSS risks (unescaped user input in output)
3. Authentication bypasses (missing auth checks)
4. Authorization gaps (missing permission checks)  
5. Exposed secrets (hardcoded keys, tokens)
6. Insecure data handling (plaintext passwords, unencrypted PII)
7. CSRF vulnerabilities (state-changing operations without protection)

For HIGH severity issues:
- Mark as CRITICAL
- Explain the attack vector
- Provide secure alternative
- Estimate risk level

Real Example: SQL Injection

Before AI Review:

// User search endpoint - VULNERABLE
async searchUsers(searchTerm: string) {
  // SQL INJECTION VULNERABILITY
  const query = `
    SELECT * FROM users 
    WHERE username LIKE '%${searchTerm}%'
  `;
  
  return await this.db.query(query);
}

AI Detection:

🚨 CRITICAL: SQL Injection Vulnerability

File: user-service.ts
Line: 4-6

Vulnerability: User input (searchTerm) is directly concatenated into 
SQL query without sanitization or parameterization.

Attack Vector:
An attacker could input: ' OR '1'='1' --
Resulting query: SELECT * FROM users WHERE username LIKE '%' OR '1'='1' --%'
This would return ALL users in the database.

More dangerous attacks possible:
- Data exfiltration: '; SELECT * FROM credit_cards --
- Data deletion: '; DROP TABLE users --
- Privilege escalation: '; UPDATE users SET role='admin' WHERE id=1 --

Risk Level: CRITICAL
- Exploitable: Yes, trivially  
- Impact: Full database compromise
- Likelihood: High (searchTerm comes from user input)

Secure Fix:

async searchUsers(searchTerm: string) {
  // Use parameterized query - safe from SQL injection
  const query = `
    SELECT * FROM users 
    WHERE username LIKE ?
  `;
  
  return await this.db.query(query, [`%${searchTerm}%`]);
}

Or with query builder:

async searchUsers(searchTerm: string) {
  return await this.userRepo
    .createQueryBuilder('user')
    .where('user.username LIKE :term', { term: `%${searchTerm}%` })
    .getMany();
}

Real Example: Authentication Bypass

Before AI Review:

// API endpoint - INSECURE
@Get('/user/:id')
async getUser(@Param('id') id: string) {
  // No authentication check!
  return await this.userService.findById(id);
}

@Put('/user/:id')  
async updateUser(
  @Param('id') id: string,
  @Body() updates: UpdateUserDto
) {
  // Authentication check present but wrong
  const token = this.request.headers.authorization;
  
  // VULNERABILITY: Not actually verifying the token!
  if (token) {
    return await this.userService.update(id, updates);
  }
  
  throw new UnauthorizedException();
}

AI Detection:

🚨 CRITICAL: Missing Authentication

File: user-controller.ts
Line: 2-5

Issue: GET /user/:id endpoint has no authentication check. Any user 
can access any other user's data by guessing/enumerating IDs.

Risk: Unauthorized access to user PII (names, emails, preferences, etc.)

---

🚨 CRITICAL: Improper Authentication Verification

File: user-controller.ts
Line: 12-18

Issue: Code checks IF token exists, but never VERIFIES the token is valid.
An attacker can pass any string as Authorization header and bypass auth.

Attack Vector:
curl -H "Authorization: fake-token" PUT /user/123
This would succeed even with invalid token.

Secure Fix:

@UseGuards(JwtAuthGuard) // Verify JWT automatically
@Get('/user/:id')
async getUser(
  @Param('id') id: string,
  @CurrentUser() user: User // Decoded from verified JWT
) {
  // Also check authorization: can this user access this ID?
  if (user.id !== id && !user.isAdmin) {
    throw new ForbiddenException();
  }
  
  return await this.userService.findById(id);
}

@UseGuards(JwtAuthGuard)
@Put('/user/:id')
async updateUser(
  @Param('id') id: string,
  @Body() updates: UpdateUserDto,
  @CurrentUser() user: User
) {
  // Authorization check
  if (user.id !== id && !user.isAdmin) {
    throw new ForbiddenException();
  }
  
  return await this.userService.update(id, updates);
}

Success Metrics

Team C (fintech, 40 engineers):

• Before AI security review: 3-5 security issues per quarter reaching production
• After implementation: 1 security issue in 9 months
• Specific catches:
  • JWT verification bypass in payment API (would have been CRITICAL)
  • Exposed API keys in client-side code (caught before deploy)
  • Missing authorization check on admin endpoint
  • SQL injection in reporting module

ROI: Prevented potential $500K+ incident (regulatory fines, customer impact, reputation damage)

Pattern 4: Tech Debt Accumulation Tracking

What It Catches

Duplicated code, increasing complexity, pattern violations, missing tests, code smells, shortcuts that will bite you later.

Why It Matters

Tech debt compounds. One copy-pasted function becomes five. Five becomes twenty. Before you know it, a simple bug fix requires updating code in 20 places, and you miss 3 of them.

AI can track tech debt delta: "This PR adds X lines of duplicated code, increases cyclomatic complexity by Y, adds Z pattern violations."

How to Implement

Step 1: Establish Baseline

Document your quality standards:

# Code Quality Standards

## Duplication
- Max 10 lines of duplicated code
- Shared logic must be extracted to utilities/services
- Copy-paste is tech debt

## Complexity
- Max cyclomatic complexity: 10 per function
- Max function length: 50 lines
- Max file length: 300 lines
- Max parameters: 4 per function

## Testing
- All new functions must have unit tests
- Critical paths must have integration tests
- Bug fixes must have regression tests
- Target coverage: 80%+

## Patterns
- Follow repository pattern for data access
- Use dependency injection
- Async operations must handle errors
- No business logic in controllers

Step 2: Tech Debt Analysis Prompt

Analyze this PR for technical debt:

Quality Standards:
[Paste your standards]

PR Changes:
[Paste diff]

Calculate:
1. Lines of duplicated code added (vs. existing codebase)
2. Cyclomatic complexity changes
3. Functions missing tests
4. Pattern violations
5. Code smells (long functions, many parameters, nested logic)

For each issue:
- Severity (low/medium/high)
- Effort to fix (quick/medium/substantial)
- Recommendation (fix now / address in follow-up / accept as-is)

Provide:
- Tech debt score (0-10, where 0 = no debt, 10 = severe)
- Should this PR be blocked? (Yes/No with rationale)

Real Example: Code Duplication

Before AI Review:

// File 1: order-validator.ts
validateOrder(order: Order): ValidationResult {
  const errors = [];
  
  if (!order.customerId) {
    errors.push('Customer ID is required');
  }
  
  if (!order.items || order.items.length === 0) {
    errors.push('Order must have at least one item');
  }
  
  if (order.total < 0) {
    errors.push('Order total cannot be negative');
  }
  
  return { isValid: errors.length === 0, errors };
}

// File 2: payment-validator.ts  
validatePayment(payment: Payment): ValidationResult {
  const errors = [];
  
  if (!payment.customerId) {
    errors.push('Customer ID is required');
  }
  
  if (!payment.orderId) {
    errors.push('Order ID is required');
  }
  
  if (payment.amount < 0) {
    errors.push('Payment amount cannot be negative');
  }
  
  return { isValid: errors.length === 0, errors };
}

// File 3: refund-validator.ts
validateRefund(refund: Refund): ValidationResult {
  const errors = [];
  
  if (!refund.customerId) {
    errors.push('Customer ID is required');
  }
  
  if (!refund.paymentId) {
    errors.push('Payment ID is required');
  }
  
  if (refund.amount < 0) {
    errors.push('Refund amount cannot be negative');
  }
  
  return { isValid: errors.length === 0, errors };
}

AI Detection:

⚠️ Tech Debt: Significant Code Duplication

Files: order-validator.ts, payment-validator.ts, refund-validator.ts

Duplication Detected:
- ValidationResult pattern repeated 3 times (21 lines duplicated)
- Customer ID validation repeated 3 times
- Negative amount validation repeated 3 times

Current State:
- 63 lines of code with 42 lines duplicated (67% duplication)
- If validation logic needs to change, must update 3 places
- Inconsistency risk: Already different error messages across validators

Tech Debt Score: 7/10 (High)

Impact:
- Bug Fix Overhead: Fix in one place, must remember to fix in 2 others
- Inconsistency Risk: Error messages already diverging
- Test Overhead: Must test same logic 3 times
- Maintenance: 3x the code to maintain

Recommendation: REFACTOR BEFORE MERGE

Refactored Solution:

// validators/base-validator.ts
export abstract class BaseValidator<T> {
  protected errors: string[] = [];
  
  protected requireField(value: any, fieldName: string): void {
    if (!value) {
      this.errors.push(`${fieldName} is required`);
    }
  }
  
  protected requirePositive(value: number, fieldName: string): void {
    if (value < 0) {
      this.errors.push(`${fieldName} cannot be negative`);
    }
  }
  
  getResult(): ValidationResult {
    return {
      isValid: this.errors.length === 0,
      errors: [...this.errors]
    };
  }
  
  abstract validate(entity: T): ValidationResult;
}

// validators/order-validator.ts
export class OrderValidator extends BaseValidator<Order> {
  validate(order: Order): ValidationResult {
    this.errors = [];
    
    this.requireField(order.customerId, 'Customer ID');
    this.requireField(order.items, 'Items');
    
    if (order.items && order.items.length === 0) {
      this.errors.push('Order must have at least one item');
    }
    
    this.requirePositive(order.total, 'Order total');
    
    return this.getResult();
  }
}

// Similar for payment-validator and refund-validator...

Result:
- 42 lines of duplication → 0 lines
- Single source of truth for validation logic
- Easy to add new validation rules (one place)
- Consistent error messages
- Easier to test (test base class once)

Real Example: Complexity

Before AI Review:

// Order processing with high complexity
async processOrder(order: Order): Promise<ProcessResult> {
  if (order.items && order.items.length > 0) {
    let total = 0;
    for (const item of order.items) {
      if (item.quantity > 0) {
        if (item.discount) {
          if (item.discount.type === 'percentage') {
            total += item.price * item.quantity * (1 - item.discount.value / 100);
          } else if (item.discount.type === 'fixed') {
            total += (item.price - item.discount.value) * item.quantity;
          } else {
            total += item.price * item.quantity;
          }
        } else {
          total += item.price * item.quantity;
        }
        
        if (item.inventory) {
          if (item.inventory.available >= item.quantity) {
            item.inventory.available -= item.quantity;
            await this.inventoryRepo.save(item.inventory);
          } else {
            throw new Error(`Insufficient inventory for ${item.name}`);
          }
        }
      }
    }
    
    if (order.shippingAddress) {
      if (order.shippingAddress.country === 'US') {
        if (order.shippingAddress.state) {
          total += this.calculateUSTax(total, order.shippingAddress.state);
        }
      } else {
        total += this.calculateInternationalTax(total, order.shippingAddress.country);
      }
    }
    
    order.total = total;
    return { success: true, order };
  } else {
    throw new Error('Order must have items');
  }
}

AI Detection:

⚠️ Tech Debt: High Complexity

File: order-processor.ts
Function: processOrder
Lines: 2-42

Complexity Metrics:
- Cyclomatic complexity: 18 (Target: <10) ❌
- Nesting depth: 5 levels (Target: <3) ❌
- Function length: 41 lines (Target: <50) ⚠️
- Responsibilities: 4 (calculating total, applying discounts, checking inventory, calculating tax)

Issues:
1. Single function doing too much (violates SRP)
2. Deeply nested conditionals (hard to read and test)
3. Mixed concerns (business logic + data access)
4. No early returns (could reduce nesting)

Tech Debt Score: 8/10 (High)

Impact:
- Hard to test: Would need 15+ test cases to cover all paths
- Hard to modify: Change discount logic? Navigate 5 levels of nesting
- Bug-prone: Easy to miss edge cases in nested conditions
- Hard to review: Reviewer must hold entire flow in head

Recommendation: REFACTOR BEFORE MERGE

Refactored Solution:

async processOrder(order: Order): Promise<ProcessResult> {
  this.validateOrderHasItems(order);
  
  const itemsTotal = await this.calculateItemsTotal(order.items);
  const tax = this.calculateTax(itemsTotal, order.shippingAddress);
  
  order.total = itemsTotal + tax;
  
  return { success: true, order };
}

private validateOrderHasItems(order: Order): void {
  if (!order.items?.length) {
    throw new Error('Order must have items');
  }
}

private async calculateItemsTotal(items: OrderItem[]): Promise<number> {
  let total = 0;
  
  for (const item of items) {
    const itemTotal = this.calculateItemTotal(item);
    await this.reserveInventory(item);
    total += itemTotal;
  }
  
  return total;
}

private calculateItemTotal(item: OrderItem): number {
  if (item.quantity <= 0) return 0;
  
  const basePrice = item.price * item.quantity;
  return this.applyDiscount(basePrice, item.discount);
}

private applyDiscount(price: number, discount?: Discount): number {
  if (!discount) return price;
  
  switch (discount.type) {
    case 'percentage':
      return price * (1 - discount.value / 100);
    case 'fixed':
      return price - discount.value;
    default:
      return price;
  }
}

private async reserveInventory(item: OrderItem): Promise<void> {
  if (!item.inventory) return;
  
  if (item.inventory.available < item.quantity) {
    throw new Error(`Insufficient inventory for ${item.name}`);
  }
  
  item.inventory.available -= item.quantity;
  await this.inventoryRepo.save(item.inventory);
}

private calculateTax(total: number, address?: Address): number {
  if (!address) return 0;
  
  return address.country === 'US'
    ? this.calculateUSTax(total, address.state)
    : this.calculateInternationalTax(total, address.country);
}

Result:
- Cyclomatic complexity: 18 → 3 per function ✅
- Nesting depth: 5 → 2 maximum ✅
- Each function has single responsibility ✅
- Easy to test: Each function testable independently ✅
- Easy to modify: Change discount logic? Edit one function ✅

Success Metrics

Team D (SaaS platform, 25 engineers):

• Baseline: Code duplication increasing 5% per quarter
• After AI debt tracking: Duplication decreased 15% in 6 months
• Specific wins:
  • Blocked 12 PRs with high duplication (refactored before merge)
  • Reduced average cyclomatic complexity from 14 to 8
  • Increased test coverage from 68% to 83%
  • Team velocity remained stable (debt reduction didn't slow features)

The Key: Making tech debt visible and measurable. Teams make better decisions when they see the numbers.

Pattern 5: Consistency Enforcement Across Microservices

What It Catches

API design inconsistencies, error handling mismatches, logging standard violations, different patterns for same problems, naming convention drift.

Why It Matters

I reviewed a 15-microservice architecture where:

• 4 different error response formats
• 3 different authentication patterns
• 5 different ways to handle pagination
• No consistent logging structure

Result? Frontend team frustrated. New engineers confused. Debugging nightmares.

Consistency isn't perfectionism—it's reducing cognitive load. When all services work the same way, understanding one teaches you all.

How to Implement

Step 1: Document Service Standards

# Microservices Standards

## API Response Format
All APIs must return consistent structure:

Success:
{
  "success": true,
  "data": { /* response data */ },
  "meta": {
    "timestamp": "ISO 8601",
    "requestId": "uuid"
  }
}

Error:
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { /* additional context */ }
  },
  "meta": {
    "timestamp": "ISO 8601",
    "requestId": "uuid"
  }
}

## Error Codes
- 400: BAD_REQUEST
- 401: UNAUTHORIZED
- 403: FORBIDDEN
- 404: NOT_FOUND
- 409: CONFLICT
- 422: VALIDATION_ERROR
- 429: RATE_LIMIT_EXCEEDED
- 500: INTERNAL_SERVER_ERROR
- 503: SERVICE_UNAVAILABLE

## Pagination
Use cursor-based pagination:
- Query params: ?limit=20&cursor=abc123
- Response includes: data[], nextCursor, hasMore

## Logging
All logs must include:
- timestamp (ISO 8601)
- level (ERROR, WARN, INFO, DEBUG)
- service name
- requestId (from headers)
- userId (if authenticated)
- message
- Additional context as structured data

Format: JSON for production, pretty for development

## Authentication
- All endpoints require JWT (except /health, /metrics)
- JWT in Authorization header: "Bearer <token>"
- Validate signature, expiry, issuer
- Extract userId from token claims

Step 2: Cross-Service Consistency Prompt

Review this PR for consistency with our microservices standards:

Service: [service name]
PR Changes: [paste diff]

Standards:
[Paste your standards]

Comparison Context:
Here's how other services handle similar functionality:
[Paste examples from other services if relevant]

Check for:
1. API response format matches standard
2. Error codes and messages consistent
3. Logging follows standard structure
4. Authentication pattern matches other services
5. Naming conventions align with other services
6. Similar functionality implemented the same way

For each inconsistency:
- Show what this PR does
- Show what the standard is
- Explain impact of inconsistency
- Provide fix to match standard

Real Example: API Response Inconsistency

Existing Services (Correct):

// User Service - Consistent format
@Get('/users/:id')
async getUser(@Param('id') id: string): Promise<ApiResponse> {
  const user = await this.userService.findById(id);
  
  return {
    success: true,
    data: user,
    meta: {
      timestamp: new Date().toISOString(),
      requestId: this.request.id
    }
  };
}

// Order Service - Consistent format
@Get('/orders/:id')
async getOrder(@Param('id') id: string): Promise<ApiResponse> {
  const order = await this.orderService.findById(id);
  
  return {
    success: true,
    data: order,
    meta: {
      timestamp: new Date().toISOString(),
      requestId: this.request.id
    }
  };
}

New PR (Inconsistent):

// Payment Service - INCONSISTENT format
@Get('/payments/:id')
async getPayment(@Param('id') id: string) {
  try {
    const payment = await this.paymentService.findById(id);
    
    // Returns bare object - inconsistent!
    return payment;
    
  } catch (error) {
    // Error format also inconsistent
    return {
      error: error.message,
      code: 500
    };
  }
}

AI Detection:

⚠️ Consistency Violation: API Response Format

File: payment-controller.ts
Lines: 4-15

Issue: Payment Service API response format doesn't match User and Order services.

Current Implementation (Payment Service):
- Success: Returns bare payment object
- Error: Returns { error, code }

Standard Format (User/Order Services):
- Success: { success: true, data: {...}, meta: {...} }
- Error: { success: false, error: { code, message, details }, meta: {...} }

Impact:
1. Frontend must handle different response shapes per service
2. Middleware that expects standard format will break
3. Logging/monitoring tools expect consistent structure  
4. New engineers see inconsistent patterns

Example Frontend Confusion:
// Works for User and Order
const user = await api.get('/users/123');
if (user.success) {
  console.log(user.data);
}

// Breaks for Payment (different format)
const payment = await api.get('/payments/123');
if (payment.success) { // undefined!
  console.log(payment.data); // doesn't exist
}

Corrected Implementation:

@Get('/payments/:id')
async getPayment(
  @Param('id') id: string,
  @Req() request: Request
): Promise<ApiResponse> {
  try {
    const payment = await this.paymentService.findById(id);
    
    return {
      success: true,
      data: payment,
      meta: {
        timestamp: new Date().toISOString(),
        requestId: request.id
      }
    };
    
  } catch (error) {
    return {
      success: false,
      error: {
        code: this.getErrorCode(error),
        message: error.message,
        details: this.getErrorDetails(error)
      },
      meta: {
        timestamp: new Date().toISOString(),
        requestId: request.id
      }
    };
  }
}

Better Yet: Use Response Interceptor

@UseInterceptors(ApiResponseInterceptor) // Enforces format automatically
@Get('/payments/:id')
async getPayment(@Param('id') id: string): Promise<Payment> {
  // Return data directly, interceptor wraps in standard format
  return await this.paymentService.findById(id);
}

This ensures ALL endpoints in ALL services return consistent format.

Real Example: Error Code Inconsistency

Existing Services:

// User Service
throw new NotFoundException({
  code: 'USER_NOT_FOUND',
  message: `User with ID ${id} not found`
});

// Order Service  
throw new NotFoundException({
  code: 'ORDER_NOT_FOUND',
  message: `Order with ID ${id} not found`
});

New PR:

// Payment Service - INCONSISTENT
throw new NotFoundException(`Payment ${id} doesn't exist`);
// Missing: code, structured format

AI Detection:

⚠️ Consistency Violation: Error Handling

File: payment-service.ts
Line: 23

Issue: Payment Service throws errors differently than User and Order services.

Payment Service: throw new NotFoundException(string)
Other Services: throw new NotFoundException({ code, message })

Impact:
- Frontend can't programmatically handle errors (no error code)
- Monitoring can't categorize errors properly
- Error messages less structured

Corrected:

throw new NotFoundException({
  code: 'PAYMENT_NOT_FOUND',
  message: `Payment with ID ${id} not found`
});

Pattern Across Services:
✅ User: USER_NOT_FOUND
✅ Order: ORDER_NOT_FOUND  
✅ Payment: PAYMENT_NOT_FOUND (consistent naming)

Success Metrics

Team E (microservices platform, 100 engineers, 15 services):

Before AI Consistency Checks:

• 4 different API response formats
• 12 different ways to structure errors
• Frontend had 500 lines of normalization code
• New service took 2 weeks to "match" patterns

After Implementation (6 months):

• 1 consistent API response format (enforced by interceptor)
• Standardized error codes and formats
• Frontend normalization code reduced to 50 lines
• New service matches patterns automatically (AI enforces in PRs)
• Cross-service debugging time reduced 40%

Key Insight: Consistency compounds. The more consistent your services, the easier everything else becomes.

Implementation Guide

Ready to implement AI code reviews? Here's your 4-week plan.

Week 1: Setup and Configuration

Day 1-2: Choose and Configure Your AI Tool

Options:

• GitHub Copilot: Best for inline suggestions during coding
• Claude/GPT via API: Best for detailed PR analysis
• CodeRabbit/Greptile: Purpose-built for PR reviews

Start with what you already have. GitHub Copilot + custom PR script works great.

Day 3-4: Create Architecture Context Files

File: .github/copilot-instructions.md (or .context.md)

Include:

• Domain boundaries and rules
• Performance requirements and anti-patterns
• Security requirements
• Code quality standards
• Cross-service consistency rules

Keep it under 10KB—AI works better with concise context.

Day 5: Document Top 10 Architecture Violations

Review last quarter's PRs and production issues:

• What violations occurred most frequently?
• What violations caused production issues?
• What violations create most tech debt?

These become your first AI checks. You can expand later.

Example Week 1 Deliverables:

✅ AI tool configured and accessible
✅ .github/copilot-instructions.md created
✅ Top 10 violations documented
✅ Test PR reviewed with AI (validate setup works)

Week 2: Pattern Implementation

Start with Pattern 1: Domain Boundaries

Why first? Lowest risk, highest impact, easiest to validate.

Day 1-2: Implement Domain Boundary Checks

Add domain rules to context file. Create PR review prompt template. Test on 5 recent PRs (retrospectively).

Day 3: Adjust Based on Results

Review false positives and false negatives. Refine rules and prompts. Update context with learnings.

Day 4-5: Train Team

Show examples of AI-caught violations. Explain how to interpret AI feedback. Document workflow: AI review → Human review.

Example Week 2 Deliverables:

✅ Domain boundary checks active
✅ 5 test PRs reviewed successfully
✅ Team trained on interpreting AI feedback
✅ False positive rate < 15%

Week 3: Scale to More Patterns

Add Patterns 2-3: Performance and Security

Now that team is comfortable with Pattern 1, add more.

Day 1-2: Performance Anti-Pattern Checks

Add performance rules to context. Create performance review prompts. Test on recent performance-related PRs.

Day 3-4: Security Vulnerability Checks

Add security requirements to context. Create security review prompts. Test on authentication/authorization PRs.

Day 5: Establish Review Workflow

Document when to use which patterns:

• All PRs: Domain boundaries, consistency
• Data access PRs: Add performance checks
• Auth/sensitive data PRs: Add security checks

Example Week 3 Deliverables:

✅ Performance checks active
✅ Security checks active
✅ Clear workflow documented
✅ Team using AI in daily reviews

Week 4: Measurement and Optimization

Track Metrics and Refine

Day 1-2: Set Up Metrics Dashboard

Track:

• Violations caught per 100 PRs
• False positive rate
• Average code review time
• Bugs related to architecture violations in production

Use simple spreadsheet or add to existing metrics tool.

Day 3-4: Gather Team Feedback

Survey team:

• Is AI feedback useful?
• What should be added/removed?
• Is review process faster or slower?
• Are they learning from AI feedback?

Day 5: Refine and Optimize

Based on metrics and feedback:

• Remove low-value checks (high false positives, low impact)
• Add checks for issues AI is missing
• Improve prompt templates
• Update documentation

Example Week 4 Deliverables:

✅ Metrics tracked for 4 weeks
✅ Team feedback collected
✅ Prompts refined based on learnings
✅ Clear ROI documented

Measuring Impact

Track these metrics to prove AI code reviews are working:

Metric 1: Violations Caught Per 100 PRs

Before AI: Estimate from production bugs + post-merge fixes After AI: Track violations caught in PR review

Example:

• Before: 8 architecture violations per 100 PRs reached production
• After: 32 violations caught in PR, 2 reached production
• Result: 75% more violations caught before merge

Metric 2: Average Code Review Time

Track time from PR opened to approved.

Counterintuitive Result: Review time often DECREASES.

• AI catches obvious issues instantly
• Humans focus on nuanced architectural decisions
• Less back-and-forth on style/simple violations

Example:

• Before: 4.2 hours average review time
• After: 3.4 hours average (19% faster)

Metric 3: False Positive Rate

AI flags something as violation, but it's actually fine.

Target: <10% false positive rate

How to Measure: Team marks AI flags as "correct" or "false positive"

Example:

• Month 1: 22% false positives (needs tuning)
• Month 2: 14% false positives (improving)
• Month 3: 8% false positives (acceptable)

Metric 4: Production Bugs Related to Architecture

Most important metric: Are fewer architecture bugs reaching production?

Example:

• Quarter 1 (before AI): 12 production issues from architecture violations
• Quarter 2 (after AI): 3 production issues
• Result: 75% reduction

Metric 5: Developer Satisfaction

Simple NPS survey: "How useful is AI code review feedback?"

Example Results (3 months after implementation):

• 68% highly positive: "Catches things I miss"
• 24% neutral: "Sometimes helpful"
• 8% negative: "Too many false positives"

Action: Focus on reducing false positives for the 8%.

Presenting ROI to Leadership

Here's how to make the business case:

Cost of Implementation

One-time:

• 2 weeks senior engineer time setting up: ~$10K
• Documentation and context files: ~$2K

Ongoing:

• AI API costs: ~$200/month
• Maintenance: ~$500/month engineer time

Total First Year: ~$15K

Value Delivered

Production Incident Prevention:

• 9 incidents prevented (12 before → 3 after)
• Average incident cost: $15K (engineering time + customer impact)
• Value: $135K

Reduced Code Review Time:

• 0.8 hours saved per PR × 500 PRs/quarter × $100/hour
• Value: $40K/quarter = $160K/year

Faster Onboarding:

• New engineers learn patterns from AI feedback
• 2 weeks faster to productivity × 8 new hires × $10K
• Value: $160K

Total First Year Value: $455K ROI: 30x

Even if conservative (half those numbers): ROI of 15x

Common Pitfalls

Learn from teams that struggled:

Pitfall 1: Too Many Rules Upfront

The Mistake: Team documented 47 different rules, AI flagged everything, team got overwhelmed and disabled it.

The Fix: Start with 3-5 critical patterns. Add more as team adapts.

Pitfall 2: Trusting AI Blindly

The Mistake: Team auto-merged PRs that passed AI review. AI missed subtle bug, caused production incident.

The Fix: AI is first pass, not final authority. Always human review, especially first 3 months.

Pitfall 3: Poor Documentation

The Mistake: "Please check for architecture violations" (vague). AI gives generic feedback that doesn't match team's actual patterns.

The Fix: Specific context: "Domain boundaries: Service A never accesses Service B's database directly. Communication via REST APIs or events only."

Pitfall 4: Ignoring False Positives

The Mistake: AI flags 40% false positives, team loses trust, stops using it.

The Fix: Track false positives. If >15%, refine prompts and rules. Teams that iterate reach <10% within 2 months.

Pitfall 5: No Feedback Loop

The Mistake: Set up AI reviews, never adjusted based on what worked/didn't work.

The Fix: Monthly review: What did AI miss? What false positives occurred? Update prompts accordingly.

Advanced Techniques

Once basics are working, level up:

Technique 1: AI-Suggested Fixes

Don't just flag violations—have AI suggest fixes.

Prompt Addition:

For each violation found, provide:
1. Explanation of the violation
2. Why it's problematic  
3. Specific code fix (show before/after)
4. Estimated effort to fix

Result: Developers can fix issues faster.

Technique 2: Integration with ADRs

When making architecture decision, document in ADR. Reference ADR in context file.

Example:

# Architecture Decisions

See /docs/adr/0001-microservices-communication.md

Summary:
- Services communicate via REST APIs for synchronous operations
- Services use events (EventBridge) for async operations
- NO direct database access between services
- NO RPC or gRPC (REST only for simplicity)

AI: Check PRs against this ADR. Flag violations.

Technique 3: Custom AI Models

Train AI on your specific codebase.

Tools: Fine-tune GPT-4, train CodeBERT, use Copilot for Business with custom context.

Investment: High (weeks of engineering) Payoff: AI understands your domain-specific patterns

When Worth It: Large teams (100+ engineers), unique domain, high cost of violations.

Technique 4: Cross-Repository Pattern Detection

Check patterns across all repos in organization.

Example: "All 15 services should handle rate limiting the same way. Flag any that don't match pattern in User Service."

Tool: Custom script that analyzes multiple repos, uses AI to compare patterns.

Conclusion

AI code reviews aren't about replacing human judgment—they're about focusing human attention where it matters most.

The numbers are clear:

• 75%+ of architecture violations caught before production
• 20-30% faster review cycles
• Measurably better code quality

But the real win is cultural: Teams start thinking about architecture patterns upfront because they know AI will check. Violations decrease not just because AI catches them, but because developers stop creating them.

Start this week:

1. Document your top 5 architecture rules
2. Add domain boundary checks
3. Review 3 PRs with AI assistance
4. Iterate based on results

The teams winning in 2026 aren't the ones generating the most code with AI—they're the ones maintaining the highest quality while moving faster.

Practical Takeaways

Week 1 Checklist:

• Choose AI tool (Copilot, Claude, or custom)
• Create .github/copilot-instructions.md
• Document top 5 architecture violations from last quarter
• Test AI review on 3 recent PRs
• Measure baseline: How many violations currently reach production?

Pattern Implementation Priority:

1. Domain boundaries (lowest risk, highest impact)
2. Performance anti-patterns (high ROI)
3. Security vulnerabilities (highest severity)
4. Tech debt tracking (long-term value)
5. Cross-service consistency (scales with team size)

Success Metrics Dashboard:

• Violations caught per 100 PRs (target: 30+)
• False positive rate (target: <10%)
• Average review time (track trend)
• Production bugs from architecture issues (target: -50%+)
• Developer satisfaction (target: 70%+ positive)

Monthly Review Questions:

• What did AI catch that humans missed?
• What did AI miss that caused production issues?
• What false positives occurred most?
• How can we refine prompts?
• Should we add/remove patterns?

Start simple. Measure constantly. Iterate quickly. That's how you make AI code reviews work for your team.