Claude Code 첫 작업에서 확인할 것: 편집 승인과 검증 완료의 차이
권한 모드별 범위를 구분하고, 작은 수정의 diff·실행한 검사·미실행 항목을 확인하는 첫 작업 절차를 설명한다.
터미널에서 파일과 명령을 다루는 에이전트
Claude Code CLI는 Anthropic이 개발한 터미널 기반 AI 코딩 에이전트다. 터미널에서 프로젝트 디렉토리에 직접 접근해 코드를 읽고 수정하며 커밋까지 수행한다.
주요 특징
자연어 명령으로 파일 생성·수정·삭제
셸 명령 실행 및 테스트 자동화
CLAUDE.md 파일로 프로젝트 컨텍스트 유지
MCP(Model Context Protocol) 기반 외부 서비스 연동(Jira, Slack, Google Drive 등)
VS Code·JetBrains·Cursor 등 주요 IDE 확장 지원
설치 방법
설치 방식은 Native Install(권장), 패키지 관리자, npm Install을 지원한다. Native 방식은 별도 런타임 없이 curl 등으로 설치하며 자동 업데이트를 지원한다. 공식 설치 문서에 따르면 npm 패키지는 Node.js 22 이상을 요구하며, 설치된 Claude Code 자체는 네이티브 바이너리로 실행된다.
Native 설치
공식 설치 스크립트는 자동 업데이트를 지원한다. Homebrew나 WinGet으로 설치하면 수동으로 업데이트해야 한다.
npm 설치
권한 충돌을 피하려면 npm으로 설치할 때 sudo를 사용하지 않는다.
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
# 설치 확인
claude --version# Homebrew (macOS)
brew install --cask claude-code
# WinGet (Windows)
winget install Anthropic.ClaudeCodenpm install -g @anthropic-ai/claude-code초기 설정 및 로그인
설치 후 터미널에서 claude를 처음 실행하면 대화형으로 계정을 연동하고 기본 설정을 진행한다. 대화형 로그인이나 API 키 환경 변수로 인증하며, 로그인 후 `/status` 명령어로 현재 계정과 인증 상태를 확인한다.
# 방법 1: 대화형 로그인 (claude.ai 계정)
claude auth login
# 방법 2: API 키 직접 설정
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"
# 환경 진단
claude doctor핵심 사용법
프로젝트에서 대화형 작업 시작하기
프로젝트 디렉토리에서 `claude`를 실행해 대화형 모드를 시작하고 자연어로 명령을 입력한다.
Shift+Tab으로 권한 모드 전환하기
Shift+Tab을 누르면 권한 모드가 전환되며, 표시되는 모드는 버전과 계정 설정에 따라 다르다. `Plan`은 소스 파일을 수정하지 않고 탐색과 계획만 수행한다. `acceptEdits`는 파일 편집과 일부 파일시스템 명령을 자동 승인하지만 모든 셸 명령을 허용하지는 않는다. `default`는 필요한 도구 권한을 그때그때 요청한다. `auto`와 `bypassPermissions`는 별도 모드이므로 `acceptEdits`와 구분해야 한다.
cd my-project
claude> 이 프로젝트의 전체 구조를 설명해줘
> auth.js 파일에서 토큰 만료 처리 로직을 추가해줘
> 테스트를 실행하고 실패한 케이스를 수정해줘| 명령어 | 설명 |
|---|---|
| /status | 현재 계정·인증 상태 확인 |
| /memory | 메모리(CLAUDE.md) 관리 |
| /permissions | 허용된 도구 목록 확인 및 편집 |
| /schedule | 클라우드 루틴 생성·관리 (계정별 제공 조건 확인) |
| /loop | 세션을 연 동안 prompt 반복 실행 |
CLAUDE.md에 반복할 프로젝트 지침 남기기
CLAUDE.md는 Claude Code가 세션을 시작할 때마다 읽는 마크다운 지침 파일이다. 코딩 표준, 아키텍처 결정, 선호 라이브러리, 검토 체크리스트 등을 정의해 두면 세션을 시작할 때마다 반복해서 설명할 필요가 없다.
Claude Code는 현재 작업 디렉토리(cwd)부터 루트 디렉토리까지 거슬러 올라가며 발견하는 모든 CLAUDE.md와 CLAUDE.local.md 파일을 재귀적으로 읽어 메모리에 로드한다.
# CLAUDE.md 예시
## 프로젝트 개요
- 기술 스택: React 18 + TypeScript + Tailwind CSS
- 백엔드: Node.js + PostgreSQL
## 코딩 컨벤션
- 함수명은 camelCase, 컴포넌트명은 PascalCase
- 모든 함수에 JSDoc 주석 필수
## 금지 사항
- console.log 프로덕션 코드 사용 금지
- any 타입 사용 금지권한 관리
Claude Code는 파일 수정이나 셸 명령 같은 주요 작업을 처음 실행할 때 사용자에게 허가를 요청한다. 승인 적용 범위는 선택한 옵션과 설정에 따라 달라지며, `settings.json`에 세부 권한을 미리 정의해 둘 수도 있다.
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test:*)",
"Read(~/.zshrc)"
],
"deny": [
"Bash(curl *)"
]
}
}
MCP로 외부 서비스 연동
MCP(Model Context Protocol)는 AI 도구를 외부 데이터 소스에 연결하는 개방형 표준이다. Claude Code에 MCP를 연결하면 Google Drive 설계 문서 읽기, Jira 티켓 업데이트, Slack 데이터 조회 등 외부 작업을 함께 처리할 수 있다.
# JetBrains MCP 연동 예시
claude mcp add jetbrains -- npx -y @jetbrains/mcp-proxy효과적인 사용 팁
작업 범위와 성공 조건을 먼저 정해 실행한 뒤 diff와 테스트 결과를 검토한다. 확인한 결과를 바탕으로 다음 단계를 지시해야 원치 않는 변경이 누적되지 않는다.
세션 시작 체크리스트
git status 확인 (작업 디렉토리 상태 점검)
작업 목표를 1~2문장으로 명확히 정의
산출물 형식 지정 (파일/테스트/문서)
성공 조건 정의 (테스트 통과, 빌드 통과 등)
세션 종료 체크리스트
git diff 검토
테스트 로그 확인
변경 요약 작성
다음 작업 TODO 정리
첫 작업을 “날짜 표시 함수가 빈 값을 받으면 대시를 보여 주게 수정”으로 좁혔다고 하자. 시작하기 전에 현재 변경 파일을 기록하고, 기대 동작에는 빈 값과 정상 날짜를 함께 적어 둔다. 종료 후에는 해당 함수와 이를 사용하는 화면의 diff를 읽고, 실제로 실행한 검사와 결과를 확인한다. 에이전트가 “테스트를 추가했다”고 말한 것과 그 테스트를 실행해 통과한 것은 다르다. 이 예시는 사용 절차를 설명한 것이며 실제 프로젝트를 수정했다는 보고는 아니다.
검사 실행에 필요한 의존성이 없어 실행하지 못했다면 결과는 미실행이다. 소스 수정이 끝났다는 이유로 결과를 통과로 바꾸지 않는다. 실패했다면 이번 수정 때문인지 기존부터 있던 실패인지 근거를 확인하고, 같은 조건에서 다시 실행한 결과를 남긴다. 작은 문구를 변경했을 때는 관련 없는 전체 검사를 반복하기보다 영향받는 화면이나 동작을 확인하는 편이 적절할 수 있다.
파일 편집을 허용하는 모드라도 외부 서비스에 게시하거나 저장소에 푸시하는 권한까지 자동으로 생기는 것은 아니다. 요청 범위와 현재 권한 설정을 함께 확인하고 실제로 수행한 동작을 구분해 보고한다. 프로젝트 지침은 반복되는 선택을 줄이는 자료일 뿐, 실행 결과를 대신하는 증거는 아니다.
첫 작업의 변경과 검사 결과 확인하기
작은 작업부터 시작해 파일 변경과 테스트 결과를 직접 확인한 뒤, 반복되는 프로젝트 규칙을 CLAUDE.md에 남기고 필요한 외부 연동만 추가한다. 생산성은 코드 생성 속도뿐만 아니라 검토·수정 시간까지 포함해 평가해야 한다.
참고 자료
권한 모드와 명령은 공식 권한 문서 (https://code.claude.com/docs/en/permissions (새 창))와 명령 목록 (https://code.claude.com/docs/en/commands (새 창))을 기준으로 2026-09-22에 재확인했다.
Claude Code 시작하기 — Anthropic (https://code.claude.com/docs/en/quickstart (새 창))
Claude Code CLI 레퍼런스 — Anthropic (https://code.claude.com/docs/en/cli-reference (새 창))
Claude Code의 작업 흐름 — 공식 문서 (https://code.claude.com/docs/en/how-claude-code-works (새 창))