How to Stop Cursor and Claude Code from Breaking Clean Architecture in 12ms

Prevent AI coding tools from turning your repository into architectural spaghetti with zero-dependency pre-commit guardrails.
tags: webdev, ai, nextjs, programming

canonical_url: https://taylormatematica-beep.github.io/repoguard/

AI coding assistants like Cursor, Claude Code, GitHub Copilot, and Windsurf have fundamentally changed how we write software. They can scaffold a feature, draft an endpoint, or generate UI components in seconds.

However, after 6 months of daily use across growing codebases, a subtle and dangerous problem emerges: Architectural Drift.

Because LLMs prioritize local completion over systemic architecture, they inevitably introduce patterns that pass quick compilation but destroy long-term maintainability:

• ❌ Direct Database Queries in UI: Importing Prisma, Drizzle, or SQLAlchemy directly inside React UI components or route handlers.
• ❌ Type Safety Escape Hatches: Sprinkling : any or as any across TypeScript code whenever a type error gets tricky.
• ❌ Silenced Errors in Go: Discarding errors via blank identifiers (_ = err) to force compilation.
• ❌ Client-Side Secret Leaks: Prefixing private database credentials or API secrets with NEXT_PUBLIC_ or VITE_ so the frontend can access them directly.
• ❌ Duplicate Helper Utilities: Re-writing 20 lines of date or email formatting instead of reusing shared functions in /utils.

When your team is merging dozens of AI-assisted PRs every week, code reviews become exhausting and tech debt compounds rapidly.

To solve this, we built RepoGuard — a zero-dependency, open-source architecture linter and context generator that audits codebases in ~12ms.

---

🛠️ The Anatomy of an Architecture Linter

Unlike standard linters (like ESLint or Biome) that focus on syntax and formatting, RepoGuard enforces architectural boundaries between layers:

┌──────────────────────────────────────────────┐
│        Presentation / UI Layer               │
│  (React, Next.js Server Components, Pages)   │
└──────────────────────┬───────────────────────┘
                       │ ❌ DIRECT DB ACCESS FORBIDDEN (RULE-01)
                       ▼
┌──────────────────────────────────────────────┐
│        Service / Domain Layer                │
│    (Business logic, validation, orchestrator)│
└──────────────────────┬───────────────────────┘
                       │ ✅ Encapsulated data flow
                       ▼
┌──────────────────────────────────────────────┐
│      Persistence / Repository Layer          │
│       (Prisma, GORM, SQLAlchemy, SQL)        │
└──────────────────────────────────────────────┘

---

🔍 Real-World Example: Before vs After

❌ The Anti-Pattern (What Cursor Generates):

// components/UserProfile.tsx
export default async function UserProfile({ id }: { id: string }) {
  // 🚨 Violation: Direct Prisma database query inside UI component!
  const user = await prisma.user.findUnique({
    where: { id },
    include: { billing: true }
  });
  return <div>{user.name}</div>;
}

✅ Clean Architecture (Enforced by RepoGuard):

// components/UserProfile.tsx
import { getUserProfile } from '@/services/user.service';

export default async function UserProfile({ id }: { id: string }) {
  // Encapsulated in the domain service layer
  const user = await getUserProfile(id);
  return <div>{user.name}</div>;
}

---

🚀 Getting Started in 2 Seconds (Zero-Install)

You can run RepoGuard directly in your repository without installing any packages globally:

# 1. Initialize context rules for Cursor, Claude Code & Copilot
npx repoguard-rules init

# 2. Audit your entire codebase health score (A+ to F)
npx repoguard-rules audit

What npx repoguard-rules init does:

1. Auto-detects your tech stack: TypeScript/Next.js, Python (FastAPI/Django), or Golang (Gin/Fiber/GORM).
2. Generates tailored context files:
   • .cursorrules (for Cursor AI)
   • CLAUDE.md (for Claude Code CLI)
   • .windsurfrules (for Windsurf Cascade)
   • .github/copilot-instructions.md (for GitHub Copilot)
3. Injects Pre-commit Hooks: Configures git diff checks to block architectural breaches before you commit.

---

⚡ Multi-Language Support (v1.6.0)

RepoGuard v1.6.0 introduces native support for Python and Golang:

Rule ID	Language	Guardrail Enforced
RULE-01	TypeScript / JS	Prohibits raw ORM/DB queries in UI components and Controllers.
RULE-PY-01	Python / FastAPI	Prohibits direct DB queries and raw commits (db.commit()) in route handlers.
RULE-GO-01	Golang	Prohibits raw GORM/database mutations inside Gin, Fiber, or Echo handlers.
RULE-GO-02	Golang	Flags unchecked errors silenced via blank identifiers (_ = err).
RULE-02	Multi-Language	Flags hardcoded secrets, private keys, and API tokens.
RULE-09	Multi-Language	Blocks private secrets exposed via public prefixes (NEXT_PUBLIC_ / VITE_).

---

🤖 GitHub Action & Security Integration

RepoGuard is officially published on the GitHub Marketplace. You can add continuous architectural enforcement to your Pull Requests in 4 lines of YAML:

# .github/workflows/repoguard.yml
name: RepoGuard Architecture Audit
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: taylormatematica-beep/repoguard@v1.6.0
        with:
          strict_mode: true

GitHub Code Scanning (SARIF Export):

RepoGuard can also output native SARIF v2.1.0 to integrate directly with GitHub's Security / Code Scanning alerts:

npx repoguard-rules audit --format=sarif > results.sarif

---

🌟 Open Source & Contributing

RepoGuard is 100% open-source under the MIT license. We believe developer tools for the AI era should be transparent, zero-dependency, and community-driven.

• 🔗 GitHub Repository: https://github.com/taylormatematica-beep/repoguard
• 🏛️ GitHub Marketplace: https://github.com/marketplace/actions/repoguard-architecture-audit
• 📦 NPM Registry: https://www.npmjs.com/package/repoguard-rules

If you're using AI coding tools on your team, give npx repoguard-rules audit a run and let us know your architectural health score in the comments! ⭐