Claude Code 안전하게 쓰기: 권한 모드·체크포인트·비밀정보

01작업 전: 폴더·비밀정보·복구 수단부터 확인하기

안전한 사용은 프롬프트를 보내기 전부터 시작합니다. 먼저 현재 터미널 위치가 맞는지 확인하고, 연습이라면 실제 업무 저장소와 분리된 폴더를 사용합니다. .env, 인증서, 개인 자료처럼 민감한 파일이 있는 프로젝트라면 AI 도구에 무엇을 노출할지 먼저 검토합니다. 예제에 API 키가 필요해 보여도 실제 키 대신 `sk-EXAMPLE-NOT-REAL`처럼 명백한 가짜 값만 사용합니다.

작업 시작 전 확인
- 현재 폴더가 내가 의도한 프로젝트인가?
- 실제 개인정보·비밀번호·API 키가 예제 파일에 없는가?
- 변경 전 상태를 git으로 확인하거나 필요한 경우 커밋했는가?
- 처음 보는 작업이면 plan 또는 Manual처럼 확인 중심 흐름으로 시작하는가?

Claude Code의 체크포인트가 있다고 해서 별도의 버전 관리가 필요 없어지는 것은 아닙니다. 공식 문서에서도 체크포인트는 git 같은 버전 관리를 대체하지 않는다고 명시되어 있습니다. 중요한 프로젝트에서는 작업 전 커밋이나 별도 브랜치처럼 기존 버전 관리 습관을 유지합니다.

02권한 모드: 자동화 수준과 사람이 확인할 지점 구분하기

공식 문서에 안내된 권한 모드는 Manual, acceptEdits, plan, auto, dontAsk, bypassPermissions입니다. 워크노트는 초보자에게 Manual 또는 plan에서 시작하기를 권합니다. 이것은 위험이 사라진다는 뜻이 아니라, 변경 범위를 먼저 읽고 판단하는 습관을 만들기 위한 선택입니다.

기본 시작 모드는 요금제에 따라 다릅니다. 2026-09-22에 확인한 공식 문서에서는 Pro·Max·Team 요금제의 대화형 터미널 기본 시작 모드를 auto, 다른 요금제는 Manual로 설명합니다. 따라서 항상 같은 승인 흐름이 나타난다고 가정하지 말고 현재 모드를 확인합니다.

claude --permission-mode plan

03작업 중: 승인하기 전에 파일과 명령의 의미 읽기

Claude Code는 필요한 파일을 스스로 읽고, 파일 수정이나 명령 실행 전에 승인을 요청할 수 있습니다. 하지만 승인 창이 나타났다는 사실 자체가 명령의 안전성을 보장하지는 않습니다. 어떤 파일이 바뀌는지, 삭제·이동·복사 명령이 포함되는지, 요청하지 않은 설치나 범위 확대가 있는지를 먼저 읽습니다.

변경 전에 다음만 먼저 알려줘.
1. 수정할 파일 이름
2. 각 파일에서 바꿀 내용
3. 실행하려는 셸 명령
4. 원본 파일을 삭제·이동·덮어쓰는 동작이 있는지
아직 수정하거나 명령을 실행하지 마.

• 요청한 범위보다 많은 파일이 선택되면 이유를 묻는다.
• rm, mv, cp처럼 파일 상태를 직접 바꾸는 명령은 대상 경로를 다시 확인한다.
• 설치 명령이 나오면 요구사항에 실제로 필요한지 확인한다.
• 예상과 다른 변경이 보이면 승인을 계속하지 않고 plan으로 돌아간다.
• 민감정보가 프롬프트·파일·로그에 들어가지 않도록 실제 값을 제거한다.

04체크포인트: 되돌리기 기능의 범위를 정확히 알기

Claude Code는 보내는 각 프롬프트마다 자동 체크포인트를 만듭니다. `/rewind` 또는 입력창이 비었을 때 Esc를 두 번 눌러 되돌리기 메뉴를 열 수 있고, 코드와 대화 복원, 대화만 복원, 코드만 복원, 요약 등을 선택할 수 있습니다. 그러나 이 기능이 모든 파일 변경을 기록하는 것은 아닙니다.

/rewind

특히 셸 명령으로 삭제하거나 이동한 파일을 `/rewind`가 전부 되살려 줄 것이라고 기대하면 안 됩니다. 체크포인트는 Claude Code 안에서의 작업을 되돌리는 보조 수단으로 보고, 프로젝트 이력과 복구는 git 등 별도 수단으로 관리합니다.

05비밀정보와 실제 데이터를 연습 예제에서 분리하기

코드가 필요로 한다는 이유만으로 비밀번호, API 키, 실제 고객 정보, 실제 연구 데이터를 프롬프트나 예제 파일에 그대로 넣지 않습니다. 튜토리얼과 오류 재현에서는 합성 데이터와 명백한 가짜 토큰을 사용합니다. 실제 프로젝트에서 어떤 데이터를 도구에 제공할 수 있는지는 조직 정책과 사용 환경을 별도로 확인해야 합니다.

연습용 가짜 값:
API_KEY=sk-EXAMPLE-NOT-REAL

가상 데이터:
date,category,amount
2026-09-01,food,12000

프로젝트에 민감정보가 이미 들어 있다면 단순히 '그 파일은 보지 마'라고 요청하는 것만으로 충분하다고 가정하지 않습니다. 도구가 접근할 수 있는 파일 범위와 보안 정책을 확인하고, 필요하면 민감정보를 제거한 작업용 복사본에서 재현합니다.

06작업 후: 설명보다 실제 diff와 실행 결과를 기준으로 보기

작업이 끝난 뒤에는 AI가 '완료했다'고 말하는 것보다 실제 파일과 실행 결과를 기준으로 판단합니다. 앞선 글처럼 git diff를 읽고 실행 명령을 다시 수행하며 기대값과 비교합니다. 오류 수정이라면 문제가 사라졌는지만 보지 않고 원래 정상 입력도 여전히 같은 결과를 내는지 확인합니다.

작업 후 확인
- git diff에서 예상한 파일만 바뀌었는가?
- 실행 결과가 요구사항의 기대값과 일치하는가?
- 임시 파일·가짜 비밀정보가 커밋 대상에 남아 있지 않은가?
- 다음 사람이 이해할 수 있게 변경 이유와 실행 방법이 남아 있는가?

Claude Code의 자연어 설명은 검토를 돕는 자료입니다. 최종 판단은 실제 diff, 실행 결과, 프로젝트 규칙과 대조해 내립니다. 이 원칙은 모델이나 권한 모드가 달라져도 유지할 수 있습니다.

07최종 결과물: 작업 전·중·후 안전 체크리스트

• 처음에는 Manual 또는 plan처럼 확인 중심 흐름을 사용한다.
• bypassPermissions는 모든 검사를 생략하므로 격리된 컨테이너·VM에서만 사용한다.
• 체크포인트를 git의 대체물로 생각하지 않는다.
• Bash 명령으로 바뀐 파일과 외부에서 직접 바꾼 파일은 체크포인트 복원을 기대하지 않는다.
• 실제 비밀번호·API 키·개인정보 대신 합성 데이터와 명백한 가짜 값을 사용한다.
• 완료 여부는 AI의 설명이 아니라 diff와 실제 실행 결과로 확인한다.

이 시리즈의 공통 원칙은 먼저 요구사항을 작게 정하고, 읽기와 계획부터 시작하며, 변경 범위를 확인하고, 실행 결과를 사람이 검증하는 것입니다. 자동화 범위가 넓어질수록 사람의 역할이 사라지는 것이 아니라 무엇을 허용했고 결과가 기준과 맞는지 확인하는 쪽으로 이동합니다.

직접 확인할 항목

Claude Code 공식 문서(2026-09-22 확인)를 기준으로 작성 · Claude Code 실제 실행 없음 · Python 실행 코드 없음

• Manual, acceptEdits, plan, auto, dontAsk, bypassPermissions 설명이 공식 문서와 일치하는지 확인
• Pro·Max·Team과 다른 요금제의 기본 시작 모드 차이를 공식 문서와 대조
• 각 프롬프트의 자동 체크포인트와 /rewind 또는 빈 입력창에서 Esc 두 번 접근 방법을 공식 문서와 대조
• Bash 명령으로 변경된 파일과 Claude Code 밖에서 바꾼 파일은 체크포인트가 추적·복원하지 않는다고 명시했는지 확인
• 체크포인트가 git을 대체하지 않는다는 한계를 명확히 적었는지 확인
• 실제 비밀정보 대신 sk-EXAMPLE-NOT-REAL 같은 명백한 가짜 값만 사용했는지 확인