1. Claude Code

한 줄 요약

Claude Code는 언어모델을 “코딩 에이전트”로 바꾸는 터미널 호스트(하네스)이며, 플러그인·훅·스킬·MCP 네 확장 표면으로 하네스 자체를 사용자가 통째로 재구성·배포하게 만든 메타 플랫폼이다. → 왜 배우나: 다른 모든 에이전트 프레임워크를 비교·평가할 때 기준이 되는 “표준 골격”이기 때문이다.

그림

CC_개요-diagram.svg

flowchart TB
    subgraph 모델["모델 (교체 가능)"]
        M["sonnet / opus / haiku"]
    end
    subgraph 코어["CLI 코어 (비공개·minified)"]
        L["에이전트 루프<br/>컨텍스트 수집 → 수행 → 검증"]
        T["내장 5범주 툴<br/>파일·검색·셸·웹·코드인텔"]
    end
    subgraph 확장["선언적 확장 표면 4종 + MCP"]
        C["commands<br/>슬래시 프롬프트"]
        A["agents<br/>서브에이전트"]
        S["skills<br/>지연로딩 매뉴얼"]
        H["hooks<br/>이벤트 강제훅"]
        P["MCP<br/>외부 툴 연결"]
    end
    subgraph 배포["배포·설정"]
        PJ["plugin.json + marketplace.json<br/>git 배포·버전드 캐시"]
        SET["settings.json 계층<br/>managed > project > user > local"]
    end

    M --> L
    L --> T
    L -.제어.-> 확장
    확장 --> PJ
    SET -.권한·샌드박스·훅 강제.-> 코어
    SET -.조직 잠금.-> 확장

쉽게 풀기

Claude Code를 한마디로 비유하면 **“AI 비서를 위한 운영체제(OS)“**다. 하나씩 풀어보자.

두뇌는 갈아끼운다. 컴퓨터의 CPU를 바꾸듯, 작업에 따라 모델(sonnet·opus·haiku)을 교체한다. 빠른 일엔 가벼운 두뇌, 정밀한 일엔 똑똑한 두뇌를 쓴다.
OS는 기본 기능을 직접 한다. CLI 코어가 “에이전트 루프”(상황을 모으고 → 일을 하고 → 결과를 검증)와 내장 도구 5종(파일 읽기·검색·셸 실행·웹·코드 이해)을 돌린다. 단, 이 부분은 소스가 비공개라 우리가 직접 뜯어볼 수는 없다.
그 위에 앱을 설치한다. 진짜 차별점은 여기다. 네 종류의 “앱”을 꽂는다.
- commands = 자주 쓰는 명령을 /이름으로 저장한 단축키
- agents = 특정 분야만 잘하는 전문 비서(서브에이전트)
- skills = 평소엔 제목만 보이다가 필요할 때 펼쳐지는 매뉴얼
- hooks = “이럴 땐 무조건 이렇게 해”라는 자동 감시 규칙
- 여기에 MCP(외부 도구를 꽂는 USB 포트)가 더해진다.
앱은 묶어서 배포한다. 여러 앱을 plugin.json으로 한 상자에 담고, marketplace.json이라는 앱스토어를 통해 git에서 설치한다.
관리자는 잠글 수 있다. settings.json이 managed > project > user > local 순서로 권한을 정한다. 회사가 managed로 잠그면 개인이 못 푼다 — 이게 “부탁”이 아닌 “강제” 레이어다.

핵심 통찰: 대부분의 프레임워크는 “닫힌 제품”이지만, Claude Code는 하네스를 “재구성 가능한 표면”으로 개방했다. 그래서 사용자가 하네스 위에서 또 다른 하네스를 만들 수 있다.

핵심 정리

네 기둥과 확장 표면

영역	무엇	비유
모델-하네스 분리	작업별 sonnet/opus/haiku 교체	갈아끼우는 두뇌
확장 4종 + MCP	commands·agents·skills·hooks·MCP	설치하는 앱들
배포	plugin.json + marketplace.json	앱스토어
설정 계층	managed>project>user>local	관리자 잠금

[!note] 사용 언어

TypeScript/JS — CLI 코어 (단, 이 repo에서 직접 검증 불가)

Markdown — commands/agents/skills 선언

JSON — plugin.json · marketplace.json · settings.json · hooks.json

Python — security-guidance · plugin-dev 훅 핸들러

Bash — hook 핸들러 · ralph stop-hook · setup 스크립트

[!note] 꼭 알아둘 독창적 아이디어 6가지

asyncRewake 훅 — 백그라운드 LLM 리뷰를 돌리고 결과가 나오면 에이전트를 “다시 깨워” 주입. 동기 차단 없는 비동기 검증.

git baseline diff (행위 귀속) — 매 프롬프트마다 working tree 스냅샷 SHA를 떠두고, 그 SHA 대비 diff만 리뷰 → “이번 세션에 에이전트가 실제 바꾼 코드”만 정확히 골라냄.

self-referential 루프(ralph) — Stop훅으로 종료를 막고 동일 프롬프트를 재주입. <promise> 태그나 max-iterations로만 종료.

프롬프트 기반 훅 — bash 대신 type:prompt로 LLM이 맥락의존 검증을 자연어 추론으로 수행.

hookify — 대화 속 불만/되돌림 신호를 자동 추출해 재발방지 훅을 생성. 재시작 없이 즉시 적용.

모델 티어 오케스트레이션 — 값싼 모델=게이트, 중간=규칙준수, 고정밀=버그탐지 + 검증 서브에이전트가 false positive 제거.

10축 점수표 (Codex 교차검증 후 최종값)

축	점수	한 줄 근거
아키텍처/포지셔닝	4	코어+확장4+MCP 표면 분리가 표준 디렉토리로 코드화. 단 코어 구현이 repo에 없어 검증 제한
컨텍스트엔지니어링	5	지연로딩 스킬·서브에이전트 격리·SessionStart 주입·자동압축까지 표준화
툴/확장	5	내장 5범주 + MCP + 플러그인 번들, plugin-dev로 확장 제작 자체를 메타-도구화
오케스트레이션	4	code-review 7단계·feature-dev 7페이즈. 강하나 markdown 프롬프트 워크플로 + 명세 불일치
가드레일/안전	4	settings 계층으로 조직이 기술적 잠금, 훅이 exit 2로 진짜 차단. strict 샌드박스 해석은 과장
검증루프	4	asyncRewake·baseline diff·검증 서브에이전트. 단 컴파일/테스트 하드게이트는 코어 미강제
자기개선/반복	3	ralph self-referential 루프. 단 종료가 자기신고 의존, 진화형 자동개선은 코어 부재
상태/영속성	4	세션 체크포인트 재개·되돌리기 코어기능. 단 마크다운/파일·SHA 위주, 구조화 DB 아님
배포/DX	4	marketplace+plugin.json git 설치·버전드 캐시·headless CI. 단 manifest 누락·npm deprecated
철학/차별점	5	soft(부탁) vs hard(강제) 이분법 명문화, 호스트+모델+생태계 수직통합 유일 포지션

[!note] 강점 ↔ 약점 강점

확장 표면이 선언적·조합가능 표준화 + 13개 1급 플러그인 레퍼런스 → 카피해 바로 쓰는 DX

soft/hard 가드레일 이분법 명확, 설정계층으로 조직이 기술적으로 잠그는 진짜 강제 레이어

모델 티어별 비용/정밀도 분배 + 검증 서브에이전트 재확인까지 갖춘 성숙한 오케스트레이션

서브에이전트·스킬 지연로딩으로 메인 컨텍스트 오염을 구조적으로 방지

모델사가 호스트+모델+생태계 수직통합 → 모델 교체 자유 + 최신 모델 우선 접근

약점

CLI 코어가 비공개·minified → 루프·압축·툴 실행 실제 구현 검증 불가(블랙박스 의존)

검증 루프가 LLM-as-judge·정규식 위주, 하드 검증 게이트는 코어가 강제 안 함

ralph 종료 판정이 <promise> 자기신고 의존 → “거짓 탈출” 여지

진화/토너먼트형 자동개선·평가자 계약은 코어 부재(서드파티 의존)

영속 상태가 파일·git SHA 위주 → 구조화 쿼리·대규모 지식누적 한계

LLM 리뷰 훅의 추가 비용/지연, 정규식 패턴 우회 가능

실제 예시

설정 계층의 “진짜 강제”가 어떻게 동작하는지 핵심 파일로 본다.

// examples/settings/settings-strict.json — network 값만 담음(주의: sandbox enabled 없음)
// 즉 "strict = Bash 샌드박스 강제"는 오해. 샌드박스는 아래 별도 파일이 담당한다.

// examples/settings/settings-bash-sandbox.json — 여기에만 enabled:true 존재
{ "sandbox": { "enabled": true } }

# examples/hooks/bash_command_validator_example.py
# 훅이 "부탁"이 아닌 "강제"인 증거: exit 2면 해당 도구 호출 자체가 차단된다.
import sys
# ... 위험 명령 패턴 검사 ...
if is_dangerous(command):
    print("이 명령은 차단되었습니다", file=sys.stderr)
    sys.exit(2)   # exit 2 → PreToolUse에서 도구 실행 봉쇄

# plugins/security-guidance/hooks/diffstate.py
# 행위 귀속(provenance) 레이어의 심장:
# UserPromptSubmit마다 git stash로 baseline SHA 스냅샷 → Stop훅에서 그 SHA 대비 diff만 리뷰.
# untracked 스냅샷 + 원자적 stop-state 소비로 asyncRewake 경합까지 처리.

// plugins/security-guidance/hooks/hooks.json — asyncRewake/Stop훅 선언
// 기본 리뷰 모델은 llm.py에서 claude-opus-4-7 (값싼 게이트가 아니라 정밀 우선 디폴트)

요약 & 셀프체크

3줄 요약

Claude Code = 모델(두뇌)을 갈아끼우는 코딩 에이전트 OS이고, 진짜 가치는 commands·agents·skills·hooks·MCP라는 설치형 확장 표면에 있다.
가드레일은 “부탁(CLAUDE.md·메모리·스킬)“과 “강제(훅·권한·설정계층)“로 나뉘며, settings 계층을 managed로 잠그면 조직이 기술적으로 통제한다.
CLI 코어는 비공개라 직접 검증 불가 — 이 저장소에서 배우는 대상은 확장/설정/공식 플러그인/CHANGELOG다.

스스로 답해보기

commands·agents·skills·hooks 네 가지가 각각 “언제” 동작하는지 한 문장으로 구분할 수 있는가?
“soft 가드레일”과 “hard 가드레일”의 차이를, 막을 수 있느냐 없느냐로 설명할 수 있는가?
“행위 귀속(provenance) 레이어”가 왜 단순 보안 기능 이상인지 말할 수 있는가?

연결

핵심 파일 (근거)

.claude-plugin/marketplace.json — 13개 1급 플러그인 카탈로그
plugins/README.md — 플러그인 표준 디렉토리 구조
plugins/security-guidance/hooks/hooks.json — asyncRewake/Stop훅 선언
plugins/security-guidance/hooks/security_reminder_hook.py — baseline diff 리뷰 진입점
plugins/security-guidance/hooks/diffstate.py — git stash baseline·untracked 스냅샷·원자적 stop-state (행위 귀속 레이어)
plugins/security-guidance/hooks/patterns.py — 보안 패턴 28개
plugins/security-guidance/hooks/llm.py — 기본 리뷰 모델 claude-opus-4-7
plugins/ralph-wiggum/hooks/stop-hook.sh — self-referential 종료 가로채기 루프
plugins/feature-dev/commands/feature-dev.md — 7페이즈 오케스트레이션
plugins/code-review/commands/code-review.md — 모델 티어 멀티에이전트 파이프라인
plugins/pr-review-toolkit/agents/ — 6개 전문 리뷰 에이전트
plugins/hookify/README.md — 경량 규칙 엔진(재시작 없이 적용)
plugins/plugin-dev/skills/plugin-structure/SKILL.md — manifest 필수 규칙(plugin-dev 자체는 위반)
examples/settings/settings-strict.json / settings-bash-sandbox.json — 강제 설정 예제
examples/hooks/bash_command_validator_example.py — exit 2 차단 훅
CHANGELOG.md — availableModels 강제·--safe-mode 등 운영 가드레일

기능별 분해 (번호순)

CC_10_agent-loop — 진입점과 에이전트 실행 루프(컨텍스트 수집→수행→검증, stop_hook_active·8회 block 종료 등 루프 안전장치).
CC_20_prompt-assembly — 컨텍스트와 프롬프트 조립(시스템 프롬프트·CLAUDE.md·메모리·도구 정의가 한 턴에 어떻게 합쳐지는가).
CC_30_hooks — 확장점 Hooks: 라이프사이클 이벤트 강제훅(exit 코드 vs JSON 출력 택일, PreToolUse 차단 등).
CC_40_skills — 확장점 Skills: 점진적 공개 패키지(SKILL.md description만 상시 노출, 트리거 시 본문 로드).
CC_50_slash-commands — 확장점 Slash Commands: 마크다운 프롬프트 템플릿을 /이름으로 호출($ARGUMENTS·!셸주입·allowed-tools).
CC_60_subagents — 확장점 Subagents: 격리 컨텍스트로 위임하는 전문 에이전트(tools 화이트리스트, 플러그인 배포 시 hooks/mcp 미지원 주의).
CC_70_mcp-and-tools — 도구 시스템과 MCP: 내장 5범주 + 외부 도구 연결, 도구 이름이 권한·matcher의 정확한 문자열.
CC_80_guardrails — 가드레일: 권한 규칙(allow/ask/deny)·권한 모드·OS 샌드박스의 3중 강제, managed settings 최상위.
CC_90_plugins-and-omc-teams — 패키징·영속성·고유기능: plugin.json/marketplace 배포, 버전드 캐시, OMC 팀·브리지.

상위 연결

_분석축_루브릭 · HOME · _비교매트릭스

[!tip] Claude ↔ Codex 교차검증 (메타검증 요약) Claude의 1차 분석을 Codex가 실제 저장소와 대조해 잡아낸 핵심. 사실 오류 정정 — ① “TS CLI 코어 minified”는 이 repo에서 검증 불가(README는 “plugins directory”로 안내, npm은 deprecated). ② “13개 모두 plugin.json 보유”는 틀림 — plugin-dev에 필수 .claude-plugin/plugin.json이 실제로 없음(자기모순). ③ “strict=Bash 샌드박스 강제”는 과장 — enabled:true는 settings-bash-sandbox.json 전용. ④ 정규식 “9패턴” 틀림 — patterns.py에 실제 28개. ⑤ 보안 리뷰 기본 모델은 haiku 아님 — claude-opus-4-7(정밀 우선 디폴트). 놓친 누락 — CHANGELOG의 엔터프라이즈 가드레일(enforceAvailableModels로 managed 목록 확장 차단), --safe-mode 탈출구, security-guidance의 3층 구조(패턴경고→LLM diff리뷰→agentic commit리뷰), PR Review Toolkit의 6개 전문 리뷰 에이전트. 가장 저평가됐던 핵심 — “이번 턴에 에이전트가 실제로 만든 변경만 식별하는 provenance(행위 귀속) 레이어”. 단순 보안 기능이 아니라, 어떤 변경이 사람이 아닌 에이전트 산출물인지 구조적으로 분리하는 설계다. 점수 보정 수용 — 아키텍처 5→4, 오케스트레이션 5→4, 가드레일 5→4, 자기개선 4→3, 배포/DX 5→4. 나머지 5축(컨텍스트5·툴5·검증4·상태4·철학5)은 Codex도 동의.