10. Harness Engineering

이 페이지에서 배우는 것

• 1Harness가 무엇이고, 왜 모델 성능보다 중요한지
• 2Codex harness를 구성하는 6가지 요소
• 3OpenAI가 강조하는 7가지 설계 원칙
• 4실전 패턴 6가지와 흔한 안티패턴 5가지
• 5본 가이드의 다른 페이지(Skills/Settings/Worktree 등)와 어떻게 맞물리는지
• 6당신의 저장소를 점검할 수 있는 성숙도 체크리스트

1. Harness란 무엇인가

Harness(하니스)는 본래 말이나 등반가에게 채우는 "안전벨트·연결 장치"를 뜻합니다. 자유롭게 움직이게 두면서도 정해진 경로 밖으로 떨어지지 않도록 잡아주는 기구죠. AI 에이전트의 세계에서도 똑같이 쓰입니다 — 모델 자체가 아니라, 모델을 둘러싼 모든 보조 장치를 가리킵니다.

한 줄로 요약하면 다음 세 가지가 모두 harness입니다.

• ✓경로 — Codex가 무엇을 봐야 하고 무엇을 건드리지 말아야 할지 알려주는 지도(폴더 구조, AGENTS.md, README, plan 파일)
• ✓도구 — 변경을 만들고 검증하는 손과 발(셸, gh, 린터, 테스트 러너, MCP 서버, Skills)
• ✓피드백 — 결과가 맞는지 즉시 알려주는 안전망(타입 체커 결과, 테스트 통과/실패, 린트 에러, 미리보기 빌드)

2. 왜 모델보다 Harness인가

같은 Codex 모델을 써도 결과 품질은 저장소마다 천차만별입니다. OpenAI가 사내·외부 사례에서 반복적으로 관찰한 결론은 단순합니다 — 대부분의 격차는 모델이 아니라 harness에서 발생합니다. 그 이유는 다음과 같습니다.

3. Codex Harness의 6가지 구성 요소

Codex(앱·CLI·IDE 확장·Cloud) 환경에서 harness는 보통 다음 6개 층으로 분해됩니다. 각 층은 본 가이드의 다른 페이지에서 자세히 다루고 있으니 링크를 따라 함께 보세요.

4. Harness 설계 원칙 7가지

아래 원칙들은 "Harness engineering" 글, 본 사이트의 Skills·Settings 페이지, 그리고 Codex 팀이 사내에서 누적해 온 베스트 프랙티스를 종합한 것입니다.

원칙 1 · 1,000장짜리 매뉴얼이 아니라 한 장의 지도

모든 규칙을 한 번에 넣은 거대한 AGENTS.md는 컨텍스트를 잡아먹고, 정작 모델은 핵심을 놓칩니다. 시작점은 작고, 안정적이고, 어디로 가야 할지 알려주는 지도여야 합니다. 세부 규칙은 폴더별 AGENTS.md나 Skills로 흩뿌려 두고, 필요할 때만 따라가게 하세요.

원칙 2 · Progressive Disclosure(점진적 노출)

Skills는 처음에 이름·설명·경로 정도의 메타데이터만 모델에 보이고, 실제로 호출이 결정되면 그때 SKILL.md 본문을 로드합니다. 같은 패턴을 직접 만든 컨텍스트에도 적용하세요 — 큰 가이드는 목차만 노출, 본문은 링크/스킬로 분리합니다.

원칙 3 · 검증을 행동에 가깝게

"PR이 올라간 뒤 CI에서 잡힌다"는 너무 늦습니다. 가능한 한 편집 → 즉시 검증 루프를 짧게 만들어, 에이전트가 자기 변경을 한 턴 안에서 확인하게 하세요. 빠른 단위 테스트, 가벼운 lint, 타입 체크, 미니 빌드를 npm test:fast·make check 같은 단일 명령으로 묶어 두면 효과가 큽니다.

원칙 4 · 저장소에 박아 두는 Skill

팀 전체가 매번 똑같이 하는 일(릴리스 노트 만들기, DB 마이그레이션 검증, 모듈 신규 생성)은 채팅으로 매번 설명하지 말고 repo 내 .agents/skills/나 .codex/skills/에 SKILL.md로 박아 두세요. Codex 앱·CLI·IDE 확장이 모두 같은 skill을 본다는 것이 큰 장점입니다.

원칙 5 · 권한은 코드로

"이 작업은 안전한가?"를 매 호출마다 사람에게 묻게 하면 자동화는 죽습니다. ~/.codex/config.toml의 sandbox_mode·approval_policy·[profiles.NAME]로 환경별 권한을 미리 묶어 두고, automations에는 approval_policy = "never" + 좁은 sandbox로 걸어 둡니다. → Settings의 config.toml 스키마

원칙 6 · Plan-as-Code

현재 진행 중인 plan, 완료된 plan, 알려진 기술 부채를 코드와 같은 저장소에 버전 관리하세요. 그러면 새 스레드를 시작해도 외부 컨텍스트에 의존하지 않고, "지금 무엇을 건드리면 안 되는지"를 에이전트가 스스로 파악합니다. 본 가이드의 Automations도 plan 파일을 입력으로 사용할 때 가장 강력합니다.

원칙 7 · Harness를 제품처럼 다뤄라

Harness는 한 번 만들고 끝나는 인프라가 아니라 지속적으로 유지·개선되는 내부 제품입니다. 누군가 "이 작업은 매번 사람이 다시 설명해야 한다"고 느끼면 그건 harness 결함입니다. AGENTS.md·Skill·검증 스크립트의 변경도 코드 리뷰처럼 다루고, 회고에서 "이번 분기에 harness가 어떻게 진화했는가"를 별도 항목으로 검토하세요.

5. 실전 패턴 6가지

패턴 A · 3단계 AGENTS.md

전역 규칙·저장소 규칙·패키지 규칙을 분리합니다. 가장 가까운 파일이 우선 적용된다는 점을 활용하세요.

~/.codex/AGENTS.md             # 모든 프로젝트 공통: 어조, 위험 명령 차단
<repo>/AGENTS.md               # 팀 공통: 빌드·테스트 한 줄 명령, 폴더 지도
<repo>/packages/api/AGENTS.md  # 패키지별: API 컨벤션, DB 마이그레이션 규칙

패턴 B · Map 섹션을 AGENTS.md 최상단에

# MAP (반드시 읽기)
- src/         애플리케이션 코드 (TypeScript)
- scripts/     로컬·CI에서 둘 다 호출되는 명령 모음
- .agents/skills  팀 공용 Skills
- docs/adr/    설계 결정 기록 — 아키텍처 변경 시 새 ADR 추가
- ⚠️ migrations/ 는 절대 수동 편집 금지, scripts/new-migration 사용

"지도 + 금지 구역" 두 개만 있어도 모델 행동이 크게 안정됩니다.

패턴 C · 단일 검증 명령

# package.json (예시)
{
  "scripts": {
    "verify": "tsc --noEmit && eslint . && vitest run --changed"
  }
}

AGENTS.md에 "변경 후에는 항상 npm run verify를 실행하라"라고 한 줄 적어 두면, 에이전트가 자기 변경을 자가 검증합니다.

패턴 D · 저장소 내장 Skill

.agents/skills/release-notes/SKILL.md
---
name: release-notes
description: |
  최신 git tag부터 HEAD까지 변경 사항을 카테고리별로 정리한
  릴리스 노트 초안을 생성합니다.
allow_implicit_invocation: true
---
1. `git log --oneline ${LAST_TAG}..HEAD` 실행
2. Conventional Commits 접두사로 그룹화
3. CHANGELOG.md 상단에 추가

패턴 E · 환경별 Profile 분리

# ~/.codex/config.toml
[profiles.review]
sandbox_mode    = "read-only"
approval_policy = "on-request"

[profiles.bot]
sandbox_mode    = "workspace-write"
approval_policy = "never"
model_reasoning_effort = "low"

대화형 검토는 codex --profile review, 야간 자동화는 codex --profile bot — 같은 저장소에서도 권한·모델 강도를 깔끔히 분리할 수 있습니다.

패턴 F · gh 우선 통합

PR 생성·리뷰·코멘트를 직접 API로 다루지 말고 gh로 통일하세요. AGENTS.md에 gh pr create, gh pr view --json, gh pr comment 같은 정확한 명령 템플릿을 박아 두면 에이전트가 사람과 같은 도구로 GitHub과 대화합니다. → Review 페이지의 PR 워크플로

6. 흔한 안티패턴 5가지

• ✗"전 사항을 다 적자"식 AGENTS.md. 5,000자가 넘는 단일 파일은 컨텍스트만 잡아먹고 본문이 묻힙니다. 짧은 지도 + 폴더별 분할이 정답.
• ✗채팅으로만 전수되는 비밀 규칙. "이 디렉터리는 건드리지 마세요"를 코드(AGENTS.md)·구조(.gitignore·CODEOWNERS)·검증(테스트)으로 박지 않으면 매번 새 스레드에서 같은 사고가 납니다.
• ✗검증을 PR 후로 미루기. CI에서만 잡히는 에러는 에이전트가 학습할 기회를 놓칩니다. 가능한 한 한 턴 안에 자가 검증되도록 하세요.
• ✗매번 권한을 묻는 자동화. automations에 사람 승인이 끼면 자동화의 의미가 없어집니다. 권한은 profile/sandbox로 미리 좁혀 두고, 결과만 Triage에서 검토하세요.
• ✗도구 과적재. 쓰지 않는 MCP 서버, 죽은 Skill, 사용처 없는 슬래시를 그대로 두면 모델이 잘못된 도구를 고를 확률이 올라갑니다. 안 쓰는 도구는 ~/.codex/config.toml의 enabled = false로 꺼두세요.

7. 본 가이드의 다른 페이지와 어떻게 맞물리나

8. Codex 에이전트 루프와 Harness

Codex의 내부 동작은 단순한 루프입니다. 사용자의 메시지를 읽고 → 어떤 도구를 쓸지 계획하고 → 도구를 호출하고 → 결과를 관찰하고 → 다시 다음 단계를 결정합니다. Harness는 이 루프의 매 단계를 형성합니다.

1. 메시지 읽기      ← AGENTS.md / @file / Memories         (컨텍스트 레이어)
2. 도구 계획        ← 노출된 Skills · MCP 서버 · CLI       (도구 레이어)
3. 도구 호출        ← sandbox / approval / profile         (격리 레이어)
4. 결과 관찰        ← lint · test · /review · codex review (검증 레이어)
5. 다음 단계 결정   ← 더 좋은 검증 신호 = 더 정확한 다음 액션
                     ↳ 막히면 사람에게 질문 (인터페이스 레이어)

Harness가 빈약하면 (2)에서 잘못된 도구를 고르고, (4)에서 검증 신호가 없어 같은 실수를 반복합니다. Harness가 잘 짜여 있으면 (4)의 신호가 명확해 (5)에서 자기 수정이 일어나고, 사람의 개입 없이 한 턴 안에 끝나는 작업이 늘어납니다.

9. Harness 성숙도 체크리스트

아래 항목 중 몇 개에 ✅를 칠 수 있는지 세어 보세요. 6개 이하면 "프롬프트 엔지니어링"에 머물고 있는 것이고, 12개 이상이면 진짜 harness 엔지니어링이 작동하고 있는 것입니다.

장점 / 단점 / 한계점