Claude Code는 대화 도구가 아니다
Anthropic 공식 문서는 Claude Code를 “코드베이스를 읽고, 파일을 수정하고, 명령을 실행하고, 개발 도구와 통합하는 에이전틱 코딩 툴”로 정의한다. 핵심은 질문에 답하는 것이 아니라 작업을 이어서 수행하는 데 있다
백엔드 개발에서 Claude Code를 사용하면 워크플로우는 다음과 같다
문제 관찰 → 원인 식별 → 관련 파일 수정 → 설정 → 테스트 → 검토
이 과정은 한 번의 답변으로 끝나지 않는다. 중간에 상태를 읽고, 다시 판단하고, 다시 실행하는 반복이 필요하다. Claude Code는 터미널 안에서 동작하는 에이전트형 실행 시스템이다. 코딩뿐 아니라 문서 작성, 빌드 실행, 파일 검색, 조사 같은 커맨드라인 작업도 수행할 수 있다
Claude Code 아키텍처 – 4개 레이어
Claude Code의 구조는 다음 4개 레이어로 나눌 수 있다
┌──────────────────────────────────┐ │ 규칙 레이어 (CLAUDE.md) │ ← 세션이 바뀌어도 유지되는 기준 ├──────────────────────────────────┤ │ 컨텍스트 레이어 │ ← 이번 작업에 필요한 문맥 ├──────────────────────────────────┤ │ 전략 레이어 │ ← 계획·분리·자동화 판단 ├──────────────────────────────────┤ │ 실행·검증 레이어 │ ← 수정, 테스트, PR, Hooks └──────────────────────────────────┘
규칙 레이어
CLAUDE.md가 여기에 해당한다. 공식 문서에 따르면 CLAUDE.md는 매 세션 시작 시 자동으로 로드되며, 코딩 표준·아키텍처 결정·선호 라이브러리·리뷰 체크리스트 같은 내용을 담는다
한 가지 중요한 점은 CLAUDE.md가 비대해지면 역효과가 난다는 것이다. 공식 문서는 CLAUDE.md가 너무 길어지면 지시사항 자체가 무시될 수 있다고 경고한다. 각 줄은 “이 줄을 삭제하면 Claude가 실수를 할 것인가?”라는 기준으로 유지 여부를 판단해야 한다
CLAUDE.md 외에 Auto Memory도 함께 이해해야 한다. Auto Memory는 Claude가 직접 작성하는 메모 시스템으로, 빌드 명령이나 디버깅 패턴 같은 학습 내용을 세션 간에 자동으로 유지한다. CLAUDE.md가 사람이 작성하는 규칙이라면, Auto Memory는 Claude가 축적하는 패턴이다
이 레이어가 약하면 같은 프로젝트인데도 세션마다 결과가 달라진다
컨텍스트 레이어
현재 해결하려는 문제, 관련 파일, 실패 로그, 수정 범위처럼 이번 작업에 필요한 문맥이 들어간다. 이 레이어가 잘못되면 Claude가 아무리 좋은 모델이어도 계속 엉뚱한 방향으로 나아간다
공식 문서는 컨텍스트 윈도우를 “가장 중요하게 관리해야 할 자원”으로 명시한다. 컨텍스트가 채워질수록 성능이 저하되고, 이전 지시사항을 “잊거나” 실수가 늘어난다
전략 레이어
바로 수정할지, 먼저 계획할지, 서브 에이전트를 써서 분리할지, 어디까지 자동화하고 어디서 검토할지 같은 판단이 여기서 이루어진다
실행·검증 레이어
파일 수정, 테스트 실행, diff 검토, Git 정리, PR 생성처럼 실제 반영과 검증이 일어나는 레이어다. Hooks와 GitHub Actions는 이 레이어를 강화하는 장치다. 공식 문서도 Hooks를 “프롬프트와 달리 반드시 실행이 보장되는 장치”로 구분한다. 린팅, 포맷팅, 보안 검사처럼 모델 선택에 관계없이 항상 실행되어야 하는 작업에 사용한다
세션마다 결과가 흔들린다면 규칙 레이어를 점검해야 한다. Claude가 엉뚱한 방향으로 나아간다면 컨텍스트 레이어를 점검해야 한다. 어느 레이어에서 병목이 생기는지 보고 그 레이어를 보강하는 것이 핵심이다
컨텍스트 컨트롤 – 많이 주는 게 아니라 정확하게 주는 것
큰 프로젝트에서 Claude가 엉뚱한 파일을 건드리거나 수정 범위가 넓어지면, 흔히 모델 성능 문제로 판단하기 쉽다. 실제 원인은 대부분 컨텍스트를 잘못 준 데 있다
공식 문서는 컨텍스트 관리가 비용과 품질 모두에 영향을 준다고 명시한다. Claude Code를 잘 쓰는 핵심은 프롬프트가 아니라 작업 범위와 맥락을 어떻게 제어하느냐에 있다
큰 코드베이스에서는 컨텍스트가 부족해서 실패하는 경우보다, 컨텍스트가 넓고 흐려서 실패하는 경우가 더 많다. 지나치게 넓은 컨텍스트를 주면 모델이 아무리 좋아도 문제 정의가 흐려진다
컨텍스트 컨트롤 3단계
1단계: 문제 범위를 줄인다
지금 무엇을 고치는지 한 문장으로 정의하지 못하면 Claude도 왔다 갔다 할 수밖에 없다
2단계: 파일 범위를 줄인다
관련 파일 후보만 먼저 모으고, 거기서 다시 실제 수정 파일을 좁힌다
3단계: 세션 범위를 줄인다
조사 세션, 수정 세션, 검토 세션을 섞지 않는다. 세션이 길어져서 판단이 흐려지면, 이전 대화를 억지로 유지하려 하기보다 핵심만 요약해서 새로 시작하는 편이 낫다
에이전트를 좋은 인턴처럼 다루기
에이전트를 좋은 인턴에게 업무를 투입하는 것처럼 생각하면 이해가 쉽다. 좋은 인턴에게도 한 번에 모든 걸 맡기지 않는다. 지금 뭘 해야 하는지, 어디까지가 범위인지, 어떤 기준으로 결과를 볼 건지 알려줘야 한다. Claude와 서브 에이전트도 마찬가지다
에이전트를 잘 쓰는 사람은 에이전트를 많이 만드는 사람이 아니라, 에이전트마다 충분한 맥락을 유지한 채 작업을 넘겨주는 사람이다
에이전트 친화적 코드베이스
아무리 Claude를 잘 써도 코드베이스 자체가 에이전트 친화적이지 않으면 결과가 흔들린다. 에이전트 친화적 코드베이스의 조건은 다음과 같다
| 조건 | 이유 |
|---|---|
| 테스트 커버리지가 충분한가 | 수정 결과를 검증할 기준이 없으면 에이전트가 오류를 오류로 인식하지 못한다 |
| README와 실제 코드가 일관적인가 | 문서와 코드가 어긋나면 에이전트가 잘못된 이해를 바탕으로 수정안을 만든다 |
| 설계 패턴이 프로젝트 전체에서 비슷한가 | 패턴이 일관되지 않으면 에이전트가 참조 기준을 잡지 못한다 |
| 빌드와 실행 방식이 명확한가 | 실행 방법이 불분명하면 검증 단계 자체가 불가능하다 |
| 스타일과 규칙이 흔들리지 않는가 | 일관성이 없으면 에이전트가 매번 다른 결과를 낸다 |
코드베이스가 약하면 에이전트는 그 약점을 증폭시킨다. 컨텍스트 컨트롤은 프롬프트 기술이 아니라 코드베이스 설계, 테스트, 문서화 수준과 연결된 엔지니어링 문제다
Plan-First, Thinking Mode, Sub-Agent
복잡한 작업일수록 문제를 받자마자 바로 수정하는 방식은 자주 실패한다. 공식 문서는 Explore → Plan → Implement → Commit의 4단계 워크플로우를 권장 흐름으로 명시한다
Plan-First는 느린 것이 아니다. 잘못된 수정, 넓어진 diff, 실패한 테스트, 되돌리기 비용을 줄이는 방식이다
Plan-First가 필요한 신호
다음 세 가지 신호가 보이면 계획부터 세운다
- 영향 범위를 확신할 수 없을 때
- 여러 디렉토리·서비스가 얽혀 있을 때
- 테스트가 약하거나 레거시 코드라 수정 한 번이 연쇄 영향을 만들 수 있을 때
공식 문서의 4단계 플로우는 다음과 같다
1. Explore — Plan 모드에서 파일을 읽고 구조를 파악한다 (파일 수정 없음) 2. Plan — 구현 계획을 작성한다. Ctrl+G로 에디터에서 직접 편집 가능 3. Implement — Plan 모드를 해제하고 구현, 테스트 실행 및 수정 4. Commit — 커밋 메시지 작성 및 PR 생성
좋은 Plan-First는 최소한 다음을 포함해야 한다
1. 지금 해결할 문제 정의 2. 가능한 원인 후보 3. 수정 범위 4. 테스트 검증 순서 5. 반영 전에 멈춰서 확인할 지점
이것 없이 Plan 모드를 썼다면 계획이 아니라 워밍업이다
Sub-Agent – 작업 경계를 분리하는 구조
Sub-Agent는 리드 에이전트가 여러 에이전트를 조율하고, 각 에이전트가 별도의 컨텍스트 윈도우에서 독립적으로 작업한 뒤 요약만 반환하는 구조다. 공식 문서에 따르면, 에이전트 팀이 Plan 모드로 작업할 경우 토큰 소비가 단일 에이전트 대비 약 7배 증가하기 때문에 서브 에이전트는 요약만 반환하도록 설계하는 것이 중요하다
역할이 겹치면 만들지 않는다. 역할이 분명할 때만 만든다. 아직 작업 경계도 모호한데 서브 에이전트부터 여러 개 만들면 혼란만 커진다. 작게 시작하고, 실패 지점을 보면서 늘려야 한다
모드 선택 기준
문제가 단순하고 수정 범위가 명확하다 → 바로 실행 문제가 복잡하고 범위가 넓다 → Plan-First (Explore → Plan → Implement → Commit) 작업 유형이 서로 다르다 → Sub-Agent로 분리 범위는 애매하지만 결과 품질이 중요하다 → Thinking Mode
Thinking Mode는 항상 켜두는 옵션이 아니다. 아키텍처 결정, 복잡한 디버깅, 보안 분석처럼 불확실성이 크고 판단 품질이 실행 속도보다 중요한 문제에서만 쓴다. 단순 파일 수정이나 루틴 리팩터링에는 과하다
Skills vs Tool use – 절차 문제와 실행 문제를 구분한다
Anthropic 문서는 Skills를 “반복 가능한 워크플로우와 전문성을 Claude에게 추가하는 구조”로, Tool use를 “Claude가 도구를 호출해서 실제 작업을 수행하게 하는 레이어”로 설명한다
- Skills: 어떻게 일할지를 재사용하는 것
- Tool use: 무엇으로 실행할지를 확장하는 것
이 구분이 없으면 매번 같은 설명을 반복하거나, 반대로 단순한 절차 문제를 과설계로 해결하려 한다
Skills가 맞는 경우
매번 같은 종류의 로그를 분석하고, 같은 형식의 PR 설명을 쓰고, 같은 체크리스트로 배포 전 점검을 하고 있다면, 이는 도구가 없어서가 아니라 반복 작업이 정의되지 않은 문제다
Skills 안에는 설명, 절차, 허용된 도구 제한(allowed_tools)까지 넣을 수 있어서 Claude가 매번 새로 추측하지 않게 만든다. Skills 후보 예시는 다음과 같다
- 버그 리포트 정리 및 로그 요약
- PR 설명 초안 작성 (
/review-pr) - 배포 전 체크리스트 점검 (
/deploy-staging) - 레거시 코드 읽기 절차
- 특정 프레임워크용 디버깅 루틴
Tool use가 맞는 경우
외부 시스템 조회, 이슈 트래커 접근, 다중 도구 병렬 실행처럼 모델 혼자서는 실행할 수 없는 경우에 Tool use를 쓴다. Skills 안에 설명만 길게 적어봤자 Claude는 실행하지 못한다
선택 기준
작업 절차가 반복되고 외부 연결이 필요 없다 → Skills 외부 시스템 호출, 데이터 조회, 병렬 실행이 필요하다 → Tool use / MCP 둘 다 필요하다 → Skills가 절차를 잡고, Tool use가 실행을 담당
같은 설명을 3번 이상 반복하고 있으면 Skills 후보다. Claude가 절차는 아는데 외부 실행 능력이 없어서 멈추면 Tool use 후보다
Skills는 Claude의 사고 절차를 강화하고, Tool use는 Claude의 손발을 늘린다. 절차 문제를 실행 문제로 착각하면 과설계가 되고, 실행 문제를 절차 문제로 착각하면 Claude는 멈춘다
Claude Code는 프롬프트를 잘 쓰는 도구가 아니라, 규칙·컨텍스트·전략·실행 레이어를 각각 탄탄하게 만들어야 안정적으로 동작하는 작업 시스템이다
출처 – 인프런 [Claude Code Harness Engineering 클로드코드 심화 CLI 하네스 엔지니어링 실무]