AI 에이전트 하네스 엔지니어링 입문 결정적 오케스트레이션 직접 짜기: 에이전트를 ‘믿는’ 대신 묶어두는 법

2026년 07월 23일

0 Views

AI 에이전트 하네스 엔지니어링 입문 결정적 오케스트레이션 직접 짜기: 에이전트를 ‘믿는’ 대신 묶어두는 법

AI 에이전트 하네스를 직접 짠다는 건, Claude Code나 Cursor에게 “알아서 해줘”라고 맡기는 대신 입력, 도구 호출, 검증, 실패 처리 순서를 코드로 고정하는 일입니다. 결론부터 말하면 처음부터 거대한 멀티에이전트 시스템을 만들 필요는 없고, 작은 작업 하나를 “계획 → 실행 → 테스트 → 리뷰”로 묶는 하네스부터 시작하는 게 가장 빠릅니다.

작은 PR 자동화부터 하네스를 구성해보고, 검증 단계가 안정되면 LangGraph나 n8n으로 확장해보세요.

제가 추천하는 첫 셋업은 Claude Code 또는 Cursor + GitHub Actions + 간단한 JSON 작업 명세입니다. 여기에 LangGraph나 n8n은 나중에 붙여도 됩니다. 핵심은 모델을 똑똑하게 만드는 것이 아니라, 모델이 엉뚱한 행동을 해도 시스템이 멈추거나 되돌릴 수 있게 만드는 것입니다.

처음 만든다면?
오늘은 “PR 설명 자동 작성” 같은 작은 작업 하나만 하네스로 묶어보세요. 성공 기준이 명확해야 에이전트가 통제됩니다.

하네스가 필요한 순간: 에이전트가 잘할수록 더 위험해진다

Claude Code, Cursor, OpenAI API 기반 에이전트는 파일 수정, 테스트 실행, 문서 생성까지 꽤 잘합니다. 문제는 “꽤 잘한다”는 말이 운영 자동화에서는 부족하다는 점입니다.

예를 들어 리팩터링을 맡겼는데 테스트는 통과했지만 API 응답 필드명이 바뀌면, 사람은 늦게 알아차립니다. 하네스는 이런 일을 막기 위해 에이전트 앞뒤에 레일을 깝니다. 어떤 파일을 읽을 수 있는지, 어떤 명령을 실행할 수 있는지, 결과를 누가 검토할지 정합니다.

직접 짜는 최소 구조

처음에는 아래 5단계면 충분합니다. 복잡한 프레임워크보다 이 흐름을 코드로 남기는 게 중요합니다.

Task spec: 작업 목표, 수정 가능 파일, 금지 작업을 JSON이나 Markdown으로 작성
Planner: Claude Code 또는 GPT-4.1 계열 모델에게 실행 계획만 요청
Executor: 계획 중 허용된 명령만 실행
Verifier: npm test, pytest, 타입체크, 린트 등 결정적 검증 실행
Reporter: 변경 요약, 실패 원인, 다음 행동을 PR 코멘트로 남김

이 방식은 “모델이 판단하는 영역”과 “코드가 판단하는 영역”을 나눕니다. 결정적 오케스트레이션의 핵심은 후자입니다. 테스트 통과 여부, diff 범위, 명령 허용 목록은 LLM이 아니라 프로그램이 판정해야 합니다.

예시: PR 설명 자동 작성 하네스

가상의 예로, 작은 SaaS 저장소에서 PR 설명을 자동 생성한다고 해보겠습니다. 에이전트에게 전체 코드를 수정하게 하지 말고, 먼저 git diff --stat, git diff, 최근 커밋 메시지만 읽게 합니다.

작업 명세는 이렇게 짧게 시작할 수 있습니다.

{
  "goal": "PR description draft 생성",
  "allowed_inputs": ["git diff", "commit messages"],
  "forbidden_actions": ["file write", "package install", "git push"],
  "output_schema": {
    "summary": "string",
    "test_plan": "string[]",
    "risk": "string"
  }
}

이 정도만 해도 ChatGPT나 Claude API 호출 결과가 길게 흔들리는 문제를 줄일 수 있습니다. 출력 스키마가 있으니 Notion, Slack, GitHub Actions로 넘기기도 쉬워집니다.

도구 선택: LangGraph부터 쓸까, 그냥 스크립트로 갈까?

하네스 엔지니어링에서 가장 많이 막히는 지점은 도구 선택입니다. 아래 기준으로 보면 결정이 쉬워집니다.

선택지	잘 맞는 상황	장점	주의할 점
Node/Python 스크립트	작은 자동화, 사내 도구, PR 보조	구조가 단순하고 디버깅이 빠름	상태 관리가 커지면 코드가 지저분해짐
LangGraph	분기, 재시도, 상태 저장이 필요한 에이전트	그래프 기반 흐름을 명확히 표현	처음부터 쓰면 학습 비용이 큼
n8n 또는 Make	Slack, Airtable, Notion 같은 SaaS 연결	비개발자와 흐름 공유가 쉬움	코드 검증·테스트 자동화에는 한계가 있음
GitHub Actions	코드 변경, 테스트, PR 코멘트	개발 워크플로에 자연스럽게 붙음	시크릿·권한 설정을 조심해야 함

제 기준으로는 처음 1주일은 스크립트 + GitHub Actions가 낫습니다. 그래프 프레임워크는 반복 작업이 3개 이상 생기고, 실패 복구 로직이 필요해질 때 도입해도 늦지 않습니다.

누구에게 추천하나

이런 개발자에게 맞습니다

AI 코딩 에이전트를 이미 쓰고 있지만 결과물을 매번 사람이 눈으로 다시 확인하는 팀이라면 하네스가 바로 효과를 냅니다. 특히 테스트가 있는 프로젝트, PR 리뷰가 많은 팀, 문서와 코드가 자주 어긋나는 제품팀에 잘 맞습니다.

아직 이 단계가 아니라면

반대로 테스트가 거의 없고 작업 기준이 문서화되어 있지 않다면, 에이전트 하네스보다 먼저 체크리스트와 테스트를 만들어야 합니다. 하네스는 없는 기준을 만들어주지 않습니다. 이미 있는 기준을 자동으로 적용하게 해주는 장치에 가깝습니다.

자주 하는 실수: 에이전트에게 검증까지 맡기는 것

가장 위험한 패턴은 “수정하고 테스트도 네가 판단해”입니다. LLM은 테스트 로그를 요약할 수는 있지만, 통과 여부의 최종 판정자가 되면 안 됩니다.

예를 들어 npm test가 실패했는데 모델이 “대부분 통과했다”고 말할 수 있습니다. 그래서 하네스에서는 종료 코드, 커버리지 기준, 변경 파일 목록처럼 기계적으로 확인 가능한 값을 기준으로 삼아야 합니다.

바로 해볼 다음 행동

오늘 할 일은 하나입니다. 기존 프로젝트에서 반복되는 작은 작업 하나를 고르고, 아래 4개 파일만 만들어보세요.

task.json: 목표와 금지 행동
run-agent.js 또는 agent.py: 모델 호출과 도구 실행
verify.sh: 테스트·린트·타입체크
report.md: 결과 요약 템플릿

이 구성이 돌아가면 그때 Cursor, Claude Code, LangGraph, n8n 중 어디를 붙일지 판단하면 됩니다. 도구를 먼저 고르면 멋진 데모는 빨리 나오지만, 운영 가능한 자동화는 늦어집니다.

FAQ

Q. MCP도 하네스에 포함되나요?

네, MCP는 에이전트가 외부 도구나 데이터에 접근하는 통로로 볼 수 있습니다. 다만 MCP 서버를 붙였다고 하네스가 완성되는 건 아닙니다. 접근 권한, 호출 순서, 실패 처리까지 정해야 합니다.

Q. Claude Code와 Cursor 중 무엇으로 시작할까요?

터미널 중심으로 자동화를 묶고 싶다면 Claude Code가 편하고, IDE 안에서 파일 수정과 리뷰를 빠르게 반복하려면 Cursor가 편합니다. 하네스 실험은 둘 다 가능하지만, 검증 단계는 GitHub Actions 같은 외부 실행기로 빼는 편이 안전합니다.

Q. 노코드 자동화 도구만으로도 가능할까요?

n8n, Zapier, Make로 알림·문서·CRM 흐름은 충분히 만들 수 있습니다. 하지만 코드 수정, 테스트 실행, 권한 제한이 중요하다면 스크립트나 CI와 함께 쓰는 하이브리드 방식이 더 현실적입니다.

하네스 엔지니어링의 출발점은 거창한 에이전트 플랫폼이 아닙니다. “이 작업에서 AI가 해도 되는 일과 절대 하면 안 되는 일”을 파일로 적는 순간부터 시작됩니다.

AI 에이전트 하네스 엔지니어링 입문 결정적 오케스트레이션 직접 짜기: 에이전트를 ‘믿는’ 대신 묶어두는 법