Cursor Projects 사용법: 장기 개발 작업을 코디네이터에 맡기는 법
Cursor Projects는 한 번의 채팅으로 끝나지 않는 개발 작업을 맡기는 기능이다. 기능 하나, 여러 저장소에 걸친 마이그레이션, 계속 들어오는 버그 정리처럼 오래 이어지는 목표를 하나의 프로젝트로 만들면 코디네이터가 계획을 세우고 여러 에이전트에 일을 나눈다. 핵심은 “에이전트를 많이 실행한다”가 아니라 공유 맥락, 병렬 작업, 반복 실행, 사람의 검토를 한 단위로 관리하는 데 있다.
Cursor는 2026년 9월 10일 Projects를 베타로 발표했고 모든 사용자에게 순차 배포한다고 안내했다. 화면에 보이는지, 쓸 수 있는 에이전트 양과 비용은 계정·플랜·조직 정책에 따라 달라질 수 있다. 이 글은 공개된 기능과 안전한 시작 순서를 설명하며, 실제 저장소에서 실행한 결과를 재현 보고하는 글은 아니다.
Projects는 일반 채팅과 무엇이 다른가
일반 에이전트 채팅은 “이 버그를 고쳐 줘”처럼 범위가 비교적 짧은 일에 잘 맞는다. 반면 Projects의 코디네이터는 직접 코드를 작성하는 역할이 아니다. 해야 할 일을 쪼개고, 구현 에이전트를 배치하고, 결과를 다시 모아 검토할 수 있게 전달한다. 프로젝트 전용 컴퓨터가 클라우드에서 계속 실행되므로 노트북을 닫아도 작업을 이어 갈 수 있고, 로컬 환경 검증이 필요할 때는 로컬 에이전트를 연결하는 구조다.
| 선택지 | 적합한 작업 | 주의할 점 |
|---|---|---|
| 일반 채팅·로컬 에이전트 | 한 파일 수정, 짧은 조사, 즉시 확인 가능한 버그 | 대화가 길어지면 맥락과 결정 기록을 직접 관리해야 한다. |
| 단일 Cloud Agent | 백그라운드에서 끝낼 수 있는 독립 작업 한 건 | 작업 간 의존성과 장기 계획은 사용자가 조정해야 한다. |
| Cursor Projects | 여러 PR, 여러 저장소, 반복 감시가 필요한 장기 목표 | 권한·비용·검토 규칙을 먼저 정하지 않으면 자동화 범위가 지나치게 넓어질 수 있다. |
시작 전에 준비할 여섯 가지
- 원격 저장소의 기준 상태: GitHub, GitLab, Azure DevOps Services, Bitbucket Cloud 가운데 연결할 저장소를 정리하고 기본 브랜치가 빌드되는지 확인한다. Cloud Agent는 원격 저장소를 복제해 별도 브랜치에서 일하므로 커밋하지 않은 로컬 변경은 자동으로 따라가지 않는다.
- 완료 조건: “기능 구현” 대신 수정 범위, 테스트 명령, 통과 기준, 제외할 파일, 필요한 문서까지 적는다.
- 검토 책임자: PR을 누가 읽고 병합할지 정한다. 결제, 권한, 개인정보, 배포 설정은 자동 병합 대상에서 제외하는 편이 안전하다.
- 실행 환경: 설치 명령과 테스트 절차를 저장소 문서에 남긴다. 에이전트가 매번 추측하게 두지 않는다.
- 비밀정보와 네트워크: 필요한 시크릿만 환경 단위로 넣고, 가능하면 외부 통신을 허용 목록으로 제한한다. 저장소에 키를 커밋하지 않는다.
- 비용 한도: Cloud Agents는 선택한 모델의 API 요금 기준으로 과금되며 큰 컨텍스트는 사용량을 늘릴 수 있다. 첫 실행 전 지출 한도와 확인 주기를 정한다.
왼쪽 메뉴에서 시작해 검토 가능한 PR까지
1. Projects를 열고 목표를 한 문장으로 고정한다
Cursor의 왼쪽 탐색 영역에서 Projects를 열고 새 프로젝트를 시작한다. 베타가 아직 계정에 도착하지 않았다면 메뉴가 보이지 않을 수 있다. 목표는 “앱을 개선해 줘”가 아니라 “관리자용 CSV 내보내기를 추가하되 기존 권한 체계와 API 응답 형식을 유지한다”처럼 결과와 경계를 함께 쓴다.
2. 저장소와 권한을 최소 범위로 연결한다
코디네이터가 사용할 저장소만 연결한다. Cloud Agent는 대상 저장소와 의존 저장소에 읽기·쓰기 권한이 필요하다. 팀 멤버라는 이유만으로 다른 사람의 에이전트 작업을 볼 수 있는 것은 아니며, 각 사용자는 자신의 소스 제어 계정을 연결하고 해당 저장소 접근 권한을 가져야 한다.
3. 첫 메시지에 작업 계약을 넣는다
첫 지시에는 목적, 변경 가능 영역, 금지 영역, 테스트 명령, PR 분할 기준, 사람에게 멈춰 물어볼 조건을 포함한다. 예를 들면 “먼저 조사와 계획만 작성하고 승인을 기다릴 것, DB 스키마·인증·배포 파일은 수정하지 말 것, 각 PR은 독립적으로 롤백 가능할 것”처럼 쓸 수 있다. 프롬프트는 설명일 뿐 강제 보안 장치가 아니므로 저장소 권한과 네트워크 제한도 따로 설정해야 한다.
4. 계획을 검토한 뒤 작은 첫 작업을 보낸다
처음부터 수십 개 PR을 만들게 하지 않는다. 코디네이터가 제시한 의존 관계와 순서를 확인하고, 영향이 작고 테스트가 분명한 한 조각을 파일럿으로 승인한다. 이때 변경 파일, 실행한 검사, 남은 위험, 롤백 방법을 PR 설명에 남기도록 요청하면 이후 검토 속도가 빨라진다.
5. 결과를 코드가 아니라 증거 묶음으로 확인한다
완료 확인은 “에이전트가 끝났다고 말했다”가 아니다. PR diff, 테스트 로그, CI 상태, 변경된 문서, 영향받는 저장소, 실패 시 되돌리는 방법을 함께 본다. 브라우저나 로컬 데이터가 필요한 검증은 로컬 에이전트에 맡길 수 있지만, 실제 결과와 예상 결과를 구분해 기록해야 한다.
6. 반복 실행은 파일럿 통과 후 켠다
Projects는 Slack 채널, 일정, PR 이벤트를 감시하는 구독을 만들 수 있다. 그러나 처음부터 모든 버그나 PR에 반응하게 하지 말고, 한 채널·한 저장소·한 유형의 이벤트로 좁혀 시작한다. 자동으로 PR을 열 수 있게 하더라도 병합과 배포는 사람의 승인 뒤에 두는 것이 기본값으로 적절하다.
세 가지 실용 예시
예시 1. 프런트엔드와 API에 걸친 내보내기 기능
목적: 관리자 화면에서 필터 결과를 CSV로 받게 한다. 입력: 관련 저장소, 권한 규칙, API 계약, 샘플 데이터, 테스트 명령을 제공한다. 코디네이터는 먼저 데이터 흐름을 조사하고 API·화면·문서 작업을 나눈다. 각 에이전트가 별도 PR을 만들더라도 API 계약 PR이 먼저 병합되어야 한다는 의존성을 계획에 표시하게 한다. 검토자는 권한 우회가 없는지, 큰 데이터에서 메모리 문제가 없는지, CSV 수식 주입 위험을 처리했는지 확인한다. 기대 산출물은 “작동한다”는 문장이 아니라 독립 검토 가능한 PR, 테스트, 문서다.
예시 2. 여러 저장소의 런타임 버전 올리기
목적: 오래된 런타임을 지원 버전으로 옮긴다. 먼저 대표 저장소 하나를 파일럿으로 고르고 빌드·테스트·배포 전 검사까지 통과시킨다. 그 결과를 공유 맥락에 기록한 뒤 저장소를 위험도별 묶음으로 나눠 순차 PR을 만든다. 일괄 변경보다 실패 원인을 찾고 되돌리기 쉽다. 잠금 파일, 네이티브 모듈, CI 이미지처럼 자동 치환으로 해결되지 않는 항목은 별도 검토 목록으로 남긴다.
예시 3. 반복되는 PR 품질 관리
목적: 디자인 시스템 규칙 위반이나 특정 회귀 패턴을 계속 찾는다. 먼저 과거 PR 몇 건을 읽게 하고 어떤 상황에서만 의견을 남길지 정의한다. 이후 새 PR을 감시하되, 초기에는 댓글과 수정 제안까지만 허용한다. 오탐률과 사람이 실제로 채택한 제안을 기록하고 기준이 안정된 뒤 작은 자동 수정 PR로 범위를 넓힌다. 보안 설정, 결제 로직, 고객 데이터 처리 코드는 항상 사람 검토 대상으로 남긴다.
비용·보안·베타 제약
| 확인 항목 | 공식 문서에서 확인되는 내용 | 실무 대응 |
|---|---|---|
| 플랜 | 현재 가격 페이지는 Hobby에 제한된 Agent 요청, Individual 월 20달러에 Cloud Agents, Teams 사용자당 월 40달러에 공유 맥락 기반 자동화를 안내한다. | Projects 메뉴가 보여도 실제 사용량과 조직 정책을 결제 화면·대시보드에서 다시 확인한다. |
| 과금 | Cloud Agents는 선택 모델의 API 가격으로 계산되고 컨텍스트 크기가 비용에 영향을 줄 수 있다. | 파일럿 저장소와 지출 한도로 시작하고 작업 유형별 사용량을 본다. |
| 코드 보관 | Cloud Agent는 실행을 위해 코드를 클라우드에 저장해야 한다. Privacy Mode와 격리 VM을 지원하지만 로컬 전용 작업과 위험 구조가 다르다. | 민감 저장소는 제외하거나 조직 정책을 먼저 확인한다. |
| 네트워크 | 외부 통신 전체 허용 또는 허용 목록 방식을 설정할 수 있다. | 패키지·SCM 등 필요한 도메인만 열고 인터넷 입력의 프롬프트 주입 가능성을 고려한다. |
| 베타 | 순차 배포 중이며 UI와 동작이 바뀔 수 있다. | 중요 작업은 작은 범위에서 검증하고 자동 병합을 피한다. |
Cursor는 내부 사용 사례와 생산성 수치를 발표했지만 이는 공급사 자체 보고다. 내 팀에서의 효과는 PR 재작업률, 실패한 CI, 검토 시간, 실제 비용처럼 직접 측정 가능한 항목으로 판단해야 한다.
자주 막히는 상황과 해결 순서
- Projects 메뉴가 없다: 앱을 최신 상태로 확인하고 계정을 다시 불러온다. 그래도 없다면 베타 순차 배포 대상이 아닐 수 있으므로 억지로 숨은 경로를 찾지 않는다.
- 로컬 수정이 사라졌다: Cloud Agent는 깨끗한 원격 상태에서 시작한다. 필요한 변경을 안전한 브랜치에 커밋·푸시하거나, 민감한 수정은 로컬에서 정리한 뒤 시작한다.
- 저장소나 하위 모듈을 못 읽는다: 연결된 계정의 읽기·쓰기 권한과 의존 저장소 범위를 확인한다.
- 시크릿이 보이지 않는다: 시크릿은 에이전트 시작 시 주입된다. 올바른 팀·환경에 저장됐는지 확인하고 새 실행으로 검증한다. 로그나 PR에 값을 출력하지 않는다.
- 작업이 목표에서 벗어난다: 프로젝트 공유 맥락에 결정 기록, 금지 영역, 테스트 절차를 짧은 문서로 고정하고 다음 배치를 줄인다.
- 비용이 예상보다 빠르게 늘어난다: 큰 컨텍스트, 병렬 에이전트 수, 선택 모델, 반복 실패를 차례로 확인한다. 지출 한도를 낮추고 독립 작업 수를 줄인다.
어떤 팀부터 써볼 만한가
여러 PR로 나뉘지만 완료 조건이 분명하고, CI와 코드 리뷰가 이미 작동하는 팀이라면 Projects의 장점이 크다. 반대로 요구사항이 계속 바뀌고 테스트가 없으며 한 사람이 모든 변경을 즉시 병합하는 환경에서는 병렬화가 혼란을 빠르게 키울 수 있다. 첫 프로젝트는 핵심 결제 시스템보다 문서 자동 점검, 비핵심 마이그레이션, 제한된 회귀 검사처럼 실패 비용이 낮은 작업이 좋다.
장기 프로젝트 관리가 아니라 팀 지침과 명령을 재사용 가능한 패키지로 배포하려는 목적이라면 Claude Code 플러그인 만들기 가이드가 더 직접적인 선택 기준을 제공한다.
시작 체크리스트
- 목표·제외 범위·완료 조건을 한 페이지에 적었는가?
- 원격 기준 브랜치가 빌드되고 테스트 명령이 문서화됐는가?
- 저장소·시크릿·네트워크 권한을 최소화했는가?
- 첫 PR을 작고 되돌릴 수 있게 정했는가?
- CI 로그와 diff를 확인할 사람이 지정됐는가?
- 지출 한도와 중단 조건을 정했는가?
- 반복 실행은 파일럿이 통과한 뒤 켜도록 했는가?
영문판: Read this guide in English
공식 출처
자료 확인일: 2026년 9월 17일
댓글
댓글 쓰기