루키스AI 공부방 · 토요일 AX · 2026-06-20

주제: 클로드 코드(Claude Code)를 **Agent SDK로 직접 모작(模作)**하며 배우는 MINICLAUDE — "에이전트의 근본". 영상 전체가 Claude Code 내용입니다.

핵심 요약 (5줄)

클로드 코드 = 에이전트(하네스)일 뿐, 본체는 LLM. 에이전트는 "머리가 텅 빈" 통신 장치이고 지능은 전부 LLM에서 온다 — "AX의 99.99%는 LLM이 한다."
Agent SDK = 리모컨. 헤드리스(claude -p)로 띄운 클로드 CLI(엔진)를 표준입출력으로 조종하는 리모컨이며, 그 위에 우리가 하네스(마구) 프로그램을 얹어 채팅 없이 자동 조작한다.
오늘은 3단계 모작 로드맵의 Step 1 — Agent SDK로 REPL·패킷뷰어·모델교체·thinking·도구·권한·컨텍스트를 하나씩 붙여 미니 클로드를 완성했다.
LLM은 기억이 없다. 그래서 매 턴 히스토리(system·tools·messages)를 통째로 다시 실어 보내야 하고, 도구는 LLM 요청(tool_use) → 우리가 실행 → 결과 보고(tool_result) 의 TAO 루프로 돈다.
실무 결론: Thinking은 항상 ON·Effort는 X-High, 권한은 **모드(Shift+Tab)**로 관리(Y 연타 금물), 모델은 보통 Opus.

핵심 개념 / 용어

용어	정의
인터랙티브(REPL) 모드	채팅하듯 티키타카로 지시하는 기본 실행 방식. 사람이 옆에 붙어 지시함. 실사용의 약 99%.
헤드리스 모드	`claude -p` 로 실행. 일회성·단발성으로 돌고 결과만 반환. UI(REPL 화면)만 뗐을 뿐 내부 동작(TAO 루프)은 완전히 동일. 자동화·하네스의 기반.
하네스(Harness)	"마구(말을 부리는 도구)"에서 온 말. LLM을 채팅 없이 코드로 부리는 우리 프로그램. Agent SDK 위에 만든다.
Agent SDK	앤트로픽 라이브러리(파이썬·TS). 헤드리스 클로드 CLI를 표준입출력으로 조종하는 리모컨. 쓰면 "진짜 찐 클로드 코드"를 프로그램이 조작한다.
에이전트	LLM을 제외한 나머지 전부. 지능은 없고(머리가 텅 빔) LLM과의 통신을 중계·관리하는 껍데기.
TAO 루프	Think(LLM이 생각) → Act(도구 실행) → Observe(결과 관찰) 반복. 엔진(헤드리스) 내부에서 돌기 때문에 Step 1에선 직접 못 본다.
query() / ClaudeAgentOptions	Agent SDK가 제공하는 질의 함수와 옵션 묶음. 옵션에 model·effort·thinking·allowed_tools 등을 넣는다.
AssistantMessage / TextBlock	LLM 응답 메시지 타입과 그 안의 텍스트 조각. 스트리밍으로 오는 여러 패킷 중 이 텍스트만 골라 화면에 출력.
멀티턴 대화 루프	무한 루프로 계속 대화(REPL). `client.query`로 질의, `exit`/`quit`로 종료. 주의: 이 루프는 TAO 루프가 아니다.
패킷 뷰어	오가는 패킷을 타입별로 나눠 JSON으로 보는 뷰어. 에이전트 내부를 "염탐"하는 학습 도구.
control_request / response	Agent SDK ↔ 하네스(엔진) 사이의 제어 통신. LLM까지 가는 통신이 아니다.
set_model	모델 교체 함수. `/model` 또는 `Alt+P` → `client.set_model()`로 엔진에 교체 요청.
Extended / Adaptive Thinking	확장 사고(깊게 생각). 옛 Manual(예산 편성) 방식은 사라지고 지금은 Adaptive(알아서 판단). "Thinking ON" = Adaptive ON.
Effort	노력 정도 5단계 Low·Medium·High·X-High·Max. Medium은 단순하면 건너뜀, High↑ 거의 항상, X-High가 권장 기본.
4대 천왕(내장 도구)	파일입출력(Read/Write/Edit), 검색(Glob/Grep), 웹(WebFetch/WebSearch), 셀(Bash).
tool_use / tool_result	LLM이 "이 도구 써"라고 요청(tool_use) → 우리가 실행 → 결과를 JSON으로 보고(tool_result). 기억 없는 LLM 위해 히스토리로 되돌려 보냄.
권한 모드	default / acceptEdits / plan / auto / bypass. `Shift+Tab`으로 전환하는 도구 허용 정책.
컨텍스트(system·tools·messages)	LLM에 실리는 것. `/context`로 토큰 확인. system=최초 박제 지시, tools=도구 카탈로그, messages=user+assistant 히스토리.

큰 그림

graph LR
  U["사용자 채팅"] --> H["하네스 (main.py)<br>우리가 만드는 것"]
  H -->|"Agent SDK · 리모컨"| CLI["Claude CLI<br>헤드리스 엔진"]
  CLI -->|"stdin / stdout"| LLM["LLM<br>본체 · 지능"]
  LLM -.응답 패킷.-> H

Ⅰ. 오리엔테이션

1. 두 가지 실행 방식 — 인터랙티브(REPL) vs 헤드리스

클로드 코드를 실행하는 방식은 두 가지다.

인터랙티브(REPL) 모드 — 채팅하듯 티키타카로 요청하며 명령을 내리는 방식. **실사용의 약 99%**가 이것이라, 다른 방식이 있다는 것조차 모르는 경우가 많다.
헤드리스 모드 — 실행 시 -p 인자를 준다: claude -p "...". 티키타카 없이 일회성·단발성으로 실행되고 결과만 반환한다.