Codex로 번역 검토 plugin 만들기

HoonDong_K·2026년 6월 4일

개요

오픈소스 컨티리뷰션 아카데미(OSSCA)에 멘티로 참여하면서 모던 JavaScript 튜토리얼 저장소에 미번역 페이지를 번역하거나 원문 저장소의 최신 커밋을 가져오는 과정에서 발생한 충돌을 해결하였다.

다양한 사람들이 한 가지 프로젝트에 기여한다는 것은 해당 프로젝트에 대한 컨벤션을 반드시 지켜야 한다는 점이고 더군다나 번역과 관련된 오픈소스는 용어집, 맞춤법, 번역 규칙 등 더 세심하고 일관된 규칙을 따라야 한다.

이번에 좋은 기회로 기여할 수 있었던 모던 자바스크립트 튜토리얼 번역 저장소에서도 맞춤법 검사기, KIGO 번역 스타일 가이드, 번역 모범 사례, 합의된 번역어 등을 통해 일관된 번역문을 이어가기 위한 지침서를 제공하였다. 이번에 기여하진 않았지만, 리액트 공식문서 한국어 번역 저장소에서도 동일하게 기여를 위한 가이드를 명시하고 있다.

ko.javascript.info	ko.react.dev

번역을 위한 지침서는 정해져있지만 사람이 직접 이 지침서를 읽어가며 번역을 진행하기엔 몇 가지 불편한 점이 존재하였다.

규칙 정보가 산발되어 있다.
하나의 문서 안에 모든 규칙이 적혀있는 것이 아닌, 참고해야할 규칙이 링크를 통해 제공되고 있기 때문에 번역을 검토하기 위해 여러 링크를 통해 들어가며 규칙을 확인해야 하는 불편함이 존재한다.
규칙을 모두 암기할 수 없다.
모든 규칙을 암기하고 있지 않는 이상, 규칙이 존재한다는 사실 자체를 망각할 수 있는 위험이 존재한다.

이러한 작업은 AI를 통해 대체될 수 있다고 생각하였다. 이미 명확한 규정집이 존재하기에, 사람이 모두 외우고 검수할 필요없이 규정집을 종합한 SKILL을 통해 누락된 규칙없이 번역 및 검토가 가능하다고 판단했다.

처음부터 내가 직접 원문을 번역할 필요없이 AI를 통해 번역과 검토 에이전트를 만들어, 서로 리뷰를 주고 받으며 완성도를 높이는 방법도 존재하겠지만 번역 작업을 AI한테 뺏기고 싶지 않았다. 원문 공식 문서를 읽는 것을 좋아하기도 하고, 이 프로젝트를 참가한 이유도 원문의 흐름을 자연스럽게 번역하여 한국 독자들에게 내용을 온전히 이해할 수 있게하기 위함에 있기에 번역의 재미를 온전히 내가 가져가고 싶었다. 이에 대해, 번역은 스스로 진행하고 AI를 통해 검토를 하도록 방향성을 잡았다.

함께 프로젝트에 참여하셨던 멘티 한 분이 작업을 진행하며 이를 기반으로 Claude Code 스킬을 만드셨다고 공유해주셨다. 하지만 Codex를 사용하고 있던 나는 이를 사용할 수 없었기에, 기존 스킬을 기반으로 Codex용 Plugin을 만들어 Codex 사용자들도 동일한 스킬이 호환되도록 내용을 수정하고 추가하기로 하였다.

기존 구조

전환을 시도하기 전 프로젝트의 구조를 간략히 설명하자면 다음과 같다.

.
├── .claude-plugin/
│   ├── plugin.json               # 플러그인 메타데이터
│   └── marketplace.json          # 마켓플레이스 정보
├── agents/
│   ├── wiki-validator.md         # WIKI 규칙 검사 에이전트
│   ├── kigo-validator.md         # KIGO 규칙 검사 에이전트
│   ├── custom-rule-validator.md  # CUSTOM 규칙 검사 에이전트
│   └── spell-checker.md          # 맞춤법 검사 에이전트
├── skills/
│   └── javascriptinfo-ko-translation-validator/
│       ├── SKILL.md              # Claude Code 스킬 정의
│       └── references/
│           ├── wiki-guidelines.md
│           ├── kigo-guidelines.md
│           └── custom-rules.md
└── scripts/
    └── check_spelling.py         # 맞춤법 검사 스크립트

/skills/ 폴더 하위에 하나의 스킬이 존재한다.
스킬이 참고할 문서들이 references 에 존재한다. 번역의 지침서로 KIGO와 WIKI, 그리고 추가적인 규칙을 추가하였다.
/scripts 폴더 하위에는 맞춤법 검사를 위한 스크립트가 존재한다. 해당 스크립트는 맞춤법 검사를 위한 hanspell을 통해 검사한다.
총 4개의 에이전트가 존재한다. 각 지침서에 대한 검토를 담당할 에이전트 3명과 맞춤법 검사 스크립트를 실행한 한 명의 에이전트다.
SKILL.md에서는 각 에이전트를 병렬로 실행시키고 어떻게 결과를 도출할 것인지에 대한 과정이 작성되어 있다.

Codex로 전환

1️⃣ AI를 통해 딸깍 시도

Claude Code를 기반으로 만들어진 스킬을 Codex로 만드는 것은 그리 어렵지 않을 것이라 생각하였다. 단순히 AI를 통해 뚝딱 만들 수 있을 것이라 판단한 것이다. 하지만 한 가지 간과한 것은 '나는 스킬을 만들어본 적도, 플러그인을 만들어본 적도 없다는 사실' 이다.

그래도 나름 프롬프트는 구체적으로 작성하면서 AI를 통해 뚝딱 생성을 시도하였다.

현재 프로젝트는 claude code를 기반으로 marketplace를 등록하고 스킬들을 정리한 자료야. 
이 자료들을 Codex에 맞춰서 plugin으로 등록하거나 앞으로 번역할 내용에 대해 skill들을 가져다 쓸 수 있게 수정할 수 있어? 
1. codex 기반으로 어떻게 변경할 수 있는지
2. plugin 등록이 가능한지,
3. skill을 사용할 수 있는지 기반으로 설명해줘

현재 상태, 어떤 결과를 원하는 지, 내가 원하는 것을 리스트로 정리하고 작업을 바로 시작하는 것이 아닌 계획을 물어보는 것을 짬뽕으로 조합해서 물어보았고 당연히 AI는 현재 프로젝트의 구조를 기반으로 이해하고 어떻게 구조를 변경하면서 Codex를 위한 플러그인을 생성할 수 있는지 설명해주었다.

그리고 Codex가 제안한 구조로 실행을 시켜서 실제 플러그인 등록까지 완료한 것을 확인하였다.

하지만 문제는 여기서 발생되었다.

실제 플러그인을 실행시키려하니 스킬을 읽어오지 못하는 문제가 발생하거나, 코덱스를 실행할 때마다 설치된 플러그인이 제대로 로드되지 않았다는 문구들이 등장하기 시작하였다. 문제가 발생하면 원인을 파악하고 해결하면 되지만, 가장 큰 문제는 Codex가 어떤 폴더의 어떤 파일을 읽어서 실행시키는 지 제대로 이해하지 못했던 것이다.

즉, 어떤 폴더 구조를 형성해야 Codex가 원하는 파일을 쉽게 찾아서 작업을 수행할 수 있는 지에 대한 지식이 없었다. 그러다보니 문제가 발생해도 어디서 문제를 해결해야할 지조차 찾지 못한 상태였고 제대로 다시 시작하기 위해 AI로 생성한 파일들과 플러그인을 모조리 제거하였다.

AI에게 의존하지 않고 AI가 생성한 결과물을 사람이 리뷰해야 한다는 점을 깨닫고 리뷰할 수 있는 지식을 기르기 위해 OpenAI 공식문서를 통해 하나씩 공부하면서 생성하기로 판단하였다.

2️⃣ 공식문서를 통한 전환

내가 만들고 싶었던 것은 Cladue Code로 만들어진 이 스킬을 Codex로 전환하는 것이기에 OpenAI 공식문서를 참고하여 크게 Plugins, Skills, Subagents 부분을 참고하였다.

⭐️ Plugins

플러그인은 스킬, App, MCP를 함께 묶어서 사용할 수 있는 하나의 패키지다.

Skills: 특정 작업을 수행하기 위한 지침서다. 작업을 수행하기 위해 스크립트를 실행하거나 적절한 레퍼런스를 참고하고 지정된 단계를 밟아가며 작업을 처리하게 해준다.
Apps: Github, Slack과 같은 도구와 연결할 수 있게 해주며 이를 통해 해당 도구 안에서의 정보를 읽고 작업을 수행할 수 있다.
MCP Servers: 로컬 외부의 정보나 도구에 접근할 수 있도록하는 서비스

플러그인과 스킬의 차이점이 여기서 드러난다. 스킬은 작업을 수행하기 위한 지침서지만, 플러그인은 스킬을 포함하여 더 포괄적인 작업을 수행할 수 있는 하나의 단위다. 여러 작업들을 스킬 별로 분리해서 보관하거나, App이나 MCP를 통해 외부 도구를 끌어다가 작업을 수행할 수 있게 해준다.

플러그인의 한 가지 더 큰 장점은 협업과 공유가 쉽다는 점이다. 단순히 하나의 작업만 수행한다면 스킬 문서 파일로만 공유가 가능하겠지만, 팀 내에서 수행할 Workflow들에 대해서는 하나의 플러그인으로 담아서 공유한다면 팀원들은 팀 내에 수행할 동일한 Workflow를 플러그인을 통해 실행시킬 수 있다.

내가 스킬이 아닌 플러그인을 택한 이유도, 나만 사용하는 것이 아닌 함께 번역을 진행하는 멘티들에게 공유하며 간단하게 번역 검토 작업을 실행시키기 위함에 있다.

플러그인을 설정하는 방법은 다음과 같다.

1️⃣ plugin 메타 데이터 설정

/.codex-plugin/plugin.json 파일을 생성하여 플러그인에 대한 메타 데이터를 관리한다.

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

전체 메타데이터 속성 목록을 보려면 Plugin Structure을 참고해주세요!

2️⃣ marketplace 등록

Marketplace는 팀이나 개인이 만든 플러그인을 등록
하고 설치해서 사용할 수 있는 저장소 공간이다.

marketplace는 두 가지로 구분된다.

Repo: 공유 저장소를 통해 만들어진 플러그인 목록을 다른 사람들과 함께 사용할 때 사용한다. $REPO_ROOT/.agents/plugins/marketplace.json 경로에 저장하며 공유되는 Repo에 .agents 폴더를 생성하여 marketplace를 공유한다.

Personal: 로컬에서만 사용할 플러그인 목록을 관리하는 공간이다. 생성한 플러그인을 ~/.codex/plugins/ 공간에 넣어두고 ~/.agents/plugins/marketplace.json 공간을 통해 생성한 플러그인은 marketplace에 등록해주면 된다.

marketplace의 메타데이터 속성 목록을 보려면 Marketplace metadata를 참고해주세요!

3️⃣ Skill 생성

플러그인의 전체 구조와 다른 팀원들과 공유할 수 있는 Marketplace의 환경을 모두 세팅하였다.

이제 이 플러그인에서 어떤 작업을 수행하는 지에 대한 스킬을 세팅할 차례다. 이 내용은 하단 Skill에서 이어서 설명하겠다.

⭐️ Skills

스킬은 어떤 작업을 수행하기 위한 workflow를 신뢰성 있게 수행할 수 있도록 지침서, 자원, 스크립트 등을 제공한다.

스킬에 대한 규격은 open agent skills standard를 따른다고 한다.

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

SKILL.md: 해당 스킬을 실행하기 위한 지침서와 메타데이터
scripts: 작업을 수행하기 위해 실행된 스크립트
references: 작업을 수행하기 위해 참고할 문서
assets: 참고할 템플릿 혹은 여러 자원들

위에서 함께 살펴본 현재 프로젝트 구조는 번역 검토를 위해서 참고해야 할 문서 3개(KIGO, WIKI, Custom)과 맞춤범 검사를 위한 Script가 존재한다.

SKILL.md 파일에서는 참고할 References와 Scipts를 통해 어떻게 작업을 수행할 것인지에 대한 지침서와 메타데이터가 작성된다.

---
name: skill-name
description: A description of what this skill does and when to use it.
---

스킬에 대한 메타 데이터는 기본적으로 name과 description이 필수적으로 포함되며 Optional한 속성들을 추가할 수 있다.

그 이후로 마크다운 형식에 맞춰 지시할 작업에 대한 지침서를 작성하면 된다. 형식은 자유롭지만, OpenAI에서는 다음과 같은 Best practice를 제공한다.

하나의 스킬은 하나의 작업만 수행하도록 작성한다.
외부 도구의 활용이나 필수적인 상황이 아니라면 스크립트보다 지침서를 우선으로 한다.
명확한 입력과 출력 형식을 갖춘 행동 지침를 작성한다.
지침서에 맞는 정확한 동작을 확인하기 위해 프롬프트를 통해 테스트해본다.

더 자세한 best pracice는 Best practices for skill creators 에서 확인할 수 있고 여러 예제 또한 Client Showcase 에서 참고해볼 수 있습니다!

⭐️ Subagents

스킬을 만들고 이제 codex의 @plugin-creator 을 통해 플러그인을 만드려고 하는데 한 가지 문제를 계속 마주하였다.

기존 Skill은 하나의 스킬을 통해 4개의 에이전트가 각각의 역할을 맞춰 병렬적으로 수행한 구조였다. 하지만 AI를 통해 스킬을 만드려고 하면 Subagent 구조가 아닌 하나의 workflow에 4개의 작업을 순차적으로 수행하게끔 만드는 것이다.

이에 대해서도 OpenAI를 통해 기본적은 Subagent 활용과 폴더 구조를 미리 구성하고 여러 에이전트를 병렬적으로 실행하는 방식을 학습하고자 하였다.

Subagents는 역할을 가진 각 에이전트를 생성하여 하위 workflow를 병렬적으로 수행하게끔 해준다.

컨텍스트 양에는 한계가 있다보니 에이전트가 하나의 큰 작업을 수행하다보면 중간에 발생하는 수많은 데이터로 인해 컨텍스트가 오염될 수도 있다. 이에 대해 메인 에이전트는 필요한 데이터만 컨텍스트에 저장하고 서브 에이전트들은 작업을 수행하고 그 결과만 메인 에이전트에 전달하는 식으로 수행하면 더 정확하고 깔끔한 데이터를 도출할 수 있다. 또한, 병렬적으로 처리하다보니 무거운 작업들을 동시에 수행하여 빠르게 처리할 수 있다는 장점도 있다.

반면에, 병렬적으로 작업을 수행하다보면 동시성 문제도 발생할 수 있으니 코드 작업보다 문서 파악, 테스트, 요약 등의 작업에서 subagent를 사용해야 한다.

subagent도 두 가지로 구분된다.

Personal: ~/.codex/agents/
project-scoped: .codex/agents/

그 하위에 생성한 에이전트를 .toml 파일을 통해 생성하면 된다.

name, description developer_instructions는 반드시 포함되어야 하지만, nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers,skills.config는 선택적으로 사용할 수 있다.

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]

이미 만들어진 여러 subagent를 공유하는 저장소 Awesome Codex Subagents도 참고해보면 좋을 것 같습니다!

실행시킬 각 에이전트에 대한 모델을 선택해야 한다. Codex에서 사용할 수 있는 모델은 Codex Models 에 자세히 나와있다.

3️⃣ 플러그인 생성

이제 모든 구조는 다 만들었으니, @plugin-creator를 통해 Codex에게 플러그인을 생성해달라고하면 필요한 작업들을 수행하고 플러그인을 사용할 수 있는 상태가 된다.

APP 환경에서도 Plugin 리스트를 통해 생성한 플러그인을 사용할 수 있고 CLI 환경에서도 plugin list 나 $ko... 명령어를 통해 플러그인과 스킬이 잘 등록된 것을 확인할 수 있다.

4️⃣ 작업 및 결과

이제 생성한 플러그인을 통해 번역 작업에 대해 검토를 실행시켜보려 한다.

$plugin-name 4-binary/01-arraybuffer-binary-arrays/article.md 번역을 완료하였는데, Subagent를 가동해서 스킬을 통해 번역을 검토해줘줘

Workflow 로그를 확인해보면 Spawned로 각각의 Agent들을 생성하여 병렬적으로 수행하고 있는 것을 확인해볼 수 있다. Description에는 각각의 Agent가 어떤 역할을 수행하는 지 작성했는데 로그에는 다 똑같은 내용만 뜨고 있어서 어떤 에이전트가 생성되었는 지는 확인하기가 어려웠다. 이거에 대해서도 Agent 파일에 추가하면 좋을 것 같다.

그렇게 번역을 검토하고 수정해야할 내용이 담긴 article_validation.json 파일을 생성하였다.

{
  "meta": {
    "validated_file": "...",
    "validated_at": "2026-06-04T08:48:29Z",
    "summary": {
      "total": 13,
      "required": 4,
      "recommended": 9,
      "info": 0
    }
  },
  "violations": [
    {
      "line": 1,
      "rule_id": "CUSTOM-병기",
      "source": "custom",
      "problem": "주제 핵심어 `이진 배열` 첫 등장 시 한-영 병기가 없습니다.",
      "suggestion": "`이진 배열(binary array)`",
      "severity": "required"
    },
    ...
    {
      "line": 194,
      "rule_id": "CUSTOM-금지표현",
      "source": "custom",
      "problem": "`기본적으로`의 `-적으로` 표현 사용",
      "suggestion": "`기본으로`",
      "severity": "recommended"
    },
    {
      "line": 268,
      "rule_id": "WIKI-8",
      "source": "wiki",
      "problem": "`이런 용어들`의 복수형 `-들`은 생략해도 자연스럽습니다.",
      "suggestion": "`이런 용어`",
      "severity": "recommended"
    }
  ],
  "passed": {
    "wiki": [...],
    "kigo": [...],
    "custom": [...],
    "spell": [...]
  }
}

SKILL.md에 명시한 입출력 포맷에 맞게 파일이 생성되었고, 어느 지점에서 어떤 규칙을 위반하였는 지에 대해서도 자세하게 작성되어 있다.

결론

스킬을 만들어보는 경험

스킬을 만들고 에이전트를 만들어서 반복되는 작업을 자동화할 수 있다는 점은 알았지만, 실제 스킬을 만들어본 적은 없었다. 하지만 이번 기회에 명확한 기준이 있는 번역 규칙을 스킬로 만들고 사람이 하나씩 검토해야 하는 불편한 작업에 대해 에이전트를 생성하여 자동화를 시켜보는 경험을 해봄으로써 AI가 할 수 있는 영역이 내가 그동안 AI를 활용했던 영역에 비해 굉장히 넓다는 것을 몸소 체감할 수 있었다.
기존에는 단순히 AI와의 주고 받는 대화를 통해 궁금한 지식을 채우고 단순한 파일을 만드는 데에 그쳤다면, 이제는 원하는 작업을 수행할 수 있는 미리 만들어두고 그 작업이 필요할 때마다 딸깍으로 실행만 시키면 된다는 것이다. 지금 깨달았다는 것은 굉장히 늦었다는 것이겠지만,, 머리로 이해하고 있는 것과 직접 체감했다는 것의 그 차이가 어마어마하다는 것을 깨달았던 순간이었다.

AI를 활용하려면 리뷰할 수 있는 지식이 있어야 한다.
AI를 통해 자동화를 해보는 경험도 즐거웠지만, 가장 큰 인사이트는 결국 사람이 판단해야 한다는 근본은 사라지지 않는다는 것이다. AI가 알아서 다해주면 좋겠지만 결국 AI가 무엇을 하고 어떻게 해야할 지는 사람이 결정하고 리뷰해야 한다는 것이다. AWS Summit에서 배웠던 AI-DLC에서도 AI가 온전히 하거나 사람이 온전히 하는 것이 아닌 AI와 사람이 주고 받으며 Human in the Loop가 형성되어야 한다는 것이 인상깊었다.
이번 플러그인을 만들면서 AI에게 모든 것을 맡기려고 시도하였지만 AI가 무엇을 만드는 지, 잘 작업하고 있는 지에 대해 전혀 판단할 수 없었다. 어떤 작업을 만들더라도 어떻게 만들 것인지, 무엇을 만들 것인지 구체적으로 방향성을 설정하는 것은 사람에게 있다는 것을 경험할 수 있었고 공식문서를 통해, 그리고 이렇게 다시 한 번 경험을 정리하면서 Codex에서 어떻게 스킬을 만들고 이를 활용할 것인지 넓게 경험할 수 있었다.