Claude Code 완전 이해 정리: 에이전트, 컨텍스트, 워크플로우 핵심

핵심 요약

Claude Code는 "코드 작성 도우미"가 아니라 로컬에서 움직이며 파일·명령·웹까지 자율적으로 다루는 에이전트형 작업 환경이다.

이 도구를 잘 쓰려면 컨텍스트(맥락) 관리, 프로젝트 규칙(CLAUDE.md), 재사용 가능한 워크플로우(Skills/Hooks/Subagents/Tasks)를 설계하는 능력이 핵심이다.

개발자뿐 아니라 투자자·사무직·PM도 "코딩 없이 로컬 작업을 자동화하는 비서"로 활용할 수 있다.

Claude Code의 정체: 채팅봇이 아닌 로컬 에이전트

Claude Code의 본질은 "터미널에서 돌아가는 AI 채팅"이 아니라, 스스로 파일을 읽고 수정하고, 명령을 실행하며, 웹을 검색하고, 다른 에이전트를 부르는 하나의 작업 에이전트다.

브라우저로 쓰는 일반 Claude/ChatGPT는 질문-답변에 그치지만, Claude Code는 Read/Write/Edit/Bash/WebSearch 같은 도구를 스스로 조합해 문제를 끝까지 밀어붙인다.

예를 들어 "이 버그 고쳐줘"라고 하면 관련 파일을 찾고, 문제를 파악하고, 수정하고, 테스트까지 실행한 뒤 결과를 보고 다시 수정하는 일련의 사이클을 사람 개입 없이 반복한다.

이게 가능한 이유는 Claude가 "어떻게 툴을 쓸지 스스로 계획하는 시스템"으로 설계되어 있기 때문이다. 사용자는 목표를 말하고, Claude는 이를 달성하기 위한 경로를 스스로 탐색한다.

로컬에서 돌아간다는 것의 의미

Claude Code는 당신 PC 안에서 돌아간다.

그래서 프로젝트 폴더 구조를 파악하고, 엑셀/파워포인트 파일을 생성하고, 브라우저 자동화를 하거나 쉘 스크립트를 돌릴 수 있다.

결국 "개발자용 코드 도구"라기보다 "키보드와 마우스로 할 수 있는 대부분의 일을 대신 처리해주는 로컬 비서"에 가깝다.

다만 로컬에서 명령을 실행한다는 건 위험도 동반한다. 잘못하면 파일을 지우거나 민감한 정보를 외부에 보내게 될 수 있으므로, Claude Code는 권한 확인, 샌드박스(파일·네트워크 제한), 체크포인트/되돌리기 같은 보호 장치를 제공한다. 사용자는 위험한 작업에서 반드시 승인·취소를 선택할 수 있어야 한다.

컨텍스트 윈도우와 Context Rot

Claude가 한 번에 다룰 수 있는 입력(과거 대화, 파일 내용, 툴 결과 등)을 "컨텍스트"라 부르고, 그 최대 용량이 컨텍스트 윈도우다.

Opus 4.5 기준 200k 토큰 정도지만, MCP·플러그인 설명과 긴 대화가 쌓이면 실제로 유효하게 쓸 수 있는 공간은 훨씬 줄어든다.

컨텍스트가 과도하게 쌓이면 다음과 같은 "Context Rot" 현상이 나타난다.
처음에 말한 중요한 전제를 잊거나, 답이 점점 흐릿해지고, 앞·뒤만 기억하고 중간 정보는 잃어버리고, 응답 속도도 느려진다.

따라서 Claude Code를 잘 쓰려면 "얼마나 많이 보여줄까?"보다 "무엇을 줄이고, 어떻게 요약하고, 무엇만 남길까?"를 설계하는 능력, 즉 컨텍스트 엔지니어링이 가장 중요해진다.

에이전트 vs 채팅: 자율성과 통제의 균형

일반 채팅봇은 "질문 → 답변"이 한 턴이다.

에이전트인 Claude Code는 "목표 → 스스로 계획 → 여러 단계 행동"이 기본 단위다. 상태를 관리하고, 여러 파일을 오가며, 여러 도구를 번갈아 쓰며 일한다.

이 자율성이 강력한 만큼, "잘못된 방향으로 열심히 달리는" 상황도 쉽게 벌어진다. 그래서 사용자가 가져가야 할 역할은 다음 두 가지다.

하나는 큰 방향과 제한을 분명히 말해주는 것(예: 어떤 폴더는 절대 수정 금지, 어떤 테스트부터 돌릴지, 어떤 코드 스타일을 쓰는지).

다른 하나는 중간 중간 작업을 멈추고(Esc), 되돌리고(/rewind), 요약하고(/compact), 새로운 세션으로 갈아타(/clear)면서 "레일 위에서 잘 달리고 있는지" 모니터링하는 것이다.

CLAUDE.md: 프로젝트의 집단 기억

CLAUDE.md는 특정 프로젝트에 들어가면 Claude가 자동으로 참고하는 "프로젝트 설명서 + 운영 규칙 문서"다.

여기에 적어야 하는 것은 코드만 봐서는 절대 알 수 없는 것들이다.

예를 들어, 필수로 돌려야 하는 테스트와 명령어, 이 프로젝트 특유의 아키텍처 선택 이유, 손대지 말아야 하는 레거시 영역, 코드 스타일에서 일반 규칙과 다른 부분, 환경변수·로컬 개발 환경의 특이 사항 등이 있다.

반대로, 언어 기본 규칙이나 "깨끗한 코드를 쓰자" 같은 뻔한 말, 코드에서 바로 읽히는 설명은 넣지 않는 편이 좋다. CLAUDE.md가 길어질수록 중요한 지침이 잡음 속에 섞여 무시되기 쉽기 때문이다.

좋은 기준은 "이 줄을 지워도 Claude가 눈에 띄게 실수할까?"이다. 그렇지 않다면 과감히 삭제해서 문서를 짧고 날카롭게 유지하는 편이 낫다.

Skills: 재사용 가능한 작업 방식 정의

Skills는 특정 작업 흐름이나 조직·도메인 특화 규칙을 담은 마크다운 정의다.

Claude는 시작할 때 각 스킬의 이름과 설명만 가볍게 읽어두고, 실제로 필요해 보이는 순간에만 그 스킬의 세부 내용을 불러와서 적용한다. 이렇게 해야 컨텍스트를 낭비하지 않고 "필요할 때만 능력을 다운받는" 구조를 만들 수 있다.

예를 들어 "TDD로 개발할 때의 단계와 테스트 이름 규칙"을 상세히 정의한 tdd-workflow 스킬을 만들어 두면, 나중에 "TDD로 진행해줘"라고 말했을 때 Claude가 그 스킬을 불러 필요 단계에 맞게 행동한다.

또 다른 유형은 "스ラ시 명령 전용 스킬"이다. 예를 들어 /fix-github-issue 1234라고 치면 GitHub Issue를 읽고, 관련 코드를 찾고, 수정·테스트·커밋·PR까지 한꺼번에 수행하는 스킬을 만들 수 있다. 이 경우는 disable-model-invocation: true를 설정해 Claude가 자동으로 쓰지 않고, 사용자가 명시적으로 호출할 때만 실행되게 한다.

결국 Skills는 "프로젝트/팀의 노하우를 재사용 가능한 매뉴얼로 외장화하는 장치"다. 자주 하는 작업은 스킬로 승격시키면, 다음부터는 짧은 호출만으로 같은 수준의 품질과 절차를 반복할 수 있다.

Hooks: "항상 해야 할 일"을 자동으로 강제하기

Hooks는 특정 이벤트가 발생할 때(파일 편집 직후, 명령 실행 전, 응답 완료 시 등) 무조건 실행되는 자동 액션이다.

예를 들어, TypeScript 파일이 수정될 때마다 npx prettier를 돌리거나, git push 전에 변경 요약을 보여 주거나, 위험한 .md 파일 생성 시도는 아예 막아버리는 식으로 쓸 수 있다.

CLAUDE.md와의 차이는 "권고"냐 "강제"냐이다. CLAUDE.md는 Claude가 상황에 따라 참고하는 가이드이고, Hooks는 조건에 맞으면 예외 없이 실행된다. 포맷팅, 린트, 형식 체크, 예기치 않은 파일 조작 차단 같이 "실수하면 큰일 나는 일"은 Hooks로 고정하는 것이 안전하다.

Hooks 설정은 ~/.claude.json 또는 프로젝트별 .claude.json 안에 넣으며, tool 종류나 파일 경로 패턴으로 언제 실행할지 세밀하게 걸러낼 수 있다.

Subagents와 Tasks: 역할 분담과 장기 작업 관리

Subagent는 특화된 역할을 맡는 작은 Claude다. 보안 리뷰 전담, 설계 플랜만 짜는 플래너, 코드 리뷰 전담 같은 식으로 역할을 분리할 수 있다. 각 서브에이전트는 자신만의 설명·규칙·툴 세트·모델을 가지며, 메인 에이전트가 필요할 때 Task 도구로 호출해 일을 시킨다.

이 구조의 장점은 크게 네 가지다. 메인 컨텍스트를 아끼고(분리), 역할별로 설정을 최적화하고(전문화), 여러 작업을 평행으로 돌릴 수 있고(병렬), 위험한 작업은 권한이 적은 에이전트에서만 수행하도록 제한할 수 있다는 점이다.

Tasks는 이전의 "Todos"를 확장한 기능으로, 해야 할 일 목록을 파일로 디스크에 저장해 세션이 끊겨도 유지한다. 각 Task는 제목, 설명, 현재 상태, 막고 있는/막히고 있는 다른 태스크를 함께 기록해 "이 작업은 A가 끝나야 시작 가능" 같은 의존 관계도 표현한다.

환경변수 CLAUDE_CODE_TASK_LIST_ID를 지정하면 여러 터미널·에이전트가 동일한 태스크 세트를 공유하며, 각자 비어 있을 때 다음 일을 가져와 처리하는 "작업 훔치기(워크스틸링)" 구조를 만들 수 있다. 큰 기능 구현을 작게 쪼개 여러 에이전트가 나누어 진행할 때 유용하다.

MCP와 Plugins: 외부 세계와의 연결과 패키지화

MCP(Model Context Protocol)는 Claude를 GitHub, 데이터베이스, 베셀, 스크래핑 서비스 같은 외부 시스템과 연결하기 위한 표준 인터페이스다. GitHub MCP를 쓰면 이슈·PR 생성·조회, Supabase MCP를 쓰면 DB 조회·RLS 정책 확인, Firecrawl MCP로는 웹 크롤링 같은 일을 바로 Claude에서 실행할 수 있다.

하지만 MCP 서버 하나하나도 "툴 설명"이라는 컨텍스트를 차지한다. 많은 MCP를 동시에 켜두면 실제 작업에 쓸 수 있는 컨텍스트 공간이 줄어든다. 그래서 전역으로 여러 MCP를 설정하더라도, 프로젝트별 .claude.json에서 disabledMcpServers로 과감히 끄는 전략이 필요하다.

Plugins는 Skills, Hooks, MCP 설정을 하나의 패키지처럼 묶어 /plugin install 명령 한 번으로 적용할 수 있는 형태다. 예를 들어 TypeScript LSP 플러그인을 설치하면 에디터 없이도 타입 점검과 심볼 점프 같은 기능을 확보할 수 있다. hookify 플러그인은 대화로 원하는 행동을 설명하면 적절한 Hooks 설정을 대신 만들어 준다.

핵심은 "쓸 것만 켜두고 나머지는 끈다"는 점이다. MCP·플러그인의 수가 늘수록 컨텍스트는 빠르게 줄어들고, 그만큼 모델 품질이 떨어지므로, 프로젝트별로 정말 필요한 것만 최소 세트로 유지하는 감각이 중요하다.

컨텍스트 엔지니어링 4원칙: Write·Select·Compress·Isolate

컨텍스트 문제를 다루는 실무적인 접근법은 네 가지로 요약된다.

Write는 "처음부터 Claude가 읽기 좋게 정리해서 넣기"다. 예를 들어 10-K 원문 100페이지를 통째로 넣는 대신, 핵심 지표와 리스크를 요약한 1~2페이지 메모를 만든 뒤 그 메모를 넣는 식이다.

Select는 "필요한 부분만 골라 넣기"다. 특정 회사의 리스크만 알고 싶다면 10-K 전체보다 'Risk Factors' 섹션만 골라 넣는 것이 효율적이다. 마찬가지로 코드베이스도 src 전체가 아니라 이번 수정과 관련 있는 디렉터리·파일만 Read하는 방향으로 설계해야 한다.

Compress는 "이미 쌓인 대화·툴 결과를 요약해서 다시 줄이는 것"이다. 같은 에러를 여러 번 시도하며 긴 로그가 쌓였다면 /compact로 "해결 과정의 핵심만 남긴 요약"을 만들고 과거 상세 로그는 잘라낸다. 이를 통해 같은 컨텍스트 용량으로 더 많은 작업을 처리할 수 있다.

Isolate는 "서브에이전트에 일을 쪼개 맡기기"다. 여러 회사 재무 분석처럼 범위가 큰 작업은 회사당 하나의 서브에이전트가 깨끗한 컨텍스트에서 분석·요약을 하고, 메인 에이전트는 그 요약들만 모아 비교하는 구조로 설계하면, 각 분석은 Context Rot의 영향을 훨씬 덜 받는다.

Plan 모드와 작업 단계 분리: 탐색·계획·실행·커밋

Claude Code에는 Plan 모드가 있어, 바로 실행에 들어가지 않고 먼저 "어떤 파일을 어떻게 바꾸고, 어떤 테스트를 돌릴지" 계획부터 제안하게 만들 수 있다. Shift+Enter가 줄바꿈, Shift+Tab으로 Plan 모드 토글을 할 수 있다.

이 모드를 활용하면 작업을 네 단계로 나누기 좋다. 먼저 코드·문서·이슈를 읽으며 "지금 상황이 어떤지" 탐색하고, 이어서 어떤 파일들을 건드릴지, 예상 위험은 무엇인지 계획을 세운다. 계획이 합의되면 일반 모드에서 실제 수정을 맡기고, 마지막으로 테스트·빌드·커밋·PR 작성까지 한 세트로 마무리한다.

이렇게 "탐색+계획"과 "구현"을 구분하면, 아직 문제 정의가 흐릿한 상태에서 과감한 리팩터링을 해버리는 실수를 줄일 수 있다. 다만 오타 수정, 로그 추가처럼 한 문장으로 diff를 설명할 수 있는 작은 수정에는 굳이 Plan 모드를 쓰지 않고 바로 실행시키는 편이 효율적이다.

비개발자를 위한 활용법과 첫걸음

Claude Code는 이름과 UI 때문에 개발자 전용처럼 보이지만, 사실 "로컬에서 엑셀·PDF·폴더·브라우저를 자동으로 다루는 비서"로서 비개발자에게도 매우 강력하다.

예를 들어 영수증·인보이스 PDF를 읽어 날짜·업체명을 뽑아 파일명을 규칙적으로 바꾸고 폴더를 나눠 저장하거나, 카드 사용 내역 CSV를 읽어 경비 정산용 엑셀을 만들게 하거나, 회의 녹취를 모아 "내가 갈등을 피한 장면만 찾기" 같은 메타 분석을 시킬 수 있다.

처음에는 매우 단순한 요청부터 시작하는 것이 좋다. "이 폴더에 뭐가 있는지 설명해줘", "용량 큰 파일 상위 10개를 알려줘", "다운로드 폴더에서 한 달 이상 묵힌 파일을 '정리' 폴더로 옮겨줘" 같은 명령으로 로컬에서 안전하게 움직이는 패턴을 익히는 식이다.

익숙해지면 "방금 했던 경비 정리 절차를 /expense-report라는 이름의 스킬로 저장해줘"라고 하여 반복 업무를 한 번의 명령으로 자동화할 수 있다. 중요 포인트는 "내가 노가다로 하던 클릭·정리·변환 작업을 문장으로 설명해 넘기고, 잘 작동하면 스킬로 승격시킨다"는 생각을 갖는 것이다.

자주 발생하는 실패 패턴과 예방책

Claude Code 초보자가 자주 빠지는 함정은 몇 가지 패턴으로 정리된다.

첫째, 한 세션에서 완전히 다른 주제(기능 개발 → 여행 계획 → 다시 버그 수정)를 마구 섞는 "주제 뒤섞기"다. 이런 세션은 컨텍스트를 쓸데없이 소모하고, 나중에는 처음 요구 사항을 Claude가 잊어버리게 만든다. 서로 관련 없는 작업은 /clear로 세션을 나누는 습관을 들이는 것이 좋다.

둘째, 같은 실패한 접근을 계속 조금씩 고치며 시도하는 것이다. 동일한 방식으로 두 번 정도 실패했다면, 과감히 /clear로 초기화하고 "지금까지 알게 된 사실"을 짧게 요약해 새 프롬프트로 시작하는 편이 훨씬 낫다.

셋째, CLAUDE.md를 팀 규칙 저장소라 착각해 온갖 것을 다 우겨 넣는 경우다. 이 경우 정말 중요한 주의사항조차 모델이 무시하게 된다. "삭제하면 실제로 실수가 생길 내용만 남긴다"는 기준으로 길이를 줄여야 한다.

마지막으로 "검증 없이 그럴듯한 답을 믿는 것"이다. 테스트 코드, 명시적 빌드/런 커맨드, 스크린샷 비교, 로그 체크 중 최소 하나는 항상 제공해 Claude가 스스로 작업을 검증하게 해야 한다. 검증 수단이 없는 작업은 결과가 아무리 그럴듯해도 실제로는 작동하지 않을 확률이 높다.

인사이트

Claude Code는 "코드를 대신 써주는 채팅봇"이 아니라, 로컬에서 움직이는 범용 작업 에이전트이며, 이 에이전트를 잘 쓰려면 모델 성능보다 환경 설계 능력이 더 중요해진다.

가장 큰 레버리지는 세 가지다. 첫째, CLAUDE.md·Skills·Hooks·Subagents·Tasks로 "내/우리 팀 방식"을 외장화하고 자동화하는 것. 둘째, 컨텍스트 엔지니어링(Write/Select/Compress/Isolate)으로 모델의 집중력을 유지하는 것. 셋째, Plan 모드와 검증 루틴을 통해 "잘못된 방향으로 열심히 달리는" 상황을 예방하는 것이다.

실천 팁을 정리하면 이렇다.

1. 새 프로젝트에서는 /init로 CLAUDE.md를 생성한 뒤 "정말 필요한 지침만" 엄선해서 채우고,

2. 자주 반복하는 작업은 먼저 한 번 잘 시켜본 다음 스킬로 승격시키며,

3. 위험하거나 복잡한 흐름에는 Hooks/Subagents/Tasks를 붙여 재현 가능하고 안전한 파이프라인을 만든다.

여기에 "한 세션에 하나의 주제만", "2번 이상 같은 방식으로 실패하면 새 세션에서 접근법을 갈아탄다", "검증 없이 신뢰하지 않는다"는 세 가지만 몸에 익히면, Claude Code는 곧 "같이 일하는 동료" 수준의 생산성을 내줄 수 있다.

출처 및 참고 : Claude Code 超完全ガイド | エンジニアから投資家まで、すべてのユーザーのための実践マニュアル｜FabyΔ