Harness 맛보기
AI 에이전트 하네스 제작 실습을 통해 접근 순서, task/phase 구조, 그리고 스크립트 활용의 이점을 정리합니다.
| ‘바이브마피아 | VibeMafia’님 라이브 영상을 보면서 직접 하네스 제작을 실습해보았다. |
하네스(Harness) 엔지니어링이란? AI 에이전트가 일관된 흐름으로 작업을 수행할 수 있도록 파이프라인(단계, 역할, 실행 방식)을 설계하는 것을 말한다. 단순히 프롬프트를 잘 쓰는 것을 넘어, 에이전트 세션을 어떻게 구성하고 오케스트레이션할지를 체계화하는 개념이다.
왜 하네스가 필요한가
단순한 작업은 AI에게 바로 요청해도 된다. 하지만 작업이 복잡해질수록 문제가 생긴다.
- 한 번의 세션에 너무 많은 작업이 몰리면 AI의 집중도와 정확도가 떨어진다.
- 이전 세션의 결과를 다음 세션으로 자연스럽게 이어가기 어렵다.
- 어느 단계에서 실패했는지 추적하기 힘들다.
- 같은 작업을 반복할 때마다 처음부터 다시 설명해야 한다.
하네스는 이런 문제를 해결하기 위해, 작업을 단계별로 쪼개고 각 단계의 입출력을 명확히 정의하는 방식으로 AI를 구조적으로 활용하는 접근이다.
접근 순서
전제
- 하네스 엔지니어링은 특정 직군을 위한 기술이 아니라, AI가 적용되는 모든 분야에서 이제 필요한 역량이라고 생각한다.
- 처음부터 너무 많은 스킬을 사용하기보다, 하나의 스킬로 시작해 필요한 부분이 생길 때마다 파이프라인을 고도화해 나가는 것이 올바른 방향이라고 생각한다.
거쳐야 할 단계
실습을 통해 정리한 하네스 파이프라인의 기본 흐름이다. 모든 단계를 처음부터 완벽하게 구현할 필요는 없고, 이 흐름을 염두에 두면서 필요한 단계부터 하나씩 붙여나가면 된다.
1. Clarify — 요구사항 이해
사용자의 요구사항을 정확히 ‘이해’하는 단계다.
- 이 단계는 반드시 거치는 것이 좋다.
- 특정 요구사항에 대해 여러 관점에서의 논의점을 제안해달라고 한 뒤, “이게 최선인가?”를 함께 검토하는 과정을 반복하는 것이 중요하다.
- 이 단계를 건너뛰면 나중에 잘못된 방향으로 구현하고 처음부터 다시 하는 일이 생긴다.
1
2
3
# Clarify 프롬프트 예시
"다음 요구사항을 구현하기 전에, 내가 놓칠 수 있는 엣지 케이스나
모호한 부분이 있으면 먼저 질문해줘. 확인 없이 바로 구현하지 말고."
2. Context Gather — 관련 컨텍스트 수집
요구사항을 명확히 이해한 뒤, 관련된 과거 기록이나 코드를 찾아보게 하는 단계다.
- 이 단계를 AI에게 통째로 맡기면 정작 참조해야 할 것을 놓치는 경우가 생긴다.
- 문서에 사용된 단어나 폴더명을 명확하게 정리해두는 것만으로도 이 문제를 상당 부분 해소할 수 있다.
- 어떤 파일을 읽어야 하는지, 어떤 문서를 참고해야 하는지를 명시적으로 알려주는 것이 효율적이다.
1
2
3
4
5
# Context Gather 프롬프트 예시
"구현 전에 먼저 아래 파일들을 읽어줘:
- src/payment/PaymentService.java (기존 결제 로직)
- docs/api-spec.md (API 스펙 문서)
읽고 나서, 새 기능과 충돌할 수 있는 부분이 있는지 먼저 알려줘."
3. Plan — 구현 계획 수립
바로 코드를 작성하지 않고 먼저 계획을 세우게 한다.
- 계획을 먼저 보고 방향이 맞는지 확인한 뒤 구현으로 넘어가는 것이 훨씬 안전하다.
- 계획 단계에서 잘못된 방향을 잡으면 구현 이후에 수정하기 훨씬 어렵다.
1
2
3
# Plan 프롬프트 예시
"구현하기 전에 어떻게 접근할지 계획만 먼저 작성해줘.
코드는 아직 작성하지 말고, 내가 계획을 검토한 뒤 진행할게."
4. Generate — 구현
계획이 확정된 후 실제 코드를 작성한다. 한 번에 너무 많은 것을 구현하려 하지 말고, 단위별로 나눠서 진행하는 것이 좋다.
5. Evaluate — 검증
구현된 결과물을 검토하는 단계다. 단순히 “잘 됐나?”가 아니라 구체적인 기준으로 검토해야 한다.
1
2
3
4
5
6
# Evaluate 프롬프트 예시
"방금 구현한 코드를 아래 기준으로 검토해줘:
1. 요구사항을 모두 충족했는가?
2. 예외 처리가 빠진 부분은 없는가?
3. 기존 코드 스타일과 일관성이 있는가?
문제가 있으면 수정하고, 없으면 완료라고 말해줘."
task/phase 구조를 사용하는 이유
규모가 큰 작업은 한 번의 호흡으로 전부 구현하기 어렵다. 작업을 작게 쪼개 두고, 여러 에이전트 세션이 이어서 작업하도록 구성하기 위해서다.
각 phase의 결과물을 파일로 저장해두면, 다음 세션에서 이어받아 작업할 때 컨텍스트를 다시 설명할 필요가 없다. 중간에 실패해도 해당 단계만 재실행하면 된다.
스크립트를 사용하는 이유
서브 에이전트에게 작업을 위임하면, 그 오케스트레이션(1번 끝나면 2번 호출, 실패 시 재시도, 중간 상태 저장 등)은 메인 세션의 책임으로 남는다. 이를 Python 스크립트로 분리하면 메인 세션은 스크립트를 실행하기만 하면 되고, 스크립트가 순서대로 에이전트를 호출하고 결과를 기록해준다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# harness.py 예시 구조
def run_phase(phase_name, prompt, input_file=None):
"""각 phase를 실행하고 결과를 파일로 저장"""
result = call_agent(prompt, input_file)
save_result(f"output/{phase_name}.md", result)
return result
def main():
# Phase 1: Clarify
requirements = run_phase("clarify", CLARIFY_PROMPT)
# Phase 2: Plan
plan = run_phase("plan", PLAN_PROMPT, input_file="output/clarify.md")
# Phase 3: Generate
code = run_phase("generate", GENERATE_PROMPT, input_file="output/plan.md")
# Phase 4: Evaluate
run_phase("evaluate", EVALUATE_PROMPT, input_file="output/generate.md")
if __name__ == "__main__":
main()
추가적인 장점도 있다. 메인 세션에 오케스트레이션 관련 컨텍스트가 쌓이지 않아 깔끔하게 유지되고, 오케스트레이션 방식을 스크립트로 고정해두면 모델이 바뀌어도 동일한 흐름으로 작업이 진행된다.
어떤 작업에 하네스를 써야 할까
모든 작업에 하네스가 필요한 건 아니다. 간단한 질문이나 단발성 코드 수정은 직접 요청하는 게 빠르다. 하네스는 아래 상황에서 효과가 크다.
- 여러 파일에 걸쳐 변경이 일어나는 작업
- 반복적으로 실행해야 하는 자동화 작업
- 단계별 검토가 필요한 복잡한 기능 구현
- 팀원이 여럿인 프로젝트에서 AI 작업 방식을 표준화할 때