Claude Code를 쓰다 보면 어느 순간 이런 질문이 생긴다. "이 AI가 지금 뭘 하고 있는 거지?" 그리고 조금 더 쓰다 보면 더 불편한 질문이 뒤따른다. "내가 이걸 제대로 통제하고 있나?" 프롬프트를 넣고 결과를 받는 것과, 에이전트가 코드베이스를 건드리도록 위임하는 것은 신뢰의 차원이 다르다. 그 차이를 좁히려면 내부 동작 원리부터 파악해야 한다.
Claude Code는 어떻게 움직이나
Mintlify에 정리된 Claude Code 동작 구조를 보면, 핵심은 Agentic Loop라는 6단계 반복 사이클이다. 사용자 입력 → 시스템 프롬프트 조립 → API 호출 → 권한 체크 → 도구 실행 → 결과 피드백, 그리고 도구 호출이 없을 때까지 반복. 단순해 보이지만 각 단계에는 제어 포인트가 숨어 있다.
특히 주목할 부분은 컨텍스트 조립 방식이다. 매 API 호출 앞에는 현재 브랜치, 최근 5개 커밋, git status, CLAUDE.md 파일이 자동으로 붙는다. 이 컨텍스트는 대화 단위로 캐싱되고, 긴 대화에서는 오래된 메시지가 요약(컴팩션)되어 윈도우를 확보한다. 즉, 에이전트가 기억하는 것은 당신이 설계한 파일 구조에 의존한다. CLAUDE.md를 제대로 짜지 않으면 에이전트는 매 세션마다 다른 판단을 내린다.
권한 모델도 명확히 세 갈래다. allow(즉시 실행), ask(확인 요청), deny(차단). 파일 읽기 같은 읽기 전용 도구는 기본 자동 승인이고, bash 명령은 acceptEdits 모드에서도 여전히 확인을 요청한다. 이 구조를 알면 "에이전트가 왜 여기서 멈추지?"라는 질문 대신, "어떤 권한 정책을 설계해야 하나?"라는 질문으로 넘어갈 수 있다.
규칙이 아니라 강제 메커니즘이 필요하다
25개 레포를 Claude Code로 관리하는 개발자가 dev.to에 올린 사례는 이 문제를 정면으로 건드린다. 그의 결론은 간단했다. "규칙을 추가하는 것은 작동하지 않는다. 강제 메커니즘을 만들어야 한다."
그가 겪은 문제 세 가지는 실제로 현장에서 흔히 마주치는 패턴이다. 첫째, 에이전트가 정보를 잘못된 위치에 쓴다. 프로젝트 상태를 SESSION.md에 써야 하는데 ~/.claude/ 메모리 디렉토리에 넣는다. 메모리는 Git에 올라가지 않고 다른 머신에서 보이지 않으니 협업이 깨진다. 둘째, 컨벤션 파일이 계속 비대해진다. 컨텍스트 압축을 방지하려고 만든 파일이 오히려 컨텍스트를 잡아먹는 역설. 셋째, 문서가 조용히 현실과 어긋난다. README는 섹션 9를 참조하는데 실제로는 섹션 5로 바뀐 지 오래다.
해결책은 Claude Code의 Hook 기능을 활용하는 것이다. 도구 호출 전후에 실행되는 셸 스크립트로, 잘못된 동작을 물리적으로 차단할 수 있다. 메모리 디렉토리 쓰기를 가로채는 PreToolUse 훅을 예로 들면, 에이전트가 잘못된 경로에 쓰려 할 때 exit 2로 차단하고 어디에 써야 하는지 결정 테이블을 보여준다. 컴파일러 에러처럼 작동하는 문서 가이드다. 규칙은 컴팩션으로 사라지지만, 훅은 사라지지 않는다.
파일 예산 관리도 같은 논리로 적용된다. SESSION.md는 80줄 예산을 두고, 매 푸시 전에 완료된 태스크는 삭제(어차피 git log에 있다), 영구 결정사항은 CLAUDE.md로 이동하는 하우스키핑을 자동화한다. "push 전에 체크하라"는 막연한 규칙 대신, 4축 리뷰(일관성·비모순성·효율성·안전성)를 구조화하면 인간 리뷰어가 놓칠 만한 번호 불일치, 오래된 참조, 중복 정보를 매번 잡아낸다.
가장 무서운 문제: 아키텍처 드리프트
훅과 파일 관리가 세션 내 일관성을 잡는다면, 크로스 세션 아키텍처 드리프트는 더 깊은 층위의 문제다. dev.to에서 'Week Seven Wall'이라고 명명된 이 현상은 AI 코딩이 처음엔 마법처럼 느껴지다가 7주 차쯤 조용히 무너지기 시작하는 패턴을 가리킨다.
메커니즘은 이렇다. 첫 번째 세션에서 앱이 단순하니 SQLite를 선택한다. 세 번째 세션에서 스케줄링이 필요해 Celery를 붙인다. 다섯 번째 세션에서 동시 쓰기가 발생한다. 각각의 결정은 그 맥락에서는 합리적이다. 하지만 세션을 가로질러 보면 서로 모순되는 아키텍처가 쌓여 있다. 누가 명시적으로 이 조합을 선택한 게 아니다. 드리프트는 의도 없이 축적된다.
이 문제를 해결하려고 Axiom Hub라는 로컬 MCP 서버가 제안되었다. 개념은 단순하다. 아키텍처 결정을 세션 간에 저장하고, 새로운 결정이 이전 결정과 충돌하면 플래그를 올리고, 인간이 어느 경로가 맞는지 판단하게 한다. 결정의 '왜'까지 저장하는 것이 핵심이다. Claude Haiku로 모순 감지, Kuzu 그래프 DB로 관계 매핑, FastAPI 대시보드로 리뷰 인터페이스를 구성한다. 여전히 초기 단계지만 방향은 명확하다. AI가 결정하고 인간이 "yes"를 누르는 구조 대신, 인간이 결정의 맥락을 유지하는 구조.
테크 리드가 지금 당장 설계해야 할 것
세 개의 문제를 하나의 프레임으로 연결하면 이렇게 된다. Claude Code를 통제 가능한 팀원으로 쓰려면 세 겹의 제어 레이어가 필요하다.
- 내부 구조 이해: Agentic Loop와 컨텍스트 조립 방식을 알면 CLAUDE.md 설계가 달라진다. 에이전트가 무엇을 읽고 어떻게 판단하는지 모르면 규칙은 언제든 컴팩션으로 사라진다.
- Hook 기반 행동 강제: 규칙이 아닌 메커니즘으로 잘못된 동작을 차단한다. 특히 파일 쓰기 경로, 문서 예산, 푸시 전 리뷰는 훅으로 강제하면 인간의 반복 검토 비용이 사라진다.
- 크로스 세션 결정 추적: 세션이 길어질수록 맥락 없는 결정이 쌓인다. 아키텍처 결정의 이유를 기록하고, 새 결정이 기존 결정과 충돌하는지 감지하는 구조 없이는 Week Seven Wall을 피하기 어렵다.
Claude Code는 빠르다. 그 속도가 진짜 가치가 되려면 속도만큼 통제 구조도 따라가야 한다. 프롬프트를 잘 쓰는 것과 에이전트 행동을 설계하는 것은 다른 기술이다. 지금 대부분의 팀이 전자에 집중하는 동안, 후자를 먼저 설계한 팀이 6개월 뒤에 코드베이스를 지배하고 있을 것이다.