Claude Code 를 하네스 로 본 그림 — chat session·Phase, 역할/금지/목표, Skill·MCP·Tool·hook

모델 은 못 바꾼다. 우리 가 바꿀 수 있는 건 모델 을 감싸는 껍데기 — 하네스(harness) 다. 하네스 엔지니어링 은 그 껍데기 를 설계 하는 실천 이고, 위 그림 은 그 껍데기 의 부품 을 한 장 에 그린 것 이다. 이 글 은 그림 을 부품 별 로 해부 한다.

같은 모델 이라도 하네스 가 다르면 결과 가 다르다. LLM 은 엔진, 하네스 는 차체·변속기·핸들. 엔진 은 벤더 가 주지만, 차 는 하네스 가 만든다.

1. 큰 상자 — 하네스 자체

그림 의 바깥 상자 가 하네스(=Claude Code 같은 에이전트 런타임) 다. 그 안 에 모델 이 앉아 있고, 나머지 부품 들 이 모델 의 입력·능력·행동·경계 를 규정 한다. 핵심 은 이거다 — 모델 은 이 상자 안 에서만 세상 을 본다. 상자 를 잘 설계 하는 게 곧 성능 이다.

2. chat session + Phase — 작업 컨텍스트 와 그 진행

왼쪽 의 chat session 이 지금 도는 작업 의 컨텍스트 다. 그 안 의 Phase: 0 / 1 / 2 가 중요 하다 — 하나 의 세션 이 단계 로 나뉜다는 것. 계획 → 실행 → 검증 처럼 국면 을 쪼개면, 각 국면 이 필요한 것 만 컨텍스트 에 담는다.

여기 출력: Return Something 도 붙어 있다. 세션 의 산출 이 잡담 이 아니라 구조화 된 반환값 이라는 표시 다. 서브에이전트 의 마지막 텍스트 가 곧 리턴값 이 되는 그 설계 — 하네스 가 출력 의 형태 를 강제 한다.

3. 역할 / 금지 / 목표 — 행동 을 빚는 시스템 프롬프트

가운데 상자 의 세 줄 — 역할: Persona, 금지: 원칙, 목표 — 이 시스템 프롬프트(또는 CLAUDE.md) 의 뼈대 다. 모델 을 미세조정 하지 않고 도 행동 을 빚는 세 손잡이:

  • 역할(Persona) — “너 는 무엇 인가”. 톤·전문성·관점 을 고정
  • 금지(원칙) — “무엇 을 하지 말라”. 안전선·경계. 하지 말 것 을 못 박는 게 시니어 의 일 인 것 처럼, 하네스 도 금지 로 사고 를 막는다
  • 목표 — “무엇 을 향하나”. 판단 의 기준점

이 셋 은 문제정의 를 시스템 레벨 에 박아 넣는 것 이다. 좋은 프롬프트 = 좋은 스펙 = 좋은 하네스 설정.

4. Skill × 3 — 재사용 가능한 능력 패킷

오른쪽 위 의 Skill 세 개. 스킬 은 그때그때 프롬프트 로 설명 하던 절차 를 재사용 가능한 단위 로 굳힌 것 이다. 필요할 때 로드 되고, 안 쓰면 컨텍스트 를 안 먹는다. 하네스 의 플러그인 — 능력 을 모듈 로 꽂고 뺀다.

핵심 은 지연 로딩. 스킬 이 100개 여도 컨텍스트 를 항상 먹지 않는다. 필요할 때 만 펼쳐지는 능력 — 이게 컨텍스트 예산 을 지키는 하네스 의 지혜 다.

5. MCP — 외부 세계 로의 창

MCP(Model Context Protocol) 는 하네스 를 바깥 시스템 에 연결 하는 표준 콘센트. GitHub·Slack·DB·디자인 툴 을 같은 규약 으로 붙인다. 스킬 이 내부 능력 이라면 MCP 는 외부 연동 이다. 하네스 가 자기 상자 밖 의 세상 과 대화 하는 통로.

6. Tool — 행동 의 손

Tool 은 모델 이 실제 로 뭔가 를 하는 수단 — 파일 읽기·쓰기, 명령 실행, 검색. 모델 은 말 하지만, 툴 이 있어야 행동 한다. 하네스 는 어떤 툴 을 줄지 로 모델 의 권한 을 정한다. 읽기전용 만 줄지, 쓰기 까지 줄지 — 이게 멀티 에이전트 에서 checker 에게 읽기만 주는 그 설계 다.

7. hook — 결정론적 개입

그림 에서 선택 돼 있는 hook. 훅 은 모델 이 아니라 하네스 가 결정론 으로 실행 하는 지점 이다. “매번 X 하면 Y 해라” 는 모델 의 판단 이 아니라 훅 이 처리 한다 — 커밋 전 린트, 툴 호출 가로채기, 특정 이벤트 자동 대응.

이게 왜 중요 하냐면, 모델 은 확률적 이고 훅 은 확정적 이기 때문. 반드시 일어나야 하는 일 은 모델 에게 부탁 하지 말고 훅 에 박는다. 하네스 의 가드레일 이자 자동화 의 자리.

8. 그래서 — 하네스 · 루프 · 멀티 에이전트 는 한 그림 의 세 축

이 부품 들 이 어떻게 최근 담론 과 이어지나:

개념 이 그림 에서 축
하네스 엔지니어링 상자 와 부품 전체 구조 (무엇 으로 감싸나)
멀티 에이전트 상자 를 여러 개 띄워 역할 분담 공간 (누가 하나)
loop engineering 상자 를 트리거 로 반복 기동 시간 (언제·몇 번 하나)

Osmani 도 loop engineering 을 “타이머 로 돌고, 헬퍼 를 낳고, 스스로 를 먹여 살리는 하네스” 라 불렀다. 즉 하네스 가 원자 단위 이고, 그걸 공간(멀티) 과 시간(루프) 으로 확장 한 게 요즘의 에이전트 시스템 이다.

마무리 — 능력 은 모델 에서, 결과 는 하네스 에서

내 홈랩·개발 환경 도 이 그림 그대로 다 — CLAUDE.md(역할·금지·목표), 프로젝트별 Skill, 텔레그램·k8s MCP, 읽기/쓰기 Tool, 커밋·배포 훅. 모델 은 남 이 만든 걸 쓰지만, 이 껍데기 만큼은 내 가 설계 한다.

AX 시대 에 실력 차 는 “누가 더 좋은 모델 을 쓰나” 가 아니라 “누가 더 좋은 하네스 를 설계 하나” 에서 난다. 엔진 은 평준화 된다. 차 를 만드는 건 여전히 사람 이다.