Cursor의 Plan vs Act 듀얼 모드 에이전트 워크플로우
AI 코딩 에이전트의 가장 큰 과제 중 하나는 무단 변경을 방지하는 것입니다. Plan vs Act 듀얼 모드 워크플로우는 에이전트가 "Plan 모드"에서 변경 사항을 제안한 후 "Act 모드"에서 실행하도록 요구함으로써 이 문제를 해결합니다. 이 가이드는 Cursor에서 이 강력한 안전 패턴을 구현하는 방법을 보여줍니다.
Plan vs Act란?
Plan 모드(읽기 전용)
Plan 모드에서 에이전트는:
- 코드를 읽고 분석합니다
- 구조화된 형식으로 변경 사항을 제안합니다
- 어떤 파일도 수정할 수 없습니다
- 사용자 검토를 위한 상세한 계획을 제시합니다
Act 모드(읽기-쓰기)
Act 모드에서 에이전트는:
- 승인된 변경 사항만 실행합니다
- 완전한 읽기-쓰기 접근 권한을 가집니다
- 제공된 정확한 계획을 따릅니다
- 완료된 작업을 보고합니다
왜 이 패턴을 사용해야 하나요?
| Plan/Act 없음 | Plan/Act 사용 |
|---|---|
| AI가 예상치 못하게 파일을 변경합니다 | 모든 변경 사항은 승인이 필요합니다 |
| 변경 내용을 검토하기 어렵습니다 | 먼저 명확한 계획이 제시됩니다 |
| 롤백이 어렵습니다 | 변경 사항은 추적 가능하고 되돌릴 수 있습니다 |
| 긴 세션에서 컨텍스트가 흐트러집니다 | 작업별 집중 실행 |
구현 방법 1: Cursor 규칙
.cursor/rules/plan-act-workflow.mdc 생성:
---
description: 'Plan vs Act 듀얼 모드 워크플로우'
globs: ['**/*']
alwaysApply: true
---
# Plan vs Act 워크플로우
## 중요한 규칙
사용자의 명시적인 승인 없이는 어떤 파일도 수정할 수 없습니다.
## Plan 모드(기본)
작업이 주어졌을 때:
1. 관련 파일을 읽고 분석합니다
2. 구체적인 변경 사항이 포함된 상세한 계획을 작성합니다
3. 다음 형식으로 계획을 제시합니다:
### 계획: [작업 이름]
#### 수정할 파일
- `file/path/one.ts` - 변경할 내용
- `file/path/two.ts` - 변경할 내용
#### 변경 사항 요약
1. 변경 1 설명
2. 변경 2 설명
#### 새 파일(있는 경우)
- `new/file/path.ts` - 용도
#### 테스트 계획
- 변경 사항이 작동하는지 확인하는 방법
4. 사용자가 "PROCEED" 또는 "ACT"를 입력할 때까지 기다립니다
## Act 모드(승인 후)
사용자가 "PROCEED"라고 말한 후에만:
1. 계획에서 변경 사항을 구현합니다
2. 승인된 변경 사항만 수행합니다
3. 파일 목록과 함께 완료를 보고합니다
4. 테스트 단계를 제안합니다
## 절대 하지 말아야 할 일
- 계획 단계를 건너뜁니다
- 계획에 없는 변경 사항을 추가합니다
- Plan 모드 중에 파일을 수정합니다
- 계획당 한 번 이상 승인을 요청합니다
구현 방법 2: 사용자 지정 모드
Cursor 설정에서 사용자 지정 모드를 생성합니다:
- Cursor 설정 열기(
Cmd/Ctrl + ,) - "Modes" 또는 "AI Features"로 이동
- "Add Custom Mode" 클릭
- 구성:
{
"name": "Planner",
"description": "계획 모드 - 읽기 전용 분석",
"systemPrompt": "당신은 계획 모드입니다. 파일을 읽을 수는 있지만 절대 수정하지 마세요. 코드베이스를 분석하고, 요구사항을 이해하고, 상세한 계획을 제시하세요. 어떤 변경이든 하기 전에 사용자 승인을 기다리세요.",
"tools": ["read", "grep", "search"],
"fileWrite": false
}
{
"name": "Executor",
"description": "실행 모드 - 승인된 변경 사항 구현",
"systemPrompt": "당신은 실행 모드입니다. 계획에서 승인된 변경 사항만 구현하세요. 승인된 범위에서 벗어나지 마세요. 변경 사항을 할 때마다 보고하세요.",
"tools": ["read", "write", "edit"],
"fileWrite": true
}
구현 방법 3: 채팅 기반 워크플로우
1단계: Plan 모드에서 시작
[PLAN MODE] 이 앱에 사용자 인증을 추가해야 합니다.
코드베이스를 분석하고 계획을 작성하세요.
아직 변경 사항을 만들지 마세요.
2단계: 에이전트가 계획 제시
## 계획: 사용자 인증 추가
### 수정할 파일
1. `src/app.ts` - 인증 미들웨어 추가
2. `src/routes/users.ts` - 로그인/등록 엔드포인트 추가
3. `src/models/user.ts` - 비밀번호 해싱 추가
### 새 파일
1. `src/middleware/auth.ts` - JWT 검증
2. `src/services/auth.ts` - 인증 로직
3. `tests/auth.test.ts` - 단위 테스트
### 구현 세부 사항
- 비밀번호 해싱에 bcrypt 사용
- 15분 만료의 JWT 토큰
- 리프레시 토큰 순환
### 테스트
- 유효/무효 자격 증명으로 로그인 테스트
- 토큰 갱신 테스 트
- 보호된 경로 테스트
3단계: 검토 및 승인
계획을 검토하고 다음 중 하나를 수행합니다:
PROCEED를 입력하여 승인- 수정 요청
- 거부하고 다시 시작
4단계: 실행
[ACT MODE] 인증 계획을 PROCEED합니다.
승인된 내용을 정확히 구현하세요.
5단계: 검증
실행 후:
모든 변경 사항이 올바르게 이루어졌는지 확인:
1. 인증 미들웨어가 적용되었는지 확인
2. 로그인 엔드포인트 테스트
3. 인증 테스트 실행
고급: 자동 계획 파싱
복잡한 프로젝트의 경우 구조화된 계획 형식을 사용합니다:
## 계획 ID: AUTH-001
## 상태: 승인 대기 중
## 우선순위: 높음
## 예상 시간: 30분
### 범위
- JWT 기반 인증 추가
- 로그인/로그아웃/등록 구현
- 비밀번호 재설정 흐름 추가
### 변경 사항
#### 파일: src/middleware/auth.ts(새로 만들기)
```typescript
import jwt from 'jsonwebtoken';
export const verifyToken = (req, res, next) => {
// 구현
};
파일: src/routes/auth.ts(새로 만들기)
// 로그인, 등록, 로그아웃 엔드포인트
파 일: src/app.ts(수정)
- 15번 줄:
app.use('/auth', authRoutes)추가
롤백
- 삭제: src/middleware/auth.ts
- 삭제: src/routes/auth.ts
- 되돌리기: src/app.ts 15번 줄
테스트
- 유효한 자격 증명으로 로그인
- 무효한 자격 증명으로 로그인
- 토큰 없이 보호된 경로 접근
- 유효한 토큰으로 보호된 경로 접근
## 버전 관리와 통합
### 실행 전 체크포인트
계획을 실행하기 전에:
```bash
# 체크포인트 브랜치 생성
git checkout -b plan/auth-implementation
# 현재 상태 커밋
git add -A && git commit -m "체크포인트: 인증 구현 전"
실행 후 검증
# 변경 사항 검토
git diff
# 문제가 있으면 되돌리기
git checkout -- .
# 또는 체크포인트로 되돌리기
git reset --hard HEAD~1
팀 워크플로우
코드 리뷰용
- 개발자가 Cursor에서 계획을 생성
- 개발자가 계획을 PR 설명에 붙여넣기
- 리뷰어가 실행 전에 계획을 승인
- 개발자가 Plan vs Act 워크플로우로 실행
- 리뷰어가 실행이 계획과 일치하는지 확인
PR 템플릿
## 계획
[AI 생성 계획을 여기에 붙여넣기]
## 실행
- [ ] 모든 계획된 변경 사항이 구현됨
- [ ] 계획되지 않은 수정 없음
- [ ] 테스트 통과
- [ ] 계획과 실행이 일치함
## 검증
[수행한 테스트를 설명]
일반적인 함정
| 함정 | 해결책 |
|---|---|
| 에이전트가 계획을 건너뜀 | 규칙과 모드 제한으로 강제 실행 |
| 계획이 너무 모호함 | 구체적인 파일 경로와 줄 번호 요구 |
| 사용자 승인 피로 | 관련 변경 사항을 단일 계획으로 그룹화 |
| 실행이 계획에서 벗어남 | 실행 후 diff를 계획과 비교 |
| 너무 많은 왕복 | 사소한 편차는 허용, 주요 편차는 플래그 지정 |
빠른 시작 체크리스트
-
.cursor/rules/plan-act-workflow.mdc생성 - 작고 안전한 작업으로 테스트
- 에이전트가 읽기 전용 모드를 존중하는지 확인
- 계획 승인 및 거부 연습
- 실행 전에 git 체크포인트 설정
- 팀을 위해 워크플로우를 문서화