Cursor Agent 장기 작업을 중단점과 완료 조건으로 나누어 통제하는 방법
계획·구현·검증 3단계 프롬프트 분리, 체크포인트 복구, Git 트리 격리 절차

핵심 요약
- 파일 5개 이상을 수정하는 장기 작업은 단일 프롬프트로 실행하지 않고 계획(Plan), 단계별 구현(Implement), 명령 기반 검증(Verify)으로 세션을 분리한다.
- DB 스키마, 백엔드 API, 프론트엔드 UI 경계마다 명시적 중단점(Checkpoint)을 지정해 사람이 중간 산출물을 승인한 뒤 다음 단계로 넘어가게 통제한다.
- 에이전트가 요구사항에 없는 패키지를 설치하거나 수정 범위가 확산될 때는 추가 프롬프트로 교정하지 않고 Cursor Checkpoint 또는 git restore로 즉시 직전 상태로 되돌린다.
- 완료 선언 기준에 tsc --noEmit과 단위 테스트 통과 명령을 명시해 에이전트가 스스로 종료 여부를 판정하게 만든다.
단일 함수를 고치거나 오타를 잡는 짧은 작업은 프롬프트 한 번으로 끝나지만, 여러 레이어에 걸친 기능 구현이나 마이그레이션은 중간에 방향이 틀어지는 순간 복구 비용이 급격히 커진다. 이 글은 Cursor 0.43 이상 환경의 Agent 모드에서 장시간 작업을 중단점(Checkpoint)과 승인 지점으로 쪼개어 통제하는 절차와 프롬프트 설계 기준을 다룬다. 읽고 나면 계획·구현·검증 단계를 분리하고 CLI 검증 명령과 Git 기준점으로 에이전트의 독주를 막는 워크플로를 바로 적용할 수 있다.
단발성 수정과 장기 에이전트 작업의 실패 구조 비교
Cursor 공식 문서의 Agent 가이드에 따르면 Agent 모드는 코드베이스 검색, 파일 편집, 터미널 명령 실행을 자율적으로 반복하며 목표를 수행한다. 자율 루프가 길어질수록 초기 프롬프트의 모호한 부분을 에이전트가 임의 가정으로 채우기 때문에, 작업 규모에 따라 통제 방식을 달리해야 한다.
| 구분 | 단발성 짧은 작업 | 중단점 기반 장기 작업 |
|---|---|---|
| 대상 규모 | 단일 파일 내 함수 1~2개 수정, 명확한 버그 패치 | DB 스키마·API·UI 연계 구현, 다중 모듈 리팩터링 |
| 프롬프트 단위 | 1회 요청 후 즉시 결과 확인 | 계획 승인 → 단계별 구현(파일 3~5개 제한) → 독립 검증 |
| 실패 감지 시점 | 코드 생성 직후 에디터 diff에서 즉시 식별 | 수십 개 파일이 바뀐 뒤 빌드나 통합 테스트에서 뒤늦게 노출 |
| 복구 메커니즘 | 단일 파일 git checkout 또는 재질문 | 단계별 Cursor Checkpoint 복원 및 git restore 롤백 |
| 완료 판정 기준 | 개발자의 육안 코드 확인 | tsc --noEmit, 테스트 스위트 통과 등 실행 가능한 종료 조건 |
장기 작업에서 가장 빈번하게 발생하는 사고는 에이전트가 컴파일 에러를 해결하려고 요구사항에 없던 외부 패키지를 임의로 설치하거나, 타입 정의를 any로 완화하며 주변 파일까지 연쇄적으로 수정하는 현상이다. 이를 막으려면 시작 전에 멈출 지점부터 설계해야 한다.
계획·구현·검증 3단계와 중단점을 적용하는 4가지 절차
장시간 작업을 하나의 프롬프트로 전달하지 않고 네 단계의 통제 루프로 나누어 실행하는 절차는 다음과 같다.
- 작업 트리 격리와 계획(Plan) 전용 프롬프트 실행 — 코드를 한 줄도 수정하기 전에 변경 대상 파일과 실행 순서만 표로 출력하게 지시한다. 병렬 작업이 필요하다면 Git Worktree 기반 에이전트 격리 전략에서 다루듯 독립된 워크트리를 먼저 생성해 메인 브랜치 오염을 차단한다.
- 레이어 및 파일 수 기준의 중단점(Checkpoint) 설정 — 승인된 계획 중 한 번에 1개 단계(최대 3~5개 파일)만 구현하고 멈추도록 제약한다. 단계가 끝나면 반드시 다음 단계 진행 여부를 질문하게 만든다.
- 실행 가능한 완료 조건(Definition of Done) 검증 — Node.js 22.11.0 및 TypeScript 5.8 환경 기준으로 타입 검사와 지정된 테스트 파일 실행을 별도 검증 프롬프트로 지시한다.
- 단계별 Git 스냅샷 기록 또는 체크포인트 롤백 — 검증을 통과한 단계만 로컬에 스테이징하거나 WIP 커밋으로 고정하고, 방향이 어긋난 단계는 추가 대화로 고치지 않고 직전 체크포인트로 즉시 되돌린다.
아래는 1단계(계획)와 2단계(중단점 기반 구현)를 분리해 전달하는 프롬프트 템플릿이다.
[1단계: 계획 수립 전용 프롬프트 — 코드 수정 금지]
주문 취소 및 부분 환불 기능을 추가하려고 한다. 아직 어떠한 파일도 수정하거나 터미널 명령을 실행하지 마라.
먼저 아래 항목만 조사해 Markdown 표로 제시하고 승인을 기다려라.
1. 수정 또는 신규 생성이 필요한 파일 경로 목록 (최대 9개 이내로 설계)
2. 작업을 3개 체크포인트(1: DB 스키마·타입, 2: 서비스·API 라우트, 3: 테스트)로 나눈 실행 순서
3. 각 체크포인트가 끝났을 때 실행할 검증 명령어
계획표를 검토해 불필요한 파일 수정이나 아키텍처 위반을 쳐낸 뒤, 아래처럼 중단점과 완료 조건을 결합한 구현 프롬프트를 입력한다.
[2단계: 체크포인트별 구현 및 완료 조건 프롬프트]
승인한 계획 중 '체크포인트 1(DB 스키마 및 도메인 타입)'만 진행해라.
제약 사항:
- 수정 허용 파일: src/db/schema/orders.ts, src/types/refund.ts (2개 파일 외 수정 금지)
- package.json 의존성 추가 금지
- 구현 후 아래 완료 조건 명령을 실행해 결과를 보고하고, 체크포인트 2로 넘어가지 말고 대기해라.
완료 조건:
- [ ] npx tsc --noEmit 통과 (에러 0건)
- [ ] npx vitest run src/types/__tests__/refund.test.ts 통과
완료 조건을 하나라도 충족하지 못하면 완료를 선언하지 말고 실패 원인과 남은 항목을 출력해라.
에이전트가 잘못된 방향으로 진입했을 때의 체크포인트 복구 기준
작업 도중 에이전트가 원래 범위를 벗어났다는 신호는 세 가지로 나타난다. 첫째, 지시하지 않은 서드파티 라이브러리를 npm install로 설치하려 시도한다. 둘째, 허용한 파일 목록 바깥의 공통 유틸리티나 설정 파일을 건드린다. 셋째, 동일한 타입 오류나 테스트 실패를 고치겠다며 3회 이상 연속으로 파일 수정과 재실행을 반복한다.
이 신호가 보일 때 채팅창에 "그 부분은 원래대로 돌리고 다시 해줘"라고 자연어로 지시하면 에이전트가 이전 상태를 완벽히 복원하지 못해 잔여 코드가 남는다. 대신 Cursor 채팅창 각 프롬프트 우측에 표시되는 Restore Checkpoint 버튼을 눌러 파일 시스템 상태를 해당 프롬프트 실행 직전으로 되돌리거나, git-restore 공식 문서에 명시된 명령으로 작업 트리를 강제 초기화해야 한다.
# 체크포인트 1 완료 후 안전한 상태를 스테이징 영역 또는 임시 커밋으로 보존
git add src/db/schema/orders.ts src/types/refund.ts
git commit -m "wip: checkpoint 1 refund schema and types"
# 체크포인트 2 진행 중 에이전트가 방향을 잃었을 때 추적 파일과 미추적 파일을 즉시 초기화
git restore --source=HEAD --staged --worktree .
git clean -fd
이처럼 Git 커밋과 체크포인트를 결합하면 에이전트가 체크포인트 2에서 10개 파일을 잘못 고쳤더라도 1초 만에 체크포인트 1 직후의 깨끗한 상태로 복귀할 수 있다. 복구 후에는 기존 프롬프트의 모호했던 제약 조건을 보강해 수정된 프롬프트로 해당 단계를 다시 실행한다.
프로젝트 규칙 파일에 중단점 프로토콜 고정하기
매번 긴 프롬프트에 중단점 규칙과 완료 조건을 반복해서 적는 대신, 저장소의 .cursor/rules/ 디렉터리에 에이전트 행동 수칙을 정의해 두면 일관성이 높아진다. Cursor의 Rules for AI 문서에 따르면 .mdc 파일로 작성된 프로젝트 규칙은 에이전트 세션에 자동으로 주입된다. 팀 단위의 세부 규칙 설계는 Cursor Rules 팀 개발 가이드에서 자세히 다룬다.
---
description: 장기 작업 및 다중 파일 수정 시 중단점(Checkpoint) 강제 규칙
globs: src/**/*
---
# Long-Task Checkpoint Protocol
- 3개 이상의 파일을 수정해야 하는 요청을 받으면 즉시 코드를 작성하지 말고 [계획표(대상 파일, 단계 구분, 검증 명령)]를 먼저 출력한 뒤 사용자 승인을 요청한다.
- 한 번의 응답 루프에서 수정하는 파일 수는 최대 4개로 제한한다.
- 각 단계가 끝나면 `npm run typecheck`를 실행하고, 통과 여부를 보고한 뒤 "다음 단계로 진행할까요?"라고 질문하며 멈춘다.
- 사용자 사전 승인 없이 `package.json`을 수정하거나 새 패키지를 설치하지 않는다.
이 규칙 파일을 저장소에 커밋해 두면 팀원 누구나 Agent 모드로 큰 작업을 시작할 때 자동으로 계획 승인 → 단계별 중단 → 명령 검증의 보호막 안에서 작업을 이어갈 수 있다.
초보자가 자주 실수하는 포인트
- 구현과 검증을 한 프롬프트에 묶어 요청해 에이전트가 실패한 테스트에 맞춰 프로덕션 로직이나 테스트 단언문을 임의로 삭제·완화하는 경우
- 방향이 틀어진 상태에서 계속 수정 프롬프트를 덧붙여 컨텍스트 윈도우가 오염되고 불필요한 파일 변경이 누적되는 경우
- 한 번의 프롬프트에 변경 대상 파일 수 상한을 두지 않아 10개 이상의 파일이 동시에 수정되어 코드 리뷰와 부분 롤백이 불가능해지는 경우
체크리스트
- 작업 시작 전 git status가 깨끗한 상태(clean working tree)인지 확인했는가
- 1단계 프롬프트에 코드 수정 금지와 변경 대상 파일 목록·순서 표 출력만 요청했는가
- 단계당 수정 파일 수를 최대 3~5개 이내로 제한하고 단계별 승인 질문을 포함했는가
- 완료 조건에 npm run typecheck 및 대상 테스트 실행 명령을 구체적으로 명시했는가
- 이탈 발생 시 되돌아갈 Git 커밋 또는 Cursor Checkpoint 기준점이 존재하는가
자주 묻는 질문
Cursor의 Restore Checkpoint 기능과 Git 커밋 중 어느 것을 기준으로 복구해야 하나요?
단일 채팅 세션 안에서의 즉각적인 프롬프트 단위 롤백은 Cursor의 Restore Checkpoint가 빠르지만, 세션이 길어지거나 터미널 명령으로 패키지 설치·파일 삭제가 일어났다면 Git 추적 영역 밖의 변경이 남을 수 있다. 따라서 각 단계가 끝날 때마다 git add와 임시 커밋(WIP)을 남겨 이중 안전장치를 두는 구성이 안전하다.
장기 작업 중 컨텍스트가 길어져 에이전트가 초기 제약을 잊어버릴 때는 어떻게 처리하나요?
하나의 채팅 스레드에서 모든 단계를 이어가면 이전 시행착오 로그가 토큰을 소모해 후반부 정확도가 떨어진다. 단계별 산출물을 Git에 커밋한 뒤 새 Agent 세션을 열고, 완료된 단계 요약과 다음 단계 목표만 전달해 컨텍스트를 초기화하는 방식이 효과적이다.
참고 자료 · 검증 기준
- Cursor Docs — Agent Overview
- Cursor Docs — Rules for AI (.cursor/rules)
- Git Documentation — git-restore
위 자료와 내용을 대조한 날짜: . 도구·서비스 정책은 이후 바뀔 수 있으므로 적용 전 공식 문서를 다시 확인하세요.
이 글은 실제 실무 환경 테스트 및 검증된 기술 자료를 바탕으로 작성되었으며, 환경 변화에 따라 지속적으로 갱신됩니다.