ai-rules › 02-code · 코드 아키텍처 규칙

02-code 코드 아키텍처 규칙

Hard Bans (위반 시 auto-fail)

Hard Bans (위반 시 auto-fail)

스택별 규칙은 extensions로 분리되었다:

  • React/Frontend: extensions/frontend-react.md → 프로파일에 extensions: [frontend-react]
  • FastAPI/Backend: extensions/backend-fastapi.md → 프로파일에 extensions: [backend-fastapi] 아래는 모든 프로젝트에 적용되는 스택 중립 규칙만 포함한다.

공통 (스택 중립 — 모든 프로젝트 적용)

  • 하드코딩 시크릿 금지 (API 키, 비밀번호 등) — guard-secrets.sh hook이 커밋 시 이중 탐지 (tooling.secret_scan)
  • 프로덕션 로그에 PII(이메일, 토큰, user_id) 미출력
  • 리포 전체 스캔 금지 — CLAUDE.md / INTENT.md / docs index에서 참조된 파일만 읽기

아키텍처 원칙

  • 과도한 엔지니어링 금지 — 현재 요구사항에 필요한 최소 복잡도
  • 비슷한 코드 3줄 이하는 추상화 금지
  • 단일 사용 헬퍼/유틸리티 금지
  • 미래 요구사항을 위한 설계 금지

새 환경변수 추가 시

  • .env.example 업데이트 필수
  • 작업 완료 보고에 명시

검증 (커밋 전 필수)

lint-staged + pre-commit hook이 자동 실행 (tooling.lint_staged):

  • TS 프로젝트: eslint --fix (staged .ts/.tsx 파일)
  • Python 프로젝트: ruff check --fix + ruff format --check (staged .py 파일)
  • Mixed 프로젝트: 위 두 가지 모두 적용

수동 검증이 필요할 때:

npx tsc --noEmit                    # Frontend 타입 체크
cd backend && ruff check .          # Backend lint