하네스 엔지니어링 위키

Claude Code 공식문서 — 핵심 개념

Properties1
tags공식문서, 개념

17 min read

Claude Code 공식문서 — 핵심 개념

Claude Code 공식문서(code.claude.com/docs, 한국어 우선·영문 보완)에서 하네스 엔지니어링 학습에 핵심인 개념을 뽑아 비개발자도 이해할 수 있게 정리한 노트. 관련 개념틀은 하네스엔지니어링이란, 용어 정의는 용어집 참고.

한 줄 요약

Claude Code는 똑똑하지만 혼자선 말밖에 못 하는 AI 모델에게 컨텍스트·툴·가드레일·검증 네 가지를 둘러 씌워 “일하는 코딩 에이전트”로 바꾸는 하네스(작업용 마구) 다. → 왜 배우나: 하네스를 이루는 20여 개 개념을 이 4기둥으로 묶어 이해하면, 도구가 아무리 늘어나도 “이건 어느 기둥의 부품인가”로 정리할 수 있기 때문이다.

그림

flowchart TD
    M["AI 모델<br/>(말만 할 수 있음)"] --> H{"하네스<br/>(작업용 마구)"}
    H --> C["기둥1 · 컨텍스트<br/>무엇을 아는가"]
    H --> T["기둥2 · 툴<br/>무엇을 할 수 있는가"]
    H --> G["기둥3 · 가드레일<br/>무엇을 못 하게 막는가"]
    H --> V["기둥4 · 검증<br/>제대로 됐는지 확인"]
    C & T & G & V --> A["유능한 코딩 에이전트"]

flowchart LR
    S(["작업 받음"]) --> L1["① 컨텍스트 수집<br/>파일·규칙·메모리 읽기"]
    L1 --> L2["② 작업 수행<br/>툴로 실제 행동"]
    L2 --> L3["③ 결과 검증<br/>정답지와 대조"]
    L3 -->|"아직 안 됨"| L1
    L3 -->|"완료"| E(["작업 끝"])

쉽게 풀기

Claude Code는 자기 자신을 “에이전트 하네스(agent harness)” 라고 정의한다. 공식문서의 핵심 문장은 이렇다.

“Claude Code는 Claude 주변의 에이전트 하네스 역할을 합니다: 언어 모델을 능력 있는 코딩 에이전트로 변환하는 도구, 컨텍스트 관리, 실행 환경을 제공합니다.”

비유로 풀면 — 모델은 막 입사한 유능한 신입 직원이다. 머리는 좋지만 회사 사정도, 권한도, 장비도 없다. 하네스는 그 직원에게 다음 네 가지를 챙겨 준다.

  • 업무 매뉴얼(컨텍스트) — “우리 회사는 이렇게 일해요”를 알려주는 자료. 무엇을 아는가.
  • 출입권·장비(툴) — 사무실 문을 열고, 컴퓨터를 켜고, 실제로 손을 움직이게 해 주는 권한. 무엇을 할 수 있는가.
  • 결재 규정(가드레일) — “이건 팀장 승인 받고 해야 해요”처럼 함부로 못 하게 막는 규칙. 무엇을 못 하나.
  • 검수 체크리스트(검증) — 다 한 뒤 “제대로 됐나” 스스로 대조하는 기준. 정말 끝났나.

이 신입은 혼자 일하지 않는다. 작업을 받으면 ① 필요한 자료를 모으고 → ② 실제로 일하고 → ③ 결과를 검수하고, 안 됐으면 다시 ①로 돌아간다. 이 끝없는 순환이 에이전트 루프이며, 4기둥 전체를 돌리는 엔진이다.

아래에서 20여 개 개념을 이 4기둥 순서로 따라간다. 각 개념은 “신입 직원에게 무엇을 챙겨 주는 일인가”로 읽으면 쉽다.

기둥 1 — 컨텍스트 (무엇을 아는가)

AI의 “작업 기억”은 책상 위 공간과 같다. 좁고, 가득 차면 오래된 서류가 밀려난다. 그래서 무엇을 올려두고, 어떻게 비우고, 무엇을 따로 보관할지가 전부다.

  • 에이전트 루프 — ①수집 → ②수행 → ③검증을 작업이 끝날 때까지 반복하는 순환.
  • 컨텍스트 윈도우 — 한 번에 책상에 올려둘 수 있는 작업 기억의 크기. 대화·파일·명령 출력·지침이 다 여기 들어가며, 꽉 차면 오래된 게 밀려난다.
  • 자동 압축(Auto-Compaction) — 책상이 꽉 차면 옛 도구 출력부터 치우고 대화를 요약해 자리를 비우는 자동 청소. 단, 초반 지침이 함께 쓸려나갈 수 있어 중요한 규칙은 따로 적어둬야 한다.
  • CLAUDE.md — 사람이 직접 쓰는 “프로젝트 업무 매뉴얼”. 매 세션 시작마다 자동으로 읽힌다.
  • 자동 메모리(MEMORY.md) — AI가 일하며 스스로 알아낸 요령을 저장소별로 적어 두고 다음 세션에 다시 읽는 학습 노트(첫 200줄/25KB만 자동 로드).
  • 경로 범위 규칙(.claude/rules/) — “이 종류 파일 건드릴 때만 적용”되는 규칙. 평소엔 책상을 차지하지 않다가 해당 파일을 열 때만 불려 나온다.
  • 세션 / 체크포인트 — 모든 대화·도구사용은 로컬에 기록(세션)되어 재개·복제가 되고, 파일 수정 직전마다 스냅샷(체크포인트)을 떠 Esc 두 번으로 되돌린다.

기둥 2 — 툴 (무엇을 할 수 있는가)

툴이 없으면 AI는 텍스트만 출력하는 채팅봇이다. 툴이 붙는 순간 “실제로 행동하는 에이전트”가 된다.

  • 내장 도구(Built-in Tools) — 파일 읽기/편집, 검색, 셸 명령 실행, 웹 검색, 코드 인텔리전스 5범주. 신입에게 주는 기본 장비.
  • MCP(Model Context Protocol) — AI를 외부 서비스(구글드라이브·Jira·Slack 등)에 꽂는 표준 규격. “AI계의 USB 포트”로, 모델 교체 없이 새 도구를 끼운다.
  • 서브에이전트(Sub-agents) — 깨끗한 별도 책상을 가진 보조 AI에게 하위 작업을 맡기고 요약만 받아, 메인 책상을 어지럽히지 않는다.
  • Skills(스킬) — 반복 작업을 “필요할 때만 펼쳐지는 접이식 매뉴얼”로 만든 것. 평소엔 한 줄 설명만 보이다가 관련 작업이 오면 전체 절차가 로드된다.
  • 슬래시 명령(Slash Commands) — /review /init처럼 자주 쓰는 프롬프트를 단축키로 등록해 한 번에 부른다.
  • 플러그인 & 마켓플레이스 — 스킬·명령·훅·MCP설정을 한 묶음으로 배포(플러그인)하고, 그것을 공유·검색하는 장터(마켓플레이스). 하네스를 통째로 나눠 쓰는 방식.
  • 모델 선택(Models) — 같은 하네스 안에서 추론 엔진(Sonnet=일상 코딩, Opus=복잡한 설계)을 작업 난이도에 맞춰 갈아 끼운다. 하네스와 모델은 분리되어 있다.

기둥 3 — 가드레일 (무엇을 못 하게 막는가)

신입이 유능해도 결재 없이 본사 서버를 지우면 안 된다. 가드레일은 AI의 자율성과 안전 사이를 조절하는 규정이다.

  • 권한(Permissions) — AI가 사람 허락 없이 할 수 있는 범위를 allow/ask/deny로 정함. 조직 정책부터 개인 취향까지 계층으로 쌓인다.
  • 권한 모드(Permission Modes) — Shift+Tab으로 도는 “운전 모드”: 기본(매번 확인) / 편집 자동수락 / 계획 모드(읽기 전용) / 자동 모드. 신뢰 수준에 따라 자율성을 조절한다.
  • 계획 모드(Plan Mode) — 코드를 건드리기 전 읽기 전용으로만 조사해 “이렇게 하겠습니다” 계획을 먼저 내고 승인을 받게 하는 실행 전 게이트.
  • 설정 계층(Settings Precedence) — 관리정책 > 프로젝트 > 사용자 > 로컬 순으로 우선순위가 정해진 settings.json 더미. 조직이 잠근 규정은 개인이 못 푼다.
  • 훅(Hooks) — “편집 전엔 무조건 X, 커밋 전엔 무조건 Y”처럼 정해진 시점에 셸 명령을 강제 실행. AI의 판단과 무관하게 항상 작동하므로 CLAUDE.md(부탁)와 달리 진짜 강제(차단)다.
  • 샌드박스 / 격리 — AI 작업을 통제된 환경(로컬·클라우드 VM)에 가둬 시스템 전체로의 부작용을 제한. 외부 부작용(DB·배포)은 되돌릴 수 없어 더 엄격히 다룬다.

기둥 4 — 검증 (제대로 됐는지 확인)

에이전트 루프의 3단계가 헛돌지 않게 하는 “정답지”를 챙겨 주는 일이다.

  • 검증 가능한 목표 제공 — 테스트 케이스·예상 출력·디자인 스크린샷 같은 “정답지”를 함께 주면 AI가 스스로 대조·자기수정해 정확도가 오른다.
  • 탐색 후 구현(2단계 접근) — 복잡한 문제는 “조사·계획”과 “코딩”을 분리해, 계획을 사람이 검토·개선한 뒤 실행한다.
  • 헤드리스 / 자동화 검증 — claude -p "..."로 사람 개입 없이 CI·스크립트에서 돌려 결과를 파이프로 받아 검증·게이팅한다. 하네스를 파이프라인에 끼우는 방법.

핵심 정리

기둥핵심 질문대표 메커니즘
컨텍스트무엇을 아는가에이전트 루프 · 컨텍스트 윈도우 · CLAUDE.md · 메모리 · 규칙 · 압축
툴무엇을 하는가내장 도구 · MCP · 서브에이전트 · 스킬 · 슬래시 · 플러그인
가드레일무엇을 못 하나권한 · 권한 모드 · 계획 모드 · 설정 계층 · 훅 · 샌드박스
검증제대로 됐나검증 대상 제공 · 탐색 후 구현 · 헤드리스

이 노트의 가장 중요한 한 문장

CLAUDE.md·메모리·스킬은 “부탁(soft)“이고, 훅·권한·설정계층은 “강제(hard)” 다. 공식문서가 반복 강조하는 핵심 원칙 — “반드시 일어나야 하는 일은 CLAUDE.md가 아니라 훅으로 작성하라.” 부탁은 AI가 안 지킬 수 있지만, 강제는 AI 판단과 무관하게 항상 작동한다.

출처(공식문서 페이지)

  • 컨텍스트: how-claude-code-works · context-window · memory
  • 툴: tools-reference · mcp · sub-agents · skills · slash-commands · plugin-marketplaces
  • 가드레일: permissions · permission-modes · settings · hooks(+hooks-guide) · how-claude-code-works
  • 검증: how-claude-code-works · best-practices · headless

실제 예시

“부탁”과 “강제”의 차이를 코드로 보면 한눈에 들어온다.

<!-- CLAUDE.md — "부탁(soft)" : 매 세션 읽히지만 AI가 안 지킬 수도 있다 -->
# 이 프로젝트 규칙
- 커밋 전에 반드시 `npm test`를 돌린다.
- 빌드 명령: `npm run build`
// .claude/settings.json — "강제(hard)" : AI 판단과 무관하게 항상 실행
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          { "type": "command", "command": "npm test" }
        ]
      }
    ]
  }
}
# 헤드리스 모드 — 사람 개입 없이 CI/스크립트에서 무인 실행
claude -p "이 PR의 변경분을 리뷰하고 결과를 JSON으로 출력" --output-format json

요약 & 셀프체크

  • 하네스 = AI 모델에 컨텍스트·툴·가드레일·검증 4기둥을 둘러 씌워 “일하는 에이전트”로 바꾸는 마구.
  • 4기둥은 에이전트 루프(수집→수행→검증) 라는 엔진으로 돌아가며, 모든 개념은 4기둥 중 하나의 부품으로 정리된다.
  • 같은 기능이라도 부탁(CLAUDE.md·메모리·스킬) 과 강제(훅·권한·설정계층) 는 다르며, 꼭 일어나야 하는 일은 강제로 짜야 한다.

스스로 답해 보기:

  1. “커밋 전 테스트 실행”을 CLAUDE.md에 적는 것과 훅으로 거는 것의 차이는?
  2. 컨텍스트 윈도우가 꽉 찰 때 무슨 일이 벌어지고, 중요한 규칙을 어떻게 지키나?
  3. 서브에이전트와 스킬은 둘 다 “툴 기둥”인데, 컨텍스트를 아끼는 방식이 어떻게 다른가?

연결

수집범위 / 누락

  • 저장한 원문 파일: 25개 (_원문아카이브/claude-code/ 하위, 한국어 우선·영문 보완).
    • ko 원문(11): how-claude-code-works, overview, settings, memory, hooks, skills, sub-agents, mcp, plugins (+ 영문 보강)
    • en 원문(14): hooks-guide, slash-commands, plugin-marketplaces, plugins-reference, permissions, permission-modes, headless, common-workflows, best-practices, cli-reference, features-overview, context-window, agent-sdk/overview, output-styles, tools-reference, glossary
  • 수집 방법: firecrawl_map으로 URL 목록 확보(총 293개 링크 중 ko 인덱싱은 10개뿐) → 각 페이지의 Mintlify 원본 마크다운 엔드포인트(<url>.md)를 직접 수집해 노이즈 없는 본문 확보.
  • 의도적으로 제외한 영역 (하네스/에이전틱 엔지니어링 핵심에서 벗어남):
    • 설치/플랫폼: setup, quickstart, vs-code, jetbrains, desktop, web-quickstart, troubleshoot-install
    • 엔터프라이즈/배포/클라우드: iam, admin-setup, amazon-bedrock, google-vertex-ai, azure-ai-foundry, llm-gateway, monitoring-usage, zero-data-retention, security/legal-and-compliance
    • 통합/주변 기능: github-actions, gitlab-ci-cd, slack, chrome, channels, routines, scheduled-tasks, voice-dictation, statusline, keybindings, ide-integrations
    • Agent SDK 세부(overview만 포함, 나머지 레퍼런스 제외), env-vars/model-config/costs(개념보다 레퍼런스 성격)
  • 관련 노트: 하네스엔지니어링이란 · 용어집

그래프 뷰

백링크