하네스 엔지니어링 위키

Codex 공식문서 — 핵심 개념

Properties1
tags공식문서, 개념

15 min read

Codex 공식문서 — 핵심 개념

한 줄 요약

OpenAI Codex 공식문서가 말하는 “코딩 에이전트”는 LLM 본체를 둘러싼 운영 골격(하네스) 위에서 돌아가며, 그 골격은 컨텍스트·툴·가드레일·검증이라는 4개 기둥으로 짜여 있다. 왜 배우나 — 같은 모델이라도 이 4기둥을 어떻게 설계하느냐에 따라 결과 품질·안전성·재현성이 크게 달라지기 때문이다.

하네스란?

“하네스(harness)“는 LLM 본체를 둘러싸고 실제로 일을 시키는 운영 골격을 말한다. 마구(馬具)처럼 모델이라는 말(馬)에 씌워 방향을 잡아주는 장치라고 보면 된다. 더 큰 그림은 하네스엔지니어링이란, 용어가 막히면 용어집을 함께 본다.

그림

flowchart TB
    subgraph H["하네스 4기둥 (LLM 본체를 둘러싼 운영 골격)"]
        direction LR
        C["① 컨텍스트<br/>일 시키기 전에<br/>쥐여줄 배경·기억"]
        T["② 툴<br/>외부 세계에<br/>손 뻗는 통로"]
        G["③ 가드레일<br/>넘지 말 선과<br/>멈춤 장치"]
        V["④ 검증<br/>한 일이 맞는지<br/>확인·되돌리기"]
    end
    LLM(["AI 모델 본체"]) --> H
    C --> 작업["에이전트 작업 실행"]
    T --> 작업
    G --> 작업
    V --> 작업
    작업 --> 결과(["검증된 결과물"])

flowchart LR
    A["① AGENTS.md<br/>(기초)"] --> B["② Skills/Plugins<br/>(골조)"]
    B --> Cc["③ MCP<br/>(배관)"]
    Cc --> D["④ Subagents<br/>(인테리어)"]
    A -.->|"맞춤화 권장 빌드 순서<br/>각 층은 경쟁 아닌 보완"| D

쉽게 풀기

새 직원(에이전트)에게 일을 맡긴다고 상상해 보자. 일을 잘 시키려면 네 가지가 필요하다. 이것이 곧 하네스 4기둥이다.

  1. 컨텍스트 — 일 시작 전에 쥐여주는 배경지식과 기억.

    • 신입에게 매번 말로 설명하는 대신 책상에 업무 수칙을 붙여두는 것과 같다.
    • 여기에 들어가는 도구들: 프로젝트 설명서(AGENTS.md), 전역/저장소를 층층이 겹치는 계층형 가이드, 지난 대화를 회상하는 Memories, 의뢰서 역할의 프롬프트, 그리고 맞춤화를 쌓는 권장 순서(Customization 4층).

  2. 툴 — 에이전트가 바깥 세계에 손을 뻗는 통로.

    • 직원이 전화·이메일·결재 시스템을 써야 일이 되듯, 에이전트도 파일을 고치고 명령을 실행하고 외부 서비스에 접속해야 한다.
    • 여기에 들어가는 것들: 재사용 워크플로(Skills), 외부 도구 연결 표준(MCP), 잡무를 위임받는 Subagents, 같은 에이전트를 여러 환경에서 부르는 실행 면(App/IDE/CLI/Cloud), 대화창 없이 자동 호출하는 Non-interactive 모드.

  3. 가드레일 — 넘지 말아야 할 선과, 넘으려 할 때 멈추는 장치.

    • 아이를 놀이터 안에서는 마음껏 뛰게 하되 도로로는 못 나가게 막는 울타리와 같다.
    • 여기에 들어가는 것들: 기술적 경계인 Sandbox, 언제 사람에게 물을지 정하는 Approval Policy, 검토자 에이전트가 대신 판단하는 Auto-review, 명령 단위 예외 규칙(Rules), 권한 묶음(Permissions), 그리고 이들을 합친 종합 보안 운영 모델.

  4. 검증 — 한 일이 진짜 맞는지 확인하고, 틀리면 되돌리는 절차.

    • 수술 전후 사진을 찍어두고 잘못되면 원상복구하는 안전망과 같다.
    • 여기에 들어가는 것들: 동작 시점마다 스크립트를 끼우는 Hooks, 스냅샷·diff 검토(Git 체크포인트/Review), 반복·검증 루프(Workflows), 시행착오로 정립된 Best Practices.

마지막으로 어느 기둥에도 딱 속하지 않고 전 기둥을 받치는 받침 개념이 둘 있다 — 기본값을 저장하는 설정 파일(Config)과, 두뇌의 성능 등급을 고르는 Models다.

핵심 정리

① 컨텍스트 — 일 시키기 전에 무엇을 쥐여줄 것인가

개념한 줄 정의핵심 포인트
AGENTS.md작업 시작 전 항상 먼저 읽는 프로젝트 설명서작게 유지·반복 실수의 교훈을 추가(피드백 루프)
계층형 가이드전역(~/.codex/AGENTS.md)+저장소를 층층이 겹침작업 폴더에 가까운 파일이 우선
Memories선호·관례·함정을 로컬 저장해 다음 작업으로 회상기본 꺼짐·보조 회상용·비밀정보 금지
Prompting”무엇을 원하는지” 전달하는 사용자 메시지의도·범위·맥락이 명확할수록 결과 좋음
Customization 4층맞춤화 권장 빌드 순서AGENTS.md → Skills/Plugins → MCP → Subagents

꼭 지켜야 할 규칙은 어디에?

“반드시 지켜야 할 규칙”은 Memories가 아니라 AGENTS.md/문서에 둔다. Memories는 어디까지나 보조 회상 계층이며 기본 꺼짐 상태, 일부 지역에서는 제공되지 않는다.

② 툴 — 에이전트가 세계에 손을 뻗는 통로

개념한 줄 정의핵심 포인트
Skills반복 작업을 SKILL.md 한 묶음으로 포장한 재사용 워크플로점진적 공개로 컨텍스트 낭비 방지
MCPCodex를 외부 도구·데이터로 잇는 표준 규격Host─Client─Server 구조
Subagents노이즈·전문 작업을 위임하는 보조 에이전트본 에이전트의 집중 보호
실행 면(Surface)App/IDE/CLI/Cloud 등 여러 진입점같은 에이전트를 어디서든 동일하게
Non-interactivecodex exec로 스크립트·CI에서 자동 호출기본 읽기전용·최소 권한만 부여

MCP 서버가 노출하는 3가지

  • Tools — 에이전트가 수행할 수 있는 행동
  • Resources — 에이전트가 읽을 수 있는 데이터
  • Prompts — 재사용 가능한 템플릿

③ 가드레일 — 넘지 말 선과 멈춤 장치

개념한 줄 정의핵심 포인트
Sandbox수정 범위·네트워크를 가두는 기술적 경계승인 피로(approval fatigue) 감소
Approval Policy언제 멈춰 사람에게 물을지 정하는 규칙샌드박스와 별개의 두 통제
Auto-review승인 요청을 검토자 에이전트가 판단권한 확장 아님·경계는 그대로
Rules샌드박스 밖 명령 접두사 허용/확인/금지위험 명령 끼워넣기 분해
Permissions접근 범위를 묶은 권한 프로파일(베타)작업별 자율성 등급 선택
보안 운영 모델위 통제들을 결합한 종합 원칙조직 차원 강제 가능
  • Sandbox 모드 3종 구분: read-only / workspace-write(기본) / danger-full-access
  • Approval Policy 3종 구분: untrusted / on-request / never
  • 샌드박스(경계 자체)와 승인정책(경계 넘을 때 멈출지)은 함께 작동하는 별개의 통제라는 점 이해

④ 검증 — 한 일이 진짜 맞는지 확인·되돌리기

개념한 줄 정의핵심 포인트
Hooks동작 특정 시점에 내 스크립트를 끼우는 확장유출 차단·검증 실행·로깅·메모리 요약
Git 체크포인트/Review작업 전후 스냅샷+diff 사람 검토언제든 원상복구 가능
Workflows작게 쪼개 테스트·리뷰로 반복 검증스스로 점검하며 전진
Best Practices시행착오로 정립된 운영 권장 원칙명확한 지시·작은 단위·검증 가능한 정지조건

Hooks 시점 예시

PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, SubagentStart — 도구 사용 전후·턴 종료·세션/서브에이전트 시작 등에 끼워 넣는다.

⑤ 받침 개념 (전 기둥 공통)

개념한 줄 정의핵심 포인트
Config (config.toml)기본 동작값을 저장하는 로컬 설정·우선순위 체계매번 손으로 안 맞춰도 됨
Models작업 난이도·속도에 맞춰 두뇌 성능 등급 선택신입 vs 베테랑 고르기

실제 예시

컨텍스트 — AGENTS.md 한 장으로 규칙 물려주기

<!-- 파일경로: <저장소루트>/AGENTS.md -->
# 이 저장소에서 일하는 법
- 빌드: `npm run build` (반드시 통과 후 커밋)
- 테스트: `npm test` — 실패 시 절대 머지 금지
- 리뷰 기준: 함수당 50줄 이하, 주석은 "왜"만
- 폴더 관례: src/ 비즈니스 로직, scripts/ 일회성 도구
 
<!-- 같은 실수가 반복되면 그 교훈을 여기에 추가해 다음 세션이 물려받게 한다 -->

가드레일 — config.toml로 기본 동작값 고정

# 파일경로: ~/.codex/config.toml
# 샌드박스(경계)와 승인정책(멈춤)은 별개의 두 통제
sandbox_mode   = "workspace-write"   # 작업폴더 내 수정만 허용(기본값)
approval_policy = "on-request"        # 경계를 넘을 때만 사람에게 물음

툴 — Non-interactive 모드로 CI에서 자동 호출

# CI 파이프라인에서 대화창 없이 에이전트 실행, 결과만 표준출력으로 받음
# 기본은 읽기전용 샌드박스 — 자동화엔 "필요한 최소 권한"만 부여한다
codex exec "변경된 파일의 타입 에러를 모두 고쳐라" \
  --sandbox workspace-write

요약 & 셀프체크

3줄 요약

  1. Codex 하네스는 컨텍스트·툴·가드레일·검증의 4기둥으로 짜이며, Config·Models가 이를 받친다.
  2. 가드레일에서 핵심은 “샌드박스(경계)“와 “승인정책(멈춤)“이 별개의 두 통제로 함께 작동한다는 점이다.
  3. 규칙은 AGENTS.md/문서에, 회상은 Memories에 — 역할을 섞지 않는 것이 운영 안정성의 출발점이다.

스스로 답해보기

  • 같은 명령이 누군가에겐 막히고 누군가에겐 통과된다면, 샌드박스와 승인정책 중 무엇을 먼저 점검해야 할까?
  • “반드시 지켜야 할 규칙”을 Memories에 넣으면 안 되는 이유는?
  • Customization 4층(AGENTS.md → Skills/Plugins → MCP → Subagents)을 순서대로 쌓는 이유를 집 짓기에 빗대 설명할 수 있는가?

연결

하네스엔지니어링이란 · 용어집

Codex 원문 교차검증 — 수집범위 / 누락

  • 저장한 원문 파일 수: 25개 (_원문아카이브/codex/ 하위, 모두 공식 .md 원문 엔드포인트에서 수집해 내비게이션 잡음 없이 본문만 확보).
  • 저장 목록: overview, quickstart, best-practices, prompting, customization, agents-md, memories, sandboxing, auto-review, subagents-concept, workflows, agent-approvals-security, permissions, rules, hooks, skills, subagents, mcp, config-basic, config-reference, config-advanced, cli-reference, noninteractive, models, glossary.
  • 의도적으로 제외한 영역(하네스/에이전틱 엔지니어링 핵심에서 벗어나 우선순위가 낮음):
    • 플랫폼·UI 운영 디테일: App/IDE 개별 settings·commands·troubleshooting, Windows/Chrome 확장, In-app browser, Appshots, Computer Use.
    • 도메인 use-cases 다수(Figma→코드, RNA-seq, 단백질 폴딩, 받은편지함 관리 등 약 25+건) — 응용 예시라 개념 도출엔 불필요.
    • 결제·조직 운영: pricing, enterprise(admin-setup/governance/managed-config), auth/access-tokens, CI/CD auth, Amazon Bedrock 배포.
    • 통합·배포 채널: GitHub/Slack/Linear integrations, github-action, sdk, app-server, sites, plugins/build, security 플러그인·threat-model.
    • 기타: changelog, videos, migrate, environment-variables, config-sample(=reference로 대체), feature-maturity, open-source, remote-connections, speed.
  • 비고: config-advanced와 config-reference는 분량이 커서(각 45KB/70KB) 원문은 보관하되, 개념 노트에서는 “Config 계층” 한 항목으로 압축.

출처(공식문서 엔드포인트)

그래프 뷰

백링크