검증 리포트
하네스 엔지니어링 핸드북의 링크·정합성·근거 검증 결과
이 문서는 하네스 엔지니어링 핸드북의 구조, 근거, 교차 링크, handbook 앱 수준 정적 검증 결과를
기록합니다.
검증 기준일
2026년 5월 23일
검증 범위
| 항목 | 기준 |
|---|---|
| 문서 구조 | meta.json 선언과 실제 MDX 파일 일치 여부 |
| 내용 정합성 | 핵심 주장과 장 구성이 서로 충돌하지 않는지 |
| 외부 근거 | OpenAI, Anthropic, Toss, gstack, revfactory/harness를 근거로 삼는 구간 점검 |
| 교차 링크 | 관련 핸드북과의 연결성 확인 |
| 앱 검증 | handbook 범위 lint, typecheck, build 결과 |
검증 방법
apps/handbook/content/books/ko/harness-engineering/meta.json과 실제 MDX 파일 목록을 대조했습니다.- 각 장의 주장을 외부 자료의 핵심 메시지와 비교해 과도한 일반화가 없는지 확인했습니다.
LLMOps·AgentOps,Codex,Claude Code,오케스트레이션,문서화책과의 링크를 확인했습니다.- OpenAI 관련 최신 정보는 OpenAI developer docs MCP와 공식 OpenAI 사이트를 우선 확인했습니다.
- Anthropic 최신 항목은 engineering/news 원문과 Claude Code / Managed Agents 공식 문서 검색 결과를 함께 대조했습니다.
- GitHub 원본 README와 GitHub API metadata로
gstack,revfactory/harness의 최신 상태를 확인했습니다. - handbook 범위 정적 검증을 실행해 MDX와 앱 빌드 정합성을 확인했습니다.
결과 요약
| 항목 | 결과 |
|---|---|
meta.json와 실제 MDX 파일 | 23개 페이지 기준 일치 |
| 구조 흐름 | 이상 없음 |
| 외부 근거 연결 | 이상 없음 |
| 교차 링크 | 이상 없음 |
pnpm --filter handbook run check:books-registry | 통과 |
pnpm --filter handbook run typecheck | 통과 |
pnpm --filter handbook run build | 통과 |
핵심 근거 목록
| 자료 | 발행일 | 이 책에서 사용한 포인트 |
|---|---|---|
| OpenAI, Harness Engineering | 2026-02-11 | agent-readable repo, 짧은 AGENTS.md, 구조화된 docs, 관측성, 가비지 컬렉션 |
| OpenAI, The next evolution of the Agents SDK | 2026-04-15 | model-native harness, native sandbox execution, MCP/skills/AGENTS.md/shell/apply_patch primitive |
| OpenAI API Changelog | 2026-05-06 / 2026-05-19 | TypeScript sandbox agents와 open-source harness, Secure MCP Tunnel |
| OpenAI Developers plugin for Codex | 2026-05-07 | OpenAI Platform access, API key setup, troubleshooting을 plugin surface로 배포 |
| OpenAI, Work with Codex from anywhere | 2026-05-14 | mobile/remote connection, approvals, hooks, enterprise environment 흐름 |
| OpenAI Agents SDK / Sandbox / Codex docs | 2026-05-23 열람 기준 | sandbox capability, hooks lifecycle, remote connections |
| Anthropic, Harness design for long-running application development | 2026-03-24 | planner/generator/evaluator, 모델 성능에 따라 바뀌는 load-bearing 구조 |
| Anthropic, Claude Code auto mode | 2026-03-25 | prompt-injection probe, transcript classifier, trust boundary, denial fallback |
| Claude Code permission / auto mode docs | 2026-05-23 열람 기준 | permission mode별 자동화 범위, protected path, classifier 평가 순서, trusted infrastructure 설정 |
| Anthropic, Scaling Managed Agents | 2026-04-08 | session/harness/sandbox 분리, durable event log, credential vault와 MCP proxy |
| Claude Managed Agents overview / MCP connector docs | 2026-05-23 열람 기준 | agent, environment, session, events 개념과 MCP auth/vault 분리 |
| Anthropic, Agents for financial services | 2026-05-05 | domain agent templates, skills/connectors/subagents, per-tool permissions, audit log |
| Toss, Harness를 통한 조직 생산성 저점 높이기 | 2026-02-26 | frictionless harness, executable SSOT, domain layer, HITL |
| gstack README | 2026-05-23 열람 기준 | 23 specialists, 8 power tools, 10 agent hosts, team mode, browser/iOS QA, checkpoint/learn |
| revfactory/harness README | 2026-05-23 열람 기준 | v1.2.0, L3 Meta-Factory / Team-Architecture Factory, 6 architecture patterns, A/B caveat |
추론으로 정리한 구간
아래 내용은 특정 한 문서의 직설적 표현이 아니라 여러 자료를 종합한 해석입니다.
| 구간 | 해석 근거 |
|---|---|
| "하네스는 프롬프트보다 작업 시스템 설계에 가깝다" | OpenAI의 repo/observability 강조 + Anthropic의 구조적 evaluation + Toss의 시스템 해석 |
| "범용 하네스는 출발점, 팀 고유 하네스는 목적지" | Toss의 domain layer/HITL + gstack의 make it yours + revfactory의 domain-specific teams |
| "운영과 cleanup은 하네스의 일부" | OpenAI의 entropy/doc gardening 관점 |
| "하네스 primitive는 제품화되지만 도메인 설계는 사라지지 않는다" | OpenAI Agents SDK의 표준 primitive + gstack/revfactory의 domain/workflow 확장 |
| "자동 승인은 사람 승인의 단순 대체가 아니라 별도 정책 계층이다" | Anthropic auto mode의 classifier/trust-boundary 구조 + 고위험 작업 caveat |
| "장시간 agent runtime은 context window가 아니라 durable session log를 중심으로 설계해야 한다" | Anthropic Managed Agents의 session/harness/sandbox 분리 |
챕터별 검증 결과
| 챕터 | 확인 포인트 | 결과 |
|---|---|---|
foundations | 프롬프트/컨텍스트/하네스 구분 | 이상 없음 |
repo-readable-systems | OpenAI/Toss 기반 repo/doc/SSOT 해석 | 이상 없음 |
five-elements | 환경, 역할, 기준, 루프, 정리의 5축 일관성 | 이상 없음 |
engineering-mechanics | 입력/상태/도구/권한 경계를 엔지니어링 문제로 설명하는지 | 이상 없음 |
evaluation-loops | planner/evaluator/browser QA 분리 기준 | 이상 없음 |
case-studies | 사례별 포인트가 서로 섞이지 않는지 | 이상 없음 |
case-openai | repo-readable/observability/cleanup 해석 | 이상 없음 |
case-openai | Agents SDK, sandbox, MCP, hooks, Developers plugin 최신 흐름 | 2026-05-23 보강 |
case-anthropic | load-bearing scaffolding, retry budget, managed runtime, auto approval 해석 | 2026-05-23 보강 |
case-toss | executable SSOT, domain layer, HITL 해석 | 이상 없음 |
case-gstack | sprint, command, release gate, 다중 host, iOS/browser QA 해석 | 2026-05-23 보강 |
case-revfactory | domain-first team architecture generation, validation caveat 해석 | 2026-05-23 보강 |
domain-playbooks | 사례를 도메인 적용 모델과 domain template 패키징으로 연결하는지 | 2026-05-23 보강 |
scenario-frontend-team | browser QA, a11y, design rules의 load-bearing 포인트 | 이상 없음 |
scenario-platform-team | invariants, impact analysis, release gate 해석 | 이상 없음 |
scenario-payments-team | approval, reconciliation, audit trail 해석 | 이상 없음 |
scenario-ai-product-team | eval set, canary, telemetry 해석 | 이상 없음 |
make-it-yours | 개인 노하우와 팀 운영체계의 구분 | 이상 없음 |
team-rollout | 개인 루틴 -> 팀 workflow/plugin/domain template 확장 경로 | 2026-05-23 보강 |
checklist | 바로 적용 가능한 질문으로 정리됐는지 | 2026-05-23 보강 |
operations | 운영과 가비지 컬렉션 관점 반영 | 2026-05-23 보강 |
교차 링크 확인
| 대상 책 | 연결 방식 | 상태 |
|---|---|---|
/books/llmops-agentops | 운영 체계 연결 | 확인 |
/books/agent-orchestration-patterns | 멀티에이전트 설계 연결 | 확인 |
/books/agentic-documentation | AI-readable 문서 연결 | 확인 |
/books/codex-advanced | Codex 환경 설계 연결 | 확인 |
/books/claude-code-advanced | Claude Code 환경 설계 연결 | 확인 |
검증 한계
범위 안내
이 리포트는 2026년 5월 23일 기준의 문서 구조와 해석을 검증합니다.
외부 자료는 빠르게 변할 수 있으므로, 실제 주장 변화가 생기면 updates.mdx에 해석 변경 로그를 먼저
남겨야 합니다.