하네스 엔지니어링
OpenAI·Anthropic·Toss·gstack·revfactory 사례와 Agents SDK·Managed Agents 흐름으로 풀어낸 하네스 설계·검증·운영 가이드
최근 수정된 챕터
프론트엔드 팀, 플랫폼 팀, 결제·정산 팀, AI 제품 팀이 하네스를 어떻게 다르게 설계해야 하는지 안내합니다.
하네스가 시간이 지나며 망가지는 이유와 이를 줄이는 운영 루틴을 설명합니다.
OpenAI와 Toss 관점에서 AGENTS.md, docs, observability, executable SSOT를 작업 환경으로 묶는 방법을 설명합니다.
Anthropic의 long-running harness를 planner/evaluator, Managed Agents, auto approval 관점에서 해부합니다.
gstack을 강한 opinion의 소프트웨어 팩토리로 보고 sprint, command, release gate 관점에서 해석합니다.
하네스 엔지니어링은 더 좋은 프롬프트를 쓰는 기술이 아닙니다. 에이전트가 오래, 크게, 안정적으로 일할 수 있도록 작업 환경을 설계하는 기술입니다.
같은 모델과 같은 IDE를 써도 생산성 차이가 크게 벌어집니다. 모델 자체보다 맥락 구조, 검증 루프, 승인 지점, 문서 품질, 도구 접근성이 다른 탓입니다.
이 책의 핵심 메시지
범용 하네스는 출발점으로 쓸 만합니다. 하지만 성능은 결국 우리 팀의 도메인 규칙과 운영 기준을 얼마나 명시적으로 밖으로 끄집어냈는지에서 갈립니다.
기존 핸드북과의 차이
- LLMOps·AgentOps: 운영 체계 중심 → 이 책은 에이전트가 일하는 작업 시스템 설계 중심
- 에이전트 오케스트레이션 패턴: 멀티에이전트 구조 중심 → 이 책은 단일/멀티에이전트 공통 하네스 중심
- Codex / Claude Code 고급 활용: 도구별 실전 활용 중심 → 이 책은 도구를 넘어서는 팀 공통 원리 중심
- 에이전틱 시대의 문서화 혁신: 문서 설계 중심 → 이 책은 문서 + 평가 + 승인 + 운영의 통합 설계 중심
이 책이 재구성한 소스 맵
| 자료 | 이 책에서 가져온 핵심 질문 | 한 줄 요약 |
|---|---|---|
OpenAI Harness Engineering | 에이전트가 어디서 일하는가 | 리포, 문서, 브라우저, 로그가 하네스다 |
| OpenAI Agents SDK / Codex updates | 하네스가 어떤 표준 primitive로 제품화되는가 | MCP, skills, AGENTS.md, sandbox, shell, apply_patch, hooks, plugin이 공통 기반으로 이동한다 |
Anthropic Harness design... / Managed Agents / auto mode | 에이전트가 어떻게 검증·격리·승인되는가 | planner/evaluator만이 아니라 session, harness, sandbox, permission classifier까지 분리하라 |
| Toss 하네스 글 | 하네스를 어떻게 팀에 배포하는가 | 개인 감각이 아니라 실행 가능한 SSOT로 내려야 한다 |
gstack | 하네스를 어떻게 워크플로우로 묶고 여러 런타임에 배포하는가 | Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect를 command surface로 고정한다 |
revfactory/harness | 하네스를 어떻게 재현 가능하게 만드는가 | 도메인 분석부터 agent team / skill 생성까지 메타 프로세스로 다룬다 |
하네스는 어디서부터 시작되는가
좋은 하네스는 작업 전체를 개선합니다.
- 계획, 구현, 리뷰, QA, 승인, 릴리즈의 배치
- 브라우저, 로그, 테스트, 문서 접근
- 실패했을 때 되돌아갈 루프
이 책이 답하는 질문
- 하네스 엔지니어링은 프롬프트 엔지니어링이나 컨텍스트 엔지니어링과 무엇이 다른가
- 좋은 하네스는 어떤 요소로 구성되는가
- 왜 하네스가 감각이 아니라 입력·상태·검증·권한 경계의 엔지니어링 문제인가
- OpenAI, Anthropic, Toss, gstack, revfactory/harness는 각각 무엇을 강조하는가
- Agents SDK, Managed Agents, sandbox, MCP, skills, hooks, plugins처럼 하네스 primitive가 표준 인프라로 이동하면 팀 설계가 어떻게 달라지는가
- 왜 결국 남의 하네스를 그대로 복제하기보다 우리 팀의 하네스로 수렴해야 하는가
- 실제 팀에서는 어떤 순서로 하네스를 설계하고 운영해야 하는가
이런 독자에게 적합합니다
| 독자 | 얻는 것 |
|---|---|
| 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 시스템, Agents SDK harness, sandbox, observability, cleanup이 왜 핵심인지
08. 사례: Anthropic
load-bearing scaffolding, managed runtime, auto approval classifier의 설계 기준
09. 사례: Toss
frictionless harness, executable SSOT, domain HITL을 팀에 배포하는 방식
10. 사례: gstack
Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect와 다중 agent host 배포를 해석
11. 사례: revfactory/harness
하네스를 생성 가능한 team architecture 산출물로 보고 설계·검증하는 메타 프로세스
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: 각 도구 안에서 하네스를 구현하는 실무 팁
한 줄 정의
하네스 엔지니어링은 에이전트가 잘 일하도록 모델 바깥의 시스템을 설계하는 일입니다.