How to Enforce Architectural Patterns When AI Generates Your Code (Without Breaking Your Team)

async findById(id: string): Promise { return this.db.query(/ ... /); } }

2. Pre-Generation Context Injection

Before generating code, query the pattern database with the target file path. Inject specific, relevant architectural constraints into the immediate context.

3. Post-Generation Validation

After code generation, validate against the same patterns. Use severity ratings to determine action:

• LOW severity → Auto-submit (pattern followed correctly)
• MEDIUM severity → Flag for human review (minor deviations)
• HIGH severity → Block and auto-fix (critical violations)

The key insight: Specificity matters more than comprehensiveness.

Better to provide 5 highly relevant rules for a specific file than 50 generic rules that might apply.

Technical Deep Dive: Architect MCP Implementation

We implemented this as a Model Context Protocol (MCP) server called @agiflowai/architect-mcp. Here's how it works under the hood.

What is MCP?

Model Context Protocol is an open standard from Anthropic that allows AI assistants to connect to external tools and data sources. Think of it as a universal adapter for AI agents.

For architectural validation, MCP provides:

• Persistent connection to the validation service
• Structured tool definitions for pattern retrieval and validation
• Standard protocol that works across any MCP-compatible AI assistant

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     AI Assistant (Claude)                     │
│                                                               │
│  1. Request pattern for "src/repos/userRepo.ts"              │
│  2. Generate code based on patterns                          │
│  3. Request validation of generated code                     │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP Protocol
┌───────────────────────────▼─────────────────────────────────┐
│                    Architect MCP Server                       │
│                                                               │
│  ┌─────────────────┐  ┌──────────────────┐                  │
│  │ Pattern Matcher │  │  Rule Validator  │                  │
│  │                 │  │                  │                  │
│  │ - Path-based    │  │ - Severity rating│                  │
│  │ - Template-aware│  │ - LLM validation │                  │
│  └────────┬────────┘  └────────┬─────────┘                  │
└───────────┼──────────────────────┼──────────────────────────┘
            │                      │
    ┌───────▼──────┐       ┌──────▼────────┐
    │architect.yaml│       │  RULES.yaml   │
    │              │       │               │
    │ Design       │       │ Coding        │
    │ Patterns     │       │ Standards     │
    └──────────────┘       └───────────────┘

Core MCP Tools

The Architect MCP server exposes four primary tools:

1. get_file_design_pattern

Provides file-specific architectural context before code generation.

Input: File path Output: Relevant patterns for that file type

// MCP Tool Call
{
  "tool": "get_file_design_pattern",
  "arguments": {
    "file_path": "src/repositories/userRepository.ts"
  }
}

// MCP Response
{
  "template": "backend/hono-api",
  "patterns": [
    {
      "pattern_name": "Repository Pattern",
      "design_pattern": "Implement IRepository<T> interface",
      "description": "✅ Use constructor-injected database connection\n✅ Named exports only\n❌ No direct database imports"
    }
  ],
  "reference_files": ["src/repositories/baseRepository.ts"]
}

This runs before Claude generates code, injecting precise architectural requirements into the active context window.

2. review_code_change

Validates generated code against architectural patterns.

Input: File path (code read from disk) Output: Structured validation results with severity rating

// MCP Tool Call
{
  "tool": "review_code_change",
  "arguments": {
    "file_path": "src/repositories/userRepository.ts"
  }
}

// MCP Response
{
  "severity": "HIGH",
  "compliance_rate": "67%",
  "violations": [
    {
      "rule": "No direct database imports",
      "severity": "HIGH",
      "line": 3,
      "description": "Found direct import: import { db } from '../database'",
      "recommendation": "Inject database connection via constructor"
    }
  ],
  "patterns_followed": [
    "✅ Implements IRepository<User>",
    "✅ Uses async methods for database operations"
  ],
  "auto_fix_available": true
}

This runs after code generation, providing structured feedback that can drive automation:

• LOW severity → Auto-submit
• MEDIUM severity → Flag for review
• HIGH severity → Block or auto-fix

3. add_design_pattern (Admin Tool)

Adds new design patterns to a template's architect.yaml.

{
  "tool": "add_design_pattern",
  "arguments": {
    "template_name": "backend/hono-api",
    "pattern_name": "Service Layer Pattern",
    "design_pattern": "Service layer with business logic isolation",
    "includes": ["src/services/**/*.ts"],
    "description": "✅ Services use repositories, never direct DB access\n✅ Business logic only, no HTTP handling\n❌ No inline SQL queries"
  }
}

4. add_rule (Admin Tool)

Adds coding standards to RULES.yaml (global or template-specific).

{
  "tool": "add_rule",
  "arguments": {
    "template_name": "backend/hono-api",
    "pattern": "src/services/**/*.ts",
    "description": "Service layer coding standards",
    "must_do": [
      {
        "rule": "Use dependency injection for all external dependencies",
        "codeExample": "constructor(private userRepo: IUserRepository) {}"
      }
    ],
    "must_not_do": [
      {
        "rule": "No direct database access",
        "codeExample": "// ❌ Wrong\nimport { db } from '../db';"
      }
    ]
  }
}

Path-Based Pattern Matching: The Critical Detail

The pattern database uses path-based matching to provide file-specific guidance. This is where the system gains real leverage.

Pattern Hierarchy

Patterns are applied from most general to most specific, with later patterns overriding earlier ones:

# File: templates/GLOBAL_PATTERNS.yaml
# Global patterns (apply to ALL projects)
design_patterns:
  "**/*.ts":
    pattern_name: "TypeScript Standards"
    design_pattern: "Global TypeScript conventions"
    description: |
      ✅ No 'any' types without justification
      ✅ Use named exports
      ✅ Explicit return types for functions

# File: templates/backend-hono-api/architect.yaml
# Template patterns (apply to projects using this template)
design_patterns:
  "src/repositories/**/*.ts":
    pattern_name: "Repository Pattern"
    design_pattern: "Repository layer implementation"
    description: |
      ✅ Implement IRepository<T>
      ✅ Use dependency injection
      ✅ Async methods for all DB operations

  "src/services/**/*.ts":
    pattern_name: "Service Layer Pattern"
    design_pattern: "Business logic isolation"
    description: |
      ✅ No direct database access
      ✅ Use repository layer
      ✅ Throw domain-specific errors

# File: backend/apis/user-management/architect.yaml
# Project-specific patterns (override template patterns)
design_patterns:
  "src/services/authService.ts":
    pattern_name: "Auth Service Pattern"
    design_pattern: "Authentication-specific patterns"
    description: |
      ✅ Must use AuthProvider interface
      ✅ Token validation on every request
      ✅ Rate limiting for auth endpoints

How Pattern Resolution Works

When Claude requests patterns for backend/apis/user-management/src/services/authService.ts:

1. Global patterns match **/*.ts → TypeScript standards applied
2. Template patterns match src/services/**/*.ts → Service layer standards applied
3. Project patterns match src/services/authService.ts → Auth-specific patterns applied (override template)

The result: Claude receives a merged, specific set of patterns relevant only to that file.

Template Inheritance at Scale

New projects inherit template patterns automatically. No need to reconfigure architectural rules for every new service:

// File: backend/apis/new-api/project.json
{
  "name": "new-api-service",
  "sourceTemplate": "backend/hono-api"
}

The service immediately inherits 50+ architectural patterns specific to Hono.js APIs.

LLM-Powered Validation: Using AI to Check AI

Here's a non-obvious design choice: we use Claude to validate Claude-generated code.

Why? Because architectural compliance isn't mechanical pattern matching. Consider:

Mechanical linter approach:

// Regex: /export\s+default/
// Violation: Uses default export
export default class UserService { }

LLM validation approach:

// Understands context and intent
export default class UserService { }

// Validation result:
{
  "violation": "Uses default export when named export required",
  "severity": "HIGH",
  "context": "Service classes must use named exports per repository pattern in architect.yaml",
  "recommendation": "Change to 'export class UserService' for consistency with DI pattern",
  "auto_fix": "export class UserService { }"
}

The LLM-based validation:

• Understands architectural intent, not just syntax
• Provides contextual explanations that help developers learn
• Reasons about related patterns (violating DI? Probably also missing interface implementation)
• Generates actionable recommendations with auto-fix options

This is more expensive than static linting (1-2 cents per validation), but the cost is justified:

• Runs only on changed files (not entire codebase)
• Provides significantly higher signal than regex matching
• Eliminates false positives from context-unaware rules
• Reduces code review time (saves $50-100 in developer time per caught issue)

How LLM Validation Works

// Simplified validation flow
async function validateCode(filePath: string, fileContent: string) {
  // 1. Get applicable patterns
  const patterns = await getFileDesignPattern(filePath);
  const rules = await getApplicableRules(filePath);

  // 2. Construct validation prompt
  const prompt = `
You are a senior software architect reviewing code for compliance.

FILE: ${filePath}

APPLICABLE PATTERNS:
${patterns.map(p => p.description).join('\n\n')}

APPLICABLE RULES:
${rules.map(r => r.must_do.concat(r.must_not_do)).join('\n')}

CODE TO REVIEW:
\`\`\`typescript
${fileContent}
\`\`\`

Analyze this code against the patterns and rules. For each violation:
1. Identify the specific rule violated
2. Explain why it's a violation (with context)
3. Assign severity: LOW (style), MEDIUM (pattern deviation), HIGH (architectural violation)
4. Provide auto-fix if possible

Respond in JSON format:
{
  "violations": [...],
  "patterns_followed": [...],
  "severity": "LOW" | "MEDIUM" | "HIGH",
  "compliance_rate": "85%"
}
  `;

  // 3. Call Claude for validation
  const response = await callClaude(prompt);

  // 4. Parse and return structured result
  return JSON.parse(response);
}

Severity-Based Automation

The severity rating drives automated responses:

const result = await reviewCodeChange(filePath);

switch (result.severity) {
  case 'LOW':
    // Pattern followed correctly, auto-submit
    await gitAdd(filePath);
    await gitCommit(`feat: ${commitMessage}`);
    break;

  case 'MEDIUM':
    // Minor violations, flag for human review
    await createReviewComment(filePath, result.violations);
    console.warn('⚠️  Review required: Minor pattern deviations detected');
    break;

  case 'HIGH':
    // Critical violations, block or auto-fix
    if (result.auto_fix_available) {
      await applyAutoFix(filePath, result.auto_fix);
      console.log('✅ Auto-fixed critical violations');
    } else {
      throw new ValidationError('Critical architectural violations - manual fix required');
    }
    break;
}

Production Results: 3 Months, 50+ Projects, 8 Developers

After deploying Architect MCP across our monorepo:

The Numbers

Architectural Compliance:

• Before: 40% compliance with documentation
• After: 92% compliance with MCP validation
• Improvement: 130% increase in pattern adherence

Code Review Efficiency:

• Before: 45 minutes average review time
• After: 22 minutes average review time
• Improvement: 51% reduction in review time

Architectural Violations:

• Before: 15-20 violations per week (across 50 projects)
• After: 1-2 violations per week
• Improvement: 90% reduction in violations

Developer Feedback (survey of 8 engineers):

• 100% reported catching violations earlier
• 87% said context-switching overhead decreased
• 75% reported learning architectural patterns faster

What Actually Changed

The obvious improvement: Architectural violations became rare instead of common. Not eliminated—there are still legitimate cases where you need to break a pattern—but the unconscious drift stopped.

Junior developers stopped ping-ponging between following patterns correctly and breaking them in the next file. The feedback loop was finally closed.

The unexpected improvement: Code review shifted focus. We thought we'd just catch violations faster. What actually happened: we stopped spending review cycles on architectural corrections.

Comments like:

• "This should use dependency injection"
• "Use named exports here"
• "Don't access the database directly from services"

These basically disappeared. Reviews focused on:

• Design decisions
• Edge case handling
• Business logic correctness
• Performance implications

Things that actually need human judgment.

The subtle improvement: Context-switching overhead decreased. When working across multiple projects with different architectural patterns (Next.js app vs Hono API vs TypeScript library), developers constantly reload mental context.

Having the validation layer means you find out immediately when you've applied the wrong pattern to the wrong project. Not three reviews later.

What didn't improve: We still see legitimate architectural violations. Sometimes you need to bypass a pattern for a specific reason. The difference is those are now conscious decisions documented in the PR, not unconscious mistakes that slip through review.

Case Study: Refactoring the Auth Service

Context: We needed to refactor our authentication service to support OAuth providers. This touched 12 files across 3 packages.

Before Architect MCP (estimated timeline):

• 2 days development
• 6 hours code review (3 rounds)
• 8 architectural violations caught in review
• 4 hours fixing violations
• Total: ~3.5 days

With Architect MCP (actual timeline):

• 1.5 days development (pre-generation patterns guided implementation)
• 2 hours code review (1 round)
• 0 architectural violations (caught during development)
• Total: ~2 days

ROI: Saved 1.5 days (42% faster delivery) with higher quality output.

What This Reveals About AI-Assisted Development

The broader lesson: AI coding assistants need tight feedback loops, not extensive documentation.

This mirrors how junior developers actually learn a codebase. They don't absorb architectural patterns by reading documentation upfront. They learn by:

1. Getting specific guidance for the task at hand
2. Making changes
3. Getting feedback on what they did wrong
4. Iterating

When junior developers pair with AI, both need the same learning structure. The difference is speed.

Human code review happens in hours or days. Automated feedback happens in seconds. That speed difference makes the approach viable.

The Unexpected Insight

This doesn't just help junior developers. Senior developers using AI make the same architectural mistakes—they just catch them earlier in their own review.

Automated validation helps everyone maintain consistency when context-switching between projects with different architectural patterns. Even senior architects benefit from having patterns explicitly surfaced at code generation time.

Getting Started: Implement in Your Codebase

Architect MCP is open source and ready to use. Here's how to get started.

Installation

# Install via pnpm
pnpm install @agiflowai/architect-mcp

# Or use npx (no install required)
npx @agiflowai/architect-mcp --version

Basic Setup (5 Minutes)

1. Configure MCP for Claude Code

Add to your .claude/mcp.json:

{
  "mcpServers": {
    "architect": {
      "command": "npx",
      "args": [
        "@agiflowai/architect-mcp",
        "mcp-serve",
        "--type", "stdio"
      ],
      "cwd": "/path/to/your/project"
    }
  }
}

2. Create Your First Pattern Definition

Create templates/your-template/architect.yaml:

design_patterns:
  # Start with your most violated pattern
  src/services/**/*.ts:
    pattern_name: "Service Layer Pattern"
    design_pattern: "Services use repositories, no direct DB access"
    includes:
      - "src/services/**/*.ts"
    description: |
      ✅ Use repository pattern for data access
      ✅ Dependency injection via constructor
      ❌ No direct database imports
      ❌ No inline SQL queries

3. Test the MCP Tools

In Claude Code, try:

Can you check what architectural patterns apply to src/services/userService.ts?

Claude will call get_file_design_pattern and show you the patterns.

Implementation Notes: Lessons Learned

If you're building something similar, a few non-obvious lessons from production:

1. Pattern Granularity Matters

Too broad ("follow clean architecture") → AI can't apply it Too narrow ("line 47 must use Promise.all") → You've hardcoded the implementation Just right: File-type specific patterns ("repository pattern for repositories")

2. Severity Ratings Enable Automation

Without severity, you can't automate responses. With severity ratings:

• LOW → Auto-submit (pattern followed correctly)
• MEDIUM → Flag for human attention (minor deviations)
• HIGH → Block submission (critical violations)

This turns validation from a manual gate into an automated safety net.

3. Template Inheritance Is Critical for Scale

Defining patterns per-project doesn't scale past ~10 projects. Template-based inheritance means:

• Define patterns once per framework/architecture
• All projects using that template inherit automatically
• Override with project-specific patterns when needed

Our 50+ project monorepo has only 8 template definitions.

4. LLM Validation Is Worth the Cost

We initially tried regex-based pattern matching. It caught obvious violations (literal string matches like export default) but missed anything requiring context.

Regex can't answer: Why is this a default export? Is this violating the pattern or is this one of the legitimate exceptions?

LLM validation understands intent and context. Yes, it costs money per validation ($0.01-0.02). But the alternative is human code review catching these issues—orders of magnitude more expensive in developer time.

ROI calculation:

• LLM validation cost: $0.02 per file
• Developer time saved: 5 minutes per violation
• Developer cost: $100/hour → $8.33 per 5 minutes
• Net savings: $8.31 per caught violation

At 10 violations prevented per week, that's $4,300/year saved for a $10/month LLM validation cost.

5. Start Small, Expand Gradually

Don't try to encode every architectural pattern on day one. Start with:

• Your top 5 most-violated patterns
• The patterns that cause the most pain in code review
• The patterns that create technical debt when violated

Add more patterns as you identify new violation patterns in PRs.

Open Questions & Future Work

We're still figuring out:

1. Pattern Evolution & Versioning

How do you version architectural patterns? When you update a pattern:

• Do you auto-update all projects using that template?
• Let them opt-in to newer patterns?
• Maintain multiple pattern versions simultaneously?

Our current approach: Template patterns are immutable. Breaking changes require new template versions.

2. Cross-File Architectural Patterns

Current implementation handles single-file patterns well. Cross-file architectural concerns are harder:

Example: "Services should only call repositories, never directly call other services"

This requires:

• Analyzing import graphs
• Understanding call chains across files
• Validating architectural boundaries

We're experimenting with graph-based validation for these cases.

3. Performance at Scale

LLM-based validation works well at our scale:

• 50 projects
• ~10 changes per day
• ~$15/month in LLM costs

What happens at 500 projects or 1000 changes/day?

Potential solutions:

• Caching: Cache validation results for unchanged file patterns
• Batching: Validate multiple files in single LLM call
• Hybrid approach: Regex pre-filter, LLM validation for edge cases
• Incremental validation: Only validate changed functions/classes, not entire files

4. Learning from Violations

Can we automatically learn new patterns from human code review corrections?

Vision: When a developer corrects an AI-generated violation in code review, automatically propose adding that as a pattern to architect.yaml.

This would create a continuous improvement loop:

1. AI generates code
2. Human catches violation in review
3. System proposes pattern definition
4. Architect approves and adds pattern
5. Future AI generations follow the new pattern

We're exploring using LLMs to draft pattern definitions from code review diff + comments.

Conclusion: Closing the Feedback Loop

AI coding assistants are incredibly powerful—but they need the right constraints to maintain architectural consistency. Documentation alone doesn't work. The temporal gap between reading patterns and applying them is too large.

The solution is feedback loops, not front-loading.

By providing architectural context before code generation and validation after, you close the loop that documentation leaves open. The results speak for themselves:

• 92% architectural compliance vs 40% with documentation
• 51% faster code reviews with higher quality output
• 90% reduction in violations across 50+ projects

And the implementation is simpler than you think. Start with:

1. Identify your top 5 violated patterns
2. Define them in YAML (path-based matching)
3. Connect MCP to Claude (pre-generation context)
4. Add validation (post-generation review)
5. Automate responses (severity-based actions)

The hard part isn't the code—it's clearly defining what your architectural patterns actually are. We spent more time debating our patterns than building the validation system.

Ready to Enforce Architecture at Scale?

Architect MCP is open source: github.com/AgiFlow/aicode-toolkit

If you're managing AI agents across multiple projects and need architectural consistency, Agiflow makes it simple:

• Parallel agent orchestration across 10+ Claude Code, Cursor, and GPT agents
• Automatic MCP provisioning with architectural validation
• Real-time cost tracking across agent workloads
• Shift scheduling for optimal parallel workflows
• Built-in architectural enforcement with Architect MCP

500+ engineering teams already use Agiflow to manage autonomous agents in production.

Start your free 14-day trial → (No credit card required)

Or book a demo to see how Agiflow enforces architecture across your AI agent workflows.

---

Related Resources

• The Complete Guide to MCP Tool Provisioning for Engineering Teams
• How to Reduce AI Agent Costs by 40% in Production
• 5 Best Practices for Multi-Agent Orchestration
• Agiflow Documentation

Have questions about enforcing architectural patterns with AI? Drop a comment below or join our community Slack.

---

Originally published on Dev.to - January 15, 2025