Claude Code 가이드

Claude Code의 실행 구조, 입력 처리, slash command, tool runtime, 권한과 비용까지 실제 코드 기준으로 정리한 가이드 모음입니다.

Claude Code는 프롬프트를 API로 넘기는 래퍼가 아니라, 입력 정규화·slash command dispatch·agent loop·tool runtime·권한/기록/비용 계층을 갖춘 실행 런타임입니다. 이 가이드는 그 계층을 순서대로 따라가면서, 각 단계에서 무엇을 설정하고 무엇을 확인해야 하는지 정리합니다.

런타임 구조 이해하기

Claude Code가 실행될 때 무엇을 준비하고 어떤 순서로 요청을 처리하는지 봅니다.

Claude Code를 뜯어보니 Agent의 핵심은 Runtime이었다Claude Code CLI 스냅샷을 runtime 관점으로 분석해 AI agent가 모델 호출이 아니라 입력, 도구, 권한, 기록 루프의 조합임을 설명합니다.
Claude Code CLI는 시작하자마자 무엇을 정리할까Claude Code CLI 분석을 바탕으로 agent runtime의 bootstrap 단계가 설정, 정책, 인증, 실행 모드를 어떻게 정리해야 하는지 설명합니다.
Claude Code의 터미널 화면은 UI가 아니라 Runtime Shell이었다Claude Code CLI 분석을 통해 터미널 화면이 단순 출력 UI가 아니라 메시지, 입력, 승인, 실행 상태를 묶는 runtime shell임을 설명합니다.

입력이 요청이 되는 과정

한 줄 프롬프트가 모델 메시지와 agent turn으로 바뀌는 경계를 봅니다.

한 줄 프롬프트가 Agent Turn이 되기까지Claude Code CLI 분석을 바탕으로 사용자의 한 줄 입력이 즉시 명령, 큐 항목, 모델 질의 중 하나로 분기되는 submit boundary를 설명합니다.
Raw Input을 Model Message로 바꾸는 입력 정규화 계층Claude Code CLI 분석에서 추출한 입력 정규화 패턴을 바탕으로 raw input, 첨부, command, hook을 model visible message로 바꾸는 방법을 설명합니다.
Slash Command는 단축키가 아니라 Runtime Dispatch다Claude Code CLI 분석을 바탕으로 slash command를 prompt 생성, local 실행, interactive UI, forked execution으로 나누는 runtime dispatch 패턴을 설명합니다.

실행 루프와 도구

agent loop, provider API 경계, tool runtime을 설계 관점에서 봅니다.

Agent Loop는 모델 호출이 아니라 상태 기계다Claude Code CLI 분석을 기반으로 agent query loop를 streaming model call, tool request, result injection이 반복되는 상태 기계로 설명합니다.
Provider API를 제품 로직에서 분리하는 법Claude Code CLI 분석을 바탕으로 model provider API 요청, streaming 응답, tool schema, usage/cost 처리를 runtime boundary로 분리하는 방법을 설명합니다.
Tool Runtime은 함수 호출 목록이 아니다Claude Code CLI 분석을 바탕으로 AI agent tool runtime을 capability registry, schema validation, permission gate, 실행 오케스트레이션으로 설명합니다.

권한, 기록, 비용

실제 운영에서 문제가 되는 권한 승인, transcript, 비용 통제를 다룹니다.

권한, Transcript, 비용이 Agent 제품성을 결정한다Claude Code CLI 분석을 바탕으로 AI agent의 permission gate, transcript recording, usage/cost accounting을 제품 안정성의 핵심 계층으로 정리합니다.

프롬프트 작성 실무

Claude에 작업을 맡길 때 지시를 어떻게 구조화할지 정리합니다.

Claude 프롬프트는 질문이 아니라 작업 명세서다Claude를 안정적으로 쓰는 첫 번째 기준은 프롬프트를 “질문”이 아니라 작업 명세서로 작성하는 것입니다.
XML 태그와 출력 형식으로 Claude 응답을 안정화하는 법Claude 프롬프트가 길어질수록 가장 먼저 무너지는 것은 정보의 경계입니다. 지시문, 참고자료, 예시, 사용자 입력, 출력 형식이 한 덩어리로 섞이면 Claude가 어느 문장이 명령이고 어느 문장이 데이터인지 헷갈릴 수 있습니다.
Claude Thinking, effort, Tool Use를 실무에서 다루는 법Claude 최신 모델을 운영할 때 프롬프트 내용만큼 중요한 것이 추론 깊이와 도구 사용 정책입니다. 복잡한 작업에서는 더 깊은 thinking이 필요하지만, 모든 요청에 높은 effort를 쓰면 비용과 지연 시간이 커집니다. 반대로 도구 사용 조건이 느슨하면 모델이 필요 이상으로 검색하거나, 위험한 액션을 시도할 수 있습니다.
바로 쓰는 Claude 프롬프트 템플릿과 실전 체크리스트프롬프트 품질을 안정화하려면 개인의 감각에 맡기면 안 됩니다. 자주 하는 작업은 템플릿으로 만들고, 작업 전 체크리스트로 빠진 조건을 확인해야 합니다.