Codex를 활용한 하네스 엔지니어링의 전체 과정을 마스터하세요. Agent.md, 스킬, MCP, 훅, 서브 에이전트 등 6가지 핵심 요소와 실전 프로젝트 구축 방법을 배웁니다.
Codex 하네스 엔지니어링 완벽 가이드: AI 에이전트 설계부터 서비스 배포까지
핵심 요약
- 하네스 엔지니어링의 정의: AI 에이전트가 원하는 방식대로 동작하도록 구조를 만드는 기술로, 반복성 확보, 강제와 자율성 분리, 팀 단위 축적을 가능하게 함
- Codex의 6가지 하네스 구성 요소: Agent.md(규칙 파일), 메모리, 스킬, MCP(모델 컨텍스트 프로토콜), 훅, 서브 에이전트로 체계적인 AI 에이전트 관리 가능
- 효과적인 개발 워크플로우: 인터뷰 → 플랜 수립 → 프로젝트 구조 설계 → 개발 → AI 기능 추가 → 배포로 진행하며 각 단계마다 AI의 도움을 받음
- 실전 예제: GitHub 데이터 기반의 RPG 캐릭터 카드 생성 서비스(Commit Hero)를 Next.js, Vercel, OpenAI API를 활용해 구축
- 코드 리뷰 자동화: Codex를 GitHub에 연동하면 풀 리퀘스트 단계에서 자동으로 코드 리뷰를 받을 수 있어 배포 전 안정성 확보 가능
하네스 엔지니어링이란 무엇인가
하네스 엔지니어링은 AI 에이전트가 우리가 원하는 방식대로 일관되게 작동하도록 만드는 구조 설계 기술입니다. 프롬프트만으로는 AI가 불안정하게 동작할 수 있지만, 하네스를 통해 이를 체계화합니다. 반복 가능한 프로세스를 만들고, 강제 사항과 자율 영역을 명확히 분리하며, 팀 전체가 축적된 노하우를 공유할 수 있게 됩니다.
현재(2026년) AI 에이전트 기술이 급속도로 발전하면서 하네스 엔지니어링은 프롬프트 엔지니어링만큼 중요한 영역이 되었습니다. 단순히 "이것을 만들어줘"라는 식의 요청이 아니라, AI가 따라야 할 명확한 규칙과 절차를 정의하고, 그 규칙 내에서 창의성을 발휘하도록 유도하는 것이 더 효과적입니다.
Codex 하네스의 6가지 핵심 구성 요소
1. Agent.md: AI의 행동 규칙을 정의하는 마스터 가이드
Agent.md는 Codex의 가장 기본적인 규칙 파일입니다. AI 에이전트가 모든 상황에서 참고해야 할 지침을 담고 있습니다. 홈 경로의 .codex/Agent.md에 전역 규칙을, 프로젝트별 Agent.md에 프로젝트 특화 규칙을 작성할 수 있습니다.
이 파일의 장점은 중첩 구조 지원 입니다. 최상위 루트에 Agent.md를 두면 모든 상황에서 적용되고, 각 폴더별로도 Agent.md를 두면 해당 폴더에서만 작동합니다. 이렇게 하면 컨텍스트 윈도우를 효율적으로 사용할 수 있습니다.
예를 들어, 특정 도메인에서만 필요한 규칙을 해당 폴더의 Agent.md에 작성하면, 그 폴더 밖에서는 그 규칙이 자동으로 로드되지 않아 컨텍스트 낭비를 줄일 수 있습니다.
Agent.md 작성의 핵심:
- 명확한 역할 정의 (예: "당신은 Next.js 전문 개발자입니다")
- 작업 원칙 설명 (예: "항상 TypeScript를 사용하세요")
- 금지 사항 명시 (예: "환경 변수 파일은 절대 수정하지 마세요")
- 버전 관리 포함 (Git에 커밋하여 팀과 공유)
마스터 프롬프트 템플릿을 활용하면 Agent.md를 더 효과적으로 구성할 수 있습니다. Codex 커뮤니티에서 공유되는 템플릿을 참고하거나, 자신의 프로젝트에 맞게 커스터마이징할 수 있습니다.
2. 메모리: 이전 대화에서 배운 내용을 자동으로 활용
메모리 기능은 기본적으로 비활성화되어 있습니다. 활성화하면 Codex가 이전 대화와 작업에서 유용한 패턴을 자동으로 저장했다가, 새로운 세션에서 필요할 때 불러옵니다.
메모리 파일에는 선호 사항, ** 반복되는 업무 흐름**, ** 기술 스택 정보**, ** 프로젝트 관리 방식**, ** 자주 발생하는 실수** 등이 기록됩니다. 예를 들어, 특정 개발 방식이나 코딩 컨벤션을 반복 사용하면 Codex가 이를 학습해서 다음 세션에서 자동으로 적용합니다.
메모리를 활성화하려면 Codex 설정에서 '개인 맞춤 설정' 항목을 찾아 활성화하면 됩니다. 활성화 후 ~/.codex/config.yaml 파일에서 메모리 관련 설정을 확인할 수 있습니다.
메모리 사용 시 장점:
- 장기 프로젝트에서 일관성 유지
- 팀의 작업 방식이 자동으로 학습됨
- 반복되는 설정을 매번 새로 설명할 필요 없음
- 이전 세션에서의 의사결정 내역 자동 참조
3. 스킬: 반복 업무를 패키징하는 전문화된 템플릿
스킬은 반복되는 절차를 완성도 높은 패키지 로 만든 것입니다. 단순 프롬프트 템플릿이 아니라, 지시사항, 참조 자료, 스크립트, 템플릿 등을 모두 포함합니다.
스킬의 구조는 다음과 같습니다:
skills/
└─ deep-interview/
├─ skill.md (프론트매터 포함)
├─ reference/
│ └─ interview-questions.md
├─ templates/
│ └─ output-template.md
└─ scripts/
└─ process.js
skill.md 파일의 프론트매터 부분만 초기에 로드되므로 컨텍스트를 적게 사용합니다. 필요할 때만 스킬의 전체 내용을 읽어오는 점진적 공개 방식 입니다.
예를 들어, "딥 인터뷰" 스킬을 사용하면 Codex가 사용자에게 필요한 질문을 자동으로 던져서 요구사항을 구체화합니다. 이렇게 하면 처음부터 명확한 계획을 세우기 어려운 개발 초기 단계에 매우 유용합니다.
효과적인 스킬 설계:
- 특정 워크플로우를 명확하게 정의
- 각 단계별 체크리스트 포함
- 실패 사례와 해결 방안 문서화
- 재사용 가능한 템플릿 준비
4. MCP: 외부 시스템을 연결하는 표준 프로토콜
MCP(모델 컨텍스트 프로토콜)는 Anthropic이 제안한 표준으로, Codex에도 구현되어 있습니다. 이를 통해 LLM이 직접 처리할 수 없는 외부 도구나 서비스를 연결할 수 있습니다.
MCP로 연결 가능한 서비스:
- Slack: 메시지 읽기, 분석, 자동 응답
- Gmail: 이메일 읽기, 분석, 답장 작성
- GitHub: 저장소 관리, 이슈 추적
- Notion: 데이터베이스 조회, 문서 작성
- Vercel: 배포 자동화
예를 들어, Slack MCP를 연동하면 Codex 에이전트가 채널 메시지를 읽어 자동으로 분류하거나 요약할 수 있습니다. GitHub MCP를 연동하면 풀 리퀘스트를 자동으로 생성하고 관리할 수 있습니다.
5. 훅: 런타임에 명령을 강제 주입하는 가드레일
훅은 다른 하네스 요소와 달리 프로그래밍 로직 기반 의 강제 장치입니다. 프롬프트로 "이렇게 해줘"라고 지시해도 AI가 따르지 않을 수 있지만, 훅은 무조건 실행됩니다.
훅이 작동하는 이벤트:
- 세션 시작 시
- 프롬프트 제출 전
- 도구 사용 전
- 턴(turn) 완료 후
- 파일 접근 시도 시
예를 들어, 환경 변수가 포함된 .env 파일을 절대 수정하지 못하도록 훅을 설정할 수 있습니다. 또는 특정 디렉토리에만 파일을 생성하도록 강제할 수 있습니다. 이렇게 하면 보안 취약점을 미리 방지할 수 있습니다.
hooks:
- name: protect-env-files
event: file-write
condition: "target matches '*.env*'"
action: deny
message: "환경 파일은 수정할 수 없습니다"
6. 서브 에이전트: 병렬 작업을 위한 독립적 컨텍스트
서브 에이전트는 메인 세션과 완전히 독립적인 컨텍스트를 가진 별도 에이전트입니다. 메인 에이전트가 필요에 따라 여러 개의 서브 에이전트를 생성해서 병렬로 작업을 요청할 수 있습니다.
서브 에이전트의 용도:
- 코드 리뷰 (개발과 독립적으로 검토)
- 병렬 기능 개발 (여러 기능을 동시에 구현)
- 검증 작업 (다른 관점에서 검증)
- 문서 작성 (개발과 동시 진행)
서브 에이전트를 사용하는 가장 큰 장점은 메인 에이전트의 컨텍스트 오염을 방지 한다는 것입니다. 코드 리뷰를 위해 메인 세션에 리뷰 결과를 계속 쌓으면 컨텍스트가 빠르게 가득 찹니다. 하지만 서브 에이전트로 리뷰를 하면 리뷰 결과만 가져올 수 있고, 메인 에이전트는 계속해서 개발에 집중할 수 있습니다.
효과적인 하네스 엔지니어링 구축 순서
하네스를 처음부터 완벽하게 설계하려고 하면 실패하기 쉽습니다. 대신 필요한 것부터 단계적으로 추가 하는 방식을 권장합니다.
추천 구축 순서:
Agent.md 작성: 먼저 AI가 따라야 할 기본 규칙을 정의합니다. 이것이 가장 중요한 기초입니다.
스킬 추가: 반복되는 워크플로우를 발견하면 스킬로 만듭니다. 예를 들어, "요구사항 정의 면접" 스킬을 만들어 인터뷰 단계를 자동화합니다.
MCP 연동: 외부 서비스(GitHub, Slack, Notion 등)와 연결해야 하면 MCP를 설정합니다.
훅 설정: 보안상 중요한 부분이나 반드시 지켜야 할 규칙은 훅으로 강제합니다.
메모리 활성화: 프로젝트가 진행되면서 반복되는 패턴이 생기면 메모리를 활성화해 자동 학습을 활용합니다.
서브 에이전트 활용: 병렬 작업이 필요하거나 컨텍스트 분리가 필요하면 서브 에이전트를 구성합니다.
실전 프로젝트: Commit Hero 서비스 구축
프로젝트 개요
Commit Hero 는 GitHub 사용자 이름을 입력받아 해당 개발자의 커밋 활동을 분석하고, RPG 캐릭터 카드 형식으로 시각화하는 웹 서비스입니다. 개발자의 기술 스택, 활동 패턴, 코딩 스타일을 분석해 재미있는 캐릭터 정보로 제시합니다.
개발 단계별 하네스 엔지니어링 적용
1단계: 인터뷰를 통한 요구사항 구체화
단순히 "GitHub 데이터 기반 카드 생성 서비스를 만들어줘"라는 요청으로는 불충분합니다. 대신 Codex의 딥 인터뷰 스킬 을 사용해 양방향 대화를 통해 요구사항을 구체화합니다.
프롬프트: "Commit Hero 웹 서비스를 만들고 싶어.
먼저 인터뷰 진행해 보자."
Codex가 자동으로 다음과 같은 질문을 던집니다:
- "1차 목표는 재미있는 카드 생성? 정확한 분석? 바이럴 가능성?"
- "MVP에서 데이터 입력 방식은? 유저네임만? OAuth 로그인?"
- "카드에 들어갈 요소는? 클래스, 레벨, 스탯, 스킬, 약점?"
- "카드 생성 방식은? 규칙 기반? AI 기반?"
각 질문에 답하면서 자동으로 프롬프트가 구체화 됩니다.
2단계: 플랜 문서 수립
인터뷰가 끝나면 Codex에게 플랜 문서를 작성하도록 요청합니다:
프롬프트: "지금까지의 인터뷰 내용을 기반으로
개발 계획 문서를 마크다운으로 작성해줘."
생성된 플랜에는 다음이 포함됩니다:
- 프로젝트 목표 및 성공 기준
- 기술 스택 (Next.js, Bun, Vercel)
- 데이터 흐름도
- API 설계 명세
- UI/UX 레이아웃
- 개발 일정
만약 플랜이 복잡하다면, HTML로 변환해 시각화하면 더 이해하기 쉽습니다:
프롬프트: "지금 작성한 플랜 문서를
사람이 5분 안에 검토할 수 있는
단일 HTML 파일로 만들어줘."
3단계: Agent.md 작성 및 프로젝트 구조 설정
플랜이 확정되면 이 프로젝트만의 규칙을 Agent.md에 정의합니다:
# Commit Hero 프로젝트 규칙
## 기술 스택
- 프론트엔드: Next.js 15 (App Router)
- 패키지 관리자: Bun
- 배포: Vercel
- 데이터 소스: GitHub Public API
- AI 모델: OpenAI GPT-5.5 (구조화된 출력)
## 코드 스타일
- TypeScript strict 모드 필수
- 모든 컴포넌트는 함수형 컴포넌트
- 상태 관리는 React Context API 사용
- API 라우트에서 예외 처리 필수
## 금지 사항
- .env 파일 수정 금지
- API 키를 코드에 하드코딩 금지
- 외부 UI 라이브러리는 사전 협의 필수
이렇게 하면 이후 모든 개발이 이 규칙을 따르게 됩니다.
4단계: 프로젝트 초기화 및 목업 UI 구현
먼저 백엔드 없이 프론트엔드 목업부터 구현합니다:
프롬프트: "Next.js 프로젝트를 세팅해줘.
Bun을 사용하고 App Router 구조로.
GitHub 유저네임 입력하는 메인 페이지와
카드를 보여주는 결과 페이지를 만들어줘.
백엔드는 아직 연동하지 말고 목업 데이터 사용."
Codex가 자동으로:
- Next.js 프로젝트 생성
- 필요한 디렉토리 구조 생성
- 메인 페이지 컴포넌트 작성
- 카드 컴포넌트 작성
- 스타일링 적용
- 로컬 호스트에서 개발 서버 실행
5단계: GitHub API 연동 (백엔드)
프론트엔드 목업이 완성되면 실제 GitHub 데이터를 가져오는 API 연동을 합니다. 이때 새로운 워크트리를 생성 하는 것이 좋습니다.
프롬프트: "새 워크트리를 생성해줘.
API 이름은 'add-github-integration'으로."
워크트리에서 병렬로 작업하면 메인 브랜치가 손상되지 않습니다:
프롬프트: "GitHub 공개 API를 사용해서
사용자 정보, 저장소 정보, 커밋 통계를 가져와줘.
데이터 분석 규칙은 단순 점수화 방식으로."
API 연동 완료 후:
프롬프트: "작업이 다 됐으니 메인 브랜치로 머지해줘."
6단계: AI 기능 추가 (OpenAI 연동)
마지막으로 AI를 활용한 창의적인 카드 설명을 추가합니다:
프롬프트: "OpenAI GPT-5.5를 사용해서
개발자의 커밋 데이터를 기반으로
재미있고 창의적인 캐릭터 설명과 스토리를 생성해줘.
구조화된 출력을 사용해서 일관된 형식 유지."
7단계: 코드 리뷰 및 배포
로컬에서 코드 리뷰를 한 후 GitHub에 푸시합니다:
프롬프트: "현재 변경 사항을 코드 리뷰해줘.
보안 문제, 성능 문제, 코드 퀄리티 모두 확인해줘."
리뷰 결과를 바탕으로 수정하고 GitHub에 푸시:
프롬프트: "현재 변경 사항을 GitHub에 푸시해줘.
풀 리퀘스트를 생성하고 issue도 자동으로 만들어줘."
Codex가 자동으로:
- 이슈 생성
- 브랜치 생성
- 변경사항 커밋
- 풀 리퀘스트 작성
GitHub에 연동된 Codex 코드 리뷰 봇이 자동으로 검토합니다. 리뷰 통과 후 메인 브랜치로 머지:
프롬프트: "코드 리뷰 완료되면 메인 브랜치로 머지해줘."
8단계: Vercel 자동 배포
메인 브랜치에 푸시되면 Vercel이 자동으로 배포합니다. 필요시 Codex Vercel 플러그인으로 수동 배포도 가능합니다:
프롬프트: "@Vercel 현재 코드를 Vercel에 배포해줘."
Codex의 Vercel 플러그인이 MCP를 통해 자동으로:
- 새 프로젝트 생성
- GitHub 저장소 연결
- 환경 변수 설정
- 배포 실행
Codex의 워크트리: 병렬 개발의 핵심
Codex의 워크트리 기능은 Git의 worktree 개념을 Codex 에이전트 관점에서 구현 한 것입니다.
워크트리 사용 흐름
- 메인 세션: GitHub API 연동 작업 (API 완성 후 메인 브랜치로 머지)
- 워크트리 세션: AI 기능 추가 작업 (독립적인 컨텍스트에서 병렬 진행)
두 세션이 동시에 실행되어도 파일 충돌이 없습니다. 작업 완료 후 머지할 때:
프롬프트: "이 워크트리에서의 작업을 메인 브랜치로 머지해줘.
conflict가 있으면 자동으로 해결해줘."
워크트리의 장점
- 병렬 개발: 여러 기능을 동시에 개발 가능
- 컨텍스트 분리: 각 세션이 독립적인 컨텍스트를 가짐
- 병합 관리: Codex가 자동으로 충돌 해결
GitHub와 Codex 연동: 자동화된 코드 리뷰
설정 방법
- Codex Cloud에 접속: codex.ai/cloud
- 커넥터 설정: GitHub 계정 연동
- 코드 검토 활성화: 리뷰 대상 저장소 선택
자동 코드 리뷰의 흐름
- 로컬에서 개발 완료
- Codex에게 코드 리뷰 요청 (새 세션)
- 리뷰 결과 반영해서 수정
- GitHub에 푸시 (풀 리퀘스트 생성)
- Codex 코드 리뷰 봇이 자동으로 PR 검토
- 리뷰 통과 후 머지
다중 에이전트 리뷰
더 견고한 리뷰를 위해 여러 리뷰 에이전트를 함께 사용할 수 있습니다:
- Codex (자동 생성된 코드 검토)
- Code Rabbit (보안 관점 리뷰)
- 팀 리드 (최종 아키텍처 검토)
각 에이전트가 다른 관점에서 리뷰하므로 더 견고한 코드 품질을 보장합니다.
컨텍스트 윈도우 최적화 전략
Codex 에이전트가 작업하면서 컨텍스트(토큰)가 점점 가득 찹니다. 컨텍스트가 100%에 가까워지면 성능이 급격히 저하됩니다.
컨텍스트 절약 기법
플랜 문서 활용: 장기 프로젝트에서 플랜을 별도 파일로 관리하면, 컨텍스트와 무관하게 에이전트가 방향을 잃지 않습니다.
계층적 Agent.md: 전역 Agent.md와 폴더별 Agent.md를 분리하면, 필요한 규칙만 로드됩니다.
스킬의 프론트매터: 스킬은 프론트매터 부분만 초기에 로드하므로, 전체 내용을 담지 않아도 됩니다.
새 세션 활용: 컨텍스트가 70% 이상 찼으면 새 세션을 시작하는 것이 효율적입니다.
서브 에이전트: 코드 리뷰나 문서 작성처럼 별도 작업이 필요하면 서브 에이전트로 분리합니다.
보안 고려사항
Codex로 작성된 코드의 보안성
오해: "AI가 만든 코드는 해킹에 취약하다"
사실: 요구사항을 명확히 정의하고 하네스를 잘 설계하면 AI가 사람보다 더 안전한 코드를 생성합니다.
보안 하네스 설계
훅으로 민감 정보 보호:
hooks: - name: prevent-env-exposure event: file-read condition: "file matches '*.env*' AND context != 'deployment'" action: denyCodex Security 플러그인: 알려진 취약점 자동 감지
다중 단계 리뷰: 로컬 → PR → 배포 전 여러 단계에서 검증
모드 선택:
- 기본 모드: 매 동작마다 승인 필요 (느리지만 안전)
- 자동 리뷰 모드: AI가 위험 판단 후 승인 요청 (효율적)
- 전체 권한 모드: 완전 자동 (빠르지만 샌드박스 필수)
실무 팁 및 모범 사례
1. 초기 설계에 시간 투자
복잡한 기능의 경우:
- 인터뷰: 10-20분
- 플랜 수립: 30분 이상
- 구현: 1-2시간
초기 설계가 명확하면 구현 시간이 절반으로 줄어듭니다.
2. 플랜 변경은 최소화
중간에 방향을 자주 바꾸면:
- 컨텍스트 오염
- 코드 일관성 저하
- 구현 시간 증가
해결책: 초기 플랜을 충분히 검토 후 변경하지 말 것.
3. 세션 분리는 필수
장시간 작업 시:
- 로컬 개발 세션
- 코드 리뷰 세션 (새로 생성)
- 배포 세션 (필요시)
각 세션이 독립적으로 최선의 결과를 냅니다.
4. 문서화 자동화
Codex가 코드를 작성하므로 문서화도 요청하세요:
프롬프트: "지금까지 개발한 모든 API 엔드포인트의
문서를 Markdown 형식으로 작성해줘.
예제 요청/응답도 포함해줘."
5. 점진적 기능 추가
1단계: 핵심 기능 (MVP)
2단계: 데이터 연동
3단계: AI 기능
4단계: 부가 기능 (공유, 다운로드 등)
각 단계마다 배포 가능한 상태를 유지합니다.
실무에서 흔한 문제와 해결책
문제 1: 설계 중간에 변경 요청 빈번
해결책: 플랜을 HTML로 변환해 이해관계자와 공유. 변경 필요시 플랜 문서부터 수정.
문제 2: 컨텍스트 부족으로 작업 못 함
해결책: 새 세션 시작, 플랜 파일 참조, 스킬 활용
문제 3: AI 생성 코드 퀄리티 편차
해결책: Agent.md에서 코드 스타일 명확히 정의, 다중 코드 리뷰 활용
문제 4: 보안 문제 발견
해결책: 훅으로 사전 차단, Codex Security 플러그인 활용, 로컬 리뷰 강화
결론: 하네스 엔지니어링의 미래
하네스 엔지니어링은 단순한 프롬프트 엔지니어링을 넘어 체계적인 AI 에이전트 관리 기법 입니다. 2026년 현재 AI 모델의 성능이 충분히 높아졌으므로, 이제는 "얼마나 좋은 코드를 생성하느냐"보다 "얼마나 안정적으로 관리하느냐"가 중요합니다.
Codex의 6가지 하네스 요소(Agent.md, 메모리, 스킬, MCP, 훅, 서브 에이전트)를 적절히 조합하면:
- ✅ 반복 가능한 개발 프로세스 구축
- ✅ 팀 전체가 동일한 기준 유지
- ✅ 보안 위험 사전 차단
- ✅ 개발 속도 비약적 증가
- ✅ 코드 퀄리티 일관성 확보
앞으로 AI 기반 개발이 더욱 보편화될수록, 체계적인 하네스 설계 능력이 개발자의 필수 역량이 될 것입니다.
원문출처: Codex 마스터 클래스 라이브 | 하네스 설계부터 서비스 배포까지 (라이브 마지막에는 작은 이벤트도 준비했습니다)
powered by osmu.app