Forem: Vuong Ngo

MCP, Code, or Commands? A Decision Framework for AI Tool Integration

Vuong Ngo — Sun, 07 Dec 2025 05:16:36 +0000

When building AI-assisted development workflows, the documentation explains what each approach does—but not the real cost implications or when to use which.

I instrumented network traffic and ran controlled experiments across five approaches using identical tasks: same 500-row dataset, same analysis requirements, same model (Claude Sonnet). The results revealed that architecture matters more than protocol choice.

MCP Optimized consumed 60,420 tokens. MCP Vanilla consumed 309,053 tokens. Same protocol. Same task. 5x difference—driven entirely by one decision: file-path references vs. data-array parameters.

This article provides a decision framework based on measured data, not marketing claims.

The Decision Framework

Before diving into data, here's the framework I developed from these experiments:

Quick Decision Guide

If your situation is...	Use this approach
Repeating task (>20 executions), large datasets, need predictable costs	MCP Optimized
One-off exploration, evolving requirements, prototyping	Code-Driven (Skills)
User must control when it runs, deterministic behavior needed	Slash Commands
Production system with security requirements	MCP Optimized (never Skills)

Decision Flowchart

Q1: One-off task (< 5 executions)?
    YES → Code-Driven or direct prompting
    NO  → Continue

Q2: Dataset > 100 rows AND need < 5% cost variance?
    YES → MCP Optimized
    NO  → Continue

Q3: User needs explicit control over invocation?
    YES → Slash Commands
    NO  → Continue

Q4: Execution count > 20 AND requirements stable?
    YES → MCP Optimized
    NO  → Code-Driven (prototype, then migrate)

NEVER:
  - MCP Vanilla for production (always suboptimal)
  - Skills for multi-user or sensitive systems

The Three Approaches Explained

MCP (Model Context Protocol)

A structured protocol for AI-tool communication. The model calls tools with JSON parameters, the server executes and returns structured results.

// MCP tool call - structured, typed, validated
await call_tool('analyze_csv_file', {
  file_path: '/data/employees.csv',
  analysis_type: 'salary_by_department'
});

Characteristics: Structured I/O, access-controlled, model-decided invocation, reusable across applications.

Critical distinction: There's a 5x token difference between vanilla MCP (passing data directly) and optimized MCP (passing file references). Same protocol, vastly different economics.

Code-Driven (Skills & Code Generation)

The model writes and executes code to accomplish tasks. Claude Code's "skills" feature lets the model invoke capabilities based on semantic matching.

# Claude writes this, executes it, iterates
import pandas as pd
df = pd.read_csv('/data/employees.csv')
result = df.groupby('department')['salary'].mean()
print(result)

Characteristics: Maximum flexibility, unstructured I/O, higher variance between runs, requires sandboxing.

Slash Commands

Pure string substitution. You type /review @file.js, the command template expands, and the result injects into your message.

<!-- .claude/commands/review.md -->
Review the following file for security vulnerabilities,
performance issues, and code quality:

{file_content}

Focus on: authentication, input validation, error handling.

Characteristics: User-explicit, deterministic, single-turn, zero tool-call overhead.

Measured Data: What the Numbers Show

Methodology

Same workload: load 500-row CSV, perform grouping, summary stats, two plots
Same model: Claude Sonnet, default settings
3-4 runs per approach with logged request/response payloads
Costs calculated at current Claude Sonnet pricing

Token Consumption

Token consumption per API request. MCP Optimized achieves consistently low usage through file-path architecture.

Approach	Avg tokens/run	vs Baseline	Why
MCP Optimized	60,420	-55%	File-path parameters; zero data duplication
MCP Proxy (warm)	81,415	-39%	Shared context + warm cache
Code-Skill (baseline)	133,006	—	Model-written Python; nothing cached
UTCP Code-Mode	204,011	+53%	Extra prompt framing
MCP Vanilla	309,053	+133%	JSON-serialized data in every call

Cost at Scale

At 1,000 monthly executions:

Approach	Per Execution	Monthly	Annual
MCP Optimized	$0.21	$210	$2,520
Code-Skill	$0.44	$440	$5,280
MCP Vanilla	$0.99	$990	$11,880

$9,360 annual difference between optimized and vanilla MCP for a single workflow.

Scalability

Cumulative token consumption. MCP Optimized maintains low growth; vanilla approaches accumulate steeply.

Approach	Scaling Factor	10K Row Projection
MCP Optimized	1.5x	~65K tokens
Code-Skill	1.1-1.6x	~150-220K tokens
MCP Vanilla	2.0-2.9x	~500-800K tokens

MCP Optimized exhibits sub-linear scaling because file paths cost the same tokens regardless of file size. MCP Vanilla exhibits super-linear scaling because larger datasets require proportionally more tokens for JSON serialization.

Variance

Approach	Coefficient of Variation	Consistency
MCP Optimized	0.6%	Excellent
MCP Proxy (warm)	0.5%	Excellent
Code-Skill	18.7%	Poor
MCP Vanilla	21.2%	Poor

MCP Optimized hit 60,307, 60,144, and 60,808 tokens across three runs. Code-Skill ranged from 108K to 158K. High variance breaks capacity planning and makes cost prediction unreliable.

Latency

Skills and sub-agents use tool-calling, which means two LLM invocations instead of one:

User message → Model decides → Tool call → Tool result → Final response

Slash commands avoid this—they're just prompt injection with direct response.

Key Lessons

1. Architecture Trumps Protocol

The 5x token difference between MCP Optimized and MCP Vanilla uses the same protocol. The difference is entirely architectural: file paths vs data arrays. Focus on data flow design, not protocol debates.

2. The File-Path Pattern

The single biggest efficiency gain: eliminate data duplication.

// Anti-pattern: 10,000 tokens just for data
await call_tool('analyze_data', {
  data: [/* 500 rows serialized */]
});

// Pattern: 50 tokens for the same operation
await call_tool('analyze_csv_file', {
  file_path: '/data/employees.csv'
});

The MCP server handles file I/O internally. Data never enters the context window.

3. Prototype with Skills, Ship with MCP

Skills execute arbitrary code—bash commands, file system access, network calls. They're excellent for figuring out what tools you need. They're inappropriate for production systems where security matters.

4. Slash Commands Are Underrated

When you need deterministic, user-controlled workflows, slash commands win. No tool-call overhead, no model surprises, no latency penalty. Use them for repeatable tasks like code review checklists or deployment procedures.

5. Sub-Agent Context Isolation

Sub-agents can't see your main conversation history. If they need context, you must explicitly pass it in the delegation prompt. This is by design—clean delegation—but requires explicit information passing.

6. CLAUDE.md Costs Compound

CLAUDE.md content injects into every message, including sub-agent conversations. Keep it concise. Use file references to pull in additional docs only when needed:

<!-- CLAUDE.md -->
# Project Standards
See @docs/CODING_STANDARDS.md for detailed guidelines.

Key rules:
- Use TypeScript strict mode
- No any types

7. Measure Before Optimizing

Instrument your network traffic. The Anthropic API returns token usage in every response—log it. You might be surprised where tokens are actually going.

Implementation Patterns

Parallel Tool Execution

File-path architecture enables parallel calls:

// Four visualizations, one API call, ~400 tokens total
await Promise.all([
  call_tool('create_viz', { file: '/data/emp.csv', type: 'bar', x: 'dept', y: 'salary' }),
  call_tool('create_viz', { file: '/data/emp.csv', type: 'scatter', x: 'exp', y: 'salary' }),
  call_tool('create_viz', { file: '/data/emp.csv', type: 'pie', col: 'department' }),
  call_tool('create_viz', { file: '/data/emp.csv', type: 'bar', x: 'location', y: 'salary' }),
]);

Progressive Tool Discovery

For large tool catalogs (20+ tools), use meta-tools for on-demand discovery instead of loading all tools upfront:

// Initial context: 2 tools, ~400 tokens
const meta_tools = [
  { name: 'describe_tools', description: 'Discover available tools' },
  { name: 'use_tool', description: 'Execute a specific tool' }
];

// Instead of: 50 tools, ~50,000 tokens upfront

Phased Migration Strategy

For uncertain repeatability:

Phase 1: Use code-driven to validate the task. Accept higher per-execution cost for flexibility.
Phase 2: If the task stabilizes and will repeat, invest in MCP Optimized.
Phase 3: Track actual execution count and token consumption. Migrate when patterns are clear.

Summary

Approach	Best For	Avoid When
MCP Optimized	Production workloads, large datasets, predictable costs, security requirements	One-off tasks, evolving requirements
Code-Driven	Prototyping, novel requirements, maximum flexibility	Production systems, multi-user environments
Slash Commands	User-controlled workflows, deterministic behavior, zero overhead	Automation, context-dependent decisions

The core insight: how you architect data flow matters more than which protocol you choose. The 5x token difference between optimized and vanilla MCP—for the same task—demonstrates this clearly.

Match the tool to your constraints. Measure the results.

References

Token Efficiency in AI-Assisted Development - Full analysis of token consumption across approaches
Claude Code Internals: Reverse Engineering Prompt Augmentation - Deep dive into how Claude Code's prompt mechanisms work
MCP Specification
AICode Toolkit (GitHub) - MCP servers and tools for AI-assisted development
Token efficiency experiments (GitHub)
Prompt augmentation analysis (GitHub)

All claims are reproducible using the open-source data and tooling in the referenced repositories.

AI Keeps Reinventing Your Components. Here's How to Stop It.

Vuong Ngo — Sun, 30 Nov 2025 10:43:40 +0000

Three days before a customer pilot, our PM pinged me: "Can we ship that analytics dashboard?" The design had been sitting in Figma for weeks. I promised I'd have it in production by Friday with AI co-pilot.

By Wednesday morning, the PR was still in draft. Not because the UI was hard—it looked exactly like the mock—but because the AI kept inventing work.

Here's what a typical week produced:

// Monday - inline styles
export const RevenueCard = () => {
  return (
    <div style={{
      background: 'white',
      borderRadius: '12px',
      padding: '24px',
      boxShadow: '0 1px 3px rgba(0,0,0,0.1)'
    }}>
      <span style={{ color: '#6B7280', fontSize: '14px' }}>Total Revenue</span>
      <div style={{ fontSize: '32px', fontWeight: 600 }}>$124,500</div>
    </div>
  );
};

// Tuesday - MUI (we use Tailwind)
import { DataGrid } from '@mui/x-data-grid';

// Wednesday - CSS modules (since when?)
import styles from './FilterPanel.module.css';

// Thursday - styled-components (not even installed)
import styled from 'styled-components';

Four days. Four completely different approaches. The code worked, technically. But maintaining it? Good luck.

The root cause became obvious: AI doesn't read documentation the way humans do. It pattern-matches. And if your codebase doesn't have clear patterns to match, AI will invent its own—differently every time.

The Lesson

AI reflects your architecture. Chaotic codebase, chaotic output. Structured codebase, structured output.

After months of trial and error, here's what actually works.

1. Separate State From Representation (Smart vs Dumb Components)

AI writes strange things when fetch logic, loading UI, and display live in the same file. Split them.

// Container: owns data fetching
export function RevenueCardContainer() {
  const { data, error, isLoading } = useRevenue();

  if (isLoading) return <RevenueCardView state="loading" />;
  if (error) return <RevenueCardView state="error" message="Revenue unavailable" />;
  if (!data) return <RevenueCardView state="empty" message="No revenue yet" />;

  return <RevenueCardView state="ready" value={data.value} previousValue={data.previousValue} />;
}

// Presentational: pure UI, tokens only
export function RevenueCardView({ state, value, previousValue, message }: Props) {
  if (state === 'loading') return <MetricCard loading label="Revenue" />;
  if (state === 'error') return <MetricCard label="Revenue" error message={message} />;
  if (state === 'empty') return <MetricCard label="Revenue" empty message={message} />;

  return (
    <MetricCard
      label="Revenue"
      value={value}
      previousValue={previousValue}
      format="currency"
    />
  );
}

Storybook becomes the contract AI must honor. Capture the four canonical states—loading, empty, error, ready—so the bot can't invent new ones:

// RevenueCardView.stories.tsx
export const Loading = { args: { state: 'loading' } };
export const Empty = { args: { state: 'empty', message: 'No revenue yet' } };
export const Error = { args: { state: 'error', message: 'Revenue unavailable' } };
export const Ready = { args: { state: 'ready', value: 124500, previousValue: 110600 } };

AI stops rebuilding components that already exist because the stories show the "golden" versions.

2. Adopt Atomic Design

Atomic Design by Brad Frost turns out to be exactly what you need when AI is generating your code.

The core insight: hierarchical composition. Atoms form molecules. Molecules form organisms. Each level has a single responsibility.

Why does this matter for AI? Because AI excels at composition when given well-defined pieces and falls apart when rules are ambiguous.

// Level 1: Atoms - indivisible primitives
export const Text = ({ variant, color, children }: TextProps) => (
  <span className={cn(textVariants[variant], textColors[color])}>
    {children}
  </span>
);

export const Skeleton = ({ variant = 'text' }: SkeletonProps) => (
  <div className={cn('animate-pulse bg-muted rounded', skeletonVariants[variant])} />
);

// Level 2: Molecules - atoms with a purpose
export const MetricValue = ({ value, previousValue, format, loading }: Props) => {
  if (loading) {
    return (
      <div className="space-y-2">
        <Skeleton variant="heading" />
        <Skeleton variant="text" className="w-16" />
      </div>
    );
  }

  return (
    <div className="space-y-1">
      <Text variant="display" color="primary">{formatters[format](value)}</Text>
      {previousValue && <TrendIndicator value={calculateChange(value, previousValue)} />}
    </div>
  );
};

// Level 3: Organisms - complete UI sections
export const MetricCard = ({ label, value, previousValue, format, loading }: Props) => (
  <Card variant="elevated" padding="lg">
    <MetricLabel label={label} />
    <MetricValue value={value} previousValue={previousValue} format={format} loading={loading} />
  </Card>
);

Now when I ask for "a revenue metric card," AI composes: <MetricCard label="Revenue" value={revenue} format="currency" />. Consistent every time.

3. Design Tokens as Vocabulary

Components solve structural consistency. Design tokens solve visual consistency.

Named constants for every visual decision—not "blue" but action-primary, not "16px" but spacing-4:

export const colors = {
  action: {
    primary: '#6366F1',
    primaryHover: '#4F46E5',
  },
  surface: {
    page: '#F9FAFB',
    card: '#FFFFFF',
  },
  content: {
    primary: '#111827',
    secondary: '#4B5563',
    muted: '#9CA3AF',
  },
} as const;

Wire them through Tailwind config:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        action: {
          primary: 'var(--color-action-primary)',
        },
        surface: {
          card: 'var(--color-surface-card)',
        },
        content: {
          primary: 'var(--color-content-primary)',
        },
      },
    },
  },
};

Now when AI writes bg-surface-card or text-content-secondary, it's speaking your design language. No hex codes that drift.

4. Scaffold Before You Generate

AI behaves best when you give it a guardrailed sandbox instead of a blank file.

A command like pnpm ui:generate metric-card should create:

MetricCard/
├── MetricCard.tsx        # Container
├── MetricCardView.tsx    # Presentational
├── MetricCard.stories.tsx
├── MetricCard.test.tsx
└── index.ts

The generated files include TODOs and comments telling AI where to edit and where not to touch. AI fills the blanks instead of rewriting the world. You can also use this mcp to help with scaffolding with the folder structure you liked.

5. Enforce Contracts with Lint and Stories

Static rules catch mistakes before they ship.

// eslint.config.mjs
export default [
  {
    rules: {
      'no-restricted-imports': [
        'error',
        {
          paths: ['styled-components', '@mui/material'],
          patterns: [
            { group: ['**/../*'], message: 'Import UI from @/components/ui' },
          ],
        },
      ],
      'tailwindcss/no-custom-classname': [
        'error',
        { callees: ['cn'], config: './tailwind.config.js' },
      ],
    },
  },
];

ESLint bans off-piste imports
Tailwind plugin forces token utilities
CI fails if stories miss the four states

Mistakes die in CI, not in code review.

Bonus: Composition Over God Components

Don't build this:

// ❌ 60+ props nobody can reason about
<DataTable
  data={transactions}
  columns={columns}
  pagination={true}
  paginationPosition="bottom"
  sortable={true}
  filterable={true}
  selectable={true}
  // ... 55 more props
/>

Build this:

// ✅ Composition: each piece does one thing well
<DataTable data={transactions} columns={columns}>
  <DataTableToolbar>
    <DataTableFilter column="status" options={statusOptions} />
    <DataTableSearch placeholder="Search..." />
  </DataTableToolbar>
  <DataTableBody loading={isLoading} emptyState={<Empty />} />
  <DataTableFooter>
    <DataTablePagination pageSize={10} />
  </DataTableFooter>
</DataTable>

Same capabilities, different mental model. When requirements change, you reorganize JSX rather than hunting through props.

Extra Tips

Embed source locations in the DOM:

<div
  data-component="MetricCard"
  data-source="src/components/MetricCard/MetricCard.tsx"
>

AI can inspect the DOM and jump straight to the file. No guessing.

Sub-agents to save context:

Your main conversation doesn't need the entire component library in memory. Spin up focused agents for specific tasks (UI fixes, story writing, a11y audits)—they load only what they need and return.

Reusable commands:

Build /add-story, /review-component, /fix-ui commands that encode your conventions. AI follows them without you repeating yourself.

The Path Forward

The fix for inconsistent AI output isn't better prompting. It's tighter architecture.

Every atom you add to your library is an atom AI never reinvents. Every design token is a decision that never drifts. Every composition pattern is a template for variations you haven't thought of yet.

Build the rails, the bot stays on track.

Originally published at agiflow.io

AI Keeps Breaking Your Architectural Patterns. Documentation Won't Fix It.

Vuong Ngo — Sun, 12 Oct 2025 07:40:32 +0000

I've been using AI coding assistants across our engineering team for over a year. Working in a data department, we had some privilege to experiment and use Claude, Roo-Code and other in-house agents for our daily workflow.

The pattern emerged slowly. Junior developers shipping features faster than before, which was great. Code reviews taking longer, which wasn't. The code functionally worked, tests passed, but something was consistently off. Direct database imports in service layers. Default exports scattered across a codebase that had standardized on named exports years ago. Repository pattern bypassed in favor of inline SQL.

These weren't bugs. The code ran fine in production. They were architectural drift—the slow erosion of patterns we'd spent years establishing. What made it frustrating was the inconsistency. A junior developer would correctly implement dependency injection in one file, then bypass it completely in the next. Same developer, same day, same codebase. The knowledge was there, but it wasn't being applied consistently.

The obvious answer was "better code review." But that doesn't scale. When you're reviewing 20+ PRs a day across a 50-package monorepo, you can't catch every architectural violation. And the ones you miss compound.

Here's what we figured out: this isn't an AI problem or a developer problem. It's a feedback timing problem.

TL;DR

AI-generated code violates architectural patterns because of timing and context, not capability
Static documentation creates a validation gap that AI can't bridge
Effective architecture enforcement requires runtime feedback loops, not upfront documentation
Path-based pattern matching provides file-specific architectural context
We built Architect MCP to close the feedback loop at code generation time
Results: 80% pattern compliance vs 30-40% with documentation alone

The Real Problem: Temporal and Spatial Context Loss

Let's be precise about what's happening here. AI coding assistants operate with ephemeral context windows. Even with project-specific documentation (CLAUDE.md, system prompts, etc.), there's a fundamental mismatch between when architectural constraints are communicated and when they need to be applied.

Consider a typical session:

Claude reads your architectural guidelines at initialization (t=0)
You discuss requirements, explore the codebase, iterate on design (t=0 to t=20min)
Claude generates code implementing the agreed-upon logic (t=20min)

By step 3, the architectural constraints from step 1 are 20 minutes and dozens of messages removed from the working context. The AI is optimizing for correctness against the immediate requirements, not consistency against architectural patterns defined at session start.

This isn't a memory problem—it's a priority and relevance problem.

What AI Optimizes For

When generating code, LLMs are fundamentally pattern-matching against their training data. Your specific architectural conventions represent a tiny signal compared to the millions of codebases in the training set. Without active feedback, the model defaults to the strongest statistical patterns:

Common > Custom: Express.js patterns over your Hono.js conventions
Simple > Structured: Direct database calls over repository pattern
Familiar > Framework-specific: Default exports because they're ubiquitous in the training data

This is why you see the same violations repeatedly, even with extensive documentation.

Why Documentation Fails (And What That Tells Us)

Our first attempt was documentation. We already had a substantial CLAUDE.md, but we expanded it. Detailed sections on dependency injection patterns, repository layer requirements, export conventions, framework-specific architectural rules. We made it comprehensive—over 3,000 lines.

Junior developers referenced it. AI assistants had access to it. Compliance rate stayed around 40%. The failure modes are instructive:

1. The Relevance Gap

A 1k-line document applies to every file equally, which means it applies to no file specifically. A repository needs repository-specific guidance. A React component needs component-specific rules. Serving generic "follow clean architecture" advice to both is essentially noise.

2. The Retrieval Problem

Even with RAG systems, retrieving the right architectural context at code generation time is non-trivial. You need to know what patterns apply before you can retrieve them. If Claude is generating a new file type, there's no obvious query to pull the relevant constraints.

3. The Validation Gap

This is the critical one. Documentation describes correct patterns but provides no mechanism to verify compliance. It's teaching without testing. The feedback loop is broken.

Rethinking the Problem: Feedback Over Front-loading

Here's the architectural insight: you can't front-load all context, but you can close the feedback loop.

Instead of trying to make AI remember everything upfront, we need to provide architectural feedback at two critical moments:

Before code generation: "What patterns apply to this specific file?"
After code generation: "Does this implementation comply with those patterns?"

This shifts from a memory problem to a validation problem. And validation can be automated.

The Feedback Loop Architecture

The system needs three components:

1. Pattern Database
Organized by file path patterns with specific architectural requirements:

src/repositories/**/*.ts → Repository pattern rules
src/services/**/*.ts → Service layer rules
src/components/**/*.tsx → Component architecture rules

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 (submit, flag, auto-fix).

The key insight: specificity matters more than comprehensiveness. Better to provide five highly relevant rules for a specific file than 50 generic rules that might apply.

Implementation: Architect MCP

We implemented this as an MCP (Model Context Protocol) server with two primary tools:

get-file-design-pattern

Provides file-specific architectural context before code generation.

// Input: File path
get-file-design-pattern("src/repositories/userRepository.ts")

// Output: Specific patterns for this file type
{
  "template": "backend/hono-api",
  "patterns": [
    "Implement IRepository<T> interface",
    "Use constructor-injected database connection",
    "Named exports only (export class RepositoryName)",
    "No direct database imports (import from '../db' is violation)"
  ],
  "reference": "src/repositories/baseRepository.ts"
}

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

review-code-change

Validates generated code against architectural patterns.

// Input: File path and generated code
review-code-change("src/repositories/userRepository.ts", generatedCode)

// Output: Structured validation results
{
  "severity": "LOW" | "MEDIUM" | "HIGH",
  "violations": [...],
  "compliance": "92%",
  "patterns_followed": ["✅ Implements IRepository<User>", ...],
  "recommendations": [...]
}

This runs after code generation, providing structured feedback that can drive automation (auto-submit on LOW, flag on MEDIUM, auto-fix on HIGH).

Path-Based Pattern Matching: The Critical Detail

The pattern database uses path-based matching to provide file-specific guidance. This deserves deeper explanation because it's where the system gains leverage.

Pattern Hierarchy

# Global patterns (apply to all projects)
**/*.ts:
  - No 'any' types without justification
  - Use named exports

# Template patterns (apply to projects using this template)
backend/hono-api:
  src/repositories/**/*.ts:
    - Implement IRepository<T>
    - Use dependency injection

  src/services/**/*.ts:
    - No direct database access
    - Use repository layer

# Project patterns (apply to specific project)
user-management-api:
  src/services/authService.ts:
    - Must use AuthProvider interface
    - Specific to auth domain

The system applies patterns from most general to most specific, with later patterns overriding earlier ones. This provides both consistency (global rules) and flexibility (project-specific exceptions).

Why This Scales

New projects inherit template patterns automatically. No need to reconfigure architectural rules for every new service—just specify the template in 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 { }
// Violation: Uses default export when named export required per repository pattern
// Recommendation: Change to 'export class UserService' for consistency with repository pattern established in architect.yaml

The LLM-based validation:

Understands architectural intent, not just syntax
Provides contextual explanations
Can reason about related patterns (if you're violating DI, you're probably also missing interface implementation)
Generates actionable recommendations

This is more expensive than static linting, but the cost is justified because it runs only on changed files and provides significantly higher signal.

Layered Validation: Defense in Depth

Architect MCP isn't a replacement for existing validation layers—it's complementary. The full validation stack:

Layer 1: TypeScript Compiler

Catches: Type errors, syntax violations
Speed: < 1s
Coverage: Type safety

Layer 2: Biome/ESLint

Catches: Code style, simple rules
Speed: < 5s
Coverage: Style consistency

Layer 3: Architect MCP

Catches: Architectural pattern violations
Speed: 5-10s (LLM call)
Coverage: Framework-specific architecture

Layer 4: Code Review (Human/AI)

Catches: Business logic, complex issues
Speed: Minutes to hours
Coverage: Domain-specific concerns

Each layer has different trade-offs. TypeScript is fast but can't enforce architectural patterns. Linting handles style but not domain architecture. Architect MCP fills the gap between syntax/style and human review.

What Actually Changed

After 3 months in production across our 50+ project monorepo with a team of 8 developers:

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 unexpected improvement: Code review shifted. We thought we'd just catch violations faster. What actually happened was we stopped spending review cycles on architectural corrections. Comments like "this should use dependency injection" or "use named exports" basically disappeared. Reviews focused on design decisions, edge cases, business logic—things that actually need human judgment.

The subtle improvement: Context-switching overhead decreased. When you're working across multiple projects with different architectural patterns (Next.js app vs Hono API vs TypeScript library), you're constantly reloading 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.

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:

Getting specific guidance for the task at hand
Making changes
Getting feedback on what they did wrong
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 is what 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.

Implementation Notes

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

1. Pattern Granularity Matters
Too broad (e.g., "follow clean architecture") and AI can't apply it. Too narrow (e.g., "line 47 must use Promise.all") and you've essentially hardcoded the implementation. The right level is "file-type specific patterns" (repository pattern for repositories, component pattern for components).

2. Severity Ratings Enable Automation
Without severity ratings, you can't automate responses. With them:

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

3. Template Inheritance Is Critical for Scale
Defining patterns per-project doesn't scale past ~10 projects. Template-based inheritance means you define patterns once per framework/architecture, then all projects using that template inherit them.

4. LLM Validation Is Worth the Cost
We initially tried regex-based pattern matching. It caught obvious violations—literal regex matches like export default—but missed anything requiring context. Why is this a default export? Is it actually violating the pattern or is this one of the legitimate exceptions? Regex can't answer that. LLM validation understands intent and context. Yes, it costs money per validation. But the alternative is human code review catching these issues, which is orders of magnitude more expensive in terms of developer time.

Getting Started

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

The implementation is straightforward—it's an MCP server that reads YAML pattern definitions and uses Claude to validate code against them. The hard part isn't the code—it's defining your architectural patterns clearly enough to encode them. We spent more time debating what our patterns actually were than building the validation system.

If you're building something similar, start with:

Identify your top 5 most-violated architectural patterns
Define them as path-based rules in YAML
Build the pre-generation context injection first (higher ROI than validation)
Add validation once you've proven the concept

Open Questions

We're still figuring out:

1. Pattern Evolution
How do you version architectural patterns? When you update a pattern, do you auto-update all projects or let them opt-in?

2. Cross-File Patterns
Current implementation handles single-file patterns well. Cross-file architectural concerns (e.g., "services should only call repositories, never directly call other services") are harder to encode and validate.

3. Performance at Scale
LLM-based validation works well at our scale (50 projects, ~10 changes/day). What happens at 500 projects or 1000 changes/day? Do you need caching, batching, or a hybrid approach?

If you've solved these problems, I'd love to hear about it.

If you're dealing with similar problems—AI generating code that works but breaks your architectural patterns—I'd be curious to hear how you're handling it. Drop a comment or reach out.

Resources:

Architect MCP GitHub
Preview post about Scaffolding technique

Scaling AI-Assisted Development: How Scaffolding Solved My Monorepo Chaos

Vuong Ngo — Sun, 05 Oct 2025 23:40:29 +0000

The Moment I Realized AI Coding Was Broken.

It was 10PM. I'd just asked Claude to add a navigation component. Thirty seconds later, I was staring at this:

// What the AI generated (again)
const Navigation = ({ items }: NavigationProps) => {
  const [open, setOpen] = useState(false);
  return <nav className="navigation">...</nav>
}
export default Navigation;

Nothing wrong with it, technically. Except I don't use default exports. I use named exports. And useState should come from our custom hooks. And we use 'isOpen', not 'open'. And the TypeScript interface should be exported separately like every other component in our codebase.

I'd explained this exact pattern so many times I'd lost count.

Same pattern. Different day. Different component. Different wrong implementation.

This wasn't a one-off. My monorepo had become a Frankenstein's monster of inconsistent patterns—each one technically correct, all of them a maintenance nightmare.

The promise was simple: AI would code faster than humans.

The reality? I was spending more time fixing AI-generated code than I would've spent just writing it myself.

How AI-Assisted Development Actually Breaks

Here's what nobody tells you about scaling with AI coding assistants:

Week 1: The Honeymoon Phase

You: "Build me a login page"
AI: ✨ generates perfect login page ✨
You: "Holy shit, this is the future"

Everything works. You're shipping features at 10x speed. Your manager thinks you're a wizard. You're thinking about that promotion.

Month 1: The Cracks Appear

You're reviewing frontend components and notice something odd:

// TaskBadge.tsx (written 2 weeks ago)
export const TaskBadge = ({ status }: TaskBadgeProps) => {
  return <span className={`badge ${getColor(status)}`}>{status}</span>;
};

// PriorityBadge.tsx (written yesterday)
export function PriorityBadge(props: PriorityProps) {
  const color = getPriorityColor(props.priority);
  return <div className={color}>{props.priority}</div>;
}

// StatusLabel.tsx (written today)
function StatusLabel({ value }: StatusProps) {
  return <Badge variant={getVariant(value)}>{value}</Badge>;
}

Three badge components. Three different patterns. All from the same AI. All from the same human (you).

And on the backend, it's the same story:

// userService.ts (2 weeks ago)
@injectable()
export class UserService {
  constructor(@inject(TYPES.Database) private db: Database) {}
}

// authService.ts (yesterday)
export class AuthService {
  private db: Database;
  constructor(database: Database) {
    this.db = database;
  }
}

// paymentService.ts (today)
class PaymentService {
  constructor(public database: Database) {}
}

Three services. One uses dependency injection properly. One doesn't. One is halfway there.

"Okay, I need better instructions," you think.

Month 2: The Documentation Death Spiral

Your CLAUDE.md file has grown massively. You've documented:

Component patterns ✓
Import styles ✓
File naming ✓
Prop validation ✓
Error handling ✓
State management ✓
API patterns ✓

You've told the AI everything.

Then you ask it to create a settings page, and it still uses a different button component than the rest of your app.

"But I literally documented this!" you scream at your screen at 3 AM.

The AI apologizes (One-time, I said "Your're f*king right" which is hilarious). Generates a new version. Wrong again, but differently wrong.

Month 3: The Breaking Point

You're now maintaining:

Dozens of CLAUDE.md files scattered everywhere
Multiple variations of what should be the same pattern
A massive style guide that the AI follows inconsistently
Code reviews that are mostly style debates instead of logic discussions

The math breaks: You're spending hours fixing what should've taken minutes to write.

This was me. And this was my monorepo:

Frontend apps built with Next.js and TanStack Start
Backend APIs using Hono.js, FastAPI and Lambda
Shared packages for everything reusable
Microservices, edge functions, and infrastructure all in one repo

The bigger it grew, the worse it got. And I wasn't alone.

My Failed Experiments

Attempt 1: The Mega CLAUDE.md

I created comprehensive documentation files referencing everything:

Project Structure
Coding Standards
Technology Stack
Conventions
Style System
Development Process

Result: Even with token-efficient docs, I couldn't cover all design patterns across multiple languages and frameworks. AI still made mistakes.

Attempt 2: CLAUDE.md Everywhere

"Maybe collocated instructions work better?" I created CLAUDE.md files everywhere for different apps, APIs, and packages.

Result: Slightly better when loaded in context (which didn't always happen). But the real issue: I only had a handful of distinct patterns. Maintaining dozens of instruction files for those same patterns? Nightmare fuel.

Attempt 3: Autonomous Workflows

I set up autonomous loops: PRD → code → lint/test → fix → repeat.

Result: I spent more time removing code and fixing bugs than if I'd just coded it myself. The AI would hallucinate solutions, ignore patterns, and create technical debt faster than I could clean it up.

The Three Core Problems

1. Inconsistency Across Codebase

Frontend:

// AgentStatus.tsx - uses our design system
export const AgentStatus = ({ status }: Props) => {
  return <Badge className={getStatusColor(status)}>{status}</Badge>;
};

// TaskStatus.tsx - reinvents the wheel
export function TaskStatus({ task }: TaskProps) {
  return <div className="status-badge">{task.status}</div>;
}

// SessionStatus.tsx - different again
const SessionStatus = (props: SessionProps) => (
  <span className={styles.badge}>{props.status}</span>
);

Backend:

// taskRepo.ts - proper DI
@injectable()
export class TaskRepository {
  constructor(@inject(TYPES.Database) private db: IDatabaseService) {}
}

// projectRepo.ts - missing decorator
export class ProjectRepository {
  constructor(private db: IDatabaseService) {}
}

// memberRepo.ts - no DI at all
export class MemberRepository {
  private db = getDatabaseClient();
}

Same concept, different implementations. All technically correct. All maintenance nightmares.

2. Context Window Overload

Your documentation grows from this:

# Conventions
- Use functional components
- Use TypeScript

To this monstrosity:

# Conventions
## Components
- Use functional components
- Props interface must be exported
- Use PascalCase for component names
...(10+ reference docs)

Eventually, even AI can't keep up.

3. Pattern Recreation Waste

How many times have you watched AI recreate the same pattern?

Authenticated API routes with similar structure
Badge components that look identical but use different approaches
Repository classes with the same DI pattern but inconsistent implementation
Service classes that all need the same base configuration

Each time slightly different. Hours wasted on work already done.

The Solution: Intelligent Scaffolding

Instead of fighting these problems with longer instructions, I needed a fundamental shift: teach AI to use templates, not just write code.
How It Works: The scaffolding approach leverages MCP (Model Context Protocol) to expose template generation as a tool that AI agents can call. It uses structured output (JSON Schema validation) for the initial code generation, ensuring variables are properly typed and validated. This generated code then serves as guided generation for the LLM—providing a solid foundation that follows your patterns, which the AI can then enhance with context-specific logic. Think of it as "fill-in-the-blanks" coding: the structure is guaranteed consistent, while the AI adds intelligence where it matters.

The Key Insight

Traditional scaffolding requires complete, rigid templates. But with AI coding assistants, you only need:

A skeleton with minimal code
A header comment declaring the pattern and rules
Let the AI fill in the blanks contextually

Example from our actual codebase:

/**
 * PATTERN: Injectable Service with Dependency Injection
 * - MUST use @injectable() decorator
 * - MUST inject dependencies with @inject(TYPES.*)
 * - MUST define constructor parameters as private/public based on usage
 * - MUST include JSDoc with design principles
 */
@injectable()
export class {{ ServiceName }}Service {
  constructor(
    @inject(TYPES.Database) private db: IDatabaseService,
    @inject(TYPES.Config) private config: Config,
  ) {
    // AI fills in initialization logic
  }

  // AI generates methods following the established pattern
}

The AI now knows the rules and generates code that follows them.

Enter: Scaffold MCP

I built the @agiflowai/scaffold-mcp to implement this approach. It's an MCP (Model Context Protocol) server that provides:

Boilerplate templates for new projects
Feature scaffolds for adding to existing projects
AI-friendly minimal templates with clear patterns

Why MCP?

✅ Works with Claude Code, Cursor, or any MCP-compatible tool
✅ Tech stack agnostic (Next.js, React, Hono.js, your custom setup)
✅ Multiple modes: MCP server or standalone CLI
✅ Always available to AI like any other tool

Real-World Workflow Transformation

Before Scaffolding: Starting a New API

You: "Create a new Hono API with authentication"
AI: *generates files with different patterns*
You: "Wait, where's the dependency injection?"
You: "Can you use our standard middleware setup?"
You: "Actually, use Zod for validation like our other APIs..."
*Back-and-forth debugging*

After Scaffolding: Starting a New API

Using CLI:

# See available templates
scaffold-mcp boilerplate list

# Create API with exact conventions
scaffold-mcp boilerplate create hono-api-boilerplate \
  --vars '{"apiName":"notification-api","port":"3002"}'

# ✓ Complete API structure created
# ✓ Dependency injection configured
# ✓ All following your team's conventions

Using Claude Code:
Simply say: "Create a new notification API"

Claude automatically uses the scaffold-mcp MCP server and creates your API with proper DI, middleware, and validation.

Before Scaffolding: Adding Features

You: "Add a new repository class for comments"
AI: *creates class without DI decorator*
You: "No, use dependency injection like the other repos"
AI: *adds DI but forgets the @injectable decorator*
You: "Look at TaskRepository as an example"
*More back-and-forth*

After Scaffolding: Adding Features

Using CLI:

# What can I add?
scaffold-mcp scaffold list ./backend/apis/my-api

# Add matching feature
scaffold-mcp scaffold add scaffold-repository \
  --project ./backend/apis/my-api \
  --vars '{"entityName":"Comment","tableName":"comments"}'

# ✓ Perfect pattern match with proper DI

Using Claude Code:
"Add a repository for comments to my API"

Claude uses scaffold-mcp to ensure the new repository matches your DI patterns, uses the correct decorators, and follows your coding standards.

Creating Your Own Templates

The real power comes from encoding your team's patterns.

Step 1: Installation

# Install
npm install -g @agiflowai/scaffold-mcp

# Initialize templates
scaffold-mcp init

Step 2: Enable Admin Tools (Claude Code)

{
  "mcpServers": {
    "scaffold-mcp": {
      "command": "npx",
      "args": ["-y", "@agiflowai/scaffold-mcp", "mcp-serve", "--admin-enable"]
    }
  }
}

Step 3: Create Template with AI

Tell Claude:

"Create a boilerplate template called 'injectable-service' in 'backend-templates'
that creates backend services with dependency injection and proper structure"

Claude uses the admin tool to generate:

# templates/backend-templates/scaffold.yaml
boilerplate:
  name: injectable-service
  description: Backend service with DI, config, and proper structure
  targetFolder: backend/apis/my-api/src/services

  variables_schema:
    type: object
    properties:
      serviceName:
        type: string
        pattern: "^[A-Z][a-zA-Z0-9]*$"
        description: Service name in PascalCase
    required:
      - serviceName

  includes:
    - {{ serviceName | camelCase }}Service.ts
    - {{ serviceName | camelCase }}Service.test.ts

Step 4: Create Template Files

Tell Claude:

"Create the service template file with dependency injection, config support, and JSDoc"

Claude generates:

// templates/backend-templates/{{ serviceName | camelCase }}Service.ts.liquid
/**
 * {{ serviceName }} Service
 *
 * DESIGN PRINCIPLES:
 * - Dependency Injection: Use Inversify for loose coupling
 * - Type Safety: Full TypeScript support
 * - Configuration: Use Config service for environment variables
 *
 * PATTERN: Injectable Service
 * - MUST use @injectable() decorator
 * - MUST inject dependencies with @inject(TYPES.*)
 * - MUST document design principles in JSDoc
 */
import { inject, injectable } from 'inversify';
import type { IDatabaseService } from '@agimonai/backend-database';
import type { Config } from '@/services';
import { TYPES } from '@/types';

@injectable()
export class {{ serviceName }}Service {
  constructor(
    @inject(TYPES.Database) private db: IDatabaseService,
    @inject(TYPES.Config) private config: Config,
  ) {
    // Initialization logic
  }

  /**
   * Add your service methods here
   */
  public async execute() {
    // Implementation
  }
}

Step 5: Use Your Template

scaffold-mcp boilerplate create injectable-service \
  --vars '{"serviceName":"Email"}'

# ✓ Created backend/apis/my-api/src/services/emailService.ts
# ✓ Created backend/apis/my-api/src/services/emailService.test.ts
# ✓ All with proper DI, JSDoc, and patterns

Or with Claude Code:

"Create a new Email service using our injectable service template"

The Results

After switching to scaffolding:

Before

Setup time: Hours of back-and-forth per project
Code consistency: Inconsistent across the codebase
Review time: Mostly spent on style debates
Onboarding: Weeks to learn all the conventions

After

Setup time: Minutes per project
Code consistency: Enforced by templates
Review time: Focused on logic, not style
Onboarding: Days instead of weeks

Net result: Dramatically faster initialization, zero convention debates, consistent quality across the entire monorepo.

Best Practices

1. Start Simple, Evolve Gradually

# Week 1: Use community templates
scaffold-mcp add --name nextjs-15 --url https://github.com/AgiFlow/aicode-toolkit

# Weeks 2-4: Observe what you change repeatedly

# Week 5+: Create custom templates for your patterns

2. Use Liquid Filters for Consistency

{% comment %}
✅ Good: Ensure consistent casing with filters
Available filters: pascalCase, camelCase, kebabCase, snakeCase, upperCase
{% endcomment %}
@injectable()
export class {{ serviceName | pascalCase }}Service {
  private readonly logger = createLogger('{{ serviceName | kebabCase }}');
  private readonly TABLE_NAME = '{{ tableName | snakeCase }}';
}

{% comment %}
❌ Bad: Rely on user input casing
{% endcomment %}
export class {{ serviceName }}Service {
  private logger = createLogger('{{ serviceName }}');
  private TABLE = '{{ tableName }}';
}

3. Validate with JSON Schema

# ✅ Good: Enforce format and patterns
properties:
  serviceName:
    type: string
    pattern: "^[A-Z][a-zA-Z0-9]*$"  # Must be PascalCase
    example: "Email"
  port:
    type: number
    minimum: 3000
    maximum: 9999

# ❌ Bad: Accept anything
properties:
  serviceName:
    type: string
  port:
    type: number

4. Document in Templates

instruction: |
  Service created successfully!

  Files created:
  - {{ serviceName | camelCase }}Service.ts: Main service with DI
  - {{ serviceName | camelCase }}Service.test.ts: Test suite

  Next steps:
  1. Register in TYPES: add {{ serviceName }}Service to dependency container
  2. Run `pnpm test` to verify tests pass
  3. Inject: @inject(TYPES.{{ serviceName }}Service)

Getting Started Today

Quick Start (5 minutes)

# 1. Install
npm install -g @agiflowai/scaffold-mcp

# 2. Initialize
scaffold-mcp init

# 3. List templates
scaffold-mcp boilerplate list

# 4. Create project
scaffold-mcp boilerplate create <name> --vars '{"projectName":"my-app"}'

Claude Code Setup (2 minutes)

{
  "mcpServers": {
    "scaffold-mcp": {
      "command": "npx",
      "args": ["-y", "@agiflowai/scaffold-mcp", "mcp-serve"]
    }
  }
}

Restart Claude Code and say: "What scaffolding templates are available?"

The Path Forward

The future of AI-assisted development isn't about AI writing more code—it's about AI writing the right code, consistently, following your conventions.

Three Levels of Adoption

Level 1: User (Start here)

Use existing templates
10x faster setup
Guaranteed consistency

Level 2: Customizer (Next step)

Adapt templates to your team
Encode patterns once, reuse forever
Zero convention debates

Level 3: Creator (Advanced)

Build custom templates for your stack
Advanced generators for complex workflows
Share across your organization

The Bottom Line

Stop fighting with AI over conventions. Stop reviewing the same style issues. Stop recreating the same patterns.

Start with templates. Scale with scaffolding.

Resources

GitHub: github.com/AgiFlow/aicode-toolkit
NPM: @agiflowai/scaffold-mcp

"The best code is the code you don't have to write. But when you do write it, scaffolding ensures you write it right the first time—every time."

This is Part 1 of my series on making AI coding assistants work on complex projects. Stay tuned for Part 2!

Questions? I'm happy to discuss architecture patterns, scaffolding strategies, or share more implementation details in the comments.