2026년에는 **에이전틱 코딩 (Agentic Coding)**에 대한 많은 논의가 이루어지고 있습니다.

매주 새로운 프레임워크, 오케스트레이터 (orchestrator), 또는 멀티 에이전트 시스템 (multi-agent system)이 등장합니다. 이러한 개념에 익숙하지 않은 사람들에게는 AI를 활용한 개발이 애플리케이션 자체보다 훨씬 더 복잡한 인프라를 요구하는 것처럼 보일 수 있습니다.

이러한 관점은 초보자뿐만 아니라 AI 사용을 여전히 망설이는 숙련된 개발자들에게도 의욕을 꺾을 수 있습니다.

며칠 전, 저는 Cole Medin의 영상인

영상을 보면서 저는 그 영상의 진정한 가치가 Claude가 아니라 그 '방법론'에 있다는 것을 깨달았습니다. 그래서 저는 실험을 해보기로 했습니다. 동일한 원칙을 Codex에 적용하되, 그 구조를 Codex의 관례에 맞게 조정하는 것입니다.

이 글은 그 이식(port) 과정과 그 과정에서 제가 배운 점들을 설명합니다.

기존 워크플로우에서의 AI 레이어 (AI Layer)

기존 워크플로우에서 Cole은 **AI 레이어 (AI Layer)**를 코딩 에이전트가 다음 사항들을 이해하도록 돕기 위해 리포지토리(repository)에 저장된 리소스 세트로 정의합니다:

• 무엇을 구축해야 하는지;
• 어떻게 구축해야 하는지;
• 어떤 워크플로우 (workflows)를 따라야 하는지;
• 작업에 따라 어떤 정보를 참조해야 하는지.

이 레이어에는 PRD (제품 요구 사항 문서), 글로벌 규칙 (global rules), 참조 문서 (reference documentation), 명령 (commands), 그리고 모든 관련 기술 (Skills)이 포함됩니다.

특히 중요한 세부 사항은 **명령 (commands)**과 기술 (Skills) 사이의 구분입니다.

Cole의 프로젝트에서 주요 워크플로우는 .claude/commands/ 디렉토리에 저장된 Markdown 파일입니다:

.claude/
└── commands/
    ├── commit.md
...

Cole은 Claude Code에서 명령과 기술이 기술적으로 매우 유사한 개념이 되었다고 설명합니다. 하지만 그는 운영적인 관점에서 이 둘을 계속해서 구분합니다.

명령 (command)은 사용자가 명시적으로 시작하기로 선택한 워크플로우입니다:

/prime
/create-prd
/plan-feature
...

반면, 스킬 (Skill)은 컨텍스트가 요구될 때 에이전트가 사용할 수 있는 기능 또는 일련의 지침 세트를 나타냅니다.

Codex에서의 명령 (Commands)과 스킬 (Skills)

Cole의 구분은 포팅 (porting) 작업에 특히 유용합니다. Codex에서도 슬래시 명령 (slash commands)과 스킬 (Skills)은 서로 다른 개념이기 때문입니다.

**슬래시 명령 (Slash commands)**은 /를 사용하여 인터페이스에서 호출할 수 있는 동작입니다. 이 중 다수는 세션의 모드나 상태를 변경하는 내장 명령이지만, 활성화된 스킬 (Skills)이나 커스텀 프롬프트 (custom prompts)가 포함될 수도 있습니다.

**스킬 (Skills)**은 이와 대조적으로, SKILL.md 파일을 포함하는 디렉토리로 구성된 재사용 가능한 워크플로우 (workflows)입니다. 최소한 이 파일에는 스킬의 이름, 설명, 그리고 작동 지침이 명시되어야 합니다.

Codex는 처음에 스킬의 메타데이터 (metadata)만 로드하며, 해당 스킬을 사용하기로 결정했을 때 전체 지침을 읽습니다. 이 메커니즘은 컨텍스트 윈도우 (context window)의 불필요한 사용을 방지합니다.

워크플로우를 Codex로 포팅하기

이 방법론을 Codex로 가져오기 위해, 저는 Claude Code의 마크다운 (Markdown) 명령들을 **사용자에 의해 명시적으로 시작되는 워크플로우 (workflows)**라는 의미를 유지하면서 Codex 스킬 (Skills)로 변환했습니다.

결과적인 구조는 다음과 같습니다:

.agents/
└── skills/
    ├── agent-browser/
...

사용자가 시작하는 워크플로우의 의미를 보존하기 위해, Codex가 자율적으로 선택하기를 원하지 않는 스킬 (Skills)에 대해서는 암시적 호출 (implicit invocation)을 비활성화할 수 있습니다.

예를 들어:

prime/
├── SKILL.md
└── agents/
...

openai.yaml 내부:

policy:
  allow_implicit_invocation: false

이렇게 하면 Codex가 프롬프트 (prompt)를 기반으로 prime, execute, 또는 commit을 암시적으로 활성화하는 것을 방지할 수 있습니다. 스킬 (Skills)은 반드시 다음과 같이 명시적으로 호출되어야 합니다:

$create-prd
$create-rules
$prime

이 시점 이후로, 제가 $create-prd, $create-rules, $prime, $plan-feature, $execute, 그리고 $commit을 언급할 때마다, 이는 Codex에 사전 설치된 기능이 아니라 제 포팅을 위해 생성된 커스텀 스킬 (custom Skills)을 의미합니다.

CLAUDE-template.md에서 AGENTS.md로

명령어(commands)를 변환하는 것만이 유일하게 필요한 변경 사항은 아니었습니다.

원본 리포지토리(repository)에는 Claude에게 제공되는 전역 지침(global instructions)의 기반 역할을 하는 CLAUDE-template.md 파일이 포함되어 있었습니다. 포팅 과정에서 저는 이를 프로젝트 루트(root)에 있는 AGENTS.md 파일로 변환했습니다.

AGENTS.md는 Codex가 지속적인 지침(persistent instructions)과 컨텍스트(context)를 전달받는 네이티브 메커니즘입니다. 세션이 시작될 때, Codex는 지침 체인(instruction chain)을 구축합니다. 리포지토리 루트에서 시작하여 현재 작업 디렉토리(working directory)로 내려가며, 그 과정에서 마주치는 모든 AGENTS.md 또는 AGENTS.override.md 파일을 로드합니다. 디렉토리 트리(directory tree)의 더 깊은 곳에서 정의된 지침은 더 일반적인 지침을 보완하거나 대체할 수 있습니다.

따라서 지속적인 지침(Persistent instructions)과 스킬(Skills)은 서로 다른 책임을 가집니다:

• AGENTS.md는 Codex가 리포지토리 내에서 어떻게 작동해야 하는지를 정의합니다.
• 스킬(Skills)은 prime, create-prd, plan-feature, execute, commit과 같은 범위가 지정된 워크플로(workflows)를 설명합니다.

AGENTS.md, 스킬(Skill), 또는 계획(plan)이 해당 문서를 언제 참조해야 하는지 명확하게 지정한다면, 특화된 문서(Specialized documentation)는 별도의 파일에 존재할 수 있습니다.

실전 실험: 할 일 목록 (Todo List)

파일 재분류를 마친 후에도, 이 방법이 실제로 Codex와 함께 작동하는지 확인해야 했습니다.

제품의 복잡성보다는 프로세스에 집중하기 위해, 저는 의도적으로 간단한 애플리케이션인 개인용 할 일 목록(todo list)을 선택했습니다.

저는 기본 파일들이 포함된 폴더에서 Codex를 실행하고 다음과 같은 짧은 프롬프트(brief)를 주었습니다:

항목을 추가하고, 목록을 확인하고, 항목을 삭제하고, 완료로 표시할 수 있는 간단한 할 일 목록 (todo list) 애플리케이션을 만들고 싶습니다.

인증 (authentication)은 필요하지 않습니다. 개인적인 용도로 Next.js를 사용하고 Vercel에 애플리케이션을 배포하고 싶습니다.

아키텍처 (architecture)에 대한 당신의 권장 사항을 듣고 싶습니다. 또한 서브에이전트 (subagent)가 이러한 유형의 대시보드에 대한 모범 사례 (best practices)를 조사하기를 원합니다.

조사가 완료되면, 아주 작은 제품 세부 사항이라도 명확히 하기 위해 필요한 모든 질문을 저에게 해주세요.

Codex는 주요 미결 사항들이 명확해질 때까지 저에게 질문을 하기 시작했습니다.

이 단계의 목표는 단순히 우리가 기대하는 것을 설명하는 것이 아니라, 가능한 한 많은 가설 (assumptions)을 제거하는 것입니다. 요구 사항이 충분히 명확해지자, 저는 다음과 같은 스킬 (Skill)을 호출했습니다:

$create-prd

브리프 (Brief)에서 PRD로

결과물로 나온 PRD.md 파일은 우리가 구축하고자 하는 것을 나타냅니다. 저의 경우, 여기에는 다음 내용이 포함되어 있습니다:

• 제품 목표 (product objective)
• 주요 사용자 (primary users)
• 유스케이스 (use cases)
• MVP 기능 (MVP features)
• 범위 외 기능 (out-of-scope features)
• 기술 스택 (technology stack)
• 아키텍처 제약 사항 (architectural constraints)
• 비기능적 요구 사항 (non-functional requirements)
• 일반적인 성공 기준 (general success criteria)
• 구현 단계 (implementation phases)

단계별로 나누는 것이 특히 중요합니다. Codex에게 단 한 번의 세션에서 제품 전체를 구현하도록 요청하는 것은 큰 의미가 없습니다.

각 단계는 별도로 계획, 구현 및 검증할 수 있을 만큼 충분히 작아야 합니다. 이는 프로세스를 검증하기 쉽게 만들며, 동시에 PRD가 효과적인 로드맵 (roadmap)이 되게 합니다.

프로젝트 규칙 추가하기

앞서 언급했듯이, 저장소에는 이미 이전 CLAUDE-template.md에서 파생된 기본 AGENTS.md 파일이 포함되어 있었습니다. 이 파일에는 모든 프로젝트에 걸쳐 유지하고 싶은 초기 구조와 일반 가이드라인이 포함되어 있습니다.

무엇을 구축해야 하는지 정의한 후, 저는 다음과 같이 호출했습니다:

$create-rules

제 워크플로에서 이 Skill은 AGENTS.md를 처음부터 새로 만들지 않았습니다. 대신 PRD(제품 요구 사항 문서)와 저장소(repository)를 분석한 다음, 다음과 같은 프로젝트별 정보를 포함하여 기존 파일을 확장했습니다:

• 기술 스택 (technology stack);
• 개발, 빌드 및 테스트 명령 (development, build, and test commands);
• 디렉토리 구조 (directory structure);
• 컨벤션 (conventions);
• 아키텍처 결정 (architectural decisions).

최종 결과물이 충분히 간결하게 유지되는 것이 중요합니다. AGENTS.md에는 저장소에 일반적으로 적용 가능한 지침이 포함되어야 합니다. 전문적인 문서(Specialized documentation)는 AGENTS.md, 특정 Skill, 또는 계획(plan)이 해당 문서를 언제 참조해야 하는지 명확하게 지시한다면 별도의 파일로 존재할 수 있습니다.

첫 번째 컨텍스트 리셋: $prime

초기 프로젝트 정의가 완료된 후, 저는 새로운 세션을 열고 다음을 호출했습니다:

$prime

이것이 첫 번째 의도적인 컨텍스트 리셋 (context reset)입니다. 새로운 세션은 길었던 초기 대화 내용을 상속받지 않습니다. 대신 PRD.md, AGENTS.md, 저장소, 그리고 Git 히스토리를 통해 프로젝트를 재구성합니다.

새 세션을 열 때, Codex는 이미 AGENTS.md에 포함된 적용 가능한 지침들을 로드한 상태입니다. 그런 다음 $prime Skill은 다음과 같은 과정을 통해 자신의 멘탈 모델 (mental model)을 완성합니다:

• PRD 읽기;
• 저장소 탐색;
• 엔트리 포인트 (entry points) 식별;
• Git 상태 확인;
• 최근 커밋 (commits) 검토;
• 이미 완료된 단계가 무엇인지 결정;
• 다음 목표 식별.

마지막으로, Codex는 프로젝트에 대해 이해한 내용을 요약하여 제공합니다.

이 단계는 주의 깊게 검토해야 합니다. 만약 에이전트의 멘탈 모델이 부정확하다면, 구현 단계로 넘어가기 전에 개입하는 것이 가장 좋습니다.

PIV 사이클

이 시점에서 우리는 PIV 사이클의 핵심에 도달합니다:

Plan → Implement → Validate

PRD의 각 단계는 이 세 단계를 거치게 됩니다.

Plan: 단계를 계획으로 전환하기

저는 Codex가 식별한 첫 번째 단계를 선택하고 다음을 호출했습니다:

$plan-feature

이 단계에서는 아직 코드를 생성하지 않습니다. 이 단계의 목적은 PRD (제품 요구 사항 문서) 기능을 상세한 기술 계획 (technical plan)으로 전환하는 것입니다.

Codex는 저장소 (repository)를 분석하고, 관련 문서를 참조하며, 다음 사항들을 정의합니다:

• 기능의 목표;
• 프로젝트의 현재 상태;
• 아키텍처 결정 (architectural decisions);
• 생성하거나 수정할 파일;
• 수행할 작업 (tasks);
• 엣지 케이스 (edge cases);
• 테스트 및 검증 전략;
• 작업이 완료된 것으로 간주되기 위해 필요한 기준.

저의 경우, $plan-feature는 다음과 같은 새로운 영구 파일 (persistent file)을 생성했습니다:

.agents/
└── plans/
    └── implement-todo-dashboard-mvp.md

이 세부 사항은 중요합니다. 계획은 대화에만 국한되지 않고 저장소에 저장되는 산출물 (artifact)이 됩니다.

이 문서는 계획이 준비되는 동안 논의에 참여하지 않았던 새로운 Codex 세션에 의해 실행될 수 있을 만큼 충분히 완전해야 합니다.

진행하기 전에, 저는 파일이 다음 사항들을 충족하는지 확인하기 위해 검토했습니다:

• PRD와 일치하는지;
• 범위를 확장하지 않았는지;
• 충분히 명확한 작업들을 포함하고 있는지;
• 진정으로 검증 가능한 완료 기준을 정의했는지.

Implement: 새로운 컨텍스트에서 계획 실행하기

계획이 승인된 후, 저는 실행을 전담하는 새로운 세션을 열었습니다.

이것이 두 번째 의도적인 컨텍스트 리셋 (context reset)입니다. 새로운 세션은 질문되었던 모든 질문, 거부된 모든 대안, 또는 계획 단계에서 발생했던 중간 추론 과정을 알 필요가 없습니다. 오직 계획에 통합된 결정 사항과 저장소에 저장된 영구적인 컨텍스트 (persistent context)만 필요로 합니다.

그 후 저는 다음을 호출했습니다:

$execute .agents/plans/implement-todo-dashboard-mvp.md

이 단계 동안 Codex는 문서에 정의된 작업들을 따랐고, 필요한 파일들을 생성했으며, 할 일 목록 대시보드 (todo list dashboard)를 구현하고, 계획된 체크 사항들을 추가했습니다.

$execute의 목적은 이미 승인된 계획을 수행하는 것입니다. 작업 중에 예상치 못한 중요한 결정 사항이 발생하면, 에이전트는 중단하고 명확한 설명을 요청합니다.

검증 (Validate): 결과 확인

구현이 완료되면, PIV 사이클의 세 번째 단계인 검증 (validation)이 시작됩니다.

Codex는 계획에 정의된 체크 항목들을 실행합니다. 예를 들어 다음과 같습니다:

npm run typecheck
npm run lint
npm run build
...

하지만 웹 애플리케이션의 경우, 이러한 체크만으로는 충분하지 않습니다. 인터페이스의 실제 동작 또한 반드시 검증되어야 합니다.

저의 경우, 주요 시나리오는 다음과 같았습니다:

• 새로운 항목 추가
• 목록에 항목 표시
• 완료 상태로 표시
• 항목 삭제
• 페이지 새로고침
• 상태가 올바르게 유지(persisted)되었는지 확인

Cole의 예시와 마찬가지로, agent-browser Skill을 사용하여 이러한 흐름을 자동화하고 사용자가 사용하는 방식대로 애플리케이션을 테스트할 수 있습니다.

자동화된 검증이 인간의 검증 필요성을 없애주는 것은 아닙니다. 프로세스의 마지막 단계에서는 애플리케이션의 주요 흐름을 직접 테스트하는 것이 여전히 중요합니다.

장기 기억으로서의 Git

기능이 올바르게 작동하는 것을 확인한 후, 저는 다음을 호출했습니다:

$commit

이 Skill은 무엇이 구현되었고 어떻게 검증되었는지를 기술하여 커밋 메시지 (commit message)를 표준화합니다.

따라서 Git 히스토리 (Git history)는 추가적인 역할을 수행하게 됩니다. 단순히 코드 변경 사항을 보존하는 것을 넘어, Codex를 위한 일종의 장기 기억 (long-term memory) 역할을 하게 되는 것입니다.