인증 쿠키를 바꾸는 요청을 바로 구현시키면 Claude는 전면 교체와 단계적 호환 중 하나를 스스로 고를 수 있습니다. Plan Mode로 시작하면 먼저 인증 파일과 테스트를 읽고, 두 선택지의 영향과 롤백을 계획으로 돌려받을 수 있습니다. 사람은 그 계획에서 불필요한 라이브러리 도입과 넓은 파일 수정을 덜어낸 뒤에만 편집을 엽니다.

핵심 좋은 실행계획은 할 일 목록이 아니라 현재 구조, 변경 대상, 단계별 결과물, 의존성, 검증과 롤백을 연결한 계약입니다. 계획을 읽고 구현 범위와 완료 기준을 사람이 설명할 수 있어야 실행 단계로 넘어갈 수 있습니다.

PRD와 실행계획은 같은 문서가 아니다. PRD에는 해결할 문제, 사용자, 범위, 제외 범위와 수용 기준이 들어갑니다. 실행계획에는 현재 코드 구조, 수정 파일, 데이터 흐름, 단계 순서와 테스트가 들어갑니다. 기능 가치가 확정되지 않은 상태에서 파일 목록부터 만드는 것은 계획이 아니라 추측입니다.

작은 수정은 짧은 계획으로 충분합니다. 모든 작업을 거대한 명세로 만드는 것도 비용입니다. 실패 영향과 변경 범위가 클수록 계획의 깊이를 높입니다.

계획 전에 탐색 범위를 지정한다. 관련 라우트, 서비스, 데이터 모델, 테스트와 유사 구현을 먼저 찾게 합니다. 사용자 변경과 현재 Git 상태도 함께 확인해야 이미 진행 중인 작업을 덮지 않습니다. 외부 라이브러리나 제품 동작이 핵심이면 최신 공식 문서를 확인하도록 명시합니다.

탐색 결과는 파일 이름 나열보다 현재 흐름과 변경 지점을 설명해야 합니다. 에이전트가 기존 구조를 잘못 이해했다면 계획 단계에서 바로잡는 비용이 구현 뒤 되돌리는 비용보다 훨씬 작습니다.

실행계획에 반드시 들어갈 항목. 단계별로 목적, 수정 대상, 입력과 출력, 선행조건, 병렬 가능 여부를 적습니다. 이어서 정적 검사, 단위·통합·브라우저 테스트와 운영 검증을 붙입니다. 데이터나 배포를 건드린다면 마이그레이션 순서와 롤백도 필요합니다.

완료 기준은 기능이 구현됨 같은 문장보다 사용자가 특정 흐름을 완료하고 어떤 상태를 확인할 수 있다는 형태가 좋습니다. 테스트가 통과하더라도 화면이나 운영 데이터 확인이 필요한 지점을 별도로 둡니다.

계획 리뷰에서 찾아야 할 위험. 요청하지 않은 리팩터링, 선제적인 추상화, 새 인프라와 광범위한 의존성 변경은 가장 먼저 줄입니다. 같은 파일을 여러 병렬 작업이 수정하거나 데이터 변경 뒤 되돌릴 방법이 없다면 순서를 다시 설계합니다.

계획이 승인되면 단계별로 구현하되 새로운 사실이 나오면 계획을 고칩니다. 처음 문서를 끝까지 강제로 따르는 것보다 변경 이유와 현재 상태를 기록하는 편이 안정적입니다.

Plan Mode는 명령과 읽기 계약으로 시작합니다. 아래는 인증 개편을 위한 예시 세션입니다. Claude는 프로젝트 지침과 인증 흐름, 테스트를 먼저 읽고 소스는 편집하지 않습니다.

계획을 받기 위한 첫 요청
claude --permission-mode plan

CLAUDE.md, package.json, src/auth/**, middleware/auth.ts, tests/auth/**를 읽으세요.
현재 Git 변경을 보존하고 파일은 수정하지 마세요.
출력 계약:
- 현재 쿠키 발급/읽기 흐름
- 선택지별 장단점과 구버전 호환성
- 최소 변경 파일과 제외 범위
- 단계별 검증 명령
- 배포 중단과 롤백 조건
운영 접속과 외부 인증 설정 조회는 금지합니다.

인증 개편 계획이 두 선택지에서 갈렸습니다. 가상의 예시로 회원 API의 세션 쿠키를 바꾸는 프로젝트에서 첫 계획은 인증 미들웨어를 새 라이브러리로 전면 교체하는 안이었습니다. 저장소를 더 읽자 관리자와 일반 사용자가 같은 세션 발급 함수를 쓰고 있었고, 배포 전환 중 이전 앱과 새 앱이 함께 실행될 수 있다는 조건이 나왔습니다. 새 쿠키만 읽는 전면 교체는 이전 앱의 로그인 상태를 모두 끊을 수 있었습니다.

선택지는 두 가지였습니다. 한 번에 교체하면 코드가 빨리 단순해지지만 즉시 로그아웃 위험이 큽니다. 기존 쿠키와 새 쿠키를 합의한 전환 기간 동안 함께 읽고 새 쿠키만 쓰는 단계적 전환은 코드가 잠시 복잡하지만 되돌릴 수 있습니다. 계획 모드에서는 후자를 권장하고, 임시 호환 코드를 언제 제거할지도 별도 단계로 적었습니다.

파일 목록을 실제 산출물과 검증으로 바꿉니다. “인증 파일 수정”만으로는 실행 순서가 보이지 않습니다. 각 단계에 변경 파일, 관찰할 결과와 중단 조건을 붙이면 구현자가 무엇을 증명해야 하는지 알 수 있습니다.

승인 가능한 실행계획의 핵심 부분
1. src/auth/cookie.ts
   산출물: 새 쿠키 발급 + 기존·신규 쿠키 읽기
   검증: 개발/운영 옵션 개발·운영 옵션 단위 테스트

2. middleware/auth.ts
   산출물: 두 쿠키가 있을 때 신규 쿠키 우선
   검증: 관리자·일반 사용자 통합 테스트

3. 배포 관찰
   기준: 로그인 실패율이 배포 전 기준에서 허용 범위 안
   중단: 401 급증 또는 관리자 경로 302 반복
   복구: 이전 배포로 전환, 새 쿠키 발급 중지

4. 전환 관찰 뒤
   산출물: 구 쿠키 읽기 제거 PR
   선행조건: 관찰 기간 동안 구 쿠키 요청이 없음

계획 승인 전에 변경 범위를 다시 줄입니다. 예시 탐색 결과가 여러 라우트가 공용 미들웨어를 통과하고 직접 쿠키를 읽는 위치는 일부뿐이라고 가리킨다면, 전체 라우트 수정안을 버리고 공용 지점과 예외 위치만 남깁니다. 이것은 실측 보고가 아니라 계획을 좁히는 방법을 보여주는 예상 결과입니다.

사람은 계획에서 새 인증 라이브러리 도입을 제외하고 단계적 호환안을 선택합니다. 후속 프롬프트는 "승인한 인증 파일과 테스트만 수정하세요. 단위 테스트와 통합 테스트를 실행한 뒤 `git diff --check`와 `git diff -- src/auth middleware tests/auth`를 보여주세요. 커밋과 배포는 하지 마세요"라고 씁니다.

계획을 버리고 다시 탐색해야 하는 순간. 운영에서 쓰는 인증 공급자 설정이 저장소와 다르거나, 세션 저장소의 실제 보존 기간을 확인할 권한이 없거나, 이전 앱 버전의 트래픽 비중을 알 수 없다면 구현으로 넘어가지 않습니다. 이런 정보는 코드 추론으로 채울 수 없는 배포 조건입니다.

현재 Plan Mode는 읽기와 탐색 명령으로 계획을 만들고 소스 편집은 하지 않습니다. 계획 승인 시 선택한 권한 모드로 전환해 편집을 시작하며, 승인하지 않고 계속 수정 의견을 줄 수도 있습니다. 이 동작과 `--permission-mode plan`, `/plan` 진입 방식은 2026년 7월 29일 공식 문서에서 확인했습니다.