Claude Code 읽기 전용 설정: 도구 제한·검증 방법
Claude Code 읽기 전용 설정은 --tools Read로 내장 도구를 제한하고, 외부 MCP와 훅을 별도로 통제하는 방식으로 시작할 수 있습니다. 2026년 9월 14일 기준, --allowedTools Read만 지정해서는 다른 도구를 제외할 수 없습니다. 이 글은 공식 Permissions·CLI reference·Settings 문서와 로컬 CLI 실험을 바탕으로 설정 방법과 검증 범위를 설명합니다.
- 검토용 세션에 필요한 준비물과 샘플 파일
- 내장 도구·MCP·훅을 분리해서 제한하는 명령
- 읽기 요청과 수정 요청을 나눈 실행 검증
- 자동화에서 확인할 오류와 결과 상태
- Plan 모드·권한 규칙·OS 격리의 선택 기준
공식 기준: Claude Code CLI reference와 Configure permissions.
1. Claude Code 읽기 전용 설정이 필요한 작업
코드 수정 전에 검토 결과만 받기
낯선 저장소의 구조 설명, 변경 후보 검토, 설정 파일 해석처럼 결과물이 보고서인 작업에 적합합니다. 수정 권한을 열기 전에 독립된 검토 단계를 두면 변경 주체와 검토 주체를 구분하기 쉽습니다.
보호 대상은 원본 파일인지 시스템 전체인지
여기서 다루는 목표는 모델이 제공받은 도구로 검토 대상 파일을 수정하지 못하게 하는 것입니다. Claude Code 자체가 만드는 실행 기록·캐시까지 없애거나, 프로세스의 모든 파일 접근을 OS 수준에서 차단하는 설정은 아닙니다.
2. 실행 대상과 준비물 확인
설치된 CLI 버전부터 기록하기
이번 실험은 Linux에 설치된 Claude Code 2.1.265에서 실행했습니다. 버전 출력은 실제 실행 결과이며, 현재 최신 버전이라는 뜻은 아닙니다. 기존 로그인 상태를 사용했고 설치·업데이트·전역 권한 설정은 변경하지 않았습니다.
비밀 정보가 없는 작은 폴더 준비
별도 실험 폴더에 sample.txt를 만들고 아래 두 줄만 저장합니다. 운영 저장소나 실제 자격증명 파일을 시험 대상으로 삼지 않습니다. 읽기 권한으로도 파일 내용이 모델에 전달되므로, 쓰기 차단과 정보 유출 방지는 서로 다른 문제입니다.
service=demo
retries=3CLI 로그인과 실행 권한, 읽어도 되는 샘플, 변경 전 내용 기록이 준비물입니다. 작업 폴더 밖에 필요한 문서가 있다면 접근 범위를 따로 검토해야 합니다.
3. 도구·MCP·훅을 제한하는 실행 명령
1단계. 내장 도구는 Read 하나만 제공
--tools는 사용할 내장 도구 목록을 정합니다. 반면 --allowedTools는 일치하는 도구 호출을 별도 승인 없이 실행하도록 허용합니다. 이름이 비슷해도 기능이 다르며, 허용 규칙만으로 Bash·Write·Edit를 목록에서 제거할 수는 없습니다.
2단계. 별도 실행 경로도 닫기
아래 명령은 POSIX 셸 기준입니다. --strict-mcp-config와 빈 서버 목록으로 다른 MCP 구성을 배제하고, --settings에서 훅을 끕니다. --setting-sources ''는 사용자·프로젝트·로컬 설정 소스의 로드를 생략하는 옵션이며, 조직의 managed 정책을 무시하는 수단은 아닙니다.
claude -p \
--tools Read \
--permission-mode dontAsk \
--setting-sources '' \
--strict-mcp-config \
--mcp-config '{"mcpServers":{}}' \
--settings '{"disableAllHooks":true}' \
--disable-slash-commands \
--no-session-persistence \
--max-turns 4 \
--output-format stream-json --verbose \
'Read sample.txt using Read and report its two values. Do not modify anything.'dontAsk는 원래 확인을 요구할 호출을 묻지 않고 거부합니다. 기본적으로 승인이 필요 없는 작업이나 이미 허용된 작업은 실행될 수 있으므로, 이것만으로 읽기 전용이 되지는 않습니다. --disable-slash-commands는 이 실험에서 스킬·명령 확장을 사용하지 않기 위한 설정이고, --no-session-persistence는 대화 저장을 줄이기 위한 별도 옵션입니다.
3단계. 기존 환경과 분리해서 적용하기
실험 명령은 한 번의 실행에만 적용합니다. 기존 settings.json을 통째로 덮어쓰지 않으므로 개인 설정을 복원할 필요가 없습니다. 위 명령은 일반 업무용 권한 프리셋이 아니라, 제한된 파일 읽기 검증에 맞춘 최소 구성입니다.
| 증상 | 가능한 원인 | 확인·해결 |
|---|---|---|
| 다른 도구가 보임 | 옵션 누락·외부 도구 설정 | 시작 이벤트의 tools와 전체 실행 인수 대조 |
| 파일을 못 읽음 | 경로·접근 범위·deny 정책 | 실험 폴더와 파일 존재 여부 확인 |
| 셸이 인수를 잘못 분리함 | 따옴표·줄 이어쓰기 차이 | POSIX 셸에서 실행하거나 해당 셸 문법으로 변환 |
4. 읽기 성공과 수정 불가를 실제로 검증하기
읽기 요청: Read 호출과 파일 값 확인
첫 번째 실행에서는 시작 이벤트의 tools가 ["Read"]였고, 실제 도구 호출도 Read 하나였습니다. 응답은 service=demo와 retries=3을 보고했습니다. 캡처는 이번 실행의 JSON 이벤트를 추출한 요약이며, 긴 실행 인수는 [isolation flags]로 줄여 표시했습니다. 전체 옵션은 앞 절 코드와 같습니다.
수정 요청: 결과 문장 대신 파일 상태 대조
두 번째 실행은 동일 옵션으로 retries=3을 retries=9로 바꾸라고 요청했습니다. 모델은 편집 도구가 없다고 답했으며 도구 호출은 없었습니다. 실행 전후 샘플 파일의 SHA-256을 비교한 결과도 일치했고, 원문은 그대로였습니다.
종료 코드 0은 수정 성공이 아닙니다. 두 실행 모두 종료 코드 0과 subtype: success를 반환했지만, 두 번째는 수정할 수 없다는 답변으로 정상 종료한 것입니다. 자동화에서는 작업별 기대 결과를 별도로 검증해야 합니다.
도해의 마지막 통과 판정은 이처럼 읽기 성공·도구 목록·파일 불변을 함께 확인하는 테스트 안에서 해석해야 합니다. 이번 결과는 샘플 파일과 두 요청에 대한 관측이며, 임의의 저장소·플러그인·취약점까지 안전하다는 보안 검증 결과는 아닙니다.
5. 코드 리뷰 자동화에 적용하는 방법
검토와 수정 작업을 분리하기
검토 단계에서는 결함 위치·근거·수정 제안만 요청합니다. 실제 패치를 적용할 때는 별도 세션과 권한으로 진행하고, 검토 결과를 승인 근거로 활용합니다. 작업 디렉터리까지 분리할 필요가 있다면 Claude Code worktree 사용법: 병렬 작업·정리 가이드의 체크아웃 분리 방식도 참고할 수 있습니다.
후속 처리에 맞춘 응답 검증
리뷰 결과를 시스템에 연결한다면 파일 경로와 문제 위치가 실제 존재하는지 검증해야 합니다. 구조화 응답이 필요할 때는 Claude Code JSON 출력 방법: 스키마 검증·자동화 가이드처럼 출력 형식을 별도로 설계합니다. 응답 형식을 바꾸는 일과 파일 수정 권한을 주는 일은 독립적입니다.
6. 읽기 전용 설정이 기대와 다를 때
권한 규칙의 출처와 우선순위 확인
공식 문서의 권한 규칙 평가 순서는 deny → ask → allow입니다. 좁은 allow를 추가해도 넓은 deny를 뒤집을 수 없습니다. 조직에서 관리하는 정책이 있다면 개인 설정이나 CLI 옵션으로 해제할 수 있다고 가정하지 말고, 대화형 /permissions와 /status에서 출처를 확인합니다.
증상별로 다른 층을 점검하기
| 증상 | 원인 후보 | 해결 방향 |
|---|---|---|
| 승인 대기 없이 요청이 거부됨 | dontAsk의 정상 동작 | 필요 도구와 호출 범위를 검토하되 전체 권한 우회는 사용하지 않기 |
| 허용 규칙을 넣어도 거부됨 | deny·ask 또는 관리 정책 | 규칙 출처와 매칭 대상을 확인 |
| 성공 응답인데 산출물이 없음 | 모델이 한계를 설명하고 종료 | 기대 파일·필드·검증 조건으로 성공 판정 |
| 검토 폴더 밖 정보가 우려됨 | 도구 제한과 데이터 접근 경계의 혼동 | 민감 자료를 제거하고 OS 격리·읽기 전용 마운트 검토 |
7. Plan 모드·deny 규칙·OS 격리 비교
작업 흐름과 강제 경계는 다르게 고르기
| 방식 | 적합한 목적 | 주의점 |
|---|---|---|
| Plan 모드 | 탐색·설계 후 구현 승인 | 읽기용 셸 명령 등을 사용할 수 있어 Read 하나만 제공하는 구성과 다름 |
| --tools Read | 내장 도구를 파일 읽기로 축소 | MCP·훅·프로세스 권한은 별도 고려 |
| permissions.deny | 특정 도구·경로·호출 금지 | 한 도구의 경로 규칙으로 다른 접근 경로까지 막는다고 가정하지 않기 |
| OS 격리·읽기 전용 마운트 | 프로세스의 파일·네트워크 경계 제한 | 환경 구성·마운트·허용 네트워크를 따로 검증 |
지속 설정이 필요하면 적용 범위부터 선택
공식 Settings 문서는 사용자 설정, 공유 프로젝트 설정, 프로젝트 로컬 설정, 관리 설정을 구분합니다. 먼저 일회성 옵션으로 동작을 확인한 뒤 팀에 공유할 규칙만 프로젝트 설정으로 옮기는 접근을 권합니다. 이 권고는 운영 판단이며, 모든 조직에 동일한 설정 파일을 강제하는 공식 규칙은 아닙니다.
8. Q&A와 정리
Q1. Read 도구로 이미지도 검토할 수 있나요?
지원하는 이미지 파일은 Read로 확인할 수 있습니다. 다만 이미지 인식 결과의 정확도까지 권한 설정이 보장하지는 않으므로 작은 글자나 오류 여부는 별도로 검수해야 합니다.
Q2. 파일 검색까지 필요하면 어떻게 하나요?
목적에 따라 --tools Read,Grep,Glob처럼 검색 도구를 추가할 수 있습니다. 이 글의 실제 실험은 Read 하나에 한정했으므로 확장 구성은 같은 방식으로 다시 확인해야 합니다.
Q3. Windows에서도 명령을 그대로 붙이면 되나요?
이 글은 Linux POSIX 셸에서 검증했습니다. PowerShell은 줄 이어쓰기와 JSON 인용 방식이 달라 그대로 실행하기보다 단일 명령 또는 해당 셸에 맞춘 인수 전달로 바꿔야 합니다.
Q4. 테스트를 대신 실행해 달라고 할 수 있나요?
이 구성에는 Bash가 없어 셸 테스트를 직접 실행할 수 없습니다. 테스트 실행은 분리된 CI에서 수행하거나, 테스트 명령이 생성할 파일과 네트워크 접근까지 검토한 별도 실행 환경을 사용합니다.
Q5. 모델이 제안한 수정 명령을 실행하면 되나요?
답변 속 코드는 실행 결과가 아닙니다. 이번 수정 요청에서도 수동 변경 명령이 제안되었지만 실행하지 않았으며, 제안을 채택할 때는 내용을 다시 검토해야 합니다.
검토용 세션의 기본값은 작업 목적에 필요한 최소 도구에서 시작하는 편이 좋습니다. 중요한 저장소로 넓히기 전에 샘플 테스트와 데이터 접근 경계 확인을 먼저 완료하십시오.
9. 참고 자료
- Anthropic — Configure permissions: 도구 권한과 규칙 평가 순서
- Anthropic — CLI reference: --tools·--allowedTools·설정 로딩 옵션
- Anthropic — Settings files and precedence: 설정 적용 범위와 관리 정책
'Claude Code' 카테고리의 다른 글
| Claude Code 서브에이전트 만들기: 위임·호출 검증 (0) | 2026.09.22 |
|---|---|
| Claude Code 스킬 만들기: SKILL.md 작성·호출 검증 (0) | 2026.09.21 |
| Claude Code 비용 제한 설정: 예산·턴·시간 제어법 (0) | 2026.09.12 |
| Claude Code 되돌리기 범위: 체크포인트와 Git 차이 (0) | 2026.09.11 |
| Claude Code 알림 훅 설정: 승인 대기·작업 완료 확인법 (0) | 2026.09.10 |
