원문: The Claude Code SDK and the Birth of HaaS (Harness as a Service)
2025년 9월 23일
업무가 에이전트에게 더 많은 자율적 행동을 요구함에 따라, AI 작업의 기본 단위가 LLM API(채팅 스타일 엔드포인트) 에서 Harness API(사용자 정의 가능한 런타임) 로 전환되고 있습니다. 저는 이를 Harness as a Service(HaaS) 라고 부릅니다. 풍부한 에이전트 하네스 생태계를 통해 에이전트를 빠르게 구축하고, 사용자 정의하며, 공유할 수 있습니다. 오늘은 하네스를 사용자 정의하여 사용 가능한 에이전트를 빠르게 구축하는 방법과 오픈 하네스 세계에서 에이전트 개발의 미래를 살펴보겠습니다.
client.chat.completions.create() --> client.responses.create() --> agent.query()
실용적 정의 — 에이전트 하네스: 모델의 런타임 실행을 향상시키는 외부 기능 집합입니다. 예를 들어 (1) 대화 및 컨텍스트 관리, (2) 도구 호출 레이어(MCP/SDK 도구), (3) 권한 관리, (4) 세션 및 파일 시스템 상태, (5) 루프 제어 및 오류 처리, (6) 기본 관찰성/원격 측정이 포함됩니다.
참고: ChatGPT 웹 앱이나 iOS 앱 같은 LLM 제품은 이미 안전성, 도구 사용 등을 위해 자체 하네스 내에서 모델을 래핑하고 있습니다. 그러나 오늘날 LLM API를 사용하려면 모델을 자체 하네스 내에 래핑해야 합니다. 이는 Claude Code의 SDK를 통해 변화하고 있으며, 기존 하네스를 자체 프롬프트, 도구, 컨텍스트 및 권한으로 쉽게 확장할 수 있습니다. 사용자는 박스 안에 담긴 사용자 정의 가능한 에이전트 런타임을 얻게 됩니다.
다룰 세 가지 주요 아이디어:
- 왜 Claude Code의 SDK가 현재 에이전트를 구축하고 노출하는 가장 완전한 방법인가?
- 빌더로서의 당신의 임무는 작업에 맞게 하네스를 집요하게 사용자 정의하는 것입니다(예제 포함)
- 하네스를 통한 에이전트 개발의 미래와 오픈 하네스 생태계의 약속
향후 블로그 게시물에서는 Claude Code SDK의 세부 사항과 아래에 공유된 예제를 넘어서는 고급 기능에 대해 더 깊이 다룰 예정입니다. 시작해 봅시다.
배터리 포함(Batteries Included) = 속도 = 실제로 존재하는 에이전트
에이전트 구축 공간은 시끄럽습니다: 에이전트, 프레임워크, 도구, MCP, Codex, Claude Code, Cursor CLI 등등. 하지만 한 걸음 물러나 보세요. 에이전트 프레임워크 회사가 아닌 이상, 당신의 목표는 에이전트 인프라를 구축하는 것이 아니라 실제 문제를 해결하는 것입니다. 뒤늦게 깨닫게 되지만 에이전트로 문제를 해결하려는 팀들이 종종 간과하는 명백한 사실이 있습니다:
좋은 에이전트 구축은 일련의 반복 작업입니다. v0.1 없이는 반복할 수 없습니다. 배터리 포함 설정은 에이전트를 내부 팀의 손에 쥐어줍니다. 그런 다음 루프 내에서 편집할 수 있습니다.
왜 이것이 중요한가? 에이전트 구축은 일련의 모멘텀
에이전트 구축에서 도구/기능은 하룻밤 사이에 변할 수 있으므로, 이전에 작동하지 않았던 킬러 기능을 테스트하는 것이 좋습니다. 하지만 여기서 성공하려면 내부적으로(그리고 외부적으로) 빠르게 테스트할 수 있어야 합니다. Claude Code SDK는 TTFF(Time to First Feedback, 첫 피드백까지의 시간)를 줄이는 에이전트 퀵스타트 역할을 합니다. create-react-app --> create-agent-app처럼 생각하세요.
프레임워크는 정신적 여유를 확보하여 문제의 복잡성에 집중할 수 있게 해줍니다. 빠르게 움직이려면 모든 것을 처음부터 구축하지 마세요. 대신, 빠르게 시작하고 실행할 수 있게 해주면서 미래를 위한 강력한 사용자 정의를 제공하는 기존 도구에 일부 작업을 맡기세요. 그것이 바로 Claude Code SDK에서 얻는 오프로딩 유형입니다. 모든 기능을 나열하지는 않겠습니다. 그들의 문서가 탄탄하니, 개요 발췌문을 소개합니다.
Claude Code를 구동하는 에이전트 하네스 위에 구축된 Claude Code SDK는 프로덕션 준비 에이전트를 구축하는 데 필요한 모든 구성 요소를 제공합니다. Claude Code에서 수행된 작업을 활용하여 다음을 포함합니다:
- 컨텍스트 관리: 에이전트가 컨텍스트를 고갈시키지 않도록 자동 압축 및 컨텍스트 관리
- 풍부한 도구 생태계: 파일 작업, 코드 실행, 웹 검색 및 MCP 확장성
- 고급 권한: 에이전트 기능에 대한 세밀한 제어
- 프로덕션 필수 요소: 내장 오류 처리, 세션 관리 및 모니터링
- 최적화된 Claude 통합: 자동 프롬프트 캐싱 및 성능 최적화
문서에서 볼 수 있듯이, Claude Code SDK는 매우 사용 가능한 기본 에이전트 프리미티브 세트를 제공하며, 이것이 바로 “하네스”입니다. 이러한 내장 기능은 몇 주간의 작업을 절약하지만, 더 중요한 것은 이제 팀이 문제에 레이저 포커스를 맞출 수 있다는 것입니다.
그렇다면 당신의 임무는 무엇일까요? 집요한 사용자 정의입니다.
모든 에이전트를 구축하는 접근법, 하네스 사용자 정의
Claude Code SDK로 하네스를 사용자 정의하고 사용 가능하게 만드는 멘탈 모델
모든 작업에는 특정한 도구와 지침 세트가 있으며, 당신의 임무는 다음 입력을 사용자 정의하는 것입니다: 시스템 프롬프트, 도구/MCP, 컨텍스트, 서브 에이전트. 무언가를 구축했으면 실행하고 에이전트가 무엇을 하는지 관찰하세요. 그것이 당신의 학습 신호입니다. 충분히 좋은 출력을 얻을 때까지 입력을 개선하세요. 다음은 하네스의 각 부분을 사용자 정의하기 위한 세부 정보와 팁입니다.
1. 시스템 프롬프트
여기서 Claude Code에게 모든 것을 알려줍니다: 문제, 목표, 작동할 환경, 사용할 수 있는 도구, 따라야 할 지침과 가이드라인, 형식 규칙, 사용자와 상호 작용하는 방법 등.
여기에 많은 시간을 투자하세요! 프롬프트 엔지니어링은 모델 동작을 안내하는 데 여전히 유효합니다. 시스템 프롬프트에 시간을 투자하는 것이 에이전트 구축 여정에서 얻을 수 있는 최고의 ROI입니다.
다음은 시작하기 위한 템플릿이지만, 프롬프트 디자인은 예술입니다. 여기에서 잘 작동한 더 긴 예제를 볼 수 있습니다. 이것은 제가 Claude Code SDK로 출시한 프로젝트로, 사용자 주제에서 자율적으로 스토리북을 생성합니다(Gemini의 Storybook 기능과 유사).
목표/페르소나: "당신은 '스토리 디렉터'로, 모든 사용자 입력을 완전한 삽화가 있는 스토리북으로 변환하는 자율 스토리북 생성 에이전트입니다..."
환경/사용 가능한 도구: ...
필수 따라야 할 지침: ...
예제 + 도구 사용법: ...
최종 체크리스트: ...
Claude Code는 시스템 프롬프트를 편집하는 두 가지 방법을 제공합니다: appendSystemPrompt를 사용하여 Claude의 기존 시스템 프롬프트에 추가하거나, custom_system_prompt를 사용하여 자체 프롬프트로 완전히 재작성할 수 있습니다.
2. 도구/MCP
Claude Code는 내장 도구(웹 검색, grep, 파일 읽기/쓰기 등)와 함께 제공되지만, 사용 사례별 도구(예: 이미지 편집 API, Slack 통합 등)에 대한 사용자 정의 로직을 정의해야 합니다. 이 모든 것을 처음부터 구축할 필요는 없습니다—Smithery와 같은 플랫폼에서 MCP로 패키징된 기존 도구 세트를 사용하세요.
도구 설계를 위해 다음 세 가지에 대해 깊이 생각하세요:
- 에이전트가 설정한 목표를 달성하기 위해 무엇을 해야 하나요? 그에 대한 도구가 있나요?
- 시스템 프롬프트와 도구 설명 모두에서 에이전트가 도구를 언제 사용해야 하는지 명확한가요?
- 오류 가능성을 줄이기 위해 여러 도구를 더 원자적인 결과로 결합할 수 있나요? 예:
generate_image—>generate_page_content
Anthropic의 에이전트를 위한 효과적인 도구 작성 블로그와 Vercel의 개발자가 아닌 LLM을 위한 MCP 블로그는 도구/MCP 디자인에 대한 두 가지 훌륭한 리소스입니다.
3. 컨텍스트
컨텍스트 엔지니어링에 대한 많은 새로운 콘텐츠가 있습니다. 에이전트에 더 나은 컨텍스트를 제공할수록 성능이 향상됩니다. 유용한 컨텍스트의 예는 다음과 같습니다:
- 코드 문서 및 스니펫: 이를 파일 시스템에 마크다운 파일로 저장하세요. 에이전트가 이미 필요할 것을 알고 있는 것을 웹에서 검색하게 하지 마세요. 필요에 따라 이러한 스니펫을 참조하세요.
- 메모리/사용자 개인화: 에이전트가 사용자에 따라 다르게 동작해야 하나요? 가장 간단한 방법은 이 정보를
user_info.md파일에 주입하거나 더 정교한 메모리 서비스를 사용하는 것입니다.
경험 법칙: 모든 중요한 컨텍스트를 시스템 프롬프트에 보관하세요. 특히 첫 번째 버전의 경우 그렇습니다. 다른 모든 유용한 컨텍스트는 마크다운 파일에 보관하고 에이전트에게 콘텐츠를 언제 어떻게 사용할지 알려주세요.
4. 서브 에이전트(선택 사항)
에이전트의 첫 번째 버전에서는 ==복잡성을 줄이고 에이전트를 신속하게 세상에 내놓기 위해 단일 에이전트 스레드에서 모든 것을 테스트할 것을 강력히 권장==합니다. 서브 에이전트는 초기에 두 가지 사용 사례에 유용할 수 있습니다: 전문화와 병렬화.
서브 에이전트는 .claude/agents/{subagent_name}.md에서 YAML을 통해 정의됩니다. 예를 들어:
---
name: character-consistency-checker
description: 전문 시각 검사자. 생성된 이미지의 캐릭터가 캐릭터 참조 이미지와 일치하는지 판단할 수 있습니다.
tools: Read, Grep, Glob, Bash
---
당신의 작업은 스토리의 캐릭터가 참조 캐릭터와 일치하는지 확인하는 것입니다. character.png와 page.png 파일, 두 개의 이미지를 읽어들일 것입니다. 그런 다음 결정에 대한 이유와 함께 True 또는 False를 출력합니다.
크기, 색상, 아트 스타일 및 스토리의 흐름과 전체적인 분위기를 깨뜨릴 수 있는 기타 요소의 일관성을 확인하세요.
HaaS, 사용자 정의 에이전트 구축의 미래
빌더가 사용자 정의 하네스를 만들고 사용자가 이를 추가로 편집하거나 제품으로 연결하는 세상으로 빠르게 나아가고 있습니다. bolt와 같은 회사에서 이러한 움직임을 이미 보기 시작했습니다. 그들은 바이브 코딩 혁명을 촉발하는 데 도움을 주었습니다. 그들은 앱 구축 제품에서 Codex와 Claude Code를 직접 사용하고 있으며, 제품이 잘 작동하도록 하기 위해 엄청난 하네스 사용자 정의를 했을 것입니다. 기업이 기존 하네스를 애플리케이션 프리미티브로 사용하여 제품 경험을 구축할 수 있는 엄청난 기회가 있습니다. 제 예측은 향후 6개월 이내에 대부분의 사용자 대면 AI 제품이 핵심 사용자 상호 작용 패턴으로 기존 에이전트 하네스를 사용할 것이라는 것입니다.
문제에 집착하는 빌더들에게 이것은 모두 좋은 소식입니다. 지속적으로 개선되고 사용자 정의 가능한 지능 레이어를 활용하면서 사용자 피드백, 더 나은 에이전트 입력 생성, 더 복잡하고 강력한 경험 엔지니어링에 시간을 집중할 수 있습니다.
Claude Code SDK가 유일한 옵션은 아닐 것입니다. 오늘날 구축하기에 가장 성숙한 것일 뿐입니다. OpenAI Codex, Gemini CLI, Cursor CLI, Amp 등에서 이미 훌륭한 작업이 진행되고 있습니다. 하지만 목표는 명확합니다: 모두가 사용자가 지능을 연결하는 하네스가 되기를 원합니다. 여기서의 기회는 훌륭한 DX와 배터리 포함 지능을 중심으로 전개될 것입니다.
오픈 하네스 테제
이 게시물과 Prime Intellect Environment Hub와 같은 릴리스에 흥분한다면, 많은 하네스가 오픈 소스이고 개발자가 이를 확장할 수 있는 미래에 대한 비전을 공유하고 있는 것입니다. 원래 모델과 그 하네스는 오픈 소스가 아닐 수 있지만, 제품 경험을 구축하는 모든 것이 오픈 소스가 될 수 있습니다. 그 미래가 훨씬 더 흥미롭습니다. 최전선 하네스를 구동하는 기반 모델은 결국 오픈 소스가 될 가능성이 매우 높기 때문입니다. 이것이 에이전트를 위한 앱 스토어입니다.
Harness as a Service(HaaS) 또는 단순히 “에이전트 구축”이라고 부르든, 하네스는 “에이전트 인프라”를 상품화하고 복리 수익이 있는 곳, 즉 도메인에 맞춘 프롬프트, 도구 및 컨텍스트로 노력을 전환합니다. Claude Code SDK는 오늘날 구축하기 가장 쉬운 하네스입니다. 그 기준선에서 시작하여 측정된 출력을 기반으로 에이전트를 공격적으로 전문화하고 개선하세요.
이 미래에 흥분한다면 연락하세요. 우리는 여기서 구축하고 있습니다. 다음 시간까지, 즐거운 하네스 구축 되세요.