Claude MD for Enforcing Architecture Patterns

Consistent architecture patterns across a codebase prevent technical debt, simplify onboarding, and make refactoring manageable. Yet enforcing these patterns manually through code reviews alone is time-consuming and error-prone. Claude Code, combined with custom skill definitions, offers a powerful solution for automating architectural consistency checks.

The Problem with Manual Pattern Enforcement

Development teams often document their architecture decisions in style guides, ADR records, or wiki pages. These documents serve as reference, but they don’t actively prevent violations. A developer unfamiliar with the conventions might introduce a service that doesn’t follow your layering rules, or create a component that bypasses your dependency injection patterns.

Traditional linters handle syntax and basic style concerns effectively. They catch missing semicolons, enforce naming conventions, and validate formatting. However, architectural patterns often exist at a higher abstraction level—relationships between modules, dependency direction, or the presence of specific abstractions—that standard linters cannot express.

How Claude MD Skills Work

Claude Code uses a skill system that extends its capabilities through custom definitions. These skills live as markdown files with specific structure, allowing you to teach Claude about your project’s conventions and expectations.

A skill definition typically includes:

Metadata: Name, description, and trigger conditions
Instructions: Detailed rules about how to handle specific patterns
Examples: Demonstrations of correct and incorrect implementations

When you invoke a skill, Claude loads these instructions into its context, influencing how it generates code, reviews changes, and suggests improvements. This makes skills ideal for enforcing architecture patterns because you can encode your team’s decisions as actionable guidance.

Creating an Architecture Enforcement Skill

Let’s build a skill that enforces a layered architecture pattern. This example assumes a standard three-layer setup: presentation, business logic, and data access.

---
name: enforce-layered-architecture
description: "Enforces consistent layered architecture patterns across the codebase"
---

# Layered Architecture Rules

## Allowed Dependencies

- presentation → business-logic
- business-logic → data-access
- business-logic → domain
- presentation → domain (interfaces only)

## Forbidden Patterns

- Never import data-access from presentation layer
- Never import presentation from business-logic
- Controllers must only depend on services, never access repositories directly
- All database operations must go through repository interfaces

## File Organization

Each layer should have its own directory:
- /presentation/controllers, /presentation/components
- /business-logic/services, /business-logic/interfaces
- /data-access/repositories, /data-access/models

To use this skill, you invoke it explicitly in your prompts:

Use the enforce-layered-architecture skill to review this code and identify any violations.

Practical Examples

Example 1: Validating Dependency Direction

Consider this TypeScript code in a presentation layer controller:

// ❌ Violation: Presentation importing from Data Access
import { UserRepository } from '../data-access/repositories/UserRepository';

class UserController {
  private repo = new UserRepository();
  
  async getUser(id: string) {
    return this.repo.findById(id);
  }
}

When you run Claude with the architecture skill, it identifies the violation and suggests the correct approach:

// ✅ Correct: Using service abstraction
import { UserService } from '../business-logic/services/UserService';

class UserController {
  private userService: UserService;
  
  async getUser(id: string) {
    return this.userService.findById(id);
  }
}

Example 2: Enforcing Interface Segregation

A skill focused on interface patterns might enforce that all data access goes through interfaces:

## Interface Requirements

- Every repository must implement an interface in the business-logic layer
- Services should only depend on interfaces, never concrete implementations
- Interface names should follow I{RepositoryName} convention

This prevents tight coupling and makes testing easier since you can swap implementations.

Example 3: Cross-Layer Communication

Your skill can also govern how layers communicate:

## Communication Patterns

- Use Data Transfer Objects (DTOs) for cross-layer data transfer
-DTOs should be defined in the consuming layer
- Never expose database entities directly to presentation layer
- Use mappers to convert between layers

When generating new features, Claude will create the appropriate DTOs and mapper functions.

Combining Skills for Comprehensive Enforcement

You can create multiple skills that work together. A mature architecture enforcement strategy might include:

enforce-layered-architecture: Validates dependency direction and layer organization
tdd-skill: Ensures tests are written before implementation, following your testing conventions
supermemory-skill: Maintains context about architectural decisions across sessions
frontend-design-skill: Enforces component patterns specific to your UI framework

The tdd skill, for instance, can verify that new features come with corresponding test files and that tests follow your established patterns—unit tests for business logic, integration tests for API endpoints, and component tests for UI.

Implementing Skills in Your Workflow

Start by documenting your existing patterns clearly. The skill format works best when you can express rules precisely. Begin with one architectural concern, create the skill, and test it on your codebase.

To apply skills during development, reference them in your prompts:

With enforce-layered-architecture active, create a new user service and its corresponding repository.

Claude will generate code that respects your patterns and explain any constraints it follows.

Measuring Effectiveness

Track pattern violations over time by running Claude’s review capabilities on pull requests. You should see violations decrease as developers internalize the patterns. The skills also serve as excellent onboarding material—new team members can see exactly what architectural expectations exist.

Conclusion

Claude MD skills transform architectural guidance from passive documentation into active enforcement. By encoding your patterns as skills, you get consistent application across your codebase, faster code reviews, and improved developer experience. Start with your most critical patterns, iterate on the skill definitions, and watch your architecture remain clean without manual policing.

Built by theluckystrike — More at zovo.one