Cursor와 Claude 코드가 클린 아키텍처를 망치는 것을 막는 방법

의존성 제로(zero-dependency)한 pre-commit 가드레일을 통해 AI 코딩 도구가 저장소를 아키텍처 스파게티로 만드는 것을 방지하세요.
tags: webdev, ai, nextjs, programming

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

AI 코딩 어시스턴트인 Cursor, Claude Code, GitHub Copilot, 그리고 Windsurf는 우리가 소프트웨어를 작성하는 방식을 근본적으로 변화시켰습니다. 이들은 기능을 스캐폴딩(scaffold)하거나, 엔드포인트를 초안 작성하거나, UI 컴포넌트를 몇 초 만에 생성할 수 있습니다.

하지만 성장하는 코드베이스 전반에 걸쳐 매일 사용한 지 6개월이 지나자 미묘하고 위험한 문제가 발생합니다: 아키텍처 드리프트(Architectural Drift).

LLM은 시스템 아키텍처보다 로컬 완성도를 우선시하기 때문에, 빠르고 쉬운 컴파일을 통과하지만 장기적인 유지보수성을 파괴하는 패턴들을 필연적으로 도입합니다:

• ❌ UI에서 직접 데이터베이스 쿼리: Prisma, Drizzle 또는 SQLAlchemy를 React UI 컴포넌트나 라우트 핸들러 내부에 직접 가져오는 것.
• ❌ 타입 안정성 탈출구(Escape Hatches): TypeScript 코드 전반에 타입 오류가 까다로워질 때마다 : any나 as any를 뿌리는 것.
• ❌ Go에서 무시된 에러: 컴파일을 강제하기 위해 빈 식별자(_ = err)로 에러를 버리는 것.
• ❌ 클라이언트 측 비밀 누출: 프런트엔드가 직접 접근할 수 있도록 민감한 데이터베이스 자격 증명이나 API 시크릿 앞에 NEXT_PUBLIC_ 또는 VITE_를 붙이는 것.
• ❌ 중복된 헬퍼 유틸리티: /utils의 공유 함수를 재사용하는 대신 날짜나 이메일 형식 지정 코드를 20줄 분량으로 다시 작성하는 것.

팀이 매주 수십 개의 AI 지원 PR을 병합할 때, 코드 리뷰는 지치게 되고 기술 부채(tech debt)는 빠르게 쌓입니다.

이를 해결하기 위해, 저희는 **RepoGuard**를 구축했습니다. 이는 의존성 제로의 오픈 소스 아키텍처 린터이자 컨텍스트 생성기로, 코드베이스를 ~12ms 만에 감사(audit)합니다.

🛠️ 아키텍처 린터의 해부학

표준 linter(ESLint 또는 Biome 등)가 구문 및 포맷팅에 초점을 맞추는 것과 달리, RepoGuard는 레이어 간의 아키텍처 경계를 강제합니다:

┌──────────────────────────────────────────────┐
│        Presentation / UI Layer               │
│  (React, Next.js Server Components, Pages)   │
... 

🔍 실제 사례: 이전 vs 이후

❌ 안티 패턴 (Cursor가 생성하는 것):

// components/UserProfile.tsx
export default async function UserProfile({ id }: { id: string }) {
  // 🚨 위반: UI 컴포넌트 내에서 직접 Prisma 데이터베이스 쿼리!
... 

✅ 클린 아키텍처 (RepoGuard가 강제하는 것):

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

... 

🚀 2초 만에 시작하기 (설치 불필요)

어떤 패키지도 전역으로 설치할 필요 없이 리포지토리에서 RepoGuard를 직접 실행할 수 있습니다:

# 1. Cursor, Claude Code 및 Copilot을 위한 컨텍스트 규칙 초기화
npx repoguard-rules init

... 

npx repoguard-rules init의 역할:

1. 기술 스택 자동 감지: TypeScript/Next.js, Python (FastAPI/Django), 또는 Golang (Gin/Fiber/GORM)을 감지합니다.
2. 맞춤형 컨텍스트 파일 생성:
   • .cursorrules (Cursor AI용)
   • CLAUDE.md (Claude Code CLI용)
   • .windsurfrules (Windsurf Cascade용)
   • .github/copilot-instructions.md (GitHub Copilot용)
3. Pre-commit Hook 주입: 커밋하기 전에 아키텍처 위반을 차단하도록 git diff 검사를 구성합니다.

⚡ 다중 언어 지원 (v1.6.0)

RepoGuard v1.6.0은 Python 및 Golang에 대한 네이티브 지원을 도입했습니다:

🤖 GitHub Action & Security Integration

RepoGuard가 GitHub Marketplace에 공식적으로 게시되었습니다. YAML에서 단 4줄만 추가하여 Pull Request에 지속적인 아키텍처 강제(continuous architectural enforcement)를 적용할 수 있습니다:

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

GitHub 코드 스캐닝 (SARIF Export):

RepoGuard는 또한 네이티브 SARIF v2.1.0을 출력하여 GitHub의 보안/코드 스캐닝(Security / Code Scanning) 알림과 직접 통합할 수 있습니다:

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

🌟 오픈 소스 및 기여 (Open Source & Contributing)

RepoGuard는 MIT 라이선스 하에 100% 오픈 소스입니다. 우리는 AI 시대의 개발자 도구는 투명하고, 의존성이 없으며(zero-dependency), 커뮤니티 주도적이어야 한다고 믿습니다.

• 🔗 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를 실행해 보고 댓글로 여러분의 아키텍처 건강 점수(architectural health score)를 알려주세요! ⭐