Plan mode와 계획 검토

계획과 실행을 분리하는 이유

영향 범위가 넓은 변경은 첫 번째 답변에서 바로 파일을 고치기보다, 요구사항·영향 파일·검증 방법을 먼저 확인하는 편이 안전하다. Claude Code의 Plan mode는 이 목적을 위한 권한 모드다. 대화형 세션에서는 권한 모드 전환 또는 /plan으로 사용할 수 있고, CLI에서는 permission mode를 plan으로 지정할 수 있다.

요청
 │
 ├─ Plan mode: 파일·의존성 조사 → 단계와 위험 제안 → 사용자 검토
 │
 └─ 승인 후: 제한된 권한으로 구현 → 테스트·diff 검증 → 완료

계획은 설계 가설이지 실행 결과가 아니다. 계획에서 언급한 파일, 명령, 마이그레이션 순서는 실제 작업 전 다시 검토하고, 특히 삭제·배포·권한 확대가 포함되면 명시적 승인을 둔다.

계획 검토의 실전 기준

| 항목 | 검토 질문 | | --- | --- | | 범위 | 어떤 파일·서비스·사용자가 영향을 받는가? | | 대안 | 더 작고 되돌릴 수 있는 변경이 있는가? | | 권한 | 읽기, 쓰기, 네트워크, MCP 중 무엇이 필요한가? | | 검증 | 테스트, 린트, diff, 운영 관찰 중 무엇으로 확인할 것인가? | | 롤백 | 실패했을 때 어떤 커밋·백업·절차로 복구하는가? |

공식 UI에 계획을 더 다듬는 흐름이 나타날 수 있어도, 이를 임의의 SDK 옵션이나 고정된 백그라운드 폴링·모델 강제 지정으로 바꾸어 사용하면 안 된다. 공개 문서에 없는 API 이름이나 플래그는 자동화 계약이 아니다.

비용과 사용량은 관측으로 관리

비용은 모델, 입력·출력 길이, 도구 사용에 따른 작업 길이, 캐시와 재시도 등 여러 조건에 따라 달라진다. 따라서 ‘특정 모드가 몇 퍼센트 절감한다’ 같은 고정 수치는 운영 기준으로 부적절하다. Agent SDK를 사용하는 애플리케이션은 공식 비용·사용량 기능과 자신의 로그 정책을 이용해 작업별 지표를 수집하고, 예산 한도와 실패 처리를 명시해야 한다.

요청 단위 기록
  ├─ 작업 종류·허용 도구
  ├─ 모델·턴·종료 상태
  ├─ 사용량·비용 지표
  └─ 테스트·승인 결과
         ↓
다음 작업의 범위·권한·예산을 조정

계획을 잘 세우는 핵심은 긴 계획을 만드는 일이 아니라, 실제 변경 전에 불확실성과 권한을 드러내는 것이다. Plan mode와 비용 관측을 함께 쓰면 작업을 작게 나누고, 검증 가능한 단위로 진행할 수 있다.