Claude Code에 큰 작업 하나를 통째로 맡기면 에이전틱 루프보다 컨텍스트 윈도우가 먼저 바닥난다

Claude Code는 맥락 파악·행동·검증 루프를 다섯 묶음의 도구로 스스로 돌린다. 루프가 도는 작업 기억인 컨텍스트 윈도우는 유한해, 차면 초반 지시부터 잊는다. 작업을 잘라 /clear로 끊고 CLAUDE.md에 규칙을 적어 뒀는지 먼저 확인한다.

Claude Code를 처음 쓰는 팀에서 가장 먼저 나오는 불만은 "아까 말한 거 왜 까먹어?"다. 세션 초반에 준 지시가 작업이 길어질수록 지켜지지 않는다. 이를 모델 지능의 문제로 읽기 쉽지만, 원인은 다른 데 있다.

이 글은 2026년 2월 기준이다. 우리는 2026년 2월 27일 네이버 글에서 Anthropic 공식 문서 "How Claude Code Works"를 바탕으로 Claude Code의 동작 구조를 정리했다. 결론은 하나다. 자율성은 도구가 만들지만 그 범위는 컨텍스트 윈도우가 정하므로, 큰 작업 하나를 통째로 맡기는 것보다 작은 작업 여러 개로 쪼개 맡기는 쪽이 결과가 좋다.

자율성은 세 단계 루프와 도구 다섯 묶음에서 나온다

Claude Code는 터미널에서 도는 에이전트형 코딩 도구다. 열린 파일 하나를 보고 다음 줄을 제안하는 자동완성과 달리, 프로젝트 전체를 읽고 여러 파일을 고치며 터미널 명령을 직접 실행한다. 뼈대는 에이전틱 루프다. 맥락 파악(파일 검색·읽기), 행동 실행(파일 수정·명령 실행), 결과 검증(테스트·빌드·오류 확인)을 스스로 반복한다.

세 단계는 한 번씩 순서대로 지나가지 않는다. "인증 버그를 고쳐 줘"라는 요청이면 파일을 검색하고, 여러 파일을 읽어 흐름을 잡고, 원인을 고치고, 테스트를 돌리고, 실패하면 다시 고치고, 통과하면 커밋한다. 앞 단계의 결과가 다음 단계의 입력이 되며, 사용자는 중간에 끼어들 수 있다. 루프를 실제로 돌리는 것은 도구이고, 내장 도구는 다섯 묶음으로 나뉜다.

묶음	도구	루프에서의 역할
읽기	Read, LS	파일 내용·디렉터리 구조 파악
검색	Grep(ripgrep), Glob	수천 파일 중 대상 좁히기
편집	Write, Edit/MultiEdit	파일 생성·수정
실행	Bash	빌드·테스트·Git 등 CLI 전부
웹	WebFetch, WebSearch	최신 문서·API 레퍼런스 참조

도구가 실행될 때마다 결과가 모델로 돌아오고, 모델은 그 결과를 보고 다음 도구를 고른다. 우리가 교육에서 매번 짚는 구분이 여기 있다. 모델이 똑똑한 것과 일을 해내는 것은 별개이고, 웹 채팅이 전자에 머무는 동안 Claude Code는 다섯 묶음의 도구로 후자에 닿는다. 도구 선택도 모델의 판단이므로 요청이 모호하면 거기서부터 어긋난다.

루프가 도는 공간은 유한하고, 그 공간에 파일·명령 결과·CLAUDE.md가 함께 들어간다

claude를 프로젝트 디렉터리에서 실행하면 네 가지에 접근한다. 현재 디렉터리와 하위의 프로젝트 파일, 터미널, 브랜치·미커밋 변경·최근 커밋 같은 Git 상태, 그리고 CLAUDE.md다. CLAUDE.md는 프로젝트 루트의 마크다운 파일로 매 세션 시작 시 자동으로 읽히며, 코딩 규칙과 빌드·테스트 명령을 적는 자리다. /init이 초안을 만든다.

이 모든 것이 컨텍스트 윈도우 하나에 쌓인다. 대화 내역, 읽은 파일, 명령 실행 결과, CLAUDE.md, 시스템 지시가 같은 공간을 쓰고, 공간은 유한하다. 작업이 길어질수록 차오르고, 가득 차면 성능이 떨어지며 초반 지시부터 잊는다. "아까 말한 거 왜 까먹어?"는 여기서 나온다.

한계에 가까워지면 Claude Code가 자동 컴팩션을 수행한다. 핵심 코드 패턴, 파일 상태, 주요 결정은 남기고 나머지 대화를 정리하는데, 무엇을 남길지는 도구가 정한다. 그래서 우리는 컴팩션에 맡기기 전에 사용자가 먼저 관리하기를 권한다. 관련 없는 새 작업 전에는 /clear로 초기화하고, /compact는 "API 변경사항에 집중해 줘"처럼 요약 기준을 붙여 수동으로 부른다. 읽을 것이 많은 리서치·리뷰는 서브에이전트에 맡겨 독립 컨텍스트에서 처리하고 요약만 메인으로 받는다. 압축 뒤 목표 표류가 커지는 문제는 Claude Code Dynamic Workflows 글에서 다뤘다. 세션도 같은 원리다. 새 세션은 이전 세션을 기억하지 않으므로 --resume으로 잇고 --fork-session으로 가르며, 같은 프로젝트 폴더에서 연 세션만 불러온다.

안전망과 확장 레이어는 루프 바깥에 붙는다

권한을 넘기는 편리함과 통제의 안정성은 트레이드오프이고, Claude Code는 안전장치 둘을 둔다. 체크포인트는 파일을 고치기 전 원본 스냅샷을 자동 저장해 언제든 되돌린다. 권한 시스템은 위험한 명령 실행 전에 사용자에게 묻고, 허용 규칙은 /permissions로 정한다.

확장은 내장 도구 위에 층으로 쌓인다. Skills는 반복 절차를 md 파일로 저장한 워크플로우, MCP는 Jira·Slack·DB 같은 외부 시스템을 잇는 프로토콜, Hooks는 편집 후 린터처럼 특정 행동 전후에 자동으로 도는 스크립트다. 서브에이전트는 리뷰·테스트·문서 갱신을 병렬로 나눠 맡는 독립 인스턴스이고, 플러그인은 마켓에서 기능을 더한다. 입구는 터미널 CLI, VS Code·JetBrains, 웹, Slack까지 여럿이지만 CLAUDE.md·설정·MCP 연결이 공유돼 내부 동작은 같다.

가져갈 것

Claude Code를 팀에 들이기 전에 예/아니오로 답할 체크리스트다.

• 프로젝트 루트에 CLAUDE.md가 있고 빌드·테스트 명령과 코딩 규칙이 적혀 있는가 (없으면 /init으로 초안부터)
• 요청을 한 세션 안에서 끝날 크기로 자르고, 관련 없는 작업으로 넘어갈 때 /clear를 치는가
• 긴 세션에서는 /compact에 "API 변경사항에 집중" 같은 기준을 붙여 먼저 부르는가
• 읽을 파일이 많은 리서치·리뷰는 서브에이전트로 떼어 요약만 메인 컨텍스트에 받는가
• /permissions에 허용 규칙을 정했고, 위험한 명령은 실행 전 확인을 받도록 남겨 두었는가

안 되는 경우

• 우리가 원문에 적지 않은 것: 컨텍스트 윈도우의 실제 크기, 자동 컴팩션이 시작되는 임계값, 요약에서 무엇이 남고 버려지는지의 정확한 규칙, 요금제·모델별 차이.
• 이 글은 2026년 2월 기준이다. 도구 이름(LS·MultiEdit), 슬래시 명령, --fork-session 같은 옵션은 버전마다 바뀌므로 도입 시점의 공식 문서로 다시 확인한다.
• 열린 파일 하나에서 다음 줄을 받는 자동완성이 주 용도인 팀. Claude Code는 Copilot류와 달리 프로젝트 전체를 읽고 명령을 실행하므로 컨텍스트 관리와 권한 설정 부담이 따라온다.

이번 주에 바꿀 것은 하나다. Claude Code에 통째로 맡겼다가 초반 규칙이 빠진 채 끝난 작업 하나를 골라, 그 규칙을 CLAUDE.md로 옮기고 작업을 세션 단위로 잘라 /clear 사이에 넣은 뒤 결과를 비교한다. 작업을 어느 크기로 자를지 팀 기준을 세우는 일은 조녁컴퍼니 사업영역에 정리돼 있다. 사업영역 →