설치 경로와 실행 위치가 결정하는 에이전트의 인식 범위

많은 사용자가 Claude Code 설치 후 권한 요청이 반복되거나 이전 결정 사항을 잊어버려 세션을 계속 다시 시작해야 하는 불편함을 겪는다. 이러한 현상은 모델의 지능 한계가 아니라 초기 설정의 부재에서 기인한다. Claude Code는 독립형 명령줄 인터페이스(CLI)로 제공되며, Anthropic은 npm보다 네이티브 설치 프로그램을 통한 설치 경로를 권장한다.

사용자는 `claude` 명령어를 실행하기 전 반드시 `cd` 명령어를 통해 실제 프로젝트 디렉토리로 진입해야 한다. Claude Code는 실행 시점의 디렉토리를 기준으로 프로젝트 메모리와 설정을 범위 지정하므로, 홈 폴더나 데스크톱에서 실행할 경우 작업 중인 코드의 맥락을 전혀 파악하지 못한다. 실행 위치가 곧 에이전트가 인식하는 컨텍스트의 물리적 경계가 된다.

인증 단계에서 사용자는 Claude Pro, Max, Team 구독 계정을 통한 OAuth 로그인 또는 Console 계정의 API 키를 입력하여 권한을 획득한다. 이렇게 구축된 환경은 VS Code 확장 프로그램, JetBrains 플러그인, 데스크톱 앱, claude.ai 웹 버전과 동일한 기본 설정 및 프로젝트 파일을 공유한다. 터미널에서 설정한 모든 내용은 IDE 패널로 그대로 이어지므로 도구 체인 전체에서 일관된 에이전트 경험을 유지할 수 있다.

세션 증발을 막는 .claude 디렉토리와 CLAUDE.md의 계층 구조

Claude Code의 성능과 지속성은 단순 설치가 아니라 `.claude` 디렉토리와 `CLAUDE.md` 파일을 통한 명시적 설정 관리에 의해 결정된다. 도구는 프로젝트 루트의 `.claude/` 디렉토리와 `CLAUDE.md` 파일, 그리고 모든 프로젝트에 공통 적용되는 글로벌 `~/.claude/` 디렉토리라는 두 가지 설정 저장소를 운용한다. 프로젝트별 설정은 특정 저장소에만 종속되며, 전역 설정은 기기 내 모든 프로젝트에 일괄 적용되어 공통 코딩 스타일이나 전역 금지 명령어를 관리하는 데 사용된다.

Claude Code는 컨텍스트 윈도우의 효율성을 높이기 위해 대화 기록을 자동으로 요약하고 줄이는 자동 압축(Automatic Compaction) 기능을 수행한다. 자동 압축이란 긴 세션에서 오래된 대화 내용을 요약하여 토큰 소모를 줄이는 메커니즘이다. 이 과정에서 채팅창에 직접 입력한 세부 규칙이나 라이브러리 사용 제한 지침은 삭제되어 모델이 초기 지침을 잊어버리는 '설정 표류' 현상이 발생한다.

사용자는 세션을 넘어 유지되어야 하는 모든 안정적인 규칙을 `CLAUDE.md` 파일에 기록해야 한다. 파일 시스템에 저장된 규칙은 모델이 매번 읽어들이는 고정 컨텍스트로 작동하여, 자동 압축 과정과 상관없이 영구적인 기준점으로 남는다. 프롬프트 지시 내용을 명시적 파일로 옮기는 습관은 도구를 단순한 챗봇에서 프로젝트의 맥락을 기억하는 에이전트로 전환하는 핵심 레버가 된다.

Shift+Tab 권한 모드와 settings.json의 정밀 제어

반복적인 권한 승인 작업은 실무자의 집중력을 저하시키므로, 권한 모드 전환과 설정 파일의 우선순위를 통해 이를 제거해야 한다. 사용자는 Shift+Tab 키를 눌러 권한 모드를 세 단계로 전환할 수 있다. 모든 명령을 확인하는 Interactive 모드, 일부를 자동화하는 Semi-auto 모드, 모든 명령을 스스로 실행하는 Full-auto 모드가 이에 해당한다.

더 정밀한 제어가 필요한 경우 사용자는 `settings.json` 파일에 명시적인 권한 규칙을 작성한다. 설정 시스템은 allow(무조건 실행), deny(무조건 차단), 미지정(직접 승인) 순의 우선순위를 적용한다. 특히 deny 규칙은 최우선 순위를 가지므로, 광범위한 allow 규칙을 설정했더라도 특정 위험 명령어만 deny로 묶어두면 안전하게 자동화를 구현할 수 있다.

이러한 권한 제어 구조는 사용자가 매번 동일한 안전 명령어를 승인하는 낭비를 없애준다. deny-first 원칙을 통해 파괴적인 명령어에 대한 방어선을 구축하는 동시에, 읽기 권한이나 테스트 실행 권한은 넓게 부여하여 에이전트의 자율성을 확보하는 것이 실무적인 설정 방향이다.

PreToolUse와 PostToolUse 훅을 이용한 자동화 및 안전장치

훅(Hook)은 단순한 허용/차단을 넘어 특정 도구 호출에 반응하여 추가 동작을 실행하는 메커니즘이다. PostToolUse 훅은 Claude가 파일을 수정하거나 작성한 직후에 실행된다. 사용자는 이 훅을 통해 수정된 파일에 대해 Prettier와 같은 포맷팅 도구를 자동으로 실행하도록 설정할 수 있다.

prettier --write $CLAUDE_TOOL_INPUT_FILE_PATH

위 설정은 `$CLAUDE_TOOL_INPUT_FILE_PATH` 환경 변수를 통해 Claude Code가 전달한 파일 경로를 받아 포맷팅을 수행한다. 이를 통해 사용자는 매 수정 후 수동으로 코드를 정리할 필요 없이 일관된 스타일 규칙을 적용할 수 있다.

PreToolUse 훅은 명령어가 실행되기 전 단계에서 위험을 차단하는 더 강력한 안전장치 역할을 한다. Claude Code는 도구 호출 세부 정보를 JSON 형태로 표준 입력(stdin)에 전달하며, 훅 스크립트는 이 텍스트를 검사한다. 만약 `sudo rm`, `recursive force-delete`, `forced push to main`과 같은 파괴적 명령어가 감지되면 스크립트는 종료 코드 2를 반환한다. Claude Code의 훅 시스템은 종료 코드 2를 하드 블록(Hard Block)으로 처리하여 명령어가 실제로 실행되기 전에 즉시 중단시킨다.

지속 가능한 에이전트 워크플로를 위한 판단 기준과 커스텀 스킬

반복 승인 작업의 제거와 안전장치 구축이 완료되었다면, 이제 '다시 시작' 없는 지속 가능한 워크플로를 확보해야 한다. 사용자는 컨텍스트 팽창을 막는 `/compact`, 작업 계획을 수립하는 `/plan`, 변경 사항을 대조하는 `/diff` 세 가지 명령어를 우선적으로 숙달하여 세션 성능 저하와 의도치 않은 코드 수정을 방지해야 한다.

더 나아가 사용자는 `.claude/skills/[skill_name]/SKILL.md` 경로에 파일을 생성하여 사용자 정의 스킬을 추가할 수 있다. 실무에서 유용한 사례는 모델의 주장을 실제 코드베이스와 대조해 검증하는 `/truth` 스킬이다. 이 스킬의 설정 파일은 다음과 같이 구성한다.

markdown

---

name: truth

capabilities: [read_only, git_diff]

---

`/truth` 스킬은 `read_only`와 `git_diff` 권한만 부여받아 검증 과정에서 코드를 수정하는 일을 원천 차단한다. 이는 모델이 정답을 맞추기 위해 코드를 조작하는 자기 확증 편향을 막고, 오직 실제 파일 상태와 git diff만을 근거로 불일치 사항을 보고하게 만든다.

결국 Claude Code의 생산성은 설치 완료 시점이 아니라 승인 버튼을 누르는 횟수를 얼마나 줄였느냐에서 결정된다. PreToolUse 훅으로 위험 명령어를 차단하고 `settings.json`으로 승인 범위를 정밀하게 제어하며, `CLAUDE.md`로 명확한 기억을 부여하는 설정의 디테일이 도구를 단순한 챗봇에서 실무 에이전트로 바꾼다.