Agent-harness-kit scaffolding for multi-agent workflows (MCP, provider-agnostic)
TL;DR Highlight
여러 AI 에이전트가 서로 역할을 나눠 협업할 수 있도록 조율하는 scaffolding 도구로, Vite처럼 설정 없이 빠르게 멀티 에이전트 파이프라인을 구성할 수 있다.
Who Should Read
Claude Code, OpenCode 같은 AI 코딩 에이전트를 여러 개 조합해서 복잡한 작업을 자동화하고 싶은 개발자, 또는 멀티 에이전트 워크플로우를 직접 구축하다가 에이전트 간 통신과 상태 관리에서 막힌 백엔드/풀스택 개발자.
Core Mechanics
- agent-harness-kit(AHK)는 Vite에서 영감을 받은 AI 에이전트 오케스트레이션 scaffolding 도구로, 복잡한 설정 없이 멀티 에이전트 워크플로우를 빠르게 구성하는 것을 목표로 한다.
- MCP(Model Context Protocol, AI 에이전트가 외부 도구·서비스와 표준화된 방식으로 통신하는 프로토콜)를 기반으로 하며, 특정 AI 제공사에 종속되지 않는 provider-agnostic 설계를 지향한다.
- 현재 Claude Code와 OpenCode를 예시로 지원하며, lead 에이전트가 여러 sub-에이전트에게 작업을 위임하고 결과를 수집하는 '리드-서브 에이전트' 구조로 동작한다.
- 각 에이전트 간 handoff(작업 인계)는 typed state(타입이 명시된 상태값)로 이루어진다. 이 덕분에 에이전트가 반쯤 완료된 상태('draft_verified_awaiting_review' 같은 중간 상태)를 넘기는 문제를 방지할 수 있다.
- 기본적인 build → review 같은 선형 파이프라인 외에, 더 복잡한 조건 분기 워크플로우(예: 리뷰 결과에 따라 X를 수행하거나 end-to-end 테스트에서 build로 롤백)를 정의할 수 있는지는 아직 문서화가 부족한 상태다.
- sub-에이전트가 작업 완료를 증명하는 방식이 명확하지 않다는 지적이 있다. lead 에이전트가 output을 읽어서 판단하면 사실상 lead가 모든 에이전트의 암묵적 reviewer가 되므로, 별도 review 단계의 필요성이 모호해진다.
- Node.js 의존성을 가진다. 이에 대해 Node 인프라를 꺼리는 개발자로부터 부정적인 반응이 있었다.
- 문서가 AI를 매일 다루는 전문가 위주로 작성돼 있어, 처음 접하는 사람은 이 도구가 무엇을 해결하는지 파악하기 어렵다는 피드백이 나왔다.
Evidence
- 워크플로우 복잡도에 대한 의문이 제기됐다. 단순한 선형 파이프라인이 아니라 '리뷰 결과 각각에 대해 X를 실행'하거나 'end-to-end 테스트 실패 시 build 단계로 롤백'하는 복잡한 분기 로직을 정의할 수 있는지, 그리고 에이전트 없이 실행되는 중간 스텝을 지원하는지에 대한 질문이 올라왔지만 명확한 답변은 없었다.
- 실제 유사 시스템을 운영한 경험자가 'typed handoff가 핵심 primitive'라고 강하게 동의했다. 에이전트 상태를 'posted'처럼 명확한 터미널 상태로만 종료하고, 'blocked_quota'나 'skipped_anti_bunching' 같은 실패 상태도 명시적으로 정의하지 않으면 메인 프로그램이 무한 재시도하며 비용을 다 써버리는 문제를 직접 겪었다는 경험담을 공유했다.
- lead 에이전트가 sub-에이전트 output을 읽는 구조가 사실상 LLM judge(LLM이 다른 LLM의 결과를 평가하는 방식)라는 지적이 있었다. post-condition 체크가 있는지, raw output이 아닌 typed state로 추론하는지 여부가 설계상 중요하다는 의견이 나왔다.
- 자동 git worktree 생성과 샌드박싱 기능이 없냐는 제안이 있었다. 댓글 작성자는 유사한 도구를 직접 만들었는데, git worktree로 에이전트별 격리 공간을 만들고 bubblewrap으로 파일시스템 수준 샌드박싱을 적용한다고 소개했다.
- 'provider-agnostic이라고 하는데 실제로는 Claude Code와 OpenCode만 예시로 있다'는 의구심이 제기됐고, RooCode 같은 기존 에이전트 오케스트레이션 도구와 차별점이 무엇인지에 대한 질문도 올라왔으나 충분한 답변은 없었다.
How to Apply
- Claude Code나 OpenCode를 사용해 코드 작성 → 리뷰 → 테스트 단계를 자동화하고 싶다면, AHK의 lead-sub 에이전트 구조를 활용해 각 단계를 별도 sub-에이전트로 분리하고, typed handoff로 단계 간 상태를 명시적으로 전달하는 파이프라인을 구성할 수 있다.
- 멀티 에이전트 시스템에서 에이전트가 중간 상태로 멈추거나 무한 재시도가 발생하는 문제를 겪고 있다면, 모든 에이전트 실행 결과를 'success', 'blocked_quota', 'skipped_anti_bunching' 등의 명시적 터미널 상태로만 종료하도록 설계해서 상위 오케스트레이터가 정확히 다음 행동을 결정할 수 있게 만들어야 한다.
- 이 도구를 평가 중이라면, 문서가 AI 전문가 위주로 작성돼 있으므로 GitHub 저장소와 함께 ahk.cardor.dev의 예시 코드를 직접 보면서 'lead 에이전트가 typed state를 어떻게 받아서 다음 sub-에이전트에게 넘기는지' 흐름을 먼저 파악하는 것이 빠르다.
- Node.js 환경을 꺼린다면 nix shell로 격리된 환경에서 먼저 테스트해볼 수 있다. 댓글 사용자들이 openspec, oh-my-codex 등 Node 기반 도구를 nix shell로 시도한 경험을 공유했다.
Terminology
Related Papers
Show HN: adamsreview – better multi-agent PR reviews for Claude Code
Claude Code에서 최대 7개의 병렬 서브 에이전트가 각각 다른 관점으로 PR을 리뷰하고, 자동 수정까지 해주는 오픈소스 플러그인이다. 기존 /review나 CodeRabbit보다 실제 버그를 더 많이 잡는다고 주장하지만 커뮤니티에서는 복잡도와 실효성에 대한 회의론도 나왔다.
How Fast Does Claude, Acting as a User Space IP Stack, Respond to Pings?
Claude Code에게 IP 패킷을 직접 파싱하고 ICMP echo reply를 구성하도록 시켜서 실제로 ping에 응답하게 만든 실험으로, 'Markdown이 곧 코드이고 LLM이 프로세서'라는 아이디어를 네트워크 스택 수준까지 밀어붙인 재미있는 사례다.
Show HN: Git for AI Agents
AI 코딩 에이전트(Claude Code 등)가 수행한 모든 툴 호출을 자동으로 추적하고, 어떤 프롬프트가 어느 코드 줄을 작성했는지 blame까지 가능한 버전 관리 도구다.
Principles for agent-native CLIs
AI 에이전트가 CLI 도구를 더 잘 사용할 수 있도록 설계하는 원칙들을 정리한 글로, 에이전트가 CLI를 도구로 활용하는 빈도가 높아지면서 이 설계 방식이 실용적으로 중요해지고 있다.
Show HN: Tilde.run – Agent sandbox with a transactional, versioned filesystem
AI 에이전트가 실제 프로덕션 데이터를 건드려도 롤백할 수 있는 격리된 샌드박스 환경을 제공하는 도구로, GitHub/S3/Google Drive를 하나의 버전 관리 파일시스템으로 묶어준다.
FlexSQL: Flexible Exploration and Execution Make Better Text-to-SQL Agents
고정된 파이프라인 대신 추론 중 언제든 DB를 탐색·실행할 수 있는 Text-to-SQL 에이전트로 Spider2.0 벤치마크에서 gpt-o3, DeepSeek-R1 기반 시스템을 더 작은 모델로 능가