Claude Code의 하네스 설계: 계층형 메모리·5단계 compaction·hooks

왕초보 설명

  • 이게 뭐야? Anthropic이 만든 터미널 AI 코딩 도구 Claude Code를 “하네스(AI를 감싸는 작업 환경)” 관점에서 뜯어본 코스 글이다. 핵심은 AI가 도는 루프 자체는 단순하고, 그 루프를 둘러싼 장치들(기억 파일, 대화 압축, 권한, 자동 검사)이 신뢰성을 만든다는 것.
  • 비유: 자동차 엔진(모델)은 그대로인데 안전벨트·ABS·블랙박스(하네스)가 사고를 줄인다.
  • 나는 뭘 하면 돼? 프로젝트 폴더에 CLAUDE.md를 두고 빌드·테스트 명령을 적는다. 처음이면 /init이 자동으로 초안을 만든다. 대화가 길어지면 /compact, 새 주제면 /clear. 반드시 지킬 검사는 말로 부탁하지 말고 hook(작업 전후에 자동으로 도는 스크립트)으로 건다.

구조 요약

한 문장: 모델 호출 → 도구 실행 → 결과 관찰 → 재호출을 반복하는 단순한 while 루프. 코드 대부분은 루프 안이 아니라 루프를 둘러싼 시스템(permissions, compaction 파이프라인, 확장, subagent 오케스트레이션, session 저장소)에 있다.

다섯 하위 시스템으로 보기(harness-subsystems, 원문 매핑 표)

하위 시스템Claude Code의 구현원문 평가
지시범위별 계층화(조직/사용자/프로젝트/로컬) + 자동 메모리계층형 메모리의 모범 구현
도구스킬 + MCP + hooks + subagent 네 가지 확장책임 구분이 명확한 핵심 강점
환경프로젝트 내 설정 + settings.jsonCLAUDE.md에서 사용자가 직접 설명하는 데 의존
상태추가 지향 session 저장소 + 5단계 compaction + resume/fork장기 작업 연속성의 참고 구현
피드백permissions 분류기 + PostToolUse hooks 강제 검사조기 완료 선언 방지를 결정론적 메커니즘으로

지시: CLAUDE.md 네 범위(넓은 범위 → 좁은 범위 순으로 로드, 더 구체적인 지시가 컨텍스트에 더 늦게 들어감)

범위위치내용
조직 정책예: /etc/claude-code/CLAUDE.md회사 규범(IT/DevOps 관리)
사용자~/.claude/CLAUDE.md여러 프로젝트에 쓰는 개인 선호
프로젝트./CLAUDE.md 또는 ./.claude/CLAUDE.md구조·기술 스택·검증 명령, 저장소에서 공유
로컬./CLAUDE.local.md프로젝트 안 개인 선호, 보통 .gitignore

추가로 하위 디렉터리 CLAUDE.md는 그 디렉터리 파일을 읽을 때만 로드되고, auto memory는 Claude가 직접 쓰는 메모로 session마다 최대 첫 200줄 또는 25KB를 로드한다. 원문은 이것을 lecture-04 “거대한 지시 파일” 문제의 제품화된 답으로 본다(map-not-manual).

컨텍스트: 5단계 compaction 파이프라인(VILA Lab 소스 분석 인용): 무손실 가지치기(중복 도구 결과 제거) → 구조화된 정제 → 마지막에야 손실 있는 LLM 요약, 과도한 압축을 막는 회로 차단기. 여기에 모든 기록을 history.jsonl에 추가만 하는 session 저장소, /resume 복구와 fork가 결합된다. “인계는 기억이 아니라 저장 계층으로 보장한다.”

도구: 네 가지 확장과 책임 분리

확장맡는 것한 줄
스킬 SKILL.md어떻게 하는가트리거 단어로 자동 로드, 점진적 공개
MCP어디에 연결하는가JSON-RPC로 외부 시스템 연결
Hooks언제 강제하는가PreToolUse·PostToolUse·Stop 등 생명주기 이벤트에 붙는 결정론적 스크립트
Plugin / Subagents누구에게 나누는가전문 agent에게 하위 작업

CLAUDE.md는 “무엇인가”를 맡는다. 이 층을 섞으면(예: MCP가 할 일을 CLAUDE.md에 적기) 컨텍스트 누수가 생긴다.

피드백

  1. Permissions: 7가지 모드 + ML 분류기. 저위험은 허용, 고위험은 정책에 따라 질문·거부. 경계를 프롬프트로 부탁하지 않고 런타임에서 강제(lecture-07).
  2. Hooks: PostToolUse가 도구 실행 뒤 검사를 강제하고 결과를 컨텍스트에 기록, Stop은 완료 선언 시점에 개입. Anthropic이 관찰한 “agent가 자기 작업을 자신 있게 칭찬”하는 현상에 대한 결정론적 대응(lecture-09, maker-checker-separation).
  3. Subagent: 대화 기록을 독립 sidechain 파일에 저장해 부모 컨텍스트를 부풀리지 않는다.

관찰·영속화: history.jsonl 전체 기록, /compact·/clear·/init 명령. /init은 코드베이스를 분석해 빌드 명령·테스트·규약을 담은 초기 CLAUDE.md를 만든다(lecture-06의 초기화를 명령 하나로).

원문이 꼽는 참고할 설계: ① 지시를 범위별로 계층화 ② compaction은 무손실 먼저, 손실 나중의 깔때기 ③ hooks로 결정론적 검사 ④ subagent 컨텍스트 격리 ⑤ session 저장소는 추가 지향·재생 가능.

다른 하네스와의 비교

항목claude-code (이 페이지)codexdeepseekpioh-my-claudecodegajae-code
정체Anthropic의 공식 CLI. 단순한 while 루프 + 루프를 둘러싼 시스템OpenAI의 오픈소스 Rust 단일 바이너리 CLI. 《Harness Engineering》 글의 배경dsh, 2026-08 Developer Preview. Agent = Model + Environment + Tools + State, 모든 것이 plugin(Cordis 커널)“minimal agent harness”. npm @earendil-works/pi-coding-agent. 작은 커널 + 프로그래밍 가능한 확장Claude Code 위에 얹는 플러그인독립 실행 CLI 하네스(oh-my-pi 계열)
지시CLAUDE.md 4범위(조직/사용자/프로젝트/로컬) + 하위 디렉터리 필요 시 로드 + auto memory(첫 200줄 또는 25KB)AGENTS.md = 약 100줄 디렉터리 페이지 + docs/ 분할, 불변 조건과 검증 명령만규칙·스킬을 plugin으로 주입. CLAUDE.md 같은 내장 규약 없음AGENTS.md 계층 로드(전역 → 상위 디렉터리 → 현재, CLAUDE.md 호환) + SYSTEM.md replace/append스킬 48개, 에이전트 19개 + 키워드 자동 감지번들 스킬 4개 + 역할 4개만, 명시적으로 부를 때만
계획 단계원문(분석 글)에 서술 없음plan mode(고위험 작업 전 계획 작성·승인 요청)원문(분석 글)에 서술 없음원문(분석 글)에 서술 없음deep-interview(모호함 ≤20%) → ralplandeep-interview(기본 기준 5%) → ralplan(최대 5회, 코드로 수정 차단)
실행 루프모델 호출 → 도구 실행 → 관찰 반복. lecture-13: /goal, /loop, Routines원문(분석 글)에 서술 없음. lecture-13: /goal(수동 활성화), Automations, codex exec + cron이벤트 파이프라인(turn/start → … → step/end). agent 루프 자체도 교체 가능한 pluginwhile 루프. TUI 외에 print/JSON 모드·RPC·SDK로 외부 프로그램이 구동ralph(prd.json 이야기별 반복), autopilot, team 5단계ultragoal(goals.json 목표별 반복 + goal 모드)
계속 돌게 하는 장치Stop hook이 완료 선언 시점에 개입 가능(OMC가 이 지점을 사용)원문(분석 글)에 서술 없음. lecture-13: 스레드 자동화·독립 실행형 자동화agent/turn-stopping 이벤트를 받아 추론 계속 여부 결정hooks로 외부(파일 감시·Webhook·CI)에서 메시지를 넣어 agent를 깨움Stop 훅(persistent-mode)이 턴 종료를 막음, 안전 상한 기본 500회goal 모드 연속 실행 + nudgeBudget(목표당 기본 10회)
상태append-only history.jsonl + /resume·fork + 5단계 compactionWrite 전략(상태를 파일·문서에) + 자동·수동 /compact(compact_prompt 설정)append-only Session Event Logsession 트리(/tree, 한 파일에 모든 브랜치) + 교체 가능한 compaction(최근 약 2만 token 유지).omc/state/sessions/<id>/prd.json, progress.txt.gjc/_session-<id>/ultragoal/goals.json, ledger.jsonl
피드백permissions 7모드 + ML 분류기, PostToolUse hook 강제 검사검증 명령을 AGENTS.md 규약에, 작업마다 git worktree + 로그·메트릭·트레이스로 검증tools/pre-execute의 permission·guard·policy·hook + “Model-visible means logged” 런타임 불변 조건강제 테스트 gate 없음. 검증 명령은 사용자가 AGENTS.md에. 커뮤니티 확장 session-summary·extract-patterns·telemetryomc ralph verify가 기준선 대비 새 실패만 판정, 리뷰어 검증목표별 quality-gate + 마지막 경계 검토 + 종료 critic OKAY
역할 분리subagent 대화를 별도 sidechain 파일로 격리spawn_agent/wait_agent subagent, .codex/agents/*.toml로 모델·지시 지정SubAgent도 교체 가능한 능력 접합부(capability seam)원문(분석 글)에 서술 없음단계별로 다른 에이전트·모델 등급(haiku/sonnet/opus)읽기 전용 planner·architect·critic vs 쓰기 가능한 executor
사람 개입permissions 정책에 따라 고위험 작업은 질문 또는 거부승인 정책(approval policies) + plan mode원문(분석 글)에 서술 없음hooks로 위험 명령 가로채기(permissions gate)·경로 보호매직 키워드만 말하면 자동 진행기본은 계획 승인 1회. autoHandoff=ultragoal이면 0회
왕초보에게기본 내장이 많아 바로 쓴다. 확장 4종(스킬·MCP·hooks·subagent)의 역할 구분은 배워야 한다기능보다 규약. 저장소를 잘 정리해 둘수록 효과가 커진다자유도가 가장 높지만 설정 비용도 가장 크다. 아직 Developer Preview가장 가볍지만 필요한 장치는 직접 만들거나 패키지로 설치해야 한다기능이 많아 강력하지만 무겁다흐름이 하나라 배우기 쉽다. 대신 git 필수
  • 코스 개관 글(harness-designs/index.md)은 네 제품을 이렇게 한 줄로 대비한다: Pi = 극도로 단순한 커널 + 프로그래밍 가능한 확장, Claude Code = 완전한 실행 환경, Codex = 저장소를 사실의 원천으로 삼고 AGENTS.md는 디렉터리 페이지로, DeepSeek = 하네스 자체를 모델과 독립된 런타임으로.
  • oh-my-claudecode는 Claude Code 위에 얹는 플러그인이다. 이 페이지의 장치 중 OMC가 직접 기대는 것은 Stop hook(지속 모드 persistent-mode가 턴 종료를 막음)과 스킬·에이전트 정의다. 즉 “Claude Code가 주는 것 = hooks·스킬·subagent라는 부품, OMC가 더하는 것 = 그 부품으로 짠 ralph·team·autopilot 워크플로와 키워드 자동 감지”.
  • gajae-code는 Claude Code를 쓰지 않는 독립 CLI지만, 프로젝트 지시 파일·스킬·역할 agent라는 같은 층 구분을 쓴다.

원문 경로

  • ko: raw/learn-harness-engineering/docs/ko/harness-designs/claude-code/index.md
  • en: raw/learn-harness-engineering/docs/en/harness-designs/claude-code/index.md
  • 개관: raw/learn-harness-engineering/docs/ko/harness-designs/index.md (코스 하네스 4개의 aux로 등록)
  • 원문이 드는 1차 출처: Claude Code 공식 문서(Memory, Skills, MCP, Hooks, Sub-agents), VILA Lab 《Dive into Claude Code》 소스 분석 보고서(5단계 compaction, 7 permissions 모드, sidechain, history.jsonl), Anthropic 《Effective harnesses for long-running agents》. 이 위키는 이 외부 문서들을 직접 확인하지 않았다.
  • 원문 끝 관련 강의는 강의 3·9·10이다. 본문은 강의 4·5·6·7·10도 언급한다.