지식위키

Codex 공식문서 — 핵심 개념

Codex 공식문서 — 핵심 개념

한 줄 요약

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

[!info] 하네스란? “하네스(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

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

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

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

[!note] 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시행착오로 정립된 운영 권장 원칙명확한 지시·작은 단위·검증 가능한 정지조건

[!note] 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)을 순서대로 쌓는 이유를 집 짓기에 빗대 설명할 수 있는가?

연결

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

[!tip] 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 계층” 한 항목으로 압축.

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