Codex 하네스 엔지니어링 가이드: AGENTS.md, 메모리, 스킬, MCP 설계

여러분, Codex를 잘 쓰려면 좋은 프롬프트만으로는 부족합니다. AI 에이전트가 어떤 순서로 일해야 하는지, 어떤 파일을 참고해야 하는지, 어떤 작업은 반드시 막아야 하는지, 어떤 반복 작업은 스킬로 묶어야 하는지까지 구조화해야 하죠. 이 구조가 바로 하네스입니다.

결론부터 말하면, Codex 하네스 엔지니어링의 핵심은 “AI에게 일을 맡긴다”가 아니라 “AI가 일하는 방식을 설계한다”입니다. AGENTS.md, 메모리, 스킬, MCP, 훅, 서브 에이전트 같은 구성 요소를 잘 조합하면 Codex를 단발성 코딩 보조가 아니라 반복 가능한 작업자로 운영할 수 있습니다. 이 글에서 그 여섯 가지 구성 요소를 하나씩 짚어보겠습니다.

Codex 하네스 핵심 요약

• 하네스는 AI 에이전트가 반복 가능한 방식으로 일하게 만드는 구조입니다.
• AGENTS.md는 전역 또는 프로젝트 단위 규칙을 에이전트에게 주입하는 기본 레이어입니다.
• 메모리는 반복되는 선호, 업무 흐름, 실수, 기술 스택을 다음 세션으로 이어 주는 장치입니다.
• 스킬은 지시, 자료, 스크립트, 템플릿을 묶어 특정 작업을 재사용 가능한 워크플로우로 만듭니다.
• MCP는 외부 도구와 서비스를 모델에 연결하는 표준 프로토콜입니다.
• 훅은 LLM이 “읽고 판단”하는 규칙을 넘어 특정 이벤트에서 명령 실행을 강제합니다.
• 서브 에이전트는 전문 역할과 독립 컨텍스트를 가진 작업자를 만들어 복잡한 작업을 나눕니다.

하네스 엔지니어링이란 무엇인가

프롬프트만으로는 반복성이 부족하다

바이브 코딩은 빠르게 결과물을 만드는 데 강합니다. 그런데 프롬프트만으로 앱을 만들다 보면 매번 결과가 흔들리죠. 어떤 날은 테스트를 잘 작성하고, 어떤 날은 검증을 건너뜁니다. 어떤 세션에서는 보안 규칙을 잘 지키다가, 다른 세션에서는 환경 변수 파일을 건드리려 하기도 합니다.

하네스는 이런 불확실성을 줄이기 위한 구조입니다. 에이전트가 항상 읽어야 하는 규칙, 작업 중 참고할 기억, 반복 실행할 절차, 외부 도구 연결, 강제 실행할 명령을 하나씩 쌓아 올리는 거죠. 그러면 “이번에는 잘하겠지”가 아니라 “이 방식으로 일하게 만든다”에 가까워집니다.

강제와 자율성을 분리한다

좋은 하네스는 모든 걸 막지 않습니다. 에이전트가 자율적으로 판단해도 되는 영역과 반드시 강제해야 하는 영역을 분리하죠. 예를 들어 코드 스타일은 AGENTS.md와 스킬로 안내해도 되지만, 환경 변수 유출 방지나 특정 명령 금지는 훅으로 강제하는 편이 안전합니다.

하네스의 목적은 AI를 답답하게 만드는 것이 아니라, 위험한 영역을 묶어 두고 나머지 영역에서 더 자유롭게 일하게 만드는 것입니다.

AGENTS.md: Codex의 기본 규칙 레이어

전역 규칙과 프로젝트 규칙

Codex는 전역 경로와 프로젝트 경로에서 규칙 파일을 읽습니다. 전역 규칙은 어떤 프로젝트에서든 적용되는 기본 행동 원칙을 담고, 프로젝트 규칙은 특정 저장소의 기술 스택, 명령어, 금지 사항, 협업 방식을 담죠.

저는 AGENTS.md를 팀원과 함께 버전 관리해야 하는 파일이라고 봅니다. 프로젝트의 구조, 테스트 명령, 보안 규칙, 브랜치 전략, 완료 보고 기준처럼 팀 전체가 공유해야 하는 내용을 이 파일에 넣으면, 에이전트가 매번 같은 기준으로 작업하게 됩니다.

중첩 구조로 세밀하게 규칙을 나눈다

AGENTS.md는 루트에 하나만 두는 방식에 그치지 않습니다. 하위 디렉터리마다 다른 규칙이 필요하다면 중첩 구조로 둘 수 있습니다. 예를 들어 프론트엔드 영역, 백엔드 영역, 인프라 영역의 작업 규칙이 다르다면 각 디렉터리에 맞는 규칙을 둘 수 있습니다.

이 구조는 큰 저장소에서 특히 유용합니다. 모든 규칙을 루트에 몰아넣으면 에이전트가 불필요한 맥락까지 읽게 되거든요. 작업 위치에 맞는 규칙만 단계적으로 적용되면 컨텍스트 효율도 좋아집니다.

메모리와 스킬: 반복 작업을 축적하는 방법

메모리는 세션 사이의 맥락을 이어 준다

Codex의 메모리는 기본적으로 항상 켜져 있는 기능은 아니지만, 활성화하면 이전 대화와 작업에서 반복적으로 필요한 맥락을 저장할 수 있습니다. 사용자의 선호, 자주 쓰는 기술 스택, 프로젝트 관리 방식, 반복 실수, 업무 흐름 같은 정보가 다음 세션에서 활용됩니다.

제가 강조하고 싶은 건 메모리가 코드베이스의 현재 상태를 대체하지는 않는다는 점입니다. 메모리는 과거 결정과 선호를 빠르게 떠올리는 데 도움을 주지만, 실제 구현 전에는 현재 파일과 명령 결과를 직접 확인해야 합니다. 오래된 기억은 언제든 드리프트될 수 있으니까요.

스킬은 전문 작업을 패키징한다

스킬은 반복되는 절차를 재사용 가능한 워크플로우로 묶는 기능입니다. 단순 프롬프트 템플릿과 달리, 지시문뿐 아니라 참고 자료, 스크립트, 템플릿까지 포함할 수 있습니다. 예를 들어 블로그 글 동기화, PR 생성, 코드 리뷰, 배포 문서 작성 같은 작업을 스킬로 만들면 매번 절차를 다시 설명하지 않아도 됩니다.

스킬의 장점은 점진적 공개입니다. 처음부터 모든 자료를 컨텍스트에 넣지 않고, 필요한 순간에 필요한 파일만 읽게 만들 수 있죠. 장기 작업에서 컨텍스트를 아끼면서도 전문성을 유지하는 방식이라고 봅니다.

MCP와 플러그인: 외부 도구를 연결하는 레이어

MCP는 모델과 도구 사이의 표준 연결이다

MCP(Model Context Protocol)는 LLM이 외부 도구를 사용할 수 있게 해 주는 표준 프로토콜입니다. 파일 시스템, 브라우저, GitHub, Slack, Notion, Vercel 같은 도구를 에이전트 작업 흐름 안으로 가져올 수 있습니다. Codex에서도 MCP를 통해 다양한 도구를 연결할 수 있습니다.

제가 보는 MCP의 가치는 단순히 “도구를 쓸 수 있다”가 아닙니다. 에이전트가 현재 작업 맥락에 맞는 외부 상태를 확인하고, 필요한 조치까지 수행한다는 데 있죠. 배포 상태 확인, PR 조회, 브라우저 검증, 문서 검색 같은 작업을 전부 대화 흐름 안에서 처리할 수 있습니다.

플러그인은 MCP와 스킬을 설치하기 쉽게 만든다

플러그인은 “MCP에 스킬을 더한” 묶음이라고 보면 쉽습니다. 예를 들어 Vercel 플러그인을 깔면 서비스 연동을 훨씬 간단하게 쓸 수 있죠. 플러그인은 MCP 서버만 제공할 수도 있고, 스킬이나 추가 지침을 함께 묶어 제공할 수도 있습니다. GitHub, Slack, Chrome, Notion, Gmail 같은 도구를 Codex 안에서 연결하는 방식입니다.

플러그인을 활용하면 에이전트가 배포 방법을 물어보고, 저장소와 Vercel 프로젝트를 연결하고, 배포 상태를 확인하는 식의 작업까지 이어서 해줍니다. 다만 외부 시스템을 조작하는 만큼 권한과 승인 범위는 명확히 해둬야 합니다.

훅과 서브 에이전트: 강제와 분업

훅은 LLM 판단을 넘어서는 강제 장치다

규칙 파일은 에이전트가 읽고 따르는 지침입니다. 그런데 LLM이 이걸 항상 100% 지킨다고 보장하긴 어렵죠. 그래서 특정 이벤트에서 반드시 실행돼야 하는 동작은 훅으로 처리하는 편이 안전합니다. 예를 들어 파일 작성 후 포매터를 실행하거나, 특정 민감 파일 접근을 막거나, 작업 완료 시 알림을 보내는 식이죠.

훅은 하네스에서 강제 레이어를 담당합니다. AI가 판단해서 지키면 되는 규칙은 문서로 두고, 반드시 보장해야 하는 규칙은 프로그램 로직으로 강제하는 거죠. 이 구분이 중요합니다.

서브 에이전트는 독립 컨텍스트를 가진 전문가다

서브 에이전트는 특정 역할에 특화된 별도 에이전트입니다. 메인 에이전트와 다른 컨텍스트를 사용하고, 사용할 수 있는 도구도 제한할 수 있습니다. 예를 들어 테스트 시나리오 분석가, Playwright 테스트 작성자, 디자인 시스템 검토자, 보안 리뷰어 같은 식으로 역할을 나눌 수 있습니다.

복잡한 작업에서는 하나의 에이전트가 모든 걸 처리하는 것보다 역할을 나누는 편이 낫습니다. 각 서브 에이전트는 필요한 맥락만 가지고 움직이니까 컨텍스트 효율이 좋아지고, 병렬 처리도 가능해지죠.

실제 서비스 빌드 흐름에서 배운 것

인터뷰와 계획을 먼저 세운다

저는 Codex 앱으로 GitHub 데이터 기반 카드와 AI 해설을 제공하는 서비스를 직접 만들어봤습니다. 여기서 제가 강조하고 싶은 건, 바로 구현에 들어가지 않는다는 겁니다. AI에게 먼저 역인터뷰를 시켜 요구사항을 구체화하는 단계를 거치죠.

에이전트가 사용자에게 질문하고, 사용자는 그 질문에 답하면서 프롬프트를 더 명확하게 만듭니다. 사실 내가 뭘 원하는지 나도 모르는 경우가 많거든요. 그래서 역으로 AI가 질문하게 하는 거죠. 이후 Plan 모드로 계획을 세우고, 그 계획을 바탕으로 구현합니다. 이 흐름이 장기 실행 에이전트 작업에서 품질을 크게 좌우합니다.

배포와 환경 변수는 별도 안전 장치가 필요하다

이 서비스는 Vercel 배포와 OpenAI API 키 설정까지 이어집니다. 이때 환경 변수는 민감 정보이니, 에이전트가 함부로 접근하지 못하게 막는 게 중요하죠. 저도 실제 업무에서는 훅으로 환경 변수 파일 접근을 아예 막아둡니다. 환경 변수가 유출되면 정말 큰일 나니까요.

그리고 AI 기능이 붙는 서비스는 요청마다 API 비용이 발생합니다. 그러니 단순히 “동작한다”에서 끝내지 말고, 비용이 과도하게 새어 나가지 않도록 제한 장치와 운영 기준을 함께 설계해야 합니다.

하네스 설계 체크리스트

구성 요소	역할	실무 질문
AGENTS.md	기본 규칙	에이전트가 항상 따라야 할 프로젝트 규칙은 무엇인가
메모리	세션 간 맥락	반복되는 선호와 업무 흐름은 무엇인가
스킬	반복 절차	매번 설명하는 작업을 패키징할 수 있는가
MCP	외부 도구	어떤 도구를 에이전트가 안전하게 사용할 수 있는가
훅	강제 실행	반드시 보장해야 하는 명령이나 금지 규칙은 무엇인가
서브 에이전트	역할 분리	전문가 역할로 나누면 품질이 올라가는 작업은 무엇인가
플랜	실행 전 설계	구현 전에 질문과 계획이 충분히 정리되었는가

마무리

정리하면, Codex 하네스 엔지니어링은 새로운 도구 목록을 외우는 일이 아닙니다. AI 에이전트가 안전하고 반복 가능하게 일하도록 작업 환경을 설계하는 일이죠. 프롬프트, 규칙 파일, 메모리, 스킬, MCP, 훅, 서브 에이전트가 각각 다른 레이어에서 맞물려 돌아가야 합니다. 그리고 이걸 처음부터 완벽하게 짜려고 하면 정말 힘듭니다. 하나씩 필요한 것부터 붙여 나가는 게 좋다고 봅니다.

제가 가장 중요하게 보는 원칙은 자율성과 강제를 구분하는 겁니다. 에이전트가 잘 판단하는 영역은 자율적으로 맡기고, 보안이나 비용, 배포, 삭제처럼 실수 비용이 큰 영역은 하네스로 묶는 거죠. 그렇게 해야 Codex를 단순 코딩 보조가 아니라 장기 실행 작업자로 쓸 수 있다고 봅니다.