Claude Code Core Concepts
Claude Code 작동 방식: 에이전트 루프부터 컨텍스트·권한·체크포인트까지
모델이 판단하고 도구가 행동하며, 결과가 다시 다음 판단이 되는 구조를 공식 문서 기준으로 해부합니다.
안녕하세요. SCV입니다.
Claude Code에 “로그인 버그를 고쳐 줘”라고 입력하면 뒤에서 무슨 일이 벌어질까요? 단순히 답변 한 번을 생성해 코드 조각을 보여 주는 것이 아닙니다. Claude Code는 프로젝트 파일을 찾고, 관련 코드를 읽고, 명령을 실행하고, 수정한 뒤 테스트 결과를 다시 읽습니다. 그리고 결과가 기대와 다르면 다음 행동을 바꿉니다. 핵심은 한 번의 답변이 아니라 관찰과 행동이 이어지는 에이전트 루프입니다.
이 반복 구조를 이해하면 결과가 좋은 이유뿐 아니라 실패를 어디서 바로잡아야 하는지도 선명해집니다.
공식 문서가 설명하는 Claude Code는 터미널에서 실행되는 에이전트 어시스턴트입니다. 코딩이 주특기지만 명령줄에서 가능한 문서 작성, 빌드, 파일 검색, Git 작업, 조사도 수행할 수 있습니다. 이번 글에서는 마케팅 문구보다 실제 작동 구조를 중심으로 살펴봅니다. 모델과 도구가 어떻게 역할을 나누는지, 무엇을 볼 수 있는지, 세션과 컨텍스트가 왜 다른지, 체크포인트와 권한이 각각 무엇을 보호하는지까지 연결해 보겠습니다.
1. 한 문장으로 이해하기: 모델이 판단하고 도구가 행동한다
Claude Code는 Claude 모델을 둘러싼 에이전트 하네스라고 이해하면 쉽습니다. 모델은 코드를 읽고 문제를 추론하며 다음 행동을 결정합니다. 하네스는 파일 읽기와 편집, 검색, 셸 실행, 웹 접근, 컨텍스트 관리, 권한 확인 같은 실행 수단과 환경을 제공합니다. 모델만 있다면 텍스트 답변에서 끝나지만 도구가 결합되면 실제 프로젝트에 변화를 만들 수 있습니다.
여기서 중요한 점은 도구 사용 결과가 다시 모델의 입력으로 돌아간다는 것입니다. 테스트 명령이 실패하면 종료 코드와 오류 출력이 다음 판단의 근거가 됩니다. 검색 결과가 예상보다 넓으면 더 구체적인 패턴으로 다시 검색할 수 있습니다. 파일을 읽었는데 원인이 다른 모듈에 있다면 탐색 범위를 바꿉니다. 따라서 Claude Code의 품질은 첫 답변의 화려함보다 올바른 증거를 모으고 결과를 검증하는 루프에서 나옵니다.
2. 핵심 엔진: 컨텍스트 수집 → 작업 수행 → 결과 검증
컨텍스트 수집
작업 수행
결과 검증
아니면 다시 수집
공식 문서는 에이전트 루프를 3단계로 설명합니다. 첫째, 컨텍스트 수집입니다. Claude는 요청과 관련된 파일, 코드 패턴, 설정, Git 상태, 프로젝트 지침을 확인합니다. 둘째, 작업 수행입니다. 파일을 편집하거나 명령을 실행하고 필요한 산출물을 만듭니다. 셋째, 결과 검증입니다. 테스트, 타입 검사, 린트, 빌드 또는 화면 비교를 통해 변경이 실제 목표를 만족하는지 확인합니다.
이 단계는 딱 한 번씩 순서대로 지나가는 고정 파이프라인이 아닙니다. 검증에서 실패하면 다시 컨텍스트를 수집하고, 수정하고, 재검증합니다. 질문처럼 읽기만 필요한 작업은 첫 단계에서 끝날 수 있습니다. 작은 오타 수정은 짧은 루프로 끝납니다. 반면 여러 모듈이 얽힌 리팩터링은 검색과 편집, 테스트를 수십 번 연결할 수 있습니다. 요청의 종류와 중간 결과에 따라 루프의 길이와 모양이 달라집니다.
사용자도 루프 밖의 관찰자가 아니라 구성원입니다. 실행 중 Esc를 눌러 멈추거나, 추가 지시를 입력해 다음 판단에 반영할 수 있습니다. “그 파일이 아니라 세션 처리부터 봐 줘”라고 방향을 바꾸면 지금까지 모은 컨텍스트를 활용하면서 접근법을 수정합니다. 처음부터 완벽한 프롬프트를 만들려고 애쓰기보다 목표와 제약을 제시하고 중간 결과를 조정하는 대화형 방식이 자연스럽습니다.
3. 예시: 실패한 테스트를 수정할 때 내부에서 벌어지는 일
“실패한 테스트를 수정해”라는 요청을 예로 들어 보겠습니다. Claude Code는 먼저 테스트 스위트를 실행해 어떤 테스트가 실패하는지 확인할 수 있습니다. 이어 오류 출력과 스택 추적을 읽고, 관련 심볼이나 파일명을 검색합니다. 소스와 테스트를 함께 읽어 기대 동작을 파악한 뒤 파일을 편집합니다. 마지막으로 같은 테스트를 다시 실행하고 필요하면 더 넓은 테스트나 빌드까지 수행합니다.
이 흐름에서 각 단계의 출력은 다음 단계의 입력입니다. 테스트 이름은 검색어가 되고, 검색 결과는 읽을 파일을 좁히며, 코드 구조는 편집 위치를 결정합니다. 재실행 결과가 성공하면 완료 근거가 됩니다. 실패한다면 새 오류가 추가 컨텍스트가 됩니다. 그래서 “코드부터 무조건 바꿔”라고 세세한 명령을 나열하는 것보다, 문제와 성공 조건을 알려 주고 조사와 검증을 위임하는 편이 에이전트의 장점을 살리기 좋습니다.
좋은 요청에는 재현 조건과 검증 기준이 있습니다. 예를 들어 “만료된 카드로 결제할 때 세션 갱신이 실패한다. src/payments를 조사하고, 먼저 실패 테스트를 추가한 다음 수정해 줘”라고 말하면 탐색 범위와 성공 기준이 함께 전달됩니다. UI 작업이라면 기대 화면 캡처를 제공하고, 함수 작업이라면 입력과 예상 출력을 제시하는 방식이 좋습니다.
실전 NLP 예시: 자연어 입력이 실행 결과로 바뀌는 흐름
Mermaid 원본 코드 보기
flowchart TD
U["사용자 자연어 입력<br/>500 오류 수정·회귀 테스트·스키마 변경 금지"] --> I["목표·제약·성공 조건 해석"]
I --> C["CLAUDE.md·Git 상태·자동 메모리 확인"]
C --> S["src/auth 검색 및 관련 파일 읽기"]
S --> Q{"원인 판단에 필요한<br/>컨텍스트가 충분한가?"}
Q -- "아니요" --> S
Q -- "예" --> P["수정 계획 수립·권한 확인"]
P --> T["실패 테스트 실행·오류 재현"]
T --> E["코드 편집·회귀 테스트 추가"]
E --> V["테스트·타입 검사로 검증"]
V --> R{"성공 조건을<br/>만족하는가?"}
R -- "아니요" --> A["오류 출력 분석"]
A --> S
R -- "예" --> O["변경 파일·검증 결과 보고"]
O --> F{"사용자의 추가 지시가<br/>있는가?"}
F -- "예" --> I
F -- "아니요" --> D["작업 완료"]
classDef input fill:#f5f5f7,stroke:#7a7a7a,color:#1d1d1f
classDef reasoning fill:#eaf3ff,stroke:#0066cc,color:#1d1d1f
classDef action fill:#272729,stroke:#272729,color:#ffffff
classDef decision fill:#ffffff,stroke:#0066cc,color:#1d1d1f
class U,C input
class I,S,A reasoning
class P,T,E,V,O,D action
class Q,R,F decision예시 입력을 하나 넣어 보겠습니다. “로그인 API가 만료된 액세스 토큰을 받으면 500 오류가 납니다. src/auth를 조사하고 회귀 테스트를 추가한 뒤 수정해 주세요. 데이터베이스 스키마는 변경하지 마세요.” 이 한 문장에는 목표, 재현 조건, 탐색 범위, 검증 기준, 금지 조건이 함께 들어 있습니다.
Claude Code는 이를 전통적인 규칙 기반 NLP처럼 고정된 의도 분류표에 한 번 넣고 끝내지 않습니다. 모델이 현재 대화와 프로젝트 지침을 함께 보고 목표와 제약을 해석합니다. 이어 CLAUDE.md와 Git 상태를 확인하고, 검색과 파일 읽기로 실제 인증 흐름을 찾습니다. 컨텍스트가 부족하면 검색 범위를 조정하며 탐색을 반복합니다.
원인을 추정한 뒤에는 권한 범위 안에서 실패 테스트를 실행하거나 새 회귀 테스트를 추가하고 코드를 수정합니다. 테스트와 타입 검사 결과가 성공 조건을 만족하면 변경 파일과 검증 결과를 요약합니다. 실패하면 오류 출력을 새 컨텍스트로 받아 원인 분석 단계로 돌아갑니다. 사용자가 중간에 “토큰 검증 라이브러리는 바꾸지 마세요”라고 추가하면 그 제약도 다음 판단에 반영됩니다.
아래 Mermaid 흐름도에서 파란 노드는 모델의 판단, 회색 노드는 프로젝트에서 얻는 컨텍스트, 검은 노드는 도구가 수행하는 행동을 뜻합니다. 마름모는 다음 단계로 진행할지, 다시 탐색하거나 수정할지를 결정하는 검증 지점입니다. 자연어 입력이 즉시 코드 변경으로 직행하는 것이 아니라 해석, 탐색, 승인, 실행, 검증을 거친다는 점이 핵심입니다.
4. Claude Code가 사용하는 도구 5가지
공식 문서가 분류한 기본 도구는 파일 작업, 검색, 실행, 웹, 코드 인텔리전스의 5가지입니다. 파일 작업은 읽기, 편집, 생성, 이름 변경과 구조 조정을 담당합니다. 검색은 파일명 패턴과 정규식으로 코드베이스를 탐색합니다. 실행은 셸 명령, 테스트, 서버, Git, 패키지 관리자를 다룹니다. 웹 도구는 문서를 가져오고 오류 메시지나 기술 정보를 조사합니다. 코드 인텔리전스는 플러그인이 있을 때 타입 오류, 정의, 참조 관계를 더 정밀하게 확인합니다.
여기에 질문, 서브에이전트 생성, 기타 오케스트레이션 도구도 더해질 수 있습니다. Skills는 특정 작업 절차와 지식을 필요할 때 불러오고, MCP는 외부 서비스와 데이터를 연결하며, hooks는 정해진 시점의 워크플로를 자동화합니다. Subagents는 독립된 컨텍스트에서 하위 작업을 수행하고 요약을 돌려줍니다. 확장 기능은 별도의 두뇌라기보다 같은 에이전트 루프가 사용할 수 있는 지식과 행동 범위를 늘리는 계층입니다.
도구가 많다고 항상 모두 사용하는 것은 아닙니다. 모델은 요청과 중간 결과에 맞춰 필요한 도구를 선택합니다. 단순 설명에 파일 편집은 필요하지 않고, 코드 수정에 웹 검색이 필요하지 않을 수도 있습니다. 반대로 최신 API를 사용하는 구현이라면 공식 문서를 먼저 확인하는 것이 안전합니다. 사용자는 특정 명령을 일일이 지정하기보다 접근 가능한 자료, 금지할 행동, 완료 조건을 분명하게 정하는 편이 효율적입니다.
5. 시작 디렉터리가 작업 세계의 기준점이다
터미널에서 claude를 실행하면 현재 디렉터리와 하위 디렉터리의 프로젝트 파일이 기본 작업 범위가 됩니다. 허가받은 다른 위치도 접근할 수 있습니다. Claude는 터미널 명령과 현재 Git 브랜치, 커밋되지 않은 변경, 최근 커밋 기록을 확인할 수 있습니다. 따라서 실행 전에 올바른 저장소와 브랜치에 있는지 확인하는 습관이 중요합니다.
프로젝트별 지침은 CLAUDE.md에 저장할 수 있습니다. 코딩 규칙, 테스트 명령, 건드리면 안 되는 경로, 리뷰 기준처럼 매 세션에 필요한 지속 규칙을 대화 속에 반복하지 않아도 됩니다. 자동 메모리는 작업 중 학습한 프로젝트 패턴과 사용자 선호를 세션 사이에 이어 주는 역할을 합니다. 공식 문서 기준으로 MEMORY.md의 처음 200줄 또는 25KB 중 먼저 도달하는 범위가 세션 시작 시 로드됩니다.
현재 파일 하나만 바라보는 인라인 자동 완성과 차이는 여기서 커집니다. Claude Code는 프로젝트 전체를 검색하고 여러 파일의 연결 관계를 이해한 뒤 조정된 편집과 테스트를 수행할 수 있습니다. 다만 넓은 접근 범위는 강력함과 위험을 동시에 늘립니다. 저장소 루트에서 시작하고, 중요한 변경 전 Git 상태를 확인하며, 외부 시스템에 영향을 주는 명령은 별도로 검토해야 합니다.
6. 실행 환경과 인터페이스를 구분해야 한다
| 환경 | 실행 위치 | 적합한 상황 |
|---|---|---|
| 로컬 | 사용자 머신 | 현재 파일·도구·환경에 직접 접근 |
| 클라우드 | Anthropic 관리 VM | 작업 오프로드, 원격 저장소 작업 |
| 원격 제어 | 사용자 머신 | 브라우저 UI를 쓰면서 실행은 로컬 유지 |
Claude Code의 핵심 루프는 여러 인터페이스에서 같지만 코드가 실행되는 장소는 다를 수 있습니다. 로컬 환경은 사용자 머신에서 실행되어 파일과 도구, 환경에 직접 접근합니다. 클라우드 환경은 Anthropic이 관리하는 VM에 작업을 맡기며, 로컬에 없는 저장소 작업이나 오프로드에 적합합니다. 원격 제어는 브라우저 UI로 조작하되 실제 코드는 사용자 머신에서 실행됩니다.
터미널, 데스크톱 앱, IDE 확장, claude.ai/code, 원격 제어, Slack, CI/CD는 상호작용 창구입니다. 인터페이스가 달라져도 모델이 컨텍스트를 모으고 도구로 행동하며 결과를 검증하는 기본 구조는 유지됩니다. 보안이나 재현성을 판단할 때는 화면 모양보다 “명령이 어느 머신에서 실행되고 어떤 자격 증명과 파일을 볼 수 있는가”를 먼저 확인해야 합니다.
7. 세션, Git 브랜치, 컨텍스트 윈도우는 서로 다르다
Claude Code는 대화의 메시지, 도구 사용, 결과를 로컬의 ~/.claude/projects/ 아래 JSONL 파일로 기록합니다. 이 기록 덕분에 대화를 재개하거나 포크할 수 있습니다. claude --continue 또는 claude --resume은 같은 세션 ID를 이어 사용합니다. --fork-session이나 /branch는 기록을 새 세션 ID로 복사해 원본을 그대로 둔 채 다른 방향을 실험하게 합니다.
세션은 현재 디렉터리에 연결되지만 Git 브랜치 자체와 동일하지는 않습니다. 대화 도중 브랜치를 바꾸면 Claude가 보는 파일은 새 브랜치의 상태로 바뀌지만 대화 기록은 이어집니다. 병렬 작업이 필요하면 Git worktree로 서로 다른 디렉터리와 브랜치를 만든 뒤 각각 별도 세션을 실행하는 방식이 충돌을 줄입니다.
컨텍스트 윈도우는 현재 모델이 한 번에 참고할 수 있는 작업 기억입니다. 대화 기록, 읽은 파일, 명령 출력, CLAUDE.md, 자동 메모리, 로드된 Skills, 시스템 지침이 공간을 함께 사용합니다. 세션 파일이 디스크에 남는다고 해서 모든 과거 내용이 언제나 모델의 활성 컨텍스트에 그대로 들어 있는 것은 아닙니다. 세션은 기록 단위이고, 컨텍스트 윈도우는 현재 추론에 사용할 수 있는 제한된 공간입니다.
8. 컨텍스트가 차면 무엇이 사라질까
작업이 길어지면 Claude Code는 먼저 오래된 도구 출력을 지우고, 필요하면 대화를 요약해 컨텍스트를 압축합니다. 요청과 핵심 코드 조각은 유지하려 하지만 초반의 세부 지침은 약해질 수 있습니다. 반드시 지켜야 할 지속 규칙을 대화 초반 한 번만 말하기보다 CLAUDE.md에 기록해야 하는 이유입니다./context를 실행하면 무엇이 공간을 차지하는지 살펴볼 수 있고, /compact에 초점을 붙여 요약 방향을 지정할 수 있습니다. 예를 들어 “/compact focus on the API changes”처럼 핵심 주제를 보존하도록 요청할 수 있습니다. MCP 도구 정의는 기본적으로 지연 로드되어 실제 필요할 때까지 이름 정도만 컨텍스트를 사용합니다. Skills도 요청 시 전체 내용이 로드됩니다.Subagents는 주 대화와 분리된 새 컨텍스트를 사용합니다. 긴 조사나 독립적인 분석을 맡겨도 주 세션의 컨텍스트를 같은 정도로 부풀리지 않고, 완료 후 요약만 돌려받을 수 있습니다. 다만 분리된 작업자가 자동으로 모든 암묵적 배경을 아는 것은 아닙니다. 하위 작업의 목표, 입력, 결과 형식을 명확히 전달해야 합니다.
9. 체크포인트와 권한은 해결하는 문제가 다르다
Claude Code에는 체크포인트와 권한이라는 2가지 안전 장치가 있습니다. 체크포인트는 파일 편집 전 내용을 스냅샷해 변경을 되돌릴 수 있게 합니다. 문제가 생기면 Esc를 2번 눌러 이전 상태로 돌아가거나 Claude에게 취소를 요청할 수 있습니다. Git과 별도의 장치이며 세션을 재개해도 사용할 수 있습니다.
그러나 체크포인트는 파일 변경만 다룹니다. 데이터베이스 쓰기, API 호출, 메시지 발송, 배포처럼 외부 시스템에 이미 발생한 부작용은 되돌리지 못합니다. 로컬 파일을 되돌릴 수 있다는 사실을 전체 작업의 만능 복구 기능으로 오해하면 안 됩니다. 외부 부작용이 있는 명령은 실행 전에 목적과 대상, 롤백 방법을 확인해야 합니다.
권한은 Claude가 사용자 확인 없이 할 수 있는 행동을 제어합니다. Shift+Tab으로 기본값, 자동 수락 편집, Plan, Auto 모드를 순환할 수 있습니다. 기본값은 파일 편집과 셸 명령 전에 묻고, 자동 수락 편집은 일반적인 파일 편집과 일부 파일 시스템 명령을 허용합니다. Plan은 소스 파일을 바꾸지 않고 탐색과 계획에 집중합니다. Auto는 백그라운드 안전 검사로 모든 작업을 평가합니다..claude/settings.json에서 npm test나 git status처럼 신뢰하는 명령을 허용하면 반복 승인을 줄일 수 있습니다. 중요한 원칙은 편의 때문에 광범위한 명령을 한꺼번에 허용하지 않는 것입니다. 자주 쓰고 영향 범위를 이해하는 읽기·검증 명령부터 좁게 허용하는 편이 좋습니다.
10. 더 잘 쓰는 법: 명령 목록보다 목표와 검증 기준
Claude Code는 대화형이므로 완벽한 첫 프롬프트가 필수는 아닙니다. 하지만 특정 파일, 재현 조건, 제약, 기대 결과를 제시하면 수정 횟수가 줄어듭니다. “로그인 버그를 고쳐 줘”보다 “토큰 만료 후 새로고침이 실패한다. src/auth를 조사하고 회귀 테스트를 추가한 뒤 전체 인증 테스트를 실행해 줘”가 훨씬 검증 가능합니다.
복잡한 작업은 구현 전에 탐색을 분리하는 편이 좋습니다. Plan 모드에서 관련 구조와 위험을 분석하고, 계획을 검토한 다음 구현으로 넘어가면 잘못된 가정에 기반한 대규모 편집을 줄일 수 있습니다. 시각 작업은 기대 화면을 제공하고, 데이터 변환은 입력과 예상 출력 예시를 제공하며, API 변경은 공식 문서 링크와 지원 버전을 알려 주는 방식으로 검증 가능성을 높일 수 있습니다.
세세한 도구 호출을 모두 지시하기보다 능력 있는 동료에게 위임하듯 문제, 맥락, 경계, 완료 조건을 전달해 보세요. Claude가 어떤 파일을 읽고 어떤 명령을 실행할지는 중간 증거에 따라 달라질 수 있습니다. 대신 “관련 없는 사용자 변경은 보존할 것”, “프로덕션 배포는 하지 말 것”, “테스트 결과를 보고할 것”처럼 행동의 경계는 명확해야 합니다.
11. 모델 선택은 루프의 판단 특성을 바꾼다
Claude Code는 여러 Claude 모델을 사용할 수 있습니다. 공식 문서는 Sonnet을 대부분의 코딩 작업에 적합한 선택으로, Opus를 복잡한 아키텍처 판단에 더 강한 선택으로 설명합니다. 세션 중 /model로 전환하거나 claude --model <name>으로 시작할 수 있습니다. 여기서 모델을 바꾼다고 파일 시스템이나 셸 같은 도구가 달라지는 것은 아닙니다. 같은 도구와 환경을 두고 어떤 증거를 중요하게 보고, 문제를 어떻게 나누며, 다음 행동을 무엇으로 선택하는지에 영향을 줍니다.
작고 명확한 수정에는 빠른 모델로 충분할 수 있습니다. 반면 요구 사항이 충돌하거나 여러 서비스의 경계를 다시 설계해야 하는 작업은 더 깊은 추론이 유리합니다. 그렇다고 강한 모델이 검증을 대신하지는 않습니다. 모델 선택은 판단 능력의 차이이고, 테스트와 빌드, 실제 출력 확인은 여전히 필요합니다. 비용과 속도, 문제 복잡도를 함께 보고 선택해야 합니다.
“Claude가 결정한다”는 표현도 정확히 이해할 필요가 있습니다. 제품이 숨겨진 규칙으로 임의 행동을 정한다는 뜻이라기보다, 현재 프롬프트와 컨텍스트, 도구 결과를 바탕으로 모델이 다음 행동을 추론한다는 뜻입니다. 좋은 컨텍스트와 명확한 경계가 없으면 강한 모델도 엉뚱한 목표를 최적화할 수 있습니다.
12. 잘못된 루프는 어떻게 생기는가
에이전트 루프는 자동으로 반복된다는 이유만으로 항상 올바른 방향으로 수렴하지 않습니다. 첫 번째 위험은 잘못된 성공 기준입니다. 테스트가 통과해도 사용자가 원한 동작을 검사하지 않는 테스트라면 잘못된 구현이 성공으로 판정될 수 있습니다. 두 번째 위험은 불완전한 탐색입니다. 이름이 비슷한 파일만 읽고 실제 진입점이나 설정을 놓치면 국소 수정으로 증상만 가릴 수 있습니다.
세 번째는 지나치게 큰 도구 출력입니다. 방대한 로그나 생성 파일을 그대로 읽으면 중요한 오류가 묻히고 컨텍스트 공간을 빠르게 사용합니다. 이때 실패 테스트 하나, 오류 전후 로그, 변경된 파일처럼 정보를 좁히는 편이 좋습니다. 네 번째는 검증 없는 완료입니다. 편집은 성공했지만 테스트를 실행하지 않았거나, 실행 환경이 없어 검증하지 못했다면 “수정 완료”와 “수정안 작성”을 구분해서 보고해야 합니다.
다섯 번째는 루프 자체의 반복 정체입니다. 같은 명령이 같은 이유로 계속 실패하면 반복 횟수보다 가정 변경이 필요합니다. 의존성 설치 상태, 환경 변수, 실행 경로, 테스트 데이터 같은 전제를 다시 확인해야 합니다. 사용자는 중간 보고에서 실행한 명령과 관찰한 결과, 아직 검증하지 못한 부분을 요청하면 루프가 실제 증거에 기대고 있는지 판단하기 쉬워집니다.
13. 읽기, 쓰기, 외부 부작용을 나눠 생각하기
Claude Code의 행동을 위험도에 따라 세 층으로 나누면 권한 설정이 쉬워집니다. 읽기 층은 파일 보기, 검색, Git 상태 확인, 문서 조회처럼 대체로 상태를 바꾸지 않는 작업입니다. 쓰기 층은 소스 편집, 파일 생성, 이름 변경처럼 로컬 작업 트리를 바꾸지만 체크포인트나 Git으로 검토하고 되돌릴 수 있는 작업입니다. 외부 부작용 층은 배포, 데이터베이스 갱신, 패키지 게시, 원격 브랜치 푸시, 이메일이나 메시지 발송처럼 다른 사람과 시스템에 영향을 주는 작업입니다.
이 구분은 “명령이 짧은가”와 무관합니다. 한 줄짜리 배포 명령이 수백 줄 편집보다 위험할 수 있습니다. 반대로 긴 테스트 명령은 계산 자원을 쓰지만 데이터 변경이 없다면 상대적으로 검토하기 쉽습니다. 권한을 설계할 때 명령 문자열만 보지 말고 대상 시스템, 사용 자격 증명, 되돌릴 방법, 다른 사용자에게 미치는 영향을 함께 봐야 합니다.
체크포인트는 주로 쓰기 층의 파일 변경을 다룹니다. 권한은 각 층으로 넘어갈 때 사용자 확인이 필요한지를 통제합니다. Git은 변경 이력과 협업 검토를 담당합니다. 세 장치는 겹치는 부분이 있지만 서로 대체 관계가 아닙니다. 특히 프로덕션 데이터와 외부 서비스는 별도의 승인, 백업, 롤백 절차가 필요합니다.
14. CLAUDE.md에는 무엇을 넣어야 할까
CLAUDE.md는 긴 제품 설명서를 그대로 복사해 넣는 장소가 아닙니다. Claude가 작업할 때 반복적으로 판단에 써야 하는 짧고 구체적인 규칙이 적합합니다. 저장소의 목적과 주요 디렉터리, 표준 빌드·테스트 명령, 코드 스타일에서 중요한 예외, 생성 파일과 수정 금지 경로, 보안상 지켜야 할 규칙, 완료 전 반드시 실행할 검증을 우선 기록하세요.
예를 들어 “패키지 관리자는 pnpm만 사용”, “src/generated는 직접 수정하지 말고 생성 명령 실행”, “데이터베이스 마이그레이션은 이전 버전과 호환”, “사용자 변경을 덮어쓰지 말 것”처럼 행동으로 판별할 수 있는 문장이 좋습니다. “깔끔하게 작성”이나 “최선을 다하기”처럼 검증하기 어려운 문구는 컨텍스트만 차지하고 판단 기준으로 쓰기 어렵습니다.
규칙이 너무 길어지면 중요한 항목이 묻힙니다. 조직 전체 규칙, 저장소 규칙, 하위 디렉터리 규칙의 범위를 나누고 서로 충돌하지 않게 관리해야 합니다. 자주 바뀌는 일회성 요구는 현재 프롬프트에, 매 작업에 적용되는 안정적인 원칙은 CLAUDE.md에 두는 구분이 유용합니다. 긴 세션에서 압축이 일어나도 지속 규칙을 다시 불러올 수 있다는 점이 가장 큰 장점입니다.
15. 작업 유형별로 달라지는 검증 방법
에이전트 루프의 마지막 단계인 검증은 작업마다 모양이 다릅니다. 순수 함수 수정은 단위 테스트와 경계값 테스트가 핵심입니다. 여러 모듈을 연결하는 기능은 통합 테스트와 타입 검사, 빌드를 함께 봐야 합니다. UI 구현은 코드가 컴파일되는 것만으로 충분하지 않습니다. 실제 브라우저에서 렌더링하고 기대 화면과 레이아웃, 반응형 동작, 콘솔 오류를 확인해야 합니다.
문서 작업은 링크 유효성, 명령 정확성, 버전과 날짜, 독자가 그대로 따라 했을 때의 재현성을 검증합니다. 데이터 변환은 입력 건수와 출력 건수, 누락과 중복, 합계 같은 불변 조건을 확인해야 합니다. 성능 개선은 “코드가 더 빨라 보인다”가 아니라 동일한 환경의 기준 측정과 변경 후 측정을 비교해야 합니다. 보안 수정은 알려진 공격 경로가 막혔는지와 정상 사용 흐름이 유지되는지를 함께 봅니다.
따라서 프롬프트에 “검증해 줘”라고만 적기보다 어떤 증거를 완료로 인정할지 말해 주면 좋습니다. “관련 단위 테스트와 전체 타입 검사를 실행”, “모바일 360px과 데스크톱 1440px 화면 캡처 비교”, “마이그레이션 전후 레코드 수와 합계 일치 확인”처럼 결과를 관찰할 수 있는 기준이 에이전트 루프의 종료 조건이 됩니다.
16. 세션을 재개할지 포크할지 결정하는 기준
같은 목표를 이어서 다듬는다면 세션 재개가 자연스럽습니다. 기존 조사와 결정, 실패 기록을 활용할 수 있기 때문입니다. 반면 서로 다른 설계안을 독립적으로 비교하거나 위험한 실험을 원본 대화와 분리하고 싶다면 포크가 유용합니다. 포크는 대화 기록을 복사하지만 새 세션 ID를 사용하므로 이후 메시지가 원본에 섞이지 않습니다.Git 브랜치까지 분리해야 하는지는 파일 충돌 가능성으로 판단합니다. 읽기 전용 분석 2개는 같은 작업 디렉터리에서도 가능하지만, 양쪽이 동시에 파일을 편집하면 서로의 변경을 예상하지 못할 수 있습니다. 독립적인 구현을 병렬로 진행하려면 Git worktree로 별도 디렉터리를 만들고 각 디렉터리에서 세션을 실행하는 편이 안전합니다.
세션을 많이 나누면 컨텍스트가 깔끔해지는 대신 결정 사항을 전달해야 합니다. 공통 요구와 완료 기준을 각 세션에 명시하고, 최종 통합 시 어떤 가정이 달랐는지 비교해야 합니다. 세션 분리는 자동 협업 기능이 아니라 작업 기억과 파일 환경을 조직하는 방법입니다.
17. 자주 혼동하는 용어를 한 번에 정리하기
모델은 현재 컨텍스트를 바탕으로 코드를 이해하고 다음 행동을 추론하는 부분입니다. 도구는 파일, 셸, 웹, 외부 서비스에 실제로 접근하는 수단입니다. 에이전트 루프는 모델의 판단과 도구의 결과가 반복해서 연결되는 과정입니다. 하네스는 이 둘을 감싸며 권한, 컨텍스트, 실행 환경과 사용자 상호작용을 관리하는 제품 구조를 뜻합니다.
세션은 대화와 도구 사용 기록을 이어 가는 단위입니다. 컨텍스트 윈도우는 그중 현재 추론에 실제로 들어가는 제한된 작업 공간입니다. 자동 메모리는 세션 사이에 프로젝트 패턴과 선호를 이어 주며, CLAUDE.md는 사용자가 명시적으로 관리하는 지속 지침입니다. 체크포인트는 파일 편집의 이전 상태를 보관하고, Git은 변경 이력과 브랜치, 협업을 관리합니다.Skill은 특정 작업에 필요한 절차와 지식을 필요할 때 불러오는 묶음입니다. MCP는 데이터베이스, 이슈 추적기, 디자인 도구 같은 외부 시스템을 표준 방식으로 연결합니다. Hook은 특정 이벤트 전후에 정해진 명령이나 검사를 실행합니다. Subagent는 별도 컨텍스트에서 하위 작업을 수행합니다. 이 기능들은 에이전트 루프를 없애는 것이 아니라 루프가 사용할 수 있는 전문 지식, 연결, 자동화, 작업 분담을 확장합니다.
마지막으로 인터페이스와 실행 환경도 구분해야 합니다. 터미널이나 IDE, 웹 화면은 사용자가 Claude Code와 대화하는 통로입니다. 로컬 머신, Anthropic 관리 VM, 원격 제어 대상 머신은 명령과 코드가 실제로 실행되는 장소입니다. 같은 화면처럼 보여도 실행 위치에 따라 접근 가능한 파일과 자격 증명, 네트워크, 보안 책임이 달라질 수 있습니다.
이 용어들을 분리해 두면 문제를 진단하기도 쉬워집니다. 과거 대화가 보이는데 세부 내용을 놓친다면 세션 기록보다 컨텍스트 압축을 의심해야 합니다. 명령이 실행되지 않는다면 모델 능력보다 권한과 실행 환경을 먼저 확인합니다. 파일은 되돌렸는데 원격 배포가 남아 있다면 체크포인트의 적용 범위를 잘못 이해한 것입니다. 기능 이름을 외우는 것보다 각 기능이 어떤 상태를 저장하고, 어디에서 실행되며, 무엇을 되돌릴 수 있는지 꼭 질문하는 습관이 중요합니다.
18. 실전 체크리스트
작업 전에는 현재 저장소와 브랜치, Git 상태를 확인합니다. 지속 규칙은 CLAUDE.md에 둡니다. 외부 시스템 접근과 자격 증명의 범위를 점검합니다. 복잡한 변경은 Plan 모드로 구조를 먼저 탐색합니다.
요청할 때는 문제와 재현 조건, 관련 경로, 바꾸면 안 되는 범위, 성공 조건을 적습니다. 가능하면 테스트 케이스나 기대 화면을 제공합니다. 조사와 구현을 분리할지 결정합니다.
작업 중에는 테스트와 명령 출력이 다음 판단에 제대로 반영되는지 봅니다. 방향이 틀리면 Esc로 멈추거나 추가 지시로 조정합니다. 컨텍스트가 길어지면 /context를 확인하고, 중요한 규칙이 대화 기록에만 남아 있지 않은지 점검합니다.
완료 후에는 변경 파일과 테스트 결과를 확인합니다. 체크포인트가 복구하는 범위와 외부 부작용을 구분합니다. 커밋이나 배포는 사용자가 의도한 범위에서만 수행합니다. 결국 좋은 결과는 에이전트에게 더 많은 자유를 주는 것만으로 나오지 않습니다. 충분한 맥락, 좁고 명확한 경계, 검증 가능한 성공 기준이 함께 있어야 합니다.
마무리
Claude Code의 본질은 “코드를 써 주는 챗봇”보다 “도구를 사용하며 증거에 따라 다음 행동을 바꾸는 에이전트”에 가깝습니다. 모델은 판단하고, 도구는 실제 세계와 상호작용하며, 도구 결과는 다시 판단의 재료가 됩니다. 그 중심에는 컨텍스트 수집, 작업 수행, 결과 검증을 반복하는 에이전트 루프가 있습니다.
프로젝트 접근 범위와 실행 환경을 이해하고, 세션과 컨텍스트 윈도우를 구분하며, 체크포인트와 권한의 한계를 알면 Claude Code를 훨씬 예측 가능하게 사용할 수 있습니다. 가장 좋은 프롬프트는 모든 클릭과 명령을 대신 설계한 지시서가 아닙니다. 문제와 맥락, 제약, 성공 조건을 분명히 하고 에이전트가 조사와 검증을 수행할 여지를 남긴 위임장입니다.
자주 묻는 질문
Q1. Claude Code는 그냥 챗봇과 무엇이 다른가요?+
Claude 모델에 파일 검색, 편집, 셸 실행, 웹 조사와 같은 도구와 실행 환경이 결합되어 실제 프로젝트에 행동할 수 있습니다. 도구 결과를 읽고 다음 행동을 바꾸는 반복 구조가 핵심 차이입니다.
Q2. Claude Code가 프로젝트 전체를 자동으로 읽나요?+
처음부터 모든 파일을 컨텍스트에 넣는 것은 아닙니다. 현재 디렉터리를 기준으로 필요한 파일을 검색하고 선택적으로 읽습니다. 큰 저장소일수록 관련 경로와 재현 조건을 알려 주면 탐색이 빨라집니다.
Q3. 체크포인트가 있으면 Git이 필요 없나요?+
아닙니다. 체크포인트는 Claude Code의 파일 편집을 되돌리는 편의 기능입니다. 협업 기록, 브랜치, 코드 리뷰와 배포 이력은 Git으로 관리해야 합니다. 데이터베이스나 API 같은 외부 부작용도 체크포인트로 되돌릴 수 없습니다.
Q4. 세션을 재개하면 이전 내용을 전부 기억하나요?+
세션 기록은 이어지지만 모델의 컨텍스트 윈도우는 제한되어 있습니다. 긴 작업에서는 오래된 도구 출력이 제거되고 대화가 요약될 수 있습니다. 지속 규칙은 CLAUDE.md에 두는 것이 안전합니다.
Q5. Plan 모드는 언제 쓰면 좋나요?+
여러 파일이 얽힌 리팩터링, 익숙하지 않은 저장소, 보안이나 데이터 영향이 큰 변경처럼 구현 전에 구조와 위험을 확인해야 할 때 유용합니다. 탐색과 계획을 검토한 후 구현으로 전환할 수 있습니다.
Q6. 좋은 요청의 최소 구성은 무엇인가요?+
문제 또는 목표, 관련 맥락, 지켜야 할 제약, 검증 가능한 완료 조건의 4가지를 권합니다. 재현 절차, 테스트 케이스, 기대 화면이 있으면 함께 제공하세요.
공식 출처
'AI > Claude' 카테고리의 다른 글
| Claude Opus 5 출시 임박? 7월 24일 현재 확인된 것 (1) | 2026.07.24 |
|---|---|
| Claude Fable 5 정액제, 결국 Pro·Max·Team 플랜에 포함 (0) | 2026.07.18 |
| Claude에서 Codex 사용하기, 일명 "claudex" 설정 가이드 (0) | 2026.07.14 |
| Claude Fable 5 또 연장, 7월 19일까지…OpenAI와의 경쟁 때문일까 (2) | 2026.07.14 |
| Claude Fable 5로 웹 페이지 속도 이슈 원인 파악하기 (1) | 2026.07.07 |
