Claude Code SDK와 HaaS(Harness as a Service)의 탄생

게시일: 2025년 10월 30일 | 원문 작성일: 2025년 9월 23일 | 원저자: Varun Trivedy | 원문 보기

핵심 개념: Harness가 뭔데?

먼저 용어 정의부터 하고 갈게요. Agent Harness는 모델의 런타임 실행을 향상시키는 외부 기능들의 집합이에요. 쉽게 말해서 LLM에 바퀴와 엔진을 달아주는 거죠.

중요한 건, ChatGPT 같은 제품들은 이미 자체 harness 안에 모델을 감싸서 제공하고 있다는 거예요. 하지만 LLM API를 직접 쓸 때는 이 모든 걸 직접 만들어야 했죠. Claude Code의 SDK는 이미 잘 만들어진 harness를 당신의 프롬프트, 도구, 컨텍스트, 권한으로 쉽게 확장할 수 있게 해줘요.

왜 “배터리 포함형”이 중요한가

에이전트 빌딩 세계는 시끄러워요. 온갖 프레임워크, 도구, MCP, Codex, Claude Code, Cursor CLI… 뭐가 이렇게 많은지. 하지만 한 발짝 물러서서 생각해봐야 해요.

당신이 에이전트 프레임워크 회사가 아니라면, 목표는 실제 문제를 해결하는 거지 에이전트 인프라를 만드는 게 아니에요. 뻔한 얘기 같지만 자주 무시되는 사실:

배터리 포함형 셋업은 당신의 에이전트를 내부 팀의 손에 빠르게 쥐어줘요. 그럼 이제 루프를 돌면서 수정할 수 있죠.

모멘텀이 핵심이에요

에이전트 빌딩에서는 도구와 기능이 하룻밤 새 바뀔 수 있어요. 그래서 전에는 안 되던 킬러 기능을 이제 테스트할 수 있죠. 여기서 성공하려면 빠르게 내부적으로(그리고 외부적으로) 테스트할 수 있어야 해요.

Claude Code SDK는 TTFF(Time to First Feedback)를 줄여줘요. 마치 create-react-app이 React 프로젝트의 퀵스타트였던 것처럼, create-agent-app 같은 거죠.

프레임워크는 당신의 멘탈 용량을 확보해줘서 문제의 디테일에 집중할 수 있게 해요. 빠르게 움직이려면 모든 걸 처음부터 만들지 말고, 당신을 빠르게 시작할 수 있게 해주면서도 나중에 커스터마이징이 강력한 기존 도구에 일부 작업을 오프로드하세요. 그게 바로 Claude Code SDK가 제공하는 오프로딩이에요.

Harness 커스터마이징: 모든 에이전트를 만드는 접근법

그럼 이제 당신의 일은 뭘까요? 신중한 커스터마이징이에요.

모든 작업은 특정 도구와 지침이 필요해요. 당신의 일은 이 입력들을 커스터마이징하는 거예요: System Prompt, Tools/MCP, Context, Subagents. 뭔가 만들었으면 실행하고 에이전트가 뭘 하는지 관찰하세요. 이게 학습 신호가 돼요. 충분히 좋은 결과가 나올 때까지 입력을 개선하세요.

1. System Prompt

여기서 시작하세요! Claude Code에게 당신의 문제에 대한 모든 것을 말해주는 곳이에요 - 목표, 환경, 사용할 도구, 따라야 할 가이드라인, 포맷팅 규칙, 사용자와 상호작용하는 방법 등등.

여기에 많은 시간을 투자하세요! 프롬프트 엔지니어링은 모델 동작을 가이드하는 데 여전히 살아있어요. System prompt에 시간을 투자하는 건 에이전트 빌딩 여정에서 최고의 비용 대비 효과를 얻을 수 있는 방법이에요.

기본 템플릿 구조:

Claude Code는 두 가지 방법을 제공해요: appendSystemPrompt로 Claude의 기존 system prompt에 추가하거나, custom_system_prompt로 완전히 새로 작성할 수 있어요.

2. Tools/MCPs

Claude Code는 빌트인 도구들(웹 검색, grep, 파일 읽기/쓰기 등)이 있지만, 당신의 사용 사례에 특화된 커스텀 로직을 위한 도구는 직접 정의해야 해요 (예: 이미지 편집 API, Slack 연동 등). 처음부터 다 만들 필요는 없어요 - Smithery 같은 플랫폼에서 MCP로 패키징된 기존 도구셋을 사용하세요.

도구 설계 시 깊게 생각해야 할 3가지:

• 필요성: 에이전트가 내가 설정한 목표를 달성하려면 뭘 해야 하나? 그걸 위한 도구가 있나?
• 명확성: System prompt와 도구 설명에서 에이전트가 언제 이 도구를 사용해야 할지 명확한가?
• 원자성: 여러 도구를 더 원자적인 결과로 합쳐서 에러 발생 가능성을 줄일 수 있나? 예: generate_image → generate_page_content

참고할 좋은 자료: Anthropic의 에이전트를 위한 효과적인 도구 작성법과 Vercel의 개발자가 아닌 LLM을 위한 MCP

3. Context

요즘 Context Engineering에 대한 콘텐츠가 많이 나오고 있어요. 에이전트에게 더 좋은 컨텍스트를 주면 더 잘 작동해요.

유용한 컨텍스트의 예시들:

• 코드 문서와 스니펫: 마크다운 파일로 파일시스템에 저장하세요. 에이전트가 필요할 게 뻔한 걸 웹에서 검색하게 하지 마세요. 필요할 때 이 스니펫들을 참조할 수 있게 해주세요.
• 메모리/사용자 개인화: 에이전트가 사용자마다 다르게 동작해야 하나요? 가장 간단한 방법은 이 정보를 ‘user_info.md’ 파일에 주입하거나 더 정교한 메모리 서비스를 만드는 거예요.

경험칙: 모든 중요한 컨텍스트는 system prompt에 넣으세요, 특히 첫 버전에서는요. 다른 도움이 되는 컨텍스트는 마크다운 파일에 넣고 에이전트에게 언제 어떻게 내용을 사용할지 알려주세요.

4. Subagents (선택사항)

에이전트의 첫 버전에서는 복잡도를 줄이고 빠르게 세상에 내보내기 위해 단일 에이전트 스레드에서 모든 걸 테스트하는 걸 강력히 추천해요. Subagent는 처음에 두 가지 사용 사례에 유용해요: 전문화와 병렬화.

Subagent는 .claude/agents/{ subagent_name }.md에 YAML로 정의해요. 예시:

HaaS, 커스텀 에이전트 빌딩의 미래

우리는 빠르게 이런 세상으로 가고 있어요 - 빌더들이 커스텀 harness를 만들고, 사용자들이 거기에 플러그인해서 추가로 편집하거나 제품으로 사용하는 세상.

이미 이런 움직임이 시작됐어요. bolt 같은 회사들이 바이브 코딩 혁명을 시작하는 데 도움을 줬죠. 그들은 Codex와 Claude Code를 앱 빌딩 제품에서 직접 사용하고 있고, 제품이 잘 작동하게 만들기 위해 엄청난 harness 커스터마이징을 했을 거예요.

회사들이 기존 harness를 애플리케이션 프리미티브로 사용해서 제품 경험을 구축할 수 있는 엄청난 기회가 있어요. 제 예상으로는 앞으로 6개월 안에 사용자 대면 AI 제품의 대부분이 기존 agent harness를 핵심 사용자 인터랙션 패턴으로 사용할 거예요.

문제에 깊이 집착하는 빌더들에게는 이게 다 좋은 일이에요. 계속 발전하는 커스터마이징 가능한 인텔리전스 레이어를 활용하면서, 사용자 피드백, 더 나은 에이전트 입력 생성, 더 복잡하고 안정적인 경험 엔지니어링에 시간을 집중할 수 있거든요.

오픈 Harness 테제

Claude Code SDK가 유일한 선택지는 아닐 거예요. 그냥 오늘 기준으로 가장 성숙한 빌딩 플랫폼일 뿐이죠. OpenAI Codex, Gemini CLI, Cursor CLI, Amp 등에서도 이미 훌륭한 작업들이 진행되고 있어요. 하지만 목표는 분명해요 - 모두가 사용자들이 인텔리전스를 위해 플러그인하는 harness가 되고 싶어 해요. 이를 위한 기회는 훌륭한 DX(개발자 경험)와 기본 제공되는 인텔리전스를 중심으로 돌아갈 거예요.

이 글과 Prime Intellect의 Environment Hub 같은 릴리즈에 흥미가 생겼다면, 아마 많은 harness가 오픈소스가 되어서 개발자들이 확장할 수 있는 미래의 비전을 공유하고 있을 거예요. 원래 모델과 그 harness는 오픈소스가 아닐 수 있지만, 제품 경험을 만드는 모든 것은 오픈소스일 수 있어요.

그 미래는 더 흥미로워요. 왜냐하면 프론티어 harness를 구동하는 기본 모델들도 언젠가 오픈소스가 될 가능성이 아주 높거든요. 이게 바로 에이전트를 위한 오픈 앱 스토어예요.

결론

Harness는 “에이전트 인프라”를 상품화하고, 당신의 노력을 복리 효과가 생기는 곳으로 이동시켜요: 당신의 도메인에 맞춰진 프롬프트, 도구, 컨텍스트. 이걸 HaaS라고 부르든 그냥 “에이전트 빌딩”이라고 부르든, Claude Code SDK는 오늘 기준으로 가장 빌드하기 쉬운 harness예요.

그 베이스라인에서 시작해서, 집요하게 전문화하고, 측정된 결과물로부터 에이전트를 개선하세요.

이런 미래가 당신을 설레게 한다면, 연락 주세요. 우리는 여기서 빌딩하고 있어요. 다음 번까지, 해피 harness 빌딩!