Cursor Rules & Cline / Roo Code를 활용한 팀 AI 프롬프트 엔지니어링 및 코딩 컨벤션 자동화

Cursor, Cline, Roo Code, Windsurf와 같은 AI IDE 및 코딩 어시스턴트는 엔지니어의 코딩 속도를 획기적으로 향상시켰습니다. 하지만 팀 차원에서 도입할 때 곧바로 직면하는 심각한 문맥 상실 이슈가 있습니다. “개발자마다 AI가 생성해내는 코드의 스타일이 제각각이고, 프로젝트의 기존 패키지 구조나 아키텍처 규칙을 무시한 레거시 코드가 양산된다” 는 점입니다.

이 문제를 해결하기 위해 필수적으로 구축해야 하는 것이 바로 프로젝트 레벨의 AI 규칙 설정 파일 (.cursorrules, .clinerules, .roomodes, AGENTS.md) 입니다.

이 글에서는 2026년 최신 AI IDE 생태계에서 팀 단위 코딩 컨벤션을 100% 자동 적용하고, 프롬프트 토큰 낭비를 줄이며, 신규 입사자도 첫날부터 팀 아키텍처에 완벽히 부합하는 코드를 작성하도록 만드는 시스템 프롬프트 엔지니어링 실전 프레임워크를 공유합니다.

핵심 요약

• 컨벤션 파일의 통합 관리: .cursorrules (Cursor 전용), .clinerules (Cline / Roo Code 전용), AGENTS.md (Google Antigravity 및 에이전트 공통) 파일 구조를 정립해 AI 도구별 통합 컨벤션 레이어를 구축합니다.
• 구체적 네거티브 프롬프트 (Negative Prompting): 단순히 “좋은 코드를 작성해” 대신 “Any 타입을 절대 사용하지 말고 strict mode를 준수해라”, “Tailwind 대신 Vanilla CSS 토큰만 써라”와 같은 명확한 금지 가드레일을 명시해야 합니다.
• 도메인 스코프 분깃점 설정: Glob 패턴([RULE[src/components/**/*.tsx]])을 활용해 파일 경로 및 레이어별로 적용되는 AI 규칙을 동적으로 차등 부여할 수 있습니다.
• 자동 검증 파이프라인: AI 코드 작성 직후 npm run lint 및 npm test를 자동 호출하는 hook 명령어를 룰 세트에 내장하여 잘못된 생성을 사전 차단합니다.

1. AI IDE별 룰 파일 체계 비교

2026년 주요 AI 도구들은 각자의 루트 규칙 정의 명세를 가지고 있습니다.

2. 프로덕션급 .cursorrules / .clinerules 실전 예제

아래는 TypeScript + React / Next.js 프로젝트에서 사용할 수 있는 팀 공유용 .cursorrules 스니펫입니다.

# .cursorrules (또는 .cursor/rules/frontend.mdc)
description: Frontend TypeScript and Architecture Conventions
globs: "src/frontend/**/*.{ts,tsx}"
alwaysApply: false
---

# 팀 프론트엔드 아키텍처 규칙

You are an expert Frontend Architect operating under strict team conventions.

## 1. Code Style & TypeScript Standards
- DO NOT use `any` or `unknown` without explicit type casting justification.
- ALWAYS enable and strictly comply with TypeScript Strict Mode.
- Prefer functional components with arrow syntax: `export const MyComponent: React.FC<Props> = (...) => {}`.
- Export named components only; DO NOT use `export default`.

## 2. CSS & UI Tokens
- DO NOT inject Tailwind CSS classes unless explicitly requested by prompt.
- Primary styling MUST rely on CSS Modules or Vanilla CSS custom properties defined in `src/styles/tokens.css`.
- Ensure all interactive buttons have `aria-label` and `id` for accessible browser testing.

## 3. Mandatory Self-Verification Step
- After generating or editing code, ALWAYS run:
  `npm run lint -- --fix`
  `npm run typecheck`
- If linting or type errors occur, self-correct immediately before reporting completion.

3. Roo Code Custom Modes (.roomodes) 구축

Cline 및 Roo Code에서는 개발 모드별로 에이전트의 역할과 도구 사용 권한을 분리할 수 있습니다.

{
  "customModes": [
    {
      "slug": "security-architect",
      "name": "Security & Code Reviewer",
      "roleDefinition": "You are a Senior Security Engineer. Your sole purpose is to audit code for OWASP Top 10 vulnerabilities, hardcoded secrets, and missing input sanitization.",
      "groups": ["read", "browser"],
      "customInstructions": "Never write new feature code. Only produce security audit reports with file links and exact line numbers."
    },
    {
      "slug": "test-engineer",
      "name": "TDD Test Automation Expert",
      "roleDefinition": "You build comprehensive Vitest/Jest unit tests for every newly created utility function or API handler.",
      "groups": ["read", "edit", "command"],
      "customInstructions": "Every test suite must achieve at least 90% branch coverage. Use mock handlers for external network calls."
    }
  ]
}

4. AGENTS.md 스코프 룰 시스템 (Google Antigravity 스타일)

프로젝트 루트에 AGENTS.md를 두고 스코프별 규칙을 선언하면, AI 에이전트가 코드를 탐색할 때 해당 가이드라인을 최우선 적용합니다.

# 프로젝트 글로벌 AI 에이전트 가이드

## Development Workflow
- 모든 백엔드 API 변경 시 `npm run test:api` 명령어로 스키마 회귀 검증을 실행할 것.

<RULE[src/api/**/*.ts]>
## 백엔드 API 작성 규칙
1. 모든 에러는 `AppError(code, message, status)` 커스텀 클래스로 래핑해 던질 것.
2. console.log 사용 금지 -> `logger.info()` 또는 `logger.error()` 사용.
3. 데이터베이스 쿼리에는 트랜잭션 타임아웃 5초 설정 필수.
</RULE[src/api/**/*.ts]>

5. 도입 효과 및 팀 생산성 지표

실제 15인 규모 개발팀에서 .cursorrules 및 AGENTS.md를 도입한 후 측정한 3개월간의 변화 지표입니다.

결론

AI IDE의 참된 가치는 단순히 코드를 빨리 타이핑해주는 것에 있지 않습니다. .cursorrules, .clinerules, AGENTS.md를 팀 코드베이스에 정밀하게 구축함으로써, “팀의 수석 아키텍트가 항상 페어 프로그래밍해주는 듯한 수준 높은 코드 일관성” 을 자동 달성해 보세요.