[Claude Code] 1. Claude Code

1. Claude Code란?

• 터미널에서 실행되는 에이전트 코딩 도구
• ✅ 코드베이스를 읽고, 파일을 편집하고, 명령을 실행할 수 있음
• ✅ 기능을 구축하고, 버그를 수정하고, 개발 작업을 자동화함
• ➡️ 전체 코드를 이해하고 여러 파일과 도구에 걸쳐 작업할 수 있음

 

2. 핵심 요소

모델

• 작업의 복잡도와 비용에 따라 선택할 수 있음

작업 유형	권장 방향	모델명
복잡한 아키텍처 설계	높은 추론 성능 모델	Opus 4.8
일반적인 코드 수정	균형 잡힌 기본 모델	Sonnet 5
빠른 검색과 단순 작업	가벼운 고속 모델	Haiku 4.5
여러 서브에이전트 병렬 실행	비용 효율적인 모델	Haiku 4.5
코드 리뷰 최종 검증	높은 추론 성능 모델	Opus 4.8

 

도구

• 각 도구의 결과는 다음 행동을 결정하는 새로운 정보가 됨

범주	수행 가능한 작업
파일 작업	파일 읽기, 생성, 수정, 이동, 이름 변경
검색	파일 검색, 문자열 검색, 정규식 검색
실행	Shell 명령, 테스트, 빌드, Git 실행
웹	문서 검색, 오류 메시지 검색, 웹페이지 조회
코드 인텔리전스	정의 이동, 참조 검색, 타입 오류 확인

 

예시) "테스트 수정해줘"

1. 테스트 실행
2. 실패 메시지 확인
3. 관련 소스 파일 검색
4. 코드 읽기
5. 원인 분석
6. 코드 수정
7. 테스트 재실행
8. 성공 여부 확인

 

핵심 파일

Claude Code가 세션 중 접근하고 활용하는 주요 대상

접근 대상	설명	주요 활용 예시	관리 시 주의사항
프로젝트 파일	실행한 디렉터리와 그 하위 디렉터리의 파일을 읽고 생성·수정 가능	코드 구조 분석, 소스 코드 수정, 설정 파일 생성, 문서 작성	프로젝트 전체를 분석하려면 반드시 프로젝트 루트에서 실행 하기
터미널	로컬 환경에서 실행 가능한 셸 명령어 실행	빌드, 테스트, 서버 실행, Docker 명령, 로그 확인	운영 명령이나 파일 삭제 명령처럼 위험한 작업은 실행 전 범위 확인하기
Git 상태	현재 브랜치, 변경 파일, 커밋 기록, diff 등을 확인할 수 있다.	변경사항 검토, 브랜치 확인, 커밋 준비, 불필요한 수정 탐지	Claude의 작업이 끝난 뒤 git status와 git diff를 반드시 확인하는 것이 좋다.
루트 CLAUDE.md	프로젝트 전체에서 매 세션 참고해야 하는 공통 규칙	프로젝트 구조, 개발 규칙, 아키텍처 원칙, 빌드·테스트 명령어, 비즈니스 용어, 금지사항, 코딩 컨벤션	항상 필요한 핵심 규칙만 유지해야 함. 현재 작업과 관계없는 정보가 많으면 컨텍스트를 불필요하게 차지할 수 있다.
모듈별 CLAUDE.md	특정 모듈을 작업할 때만 필요한 규칙과 구조를 저장한다.	모듈 역할, 패키지 구조, 의존성 규칙, 테스트 방법, 보안 주의사항	루트 CLAUDE.md의 공통 규칙을 반복하지 말고, 해당 모듈에만 적용되는 내용만 작성한다.
자동 메모리	작업 중 발견한 프로젝트 패턴, 반복되는 해결 방법, 사용자 선호 등을 저장하여 이후 세션에서 참고한다.	자주 사용하는 명령어, 반복되는 프로젝트 구조, 선호하는 작업 방식, 디버깅 패턴 기억	Claude의 개인 작업 노트에 가깝다. 팀이 반드시 알아야 할 내용은 CLAUDE.md나 docs/에 별도로 문서화해야 한다.

 

 

3. 에이전트 루프

• 작업을 수행하는 과정
• ✅ 각 단계는 필요에 따라 반복되며, 작업에 따라 루프가 달라짐

 

과정

단계	설명	주요 활동 예시
1. 컨텍스트 수집	Claude가 작업을 이해하기 위해 필요한 정보를 찾고 정리하는 단계	관련 파일 검색, 코드 읽기, 프로젝트 구조 확인, 오류 로그 분석, CLAUDE.md 규칙 확인
2. 작업 수행	수집한 정보를 바탕으로 실제 작업을 실행하는 단계	코드 수정, 새 파일 생성, 리팩터링, 설정 변경, 문서 작성
3. 결과 검증	수행한 작업이 요구사항에 맞고 정상적으로 동작하는지 확인하는 단계	테스트 실행, 빌드 실행, 컴파일 오류 확인, Git diff 검토, 예상 결과 비교

• ❗️ 사용자는 작업 도중 Claude를 중단하거나, 추가 정보를 제공하고, 수정 범위와 접근 방법을 변경할 수 있음

 

4. 에이전트 하네스

• Claude Code가 모델 주변에 제공하는 환경
• ✅ Claude 모델은 추론과 판단을 담당
• ✅ 파일 접근이나 명령 실행은 Claude Code가 제공하는 도구와 실행환경을 통해 수행함
• ➡️ 사용자는 이 하네스를 이용해 자신의 프로젝트에 맞는 규칙과 워크플로우를 추가함
• ex) 파일 접근, 터미널 실행, 컨텍스트 관리, 권한 관리, 확장 기능 등

 

권한 설정

• ".claude/settings.json" 에서 특정 명령을 허용 가능하도록 제어함

 

표) 권한 모드

권한 모드	설명
Default	파일 수정이나 명령 실행 전에 승인 요청
Accept Edits	파일 편집은 자동 수락하고 일부 명령은 승인 요청
Plan	파일을 수정하지 않고 탐색과 계획만 수행
Auto	안전성 판단을 거쳐 작업을 자동 수행

 

확장 기능

확장 기능	역할	예시
Skills	반복 작업과 전문 지식을 모듈화	코드 리뷰, 테스트 검증, API 문서 작성
MCP	외부 데이터와 서비스 연결	Github, Jira, Notion
Hooks	특정 시점에 작업을 자동 실행	파일 수정 후 → Formatter 실행
Subagents	별도 에이전트에 작업 위임	보안 분석 Agent, 아키텍처 분석 Agent
Claude in Chrome	브라우저 작업 수행

 

5. 세션

• 하나의 작업 대화 단위
• ✅ 새 세션은 이전 대화 기록 없이 시작함
• ex) 사용자 메시지, 응답, 도구 호출, 읽은 파일, 작업 기록 등

 

6. 컨텍스트 윈도우

• 한 세션에서 참고할 수 있는 전체 정보 공간
• ✅ 한계에 가까워지면 자동으로 관리해줌

 

가득 찰 경우

• 오래된 도구 출력 제거
• 이전 대화 요약 (압축 과정에서 손상 가능성 있음)
• 핵심 요청과 코드 유지

 

관리 방법

• Skills: 세션 시작 시 전체가 로드되지 않고, 실제 사용할 때 본문이 로드되므로 사용할 것만 올려서 씀
• Subagents: 메인 대화와 분리된 새로운 컨텍스트를 가짐
  • 긴 분석작업으로 메인 컨텍스트가 가득 차는것을 방지할 수 있음

 

7. 체크포인트

• Claude Code가 파일을 수정하기 전에 기존 파일 상태를 저장해두는 안전기능
• ✅ 잘못 수정한 파일을 이전 상태로 되돌릴 수 있음
• ✅ Git과 별도로 동작하며, 세션을 재개한 뒤에도 사용 가능
• ✅ 변경 취소를 요청하거나 되돌리기 기능을 통해 복구 가능

 

출처

• Claude Code Docs  - 시작하기
• Claude Code Docs - Claude Code의 작동 방식