하네스 엔지니어링 — 중국어로 비공식적으로 "The Horse Book"으로 알려져 있음 (중국어 제목이 말 마구처럼 "마구"처럼 들리기 때문입니다).

Claude Code의 기술 스택 선택은 핵심 철학을 드러냅니다. AI 코딩 에이전트는 전통적인 CLI 도구가 아닙니다. "에서 실행되는 시스템입니다. 배포' 모델은 도구를 사용하는 것뿐만 아니라 이를 작성할 수 있습니다. 자신의 도구 . 이는 전체 기술 스택이 " 일류시민 모델'을 염두에 두고 창업 초기부터 빌드 시간…

Claude Code의 도구 시스템은 40개 이상의 내장 도구와 무제한의 도구를 관리합니다. MCP 확장 도구의 수. 이러한 도구는 평면 배열이 아닙니다. 정확한 파이프라인 통과: 정의 \ 등록 \ 필터링 \ 호출 \ 렌더링 . 각 단계에는 명확한 내용이 있습니다. 계약. 이 장은 Tool.ts 인터페이스 정의부터…

이 장은 책 전체의 닻이다. 5장의 API 호출 구성부터 9장의 자동 압축 전략, 13장의 스트리밍 응답 처리부터 16장의 권한 확인 시스템까지, 후속 장에서 논의되는 거의 모든 하위 시스템은 궁극적으로 queryLoop() 코어 루프 내에서 조정, 조정 및 구동됩니다. 이 루프를 이해한다는 것은 AI 에이전트로서…

Claude Code의 도구 오케스트레이션 계층은 세 가지 핵심 문제를 해결합니다.

계획 모드는 의도 정렬 문제를 해결합니다. 에이전트가 코드를 수정하기 전에 먼저 코드베이스를 탐색하고 계획을 생성한 후 사용자 승인을 얻습니다. 이는 단순한 "실행 전 확인"이 아닙니다. 권한 모드 전환, 계획 파일 지속성, 워크플로 프롬프트 삽입, 팀 간 승인 프로토콜 및 자동 모드와의 복잡한 상호 작용을 포함하는…

1. 볼륨 및 비용 : 전체 시스템 프롬프트에는 ID 소개, 행동 지침, 도구 사용 지침, 환경 정보, 메모리 파일, MCP 지침 및 기타 10개 이상의 섹션이 포함되어 총 수만 개의 토큰이 포함됩니다. 모든 API 호출에서 이 모든 것을 재전송한다는 것은 막대한 프롬프트 캐싱 비용을 의미합니다. 2. 변경 빈도 변경…

Claude Code의 시스템 프롬프트 소스 코드 읽기 ( restored src/src/constants/prompts.ts 그리고 restored src/src/tools/BashTool/prompt.ts ), 우리는 다음을 발견했습니다.

클로드 코드의 커뮤니케이션 레이어는 바로 이런 종류의 문제를 해결합니다. 문제. 이는 단순한 "실패 시 재시도" 래퍼가 아닙니다. 다층 방어 시스템: 지수 백오프로 눈사태를 방지합니다. 효과, 529 카운터는 모델 저하를 유발하고 이중 감시 장치는 감지합니다. 스트림 중단, 고속 모드 캐시 인식 재시도를 통해 비용을…

이러한 @[MODEL LAUNCH] 주석은 일반적인 주석이 아닙니다. 그들은 형성한다 분산 체크리스트 새 모델 출시 준비가 되면 엔지니어는 코드베이스에서 @[MODEL LAUNCH] 을 전역적으로 검색하면 됩니다. 업데이트가 필요한 모든 위치를 찾으려면 이 디자인에는 릴리스가 포함되어 있습니다. 외부에 의존하지 않고…

기능 설명 : 도구의 기능 긍정적 지침 : 사용 방법 부정적인 금지 사항 : 사용하면 안 되는 방법 조건부 분기 : 특정 시나리오에서 수행할 작업 형식 템플릿 : 출력의 모양

Claude Code의 모든 장기 세션 사용자는 이 순간을 경험했습니다. 모델이 복잡한 모듈을 점진적으로 리팩토링하도록 하다가 갑자기 응답이 "잊혀지는" 것을 발견했습니다. 즉, 5분 전에 명시적으로 보존하도록 요청한 인터페이스 서명을 잊어버리거나 이미 거부한 접근 방식을 다시 제안합니다. 모델은 더 멍청해지지…

9장에서는 압축이 트리거되는 경우 와 요약이 생성되는 방법 을 다루었습니다. 그러나 압축 이야기는 요약 생성 후에도 끝나지 않습니다. 긴 대화가 하나의 요약 메시지로 압축되면 모델은 원래의 모든 컨텍스트를 잃게 됩니다. 즉, 방금 읽은 파일이 무엇인지 더 이상 알 수 없고 실행 중이던 계획도 기억하지 못하며 어떤 도구를…

이전 장(9장)에서 자동 압축을 철저하게 분석했습니다. 즉, 컨텍스트가 창 한계에 도달하면 Claude Code는 전체 대화를 구조화된 요약으로 압축합니다. 이것은 "핵 옵션"입니다. 효과적이지만 비용이 많이 듭니다. 대화의 원래 세부 정보가 손실되며 요약을 생성하려면 전체 LLM 호출이 필요합니다.

단일 grep 는 80KB의 검색 결과를 반환하고, 단일 cat 는 200KB의 로그 파일을 읽고, 5개의 병렬 도구 호출이 각각 50KB를 반환합니다.

일반적인 Claude Code 세션의 경우 시스템 프롬프트는 약 11,000개의 토큰이고 40개 이상의 도구에 대한 스키마 정의는 추가로 ~20,000개의 토큰을 제공합니다.

이를 더욱 까다롭게 만드는 것은 캐시 중단이 "자동"이라는 것입니다. API 응답의 cache read input tokens 가 삭제되지만 이유를 알려주는 오류 메시지는 없습니다. 개발자는 근본 원인을 알지 못한 채 비용이 증가하고 대기 시간이 증가한다는 사실만 알아차립니다.

이러한 최적화 패턴은 한꺼번에 설계되지 않았습니다. 각각은 BigQuery를 통해 14장에 소개된 캐시 중단 감지 시스템에서 캡처한 실제 데이터에서 유래되었습니다. tengu prompt cache break 이벤트에서 반복적으로 반복되는 특정 중단 원인이 밝혀졌을 때 엔지니어링 팀은 이를 제거하기 위한 목표 최적화…

Claude Code의 권한 시스템은 6가지 권한 모드, 3계층 규칙 일치 메커니즘 및 완전한 유효성 검사 권한 분류 파이프라인을 통해 이러한 두 가지 극단 사이의 균형을 찾으려고 시도하며 "안전한 작업은 자동으로 통과하고, 위험한 작업은 수동 확인이 필요하며, 모호한 사례는 AI 분류기에 의해 판정"되는 계층형 제어를…

이것이 AI를 감사하기 위해 AI를 사용하는 안전 결정 시스템인 YOLO 분류자(내부 코드명 "tengu 자동 모드")입니다.

에이전트가 파일을 읽고 쓸 수 있고, 셸 명령을 실행하고, 외부 API를 호출할 수 있으면 프롬프트 삽입은 더 이상 "잘못된 텍스트를 출력"하는 것이 아니라 "에이전트를 공격자의 프록시로 하이재킹하는" 것입니다.

이는 단순한 "콜백 함수" 메커니즘이 아닙니다. Hooks 시스템은 네 가지 핵심 과제를 해결해야 합니다. 신뢰 — 임의 명령 실행을 위한 보안 경계는 어디에 있습니까? 시간 초과 — 후크가 중단될 때 전체 에이전트 루프가 차단되는 것을 방지하는 방법은 무엇입니까? 의미론 — Hook의 종료 코드는 어떻게 "허용" 또는…

샌드박스는 Claude Code 보안 아키텍처의 마지막 하드 경계입니다. macOS에서는 sandbox exec (안전벨트 프로필), Linux에서는 Bubblewrap(사용자 공간 네임스페이스) + seccomp(시스템 호출 필터링) 등 OS 커널 제공 격리 메커니즘을 활용하여 프로세스 수준에서 파일 시스템 및…

CLAUDE.md의 디자인 철학은 한 문장으로 요약될 수 있습니다. 사용자 지침은 모델의 기본 동작을 재정의합니다. 이것은 수사가 아니며 문자 그대로 시스템 프롬프트에 주입됩니다.

Claude Code는 하위 에이전트 , 포크 모드 및 코디네이터 모드 라는 세 가지 점점 더 많은 다중 에이전트 패턴을 제공합니다.

팀 정보는 팀 이름, 구성원 목록, 리더 정보 등이 포함된 TeamFile 에 유지됩니다. 팀 이름은 고유해야 합니다. 충돌이 발생하면 단어 슬러그(64 72행)가 자동 생성됩니다.

┌───────────────────────────────────────────────────────────┐ │ 사용자 터미널(로컬) │ │ │ │ PromptInput.tsx processUserInput.ts │ │ ┌─────────────┐ ┌──────────────────┐ │ │ │ 키워드 │─→…

Claude Code는 노력 (추론 노력 수준), 빠른 모드 (가속 모드) 및 사고 (사고 사슬 구성)의 세 가지 독립적이지만 협력적인 메커니즘을 통해 추론 깊이를 제어합니다.

사용자가 /batch migrate from react to vue 를 입력하면 Claude Code는 "명령"을 실행하지 않습니다.

플러그인은 Claude Code 확장 아키텍처의 최상위 컨테이너입니다. 이는 "능력을 정의하는 방법"이 아니라 일련의 더 어려운 질문에 답합니다. 능력을 발견하는 방법은 무엇입니까? 그들을 신뢰하는 방법은 무엇입니까? 설치, 업데이트 및 제거 방법은 무엇입니까? 수천 명의 사용자가 서로 방해하지 않고 동일한 플러그인을…

이는 feature('KAIROS') 에 의해 제어된 코드가 공개 빌드에 전혀 존재하지 않는다는 것을 의미합니다.

Claude Code의 대답은 원시 신호 캡처부터 구조화된 지식 추출, 세션 내 요약부터 세션 간 지속성에 이르기까지 완전한 "학습 능력"을 구축하는 6계층 메모리 아키텍처 입니다. 이 6개 하위 시스템에는 명확한 업무 구분이 있습니다.

이 장에서는 이전 23개 장의 소스 코드 분석에서 얻은 6가지 핵심 하네스 엔지니어링 원칙을 추출합니다. 각 원칙에는 명확한 소스 코드 추적성, 적용 가능한 시나리오 및 패턴 방지 경고가 있습니다. 이러한 원칙의 공통 주제는 AI 에이전트 시스템에서 동작을 제어하는 ​​가장 좋은 방법은 더 많은 코드를 작성하는 것이…

200K 토큰 컨텍스트 창은 넉넉해 보이지만 실제 시나리오에서는 예상보다 빨리 소비됩니다. 시스템 프롬프트에 약 15 20K, 각 도구 호출 결과는 5 50K가 소요되며 몇 라운드 후에 파일 읽기와 코드 검색에 이미 절반을 사용했습니다. 더 비판적으로, 컨텍스트 창은 단순한 "용량" 문제가 아니라 "정보" 문제입니다.…

이러한 패턴은 공통된 특성을 공유합니다. 사소해 보일 만큼 단순해 보이지만 프로덕션 환경에서 필요에 따라 반복적으로 검증되었습니다. "편집 전 읽기" — 읽지 않고 편집할 사람이 누가 있겠습니까? 그러나 AI 모델은 실제로 읽기를 건너뛰고 직접 편집하기 때문에 Claude Code는 도구 오류로 이를 시행합니다.…

이 장에서는 소스 코드에서 관찰할 수 있는 5가지 디자인 단점을 나열합니다. 각 단점은 문제 설명 (무엇인지), 소스 코드 증거 (문제인 이유), 개선 제안 (무엇을 할 수 있는지)의 세 부분으로 구성됩니다.

Claude Code는 이를 위해 5계층 원격 측정 시스템을 구축했습니다.

Claude Code는 제품 입니다. 40개 이상의 도구, 특정 UI 상호 작용, 특정 세션 형식, 특정 청구 통합이 포함되어 있습니다. 이러한 구현 세부 정보를 복제하는 것은 의미가 없습니다. 에이전트는 코딩 보조자가 될 필요가 없습니다. 보안 스캐너, 데이터 파이프라인 모니터, 코드 검토 도구 또는 고객 서비스 봇일…

Claude Code Harness 문서 아카이브

객체 : 재귀적으로 병합된 이후 소스 필드는 이전 필드를 재정의합니다. 어레이 : 병합 및 중복 제거( mergeArrays ), 대체되지 않음 — 이는 여러 레이어의 permissions.allow 규칙이 누적됨을 의미합니다. undefined 값 : updateSettingsForSource ( restored…

Claude Code Harness 문서 아카이브

참조 수 기준 상위 5개 : KAIROS (84) \ TRANSCRIPT CLASSIFIER (69) \ TEAMMEM (44) \ BASH CLASSIFIER (33) \ COORDINATOR MODE (32)

v2.1.88 상태 : 존재하지 않습니다. restored src/src/ 에는 전원 켜기 또는 수업 관련 코드가 없습니다.

U QE: Type "/commit" QE CMD: Parse slash command CMD CMD: executeShellCommandsInPrompt() Execute git status / git diff CMD QE: Return prompt + allowedTools QE QE: Update…

사용자 → claude 로그인 → claude.com/cai/oauth/authorize → 인증 페이지(PKCE 흐름) → 콜백 → exchangeCodeForTokens() → OAuth access token + Refresh token → 토큰을 직접 사용하여 Anthropic API 호출(API 키 필요 없음)