Claude Code 란

Claude Code

터미널 기반 AI 코딩 도우미 + 코드 에이전트

요즘 유행하는 바이브 코딩 중심에 있다.

 

Chat GPT 에게 코드 수정을 부탁하려면,

상황 설명 -> 서비스 레이어 -> 레포지토리 레이어 -> DB 설계를 모두 복사 붙여넣기 해줘야했다.

하지만 Claude Code는 다음과 같은 작업을 한 번에 수행한다.

• 프로젝트 전체 코드베이스를 이해
• 테스트 코드 작성
• 테스트 실행 → 실패 확인
• 코드 수정
• 다시 실행

즉, 사람이 하던 개발 사이클 자체를 자동으로 수행한다. 이런 프로젝트 단위 사고로 인해 판단 하나하나를 일일이 알려주지 않아도 된다. 

 

Claude code는 파일 단위로 진행 되는 것이 아니라, 프로젝트 단위로 명령을 이행한다. 

 

1. 전체 코드 베이스 인식

• 단일 파일이 아닌 프로젝트 구조 전체를 컨텍스트로 사용
• 디렉토리 구조, 테스트, 설정 파일까지 함께 이해

2. 에이전트 기반 작업 수행

 

• 명령 하나로 연속 작업 자동화
• 테스트 → 수정 → 재실행 같은 루프를 스스로 판단

3. CLI 중심 설계

 

• 터미널에서 실행
• git, test runner, build tool과 자연스럽게 연결

 

단점

Claude Code는 LLM 기반 도구이므로 Hallucination 환각에서 자유롭지 않다.

프롬르트 설계에 따라 품질이 크게 달라진다. 대충 말해도 알아서 해주겠지 같은 사고는 그럴듯하지만 틀린 코드를 생산할 가능성이 높아진다.

 

환각에 대한 자세한 포스팅은: https://wonder-why.tistory.com/246

Hallucination 할루시네이션 환각 이란

 

또한, 무료 사용 불가라는 단점이 있다. 테스트 코드 자동화를 위해 클로드 코드를 도입하려고 했지만 비용 부담 때문에 Gemini CLI 를 도입했다.

 

주요기능

CLAUDE.md	Claude가 매 대화마다 먼저 읽는 설정 파일로 프로젝트 설명 노트 역할을 한다. 이 파일의 설계로 프로젝트의 품질이 좌우된다.
컨텍스트 제어	@파일명 : 특정 파일/디렉토리 명시, 이미지 드래그, URL 붙여넣기 지원
권한 제어	ask mode: 모든 작업에 승인 요청을 구한다. plan mode: 전체 작업 계획을 먼저 제시한다. auto-accept mode: 허용된 작업을 자동 실항 한다.

 

자주쓰는 명령어

/clear	대화 초기화
/compact	요약만 남기고 기록 초기화
/model	사용할 모델 전환
/permissions	권한 설정 관리
/cost	현재 사용량 확인
/init	프로젝트 초기화
/memory	CLAUDE.md 파일 편집
/help	도움말 보기
/terminal-setup	터미널 설정 도움
/config	설정 확인/ 변경
/explain []	코드 설명 요청
/search []	프로젝트 전체 코드에서 검색
/review []	코드 리뷰 요청
/diff	변경 사항 비교 설명
/edit []	기존 코드 수정
/add  []	새로운 파일, 코드 추가
/refactor []	코드 구조 개선
/test []	테스트 코드 생성 또는 테스트 실행 관련 도움
/fix []	에러 수정 요청
/commit	커밋 메세지 생성

 

 

CLI 명령어

claude	대화형 (REPL) 실행	claude
claude "qurey"	초기 질문 하고 REPL 실행	claude "explain this project"
claude -p "query"	단발성 실행. 번 질문하고 바로 종료	claude -p "explain this function"
cat file	claude -p "query"	파이프 입력 처리
claude -c	최근 대화 세션 계속	claude -c
claude -c -p "query"	최근 대화를 사용, RELP 은 열지 않고 응답 후 종료	claude -c -p "Check for type errors"
claude -r "<session>" "query"	세션 ID 또는 이름을 지정해서 재개	claude -r "auth-refactor" "Finish this PR"

 

옵션의미

-p	단발 실행
-c	최근 세션 계속
-r	특정 세션 재개

 

 

CLI 플래그

Calude code 는 CLI 플래그를 통해 컨텍스트 범위, 보안, 모델, 출력 형식, 자동화 방식을 세밀하게 제어할 수 있다. 

 

--add-dir	Claude가 접근할 수 있는 ****추가 작업 디렉토리 지정, 실제 존재하는 디렉토리만 허용.	claude --add-dir ../apps ../lib
--session-id	대화에 명시적 세션 ID(UUID) 사용	claude --session-id "550e8400-e29b"
--continue, -c	현재 디렉토리의 최근 세션 재개	claude --continue
--resume, -r	특정 세션 ID 또는 이름으로 재개	claude --resume auth-refactor
--fork-session	세션 재개 시 새 세션으로 분기, 원본 컨텍스트 보존용	claude --resume abc123 --fork-session
--agent	현재 세션에 사용할 에이전트 지정, agent 설정 재정의	claude --agent my-custom-agent
--agents	JSON으로 사용자 정의 서브 에이전트 동적 정의	claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'
--model	사용할 모델 지정 (별칭 또는 전체 이름)	claude --model sonnet
--fallback-model	기본 모델 과부하 지정된 모델로 자동 폴백 활성화	claude -p --fallback-model sonnet "query"
--tools	Claude가 사용할 수 있는 도구 제한	claude --tools "Bash,Edit,Read"
--allowedTools	권한 확인 없이 실행 가능한 도구 지정	"Bash(git diff:*)" "Read"
--disallowedTools	특정 도구 명시적 차단. 모델의 컨택스트에서 제거	"Edit" "Bash(git log:*)"
--permission-mode	세션 시작 권한 모드 지정, 저장된 권한 모드에서 시작	claude --permission-mode plan
--dangerously-skip-permissions	권한 확인 완전 생략	claude --dangerously-skip-permissions
--mcp-config	MCP 서버 설정 로드	claude --mcp-config ./mcp.json
--strict-mcp-config	지정한 MCP 설정만 사용	claude --strict-mcp-config --mcp-config ./mcp.json
--print, -p	대화형 모드 없이 출력만	claude -p "query"
--output-format	출력 형식 지정	claude -p --output-format json "query"
--input-format	입력 형식 지정	claude -p --input-format stream-json
--system-prompt	전체 시스템 프롬프트를 사용자 정의 텍스트로 변경	claude --system-prompt "You are a Python expert"
--chrome / --no-chrome	Chrome 브라우저 자동화 활성화 / 비활성화	claude [-–chrome] [--no-chrome]

 

Agent / Sub-agent 구조

긴대화를 하다보면 컨텍스트가 쌓여 속도가 느려지고 클로드가 이전 내용을 잊는 문제가 발생한다. -> 이를 해결하기 위해 서브 에이전트가 존재한다.

 

Claude Code는 상황에 따라 서브 에이전트를 호출한다.

자동호출이 되지 않는 경우 명시적 위임이 가능하다.

 

메인 에이전트: 클로드 세션에서 중심 역할 수행서브 에이전트:  리뷰 전용, 테스트 전용, 문서 적용 등 전문화된 역할을 수행하는 에이전트

 

agent 의 기본 구조:

name	O	서브에이전트 이름, 키로 사용 된다.
description	O	서브에이전트를 호출해야 할 때를 설명하는 자연어 설명
prompt	O	서브에이전트의 동작을 안내하는 시스템 프롬프트
tools	X	서브에이전트가 사용할 수 있는 특정 도구의 배열 (예: ["Read", "Edit", "Bash"]). 생략하면 모든 도구를 상속
model	X	사용할 모델 별칭: sonnet, opus, 또는 haiku. 생략하면 기본 서브에이전트 모델 사용

 

 

유용한 에이전트

1. code-reviewer: 코드 품질, 보안, 유지보수성 관점에서 전문적인 코드 리뷰 수행
2. test-automator: 단위/통합/E2E 테스트를 포함한 종합 테스트 스위트 생성
3. docs-architect: 개발자 문서 작성 및 OpenAPI/Swagger 스펙 생성
4. architect-reviewer: 시스템 아키텍처 설계 및 기술적 의사결정 검토
5. debugger: 오류, 테스트 실패, 예상치 못한 동작에 대한 디버깅 전문가
6. error-detective: 에러 로그 분석 및 근본 원인 추적 전문가

Sub - Agent 정의 방법

1. CLI: 콘솔창에 json 형태로 입력해 사용 가능. 재시작시 사라짐
2. Json 파일 형식으로 정의
3. Yaml 파일 형식으로 정의

claude --agents '{ "code-reviewer": { "description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer. Focus on code quality, security..", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "sonnet" } }

 

code-reviewer: description: Expert code reviewer. Use proactively after code changes. prompt: | You are a senior code reviewer. Focus on code quality, security, and best practices. tools: - Read - Grep - Glob - Bash model: sonnet

 

• 코드 리뷰 역할을 담당하는 서브 에이전트
• 메인 에이전트가 "코드변경" 상황이라고 판단할 경우 자동 호출
• 코드 품질, 보안 이슈를 집중적으로 판단.
• 읽기, 코드 패턴 검색, 여러 파일 매칭, git 명령어 실행 가능 -> edit 권한을 부여하지 않았기에 리뷰에 집중한다. 

 

 

HOOK

• Claude Code가 실행되는 과정에서 특정 도구를 사용하기 전에 실행되는 스크립트
• Hook 스크립트를 통해 프로젝트 외부 파일 접근, 위험한 시스템 명령 실행, 민감 정보가 담긴 파일 조작 등을 사전에 차단할 수 있음
• 훅을 사용하면 LLM의 판단에 의존하지 않고, 항상 특정 작업이 실행되도록 보장할 수 있다. 

 

• 훅 이벤트 개요

PreToolUse	도구 호출 전	차단 가능
PermissionRequest	권한 요청 전	허용/거부 제어 가능
PostToolUse	도구 호출 후	결과 후처리, 로깅 등
UserPromptSubmit	사용자가 프롬프트 제출 시	입력 전처리 가능
Notification	Claude가 알림 전송 시	데스크톱 알림 등
Stop	Claude 응답 완료 시	종료 작업 수행
SubagentStop	서브에이전트 완료 시	후속 작업 트리거
PreCompact	컴팩트 작업 전	최적화 작업 가능
SessionStart	세션 시작/재개 시	초기 설정 실행
SessionEnd	세션 종료 시	정리 작업 실행

 

 

훅의 기본 구조

• 훅은 matchers 로 구성되며 각 mathers 는 여러 hooks 을 가질 수 있다.

{ //코드 포맷팅 훅 

  "hooks": { 

    "PostToolUse": [ 

      { 

        "matcher": "Edit|Write", 

        "hooks": [ 

          { 

            "type": "command", 

            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }" 

          } 

        ] 

      } 

    ] 

  } 

}

 

실행순서

• 이벤트, 언제 (Event) → 조건, 무엇에 반응하여 (matcher) → 실행 목적, 무엇을 할지ㅡ(hooks)
  1. EventName: 해당 이벤트가 발생하면 아래 정의된 matcher, hooks 를 검사한다.
  2. matcher: 도구 이름 필터
  3. hooks: matcher가 일치하면 여기에 정의된 hooks가 실행된다. 병렬 실행 가능하다.