Claude Code 기반 Harness를 Codex 구조로 전환하기

최근 핫했던 하네스 클로드 코드 플러그인, 100개의 하네스는 특정 작업을 수행하기 위해 여러 역할의 에이전트로 구성하고, 이를 스킬과 함께 조합해 하나의 결과물을 만들어내는 사례를 소개하고 있다.

하네스(Harness)라는 용어가 AI 코딩에 본격적으로 사용되기 시작한 것은 2026년 2월이다. 하지만 사실 우리는 이미 프롬프트 엔지니어링을 통해 유사한 작업을 수행해오고 있었다. 다만 기존 방식은 컨텍스트 윈도우의 한계가 있었고, 일관된 결과를 만들기 위해 하나의 에이전트에 여러 역할과 권한을 동시에 부여해야 했다. 이러한 접근은 점점 복잡해지면서 관리와 확장에 한계를 드러냈다. 최근에는 역할과 책임을 분리한 멀티 에이전트 방식으로 전환되면서 기존의 단일 프롬프트 기반 방식 대비 결과물의 품질이 눈에 띄게 향상되고 있다.

harness-100은 Claude Code 환경을 기준으로 작성되어 있다. 에이전트와 스킬이 .claude 디렉토리 아래에 정의되어 있고, 전반적인 실행 흐름 역시 Claude Code의 동작 방식에 맞춰져 있다.

그래서 Codex 환경에서 동작할 수 있도록 샘플 하나를 선정해 전환을 시도해보았다. 접근 방식은 단순하다. Claude에 맞춰진 표현과 구성을 유지하는 대신에, 이를 Codex가 이해할 수 있는 형태로 재구성하는 것이다.

주요 변경 대상은 AGENTS.md, SubAgents, Skills 이다. OpenAI Developers에 공개된 공식 문서를 기준으로 구조와 형식을 맞췄다. 전체적으로 보면 새로운 구조를 만든다기보다는 기존 구조를 그대로 유지하면서 다른 실행 환경에 맞게 변환했다는 것이 적절하다.

Claude code 기준으로 작성된 에이전트/스킬 구조를 Codex 환경으로 변경하기 위해 다음과 같은 프롬프트를 작성하였다.

다음은 Claude Code 환경 기준으로 작성된 에이전트/스킬 구조이다.

이 구조를 OpenAI Codex 환경에 맞게 변환해줘.
반드시 아래의 공식 문서를 기준으로 판단하라:
- AGENTS.md: https://developers.openai.com/codex/guides/agents-md
- Subagents: https://developers.openai.com/codex/subagents
- Skills: https://developers.openai.com/codex/skills

요구사항:
1. Claude 구조를 Codex 구조로 변환한다.
   - CLAUDE.md → AGENTS.md
   - .claude/agents/*.md → .codex/agents/*.toml
   - .claude/skills/**/skill.md → .agents/skills/**/SKILL.md

2. 각 파일은 Codex 공식 문서의 목적과 형식에 맞게 재작성한다.
   - AGENTS.md: 프로젝트 전반 규칙, 작업 흐름, 출력 기준, 실행 시 유의사항을 포함
   - agent TOML: 반드시 top-level 필드로 name, description, developer_instructions를 포함
   - SKILL.md: 반드시 YAML front matter에 name, description 포함

3. 기존 의미는 유지하되, Codex가 자동으로 이해하고 사용할 수 있도록 더 명확하고 실행 가능한 지침으로 개선한다.

4. 출력은 반드시 다음 순서를 따른다.
   1) 전체 디렉토리 구조
   2) 각 파일의 실제 내용

5. 각 파일은 반드시 아래 형식으로 출력한다.
   --- FILE: 경로 ---
   ```확장자
   파일 내용
   ```

6. 공식 문서에 없는 규칙은 임의로 만들지 말고, 필요한 경우 “추론한 설계”라고 표시한다.

입력 구조:
[여기에 .claude 구조 붙이기]

이 프롬프트를 그대로 붙여넣고 실행한 결과 아주 만족할 만한 결과를 확인할 수 있었다.

Codex 스타일로 변경된 설정 파일들

참고

• https://github.com/revfactory/harness-100
• https://developers.openai.com/codex