하네스 엔지니어링
OpenAI·Anthropic·Toss·gstack·revfactory 사례와 기술 메커니즘으로 풀어낸 하네스 설계·검증·운영 가이드
하네스 엔지니어링은 더 좋은 프롬프트를 쓰는 기술이 아닙니다. 에이전트가 오래, 크게, 안정적으로 일할 수 있도록 작업 환경을 설계하는 기술입니다.
같은 모델과 같은 IDE를 써도 생산성 차이가 크게 나는 이유는, 모델 자체보다 맥락 구조, 검증 루프, 승인 지점, 문서 품질, 도구 접근성이 다르기 때문입니다.
이 책의 핵심 메시지
범용 하네스는 출발점으로는 유용하지만, 성능은 결국 우리 팀의 도메인 규칙과 운영 기준을 얼마나 명시적으로 외재화했는지에서 갈립니다.
기존 핸드북과의 차이
- LLMOps·AgentOps: 운영 체계 중심 → 이 책은 에이전트가 일하는 작업 시스템 설계 중심
- 에이전트 오케스트레이션 패턴: 멀티에이전트 구조 중심 → 이 책은 단일/멀티에이전트 공통 하네스 중심
- Codex / Claude Code 고급 활용: 도구별 실전 활용 중심 → 이 책은 도구를 넘어서는 팀 공통 원리 중심
- 에이전틱 시대의 문서화 혁신: 문서 설계 중심 → 이 책은 문서 + 평가 + 승인 + 운영의 통합 설계 중심
이 책이 재구성한 소스 맵
| 자료 | 이 책에서 가져온 핵심 질문 | 한 줄 요약 |
|---|---|---|
OpenAI Harness Engineering | 에이전트가 어디서 일하는가 | 리포, 문서, 브라우저, 로그가 하네스다 |
Anthropic Harness design... | 에이전트가 어떻게 검증되는가 | planner / evaluator가 언제 load-bearing인지 실험하라 |
| Toss 하네스 글 | 하네스를 어떻게 팀에 배포하는가 | 개인 감각이 아니라 실행 가능한 SSOT로 내려야 한다 |
gstack | 하네스를 어떻게 워크플로우로 묶는가 | Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect |
revfactory/harness | 하네스를 어떻게 재현 가능하게 만드는가 | 도메인 분석부터 하네스 생성까지 메타 프로세스로 다룬다 |
하네스는 어디서부터 시작되는가
좋은 프롬프트는 한 번의 출력을 개선합니다.
- 목표를 더 선명하게 설명
- 출력 형식을 더 잘 고정
- 한 번의 호출 품질을 개선
좋은 컨텍스트는 모델이 참고할 재료를 개선합니다.
- 어떤 문서를 읽을지
- 어떤 파일을 먼저 볼지
- 어떤 규칙을 우선시할지
좋은 하네스는 작업 전체를 개선합니다.
- 계획, 구현, 리뷰, QA, 승인, 릴리즈의 배치
- 브라우저, 로그, 테스트, 문서 접근
- 실패했을 때 되돌아갈 루프
좋은 플랫폼은 하네스를 팀 전체에 배포합니다.
- 공통 스킬/커맨드/템플릿
- 도메인별 규칙 레이어
- 업데이트 로그, 관찰 지표, 가비지 컬렉션
이 책이 답하는 질문
- 하네스 엔지니어링은 프롬프트 엔지니어링이나 컨텍스트 엔지니어링과 무엇이 다른가
- 좋은 하네스는 어떤 요소로 구성되는가
- 왜 하네스가 감각이 아니라 입력·상태·검증·권한 경계의 엔지니어링 문제인가
- OpenAI, Anthropic, Toss, gstack, revfactory/harness는 각각 무엇을 강조하는가
- 왜 결국 남의 하네스를 그대로 복제하기보다 우리 팀의 하네스로 수렴해야 하는가
- 실제 팀에서는 어떤 순서로 하네스를 설계하고 운영해야 하는가
이런 독자에게 적합합니다
| 독자 | 얻는 것 |
|---|---|
| AI 코딩 에이전트를 팀에 도입하는 리드 | 개인 요령을 팀 시스템으로 바꾸는 설계 기준 |
| Codex, Claude Code, Cursor 등을 쓰는 실무 개발자 | 도구 활용을 넘어 작업 환경 자체를 개선하는 관점 |
| AgentOps/Platform 역할 | 평가, 승인, 관측성, 문서 구조를 묶는 운영 프레임 |
| 사내 AI 표준을 고민하는 팀 | 실행 가능한 SSOT와 팀 공통 워크플로우 설계 방법 |
5분 자가진단
| 지금 가장 크게 막히는 지점 | 먼저 읽을 장 |
|---|---|
| 같은 모델을 써도 팀원마다 결과 편차가 너무 큼 | foundations -> engineering-mechanics |
| 프롬프트는 많은데 반복 품질이 안 나옴 | five-elements -> engineering-mechanics |
| 리뷰와 QA가 항상 뒤늦게 문제를 잡음 | evaluation-loops -> case-anthropic |
| 남의 하네스를 복사했는데 우리 팀엔 잘 안 맞음 | case-studies -> make-it-yours |
| 문서, 승인, 브라우저 검증이 따로 놀고 있음 | case-openai -> checklist |
하네스 성숙도 지도
추천 읽기 경로
| 목적 | 추천 순서 |
|---|---|
| 개념부터 빠르게 이해하고 싶음 | foundations -> engineering-mechanics -> five-elements |
| 외부 사례를 비교해 보고 싶음 | case-studies -> case-openai -> case-anthropic |
| 프론트엔드/UI 팀에 바로 적용하고 싶음 | domain-playbooks -> scenario-frontend-team |
| 플랫폼/모노레포 팀 규칙을 만들고 싶음 | domain-playbooks -> scenario-platform-team |
| 결제·정산처럼 승인과 정합성이 핵심임 | domain-playbooks -> scenario-payments-team |
| AI 제품의 eval과 rollout이 핵심임 | domain-playbooks -> scenario-ai-product-team |
| 팀 배포 감각이 필요함 | case-toss -> team-rollout |
| workflow와 release gate를 보고 싶음 | case-gstack -> operations |
| 메타 하네스 설계가 궁금함 | case-revfactory -> make-it-yours |
| 검증 루프를 먼저 잡고 싶음 | evaluation-loops -> checklist |
| 팀에 바로 적용하고 싶음 | team-rollout -> checklist -> operations |
| LLMOps/AgentOps와 연결해 보고 싶음 | five-elements -> checklist -> /books/llmops-agentops |
책의 구조
목차
01. 하네스 엔지니어링의 기초
하네스의 정의, 프롬프트/컨텍스트 엔지니어링과의 차이, 왜 지금 중요한가
02. Repo-readable 시스템
AGENTS.md, docs, observability, executable SSOT를 작업 환경으로 묶는 방법
03. 하네스의 5요소
환경, 역할, 기준, 루프, 정리라는 5개의 설계 축
04. 하네스의 기술 메커니즘
입력, 상태, 도구, 평가, 권한 경계가 왜 엔지니어링 문제인지
05. 검증 루프 설계
planner / builder / evaluator / QA를 언제 분리해야 하는지
06. 외부 사례 비교
OpenAI, Anthropic, Toss, gstack, revfactory/harness를 같은 기준으로 읽기
07. 사례: OpenAI
repo-readable 시스템, observability, cleanup이 왜 하네스의 핵심인지
08. 사례: Anthropic
load-bearing scaffolding, evaluator, retry budget의 설계 기준
09. 사례: Toss
frictionless harness, executable SSOT, domain HITL을 팀에 배포하는 방식
10. 사례: gstack
Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect를 sprint 구조로 해석
11. 사례: revfactory/harness
하네스를 생성 가능한 산출물로 보고 설계·검증하는 메타 프로세스
12. 도메인별 적용 지도
프론트엔드, 플랫폼, 결제, AI 제품 팀이 어디서 다르게 하네스를 설계해야 하는지
13. 시나리오: 프론트엔드 팀
브라우저 QA, a11y, design rule이 load-bearing인 팀의 하네스
14. 시나리오: 플랫폼 팀
invariants, impact analysis, release gate가 핵심인 팀의 하네스
15. 시나리오: 결제·정산 팀
approval, reconciliation, audit trail이 핵심인 팀의 하네스
16. 시나리오: AI 제품 팀
eval set, safety policy, canary rollout이 핵심인 팀의 하네스
17. 왜 결국 자기 하네스로 가는가
무엇을 복사하고 무엇을 팀에 맞게 재설계해야 하는지
18. 팀 하네스 배포 전략
개인 루틴을 팀 워크플로우와 도메인 레이어로 확장하는 방법
19. 팀 하네스 설계 체크리스트
리포지터리, 승인, 평가, 브라우저, 로그, 릴리즈 루프를 설계하는 실전 질문
20. 운영: 엔트로피와 가비지 컬렉션
오래된 규칙, 깨진 워크플로우, 문서 드리프트를 줄이는 운영 루틴
다른 핸드북과의 관계
같이 보면 좋은 책
/books/llmops-agentops: 하네스를 운영 체계와 연결하는 방법/books/agent-orchestration-patterns: 멀티에이전트 구조 패턴/books/agentic-documentation: AI-readable 문서 설계/books/codex-advanced,/books/claude-code-advanced: 각 도구 안에서 하네스를 구현하는 실무 팁
한 줄 정의
하네스 엔지니어링은 에이전트가 잘 일하도록 모델 바깥의 시스템을 설계하는 일입니다.