Cursor Composer는 AI 기반 코딩 환경을 단일 파일 수준의 자동 완성 도구에서 전체 코드베이스를 이해하고 조율하는 '자율 에이전트(Agent)' 단위로 격상시켰습니다. 엔지니어는 더 이상 여러 파일을 번갈아 가며 코드를 복사하고 수동으로 연결할 필요 없이, Composer를 통해 계층을 넘나드는 기능 구현, 아키텍처 리팩터링 및 시스템 간 인터페이스 동기화를 한 번에 수행할 수 있습니다.
그러나 전체 리포지토리에 걸친 코드 수정은 그만큼 높은 아키텍처 결함 리스크를 수반합니다. 경험 많은 소프트웨어 엔지니어는 Composer(단축키 Cmd + I 또는 Ctrl + I)를 사용할 때 '무계획적 코드 생성'을 지양하며, 컨텍스트 및 제약 조건의 사전 계획(Plan), 자체 복구 기능을 동반한 조율된 생성(Generate), **정밀한 차이점(Diff) 검사 및 체크포인트 기반의 검토(Review)**라는 3단계 엔지니어링 절차를 엄격히 준수합니다.
사전 준비: 아키텍처 경계 설정과 정밀한 컨텍스트 주입
프로젝트의 전체 아키텍처와 규칙을 파악하지 못한 상태에서 다중 파일 수정을 지시하면 시스템 전반의 규약이 쉽게 깨집니다. 엔지니어는 Composer를 실행하기 전 명확한 규칙과 참조 체계를 설정합니다.
1. Cursor Rules(.cursor/rules)를 통한 엔지니어링 표준 정립
매 대화마다 동일한 코딩 스타일이나 의존성 규칙을 반복 지시하지 않도록, 팀은 .cursor/rules/*.mdc(또는 루트 경로의 .cursorrules)에 프로젝트 규칙을 정의합니다.
- 상시 활성 규칙(Always-on): TypeScript 엄격 모드, Python 3.12+ 문법, 표준 예외 처리 패턴, 단위 테스트 작성 규약 등 전역 기술 스택 기준을 지정합니다.
- 경로 매칭 규칙(Glob-scoped): 대상 파일의 경로 패턴에 따라 규칙을 동적으로 적용합니다. 예를 들어
src/api/**/*.ts경로에는 Zod를 통한 파라미터 검증과 구조화된 로깅을 필수화하고,src/components/**/*.tsx에는 디자인 시스템 및 접근성(a11y) 기준을 강제할 수 있습니다.
이러한 규칙이 확립되어 있으면 Composer가 새로운 파일을 생성하거나 기존 코드를 수정할 때 프로젝트 고유의 아키텍처 규약을 벗어나지 않습니다.
2. @ 기호를 통한 정밀한 컨텍스트 주입
불필요한 파일을 과도하게 주입하면 '컨텍스트 비대화(Context Bloat)'가 발생하여 토큰이 낭비되고 환각(Hallucination) 위험이 커집니다. 숙련된 개발자는 상황에 맞춰 @ 기호를 선별적으로 사용합니다.
@codebase: 리포지토리 전체 인덱스를 대상으로 의미론적(Semantic) 검색을 수행합니다. 영향 범위를 알기 어려운 호출부나 복잡한 의존성 구조를 파악할 때 유용합니다.@file및@folders: 필수적인 인터페이스 파일(예:@schema.prisma,@userService.ts, 공통 타입 정의 폴더)을 명시적으로 참조시켜 모델이 정확한 정의를 기준으로 작업하도록 유도합니다.@docs: 사용하는 서드파티 라이브러리나 프레임워크의 최신 공식 문서를 직접 주입하여, 폐기된 API나 구버전 문법을 사용하는 실수를 방지합니다.@git: 최근 커밋 내역이나 현재 브랜치의 Diff 정보를 모델에 제공하여 진행 중인 작업 맥락을 유지합니다.
1단계: Plan Mode(Shift + Tab)를 활용한 아키텍처 계획
데이터베이스 스키마 마이그레이션이나 대규모 서비스 리팩터링과 같이 여러 모듈에 영향을 미치는 작업의 경우, 바로 코드를 작성하도록 지시해서는 안 됩니다. 먼저 Plan Mode를 활성화하여 구현 계획을 정립해야 합니다.
Plan Mode 활성화 및 탐색
Composer 입력창에서 **Shift + Tab**을 누르면 계획 수립 전용 모드로 전환됩니다.
- 코드베이스 자율 분석: 에이전트가 영향받는 파일, 인터페이스 의존성 및 설정 파일들을 탐색하여 변경이 미칠 파급력을 계산합니다.
- 요구사항 능동 확인: 비즈니스 로직의 경계, 하위 호환성 유지 여부, 예외 상황 처리 기준이 모호한 경우, Composer는 임의로 추측하지 않고 엔지니어에게 질문을 던져 의도를 확인합니다.
- 구조화된 Markdown 계획서 생성: 모델은 다음과 같은 구체적 실행 계획을 출력합니다.
- 신규 생성, 수정, 삭제가 필요한 구체적인 파일 목록
- 구현 순서(예: 데이터베이스 마이그레이션 및 타입 선언 → 서비스 계층 구현 → API 라우터 갱신 → 프론트엔드 연동)
- 잠재적 브레이킹 체인지와 이에 대응하는 테스트 검증 계획
엔지니어의 계획 검토 및 수정
엔지니어는 수석 아키텍트의 관점에서 Markdown 계획을 검토합니다. 불필요하게 건드리는 파일을 제외하고, 네이밍 규칙을 수정하며, '데이터 계층 완성 후 타입 체크 실행'과 같은 중간 검증 지점을 삽입합니다. 계획이 확정된 후에만 코드 생성 단계로 넘어갑니다.
2단계: 조율된 다중 파일 생성 및 자체 복구 루프
계획이 승인되면 Composer가 본격적인 구현에 착수합니다. 최신 Cursor 버전에서 Composer는 터미널 도구와 워크스페이스 권한을 갖춘 자율 에이전트로 작동합니다.
1. 계층 간 동기화된 코드 생성
단일 파일만 수정하는 보조 도구와 달리, Composer는 한 번의 작업 흐름 내에서 시스템의 여러 계층을 일관되게 변경합니다.
- 데이터 계층: 마이그레이션 스크립트를 작성하고 ORM 스키마 모델을 갱신합니다.
- 서비스 및 도메인 계층: 비즈니스 로직을 구현하고 메서드 시그니처 및 타입 정의를 수정합니다.
- 라우팅 및 컨트롤러 계층: 새로운 API 엔드포인트를 열고 인증 가드 및 미들웨어를 연결합니다.
- 프론트엔드 및 클라이언트 계층: UI 컴포넌트, 커스텀 훅 및 상태 관리 로직을 동기화합니다.
- 테스트 스위트: 변경된 기능에 맞는 단위 및 통합 테스트 코드를 동시 생성합니다.
수정 대기 중인 파일들은 작업 큐에 정리되어 플로팅 창, 사이드 패널 또는 전체 화면 에디터 모드에서 실시간으로 확인할 수 있습니다.
2. 터미널 연동 및 자체 복구 루프(Self-Healing)
Composer Agent 모드의 핵심 차별점은 로컬 터미널 명령을 직접 실행하고 그 결과를 스스로 분석하여 수정할 수 있다는 점입니다.
- 정적 타입 검사:
tsc --noEmit,mypy,cargo check등을 실행해 다중 파일 수정 과정에서 발생한 타입 불일치를 찾아냅니다. - 테스트 및 Linter 실행:
npm test나pytest를 구동하여 즉시 검증합니다. - 에러 기반 자동 교정: 컴파일 실패나 테스트 실패가 발생하면, Composer는 터미널에 출력된 에러 스택 트레이스를 분석해 원인이 된 파일을 찾아내고 스스로 코드를 수정합니다. 모든 테스트가 통과할 때까지 이 과정을 반복합니다.
3. 작업을 원자적(Atomic) 마일스톤으로 세분화
숙련된 엔지니어는 단일 프롬프트로 30~40개 파일을 한꺼번에 수정하도록 요구하지 않습니다. 계획 단계에서 설정한 마일스톤에 따라 단계적으로 작업을 진행합니다.
- 1단계: "새로운 데이터 모델을 정의하고 TypeScript 타입을 내보내세요." (타입 체크 검증)
- 2단계: "데이터베이스 서비스 계층 메서드를 구현하고 단위 테스트를 통과시키세요." (테스트 통과 검증)
- 3단계: "API 라우트를 리팩터링하고 프론트엔드 호출부를 업데이트하세요." (전체 빌드 검증)
작업 단위를 작게 유지해야 모델의 집중력을 최상으로 유지할 수 있으며, 이후의 Diff 검토도 사람이 통제할 수 있는 범위 안에 머무릅니다.
3단계: 변경 사항 Diff 검토, 체크포인트 복원 및 검증
AI가 생성한 다중 파일 코드의 가장 큰 위험은 누락된 예외 처리나 임의로 수정된 기본값처럼 눈에 잘 띄지 않는 회귀 결함(Regression)입니다. 철저한 검토 프로세스가 반드시 뒤따라야 합니다.
1. 정밀한 차이점(Diff) 검토
Composer 생성이 완료되면 다중 파일 변경 내역을 확인할 수 있는 Diff 뷰가 제공됩니다.
- 파일별 순차 확인: 엔지니어는 좌우 병렬 뷰(Side-by-side)나 인라인 뷰를 통해 변경된 각 파일을 순서대로 검토합니다.
- 부분 수락 및 거절: 'Keep All(전체 수락)'을 무비판적으로 누르는 대신, 파일별 또는 코드 블록별로
Accept와Reject를 선택합니다. - 대화형 추가 수정: 특정 부분에 수정이 필요한 경우, 활성화된 대화창에 직접 지시(예: "
OrderService.ts에서는 기본 에러 대신 프로젝트 공통AppError를 사용하세요")를 입력하여 해당 파일만 즉시 재조정하도록 합니다.
2. 체크포인트(Checkpoints) 안전망 활용
Composer는 코드를 생성하기 직전 워크스페이스 상태를 스냅샷 형태로 기록하는 **체크포인트(Checkpoint)**를 자동 생성합니다.
- 모델이 엉뚱한 방향으로 구현을 진행하거나 자체 복구 과정에서 코드가 꼬였을 때, 언제든지 Restore Checkpoint를 클릭하여 이전 상태로 되돌릴 수 있습니다.
- 대화 내역은 그대로 유지되면서 파일 상태만 직전으로 롤백되므로, 프롬프트를 보완하여 즉시 다시 시도할 수 있습니다.
3. Agent Review 도구 실행
Git 스테이징 전에 Cursor에 내장된 Agent Review 기능을 활용합니다.
- Quick Review: 작업 트리의 문법 오류, 미사용 임포트, 기초적인 로직 누락을 빠르게 스캔합니다.
- Deep Review: 변경 집합 전체를 대상으로 심층적인 의미론적 분석을 수행하여 모듈 간 인터페이스 일관성, 잠재적 회귀 위험 및 보안 취약점을 점검합니다.
4. Git 최종 확인 및 원자적 커밋
AI 도구는 개발 속도를 높여줄 뿐 최종 책임은 엔지니어에게 있습니다.
- 터미널에서
git status와git diff를 실행해 불필요한 임시 파일 생성이나 민감한 환경 변수 유출이 없는지 확인합니다. - 계획된 단위별로 깔끔하고 명확한 메시지를 담아 원자적(Atomic) Git 커밋을 생성합니다.
핵심 모범 사례 요약
| 단계 | 권장 접근법 | 피해야 할 안티패턴 |
|---|---|---|
| 준비 | .cursor/rules를 구성하고 @file / @folders로 범위 좁히기 | 모든 작업에 무차별적으로 @codebase를 지정하여 컨텍스트 낭비 |
| 계획 | Plan Mode(Shift + Tab)를 활용해 파일 목록과 단계 우선 확립 | 사전 설계 없이 한 번에 수십 개 파일 생성을 지시 |
| 생성 | 터미널 타입 검사 및 테스트 실행을 허용하여 자체 복구 유도 | 컴파일 에러를 방치한 채 깨진 코드 위에 새로운 지시 누적 |
| 검토 | 파일별로 Diff를 정밀 검토하고 편차 발생 시 Checkpoints로 롤백 | 세부 변경 사항을 보지 않고 무조건 '전체 수락' 클릭 |
| 검증 | 커밋 전 Agent Review(Deep)와 로컬 전체 테스트 실행 | 로컬 검증 없이 원격 브랜치로 바로 푸시 |