零依赖 Pre-commit 守卫：防止 Cursor/Claude Code 破坏整洁架构

AI 编程助手（如 Cursor、Claude Code、GitHub Copilot 和 Windsurf）从根本上改变了我们编写软件的方式。它们能在数秒内完成功能脚手架、接口起草或 UI 组件生成。

然而，在持续半年日常使用不断增长的大型代码库后，一个隐秘而危险的问题逐渐显现：架构漂移（Architectural Drift）。

由于 LLM 优先考虑局部补全而非系统性架构，它们不可避免地会引入那些能通过快速编译、却会破坏长期可维护性的模式：

❌ 在 UI 中直接操作数据库：在 React UI 组件或路由处理器中直接导入 Prisma、Drizzle 或 SQLAlchemy。

❌ 类型安全逃生舱：当 TypeScript 类型错误变得棘手时，在代码中散布 : any 或 as any。

❌ Go 语言中的静默错误：通过空白标识符（_ = err）丢弃错误以强制编译通过。

❌ 客户端 Secret 泄露：为私有数据库凭据或 API 密钥添加 NEXT_PUBLIC_ 或 VITE_ 前缀，使前端可直接访问。

❌ 重复的辅助工具函数：重写 20 行日期或邮箱格式化代码，而不是复用 /utils 中的共享函数。

当团队每周合并数十个 AI 辅助的 PR 时，代码审查变得令人疲惫，技术债务迅速累积。

为此，我们构建了 RepoGuard——一个零依赖、开源的架构检查器和上下文生成器，能在约 12ms 内审计代码库。

🛠️ 架构检查器的组成

与标准 linter（如 ESLint 或 Biome）侧重于语法和格式不同，RepoGuard 强制执行层与层之间的架构边界：

┌──────────────────────────────────────────────┐
│        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)        │
└──────────────────────────────────────────────┘

🔍 真实案例：前与后

❌ 反模式（Cursor 生成的代码）：

// 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（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>;
}

🚀 2 秒快速上手（零安装）

你可以在仓库中直接运行 RepoGuard，无需全局安装任何包：

# 1. 为 Cursor、Claude Code 和 Copilot 初始化上下文规则
npx repoguard-rules init

# 2. 审计整个代码库的健康评分（A+ 到 F）
npx repoguard-rules audit

npx repoguard-rules init 会执行以下操作：

自动检测技术栈：TypeScript/Next.js、Python（FastAPI/Django）或 Golang（Gin/Fiber/GORM）。

生成定制化上下文文件：

.cursorrules（面向 Cursor AI）

CLAUDE.md（面向 Claude Code CLI）

.windsurfrules（面向 Windsurf Cascade）

.github/copilot-instructions.md（面向 GitHub Copilot）

注入 Pre-commit Hooks：配置 git diff 检查，在提交前拦截架构违规。

⚡ 多语言支持（v1.6.0）

RepoGuard v1.6.0 引入了对 Python 和 Golang 的原生支持。

🤖 GitHub Action 与安全集成

RepoGuard 已正式发布在 GitHub Marketplace。你可以用 4 行 YAML 将持续架构检查添加到 Pull Requests 中：

# .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 导出）：

RepoGuard 还可以输出原生 SARIF v2.1.0 格式，直接对接 GitHub 的 Security / Code Scanning 告警：

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

🌟 开源与贡献

RepoGuard 采用 MIT 许可证 100% 开源。我们相信，AI 时代的开发者工具应该透明、零依赖、由社区驱动。

🔗 GitHub 仓库：https://github.com/taylormatematica-beep/repoguard

🏛️ GitHub Marketplace：https://github.com/marketplace/actions/repoguard-architecture-audit

📦 NPM 仓库：https://www.npmjs.com/package/repoguard-rules

如果你在团队中使用 AI 编程工具，不妨运行一下 npx repoguard-rules audit，并在评论区告诉我们你的架构健康评分！⭐