Claude Code와 Codex에서 OpenSpec 워크플로우를 일관되게 운영하기

배경

Claude Code와 Codex를 함께 사용해 개발하고 있다. 동일한 OpenSpec 워크플로우를 사용 중이라, 두 도구가 일관되게 동작하길 바란다.

핵심: 엔진은 같고, 어댑터만 다르다.
Claude Code, Codex 모두 같은 OpenSpec CLI(openspec status, openspec instructions, openspec archive 등)를 호출한다. 차이는 사용자 입력을 CLI로 전달하는 어댑터 계층에 있다. Claude Code에서는 .claude/commands/opsx/*.md가, Codex에서는 AGENTS.md에 정의한 매핑과 .codex/skills/*/SKILL.md가 그 역할을 맡는다.

아래에서는 두 도구의 공식 동작 차이와, 일관성을 유지하기 위해 실제로 어떻게 구성했는지를 살펴본다.

1. 공식 동작

Claude Code

맥락 전달

AGENTS.md는 자동으로 읽지 않는다. 필요하면 CLAUDE.md에서 명시적으로 읽도록 지시해야 한다.

확장 방식

경로	호출 방식	비고
`.claude/commands/{name}.md`	`/name` 슬래시 커맨드	OpenSpec이 기본 생성하는 경로(현재 `/opsx:*` 직접 진입점). 레거시지만 동작
`.claude/skills/{name}/SKILL.md`	`/name` 슬래시 커맨드 또는 Claude가 자동 사용	Claude 문서 기준 권장 경로. OpenSpec도 함께 생성

같은 이름의 command와 skill이 있으면 skill이 우선한다.

Codex

맥락 전달

Codex는 AGENTS.md를 자동으로 읽는다.

확장 방식

경로	호출 방식	비고
`.agents/skills/{name}/SKILL.md`	모델이 해석해서 매칭, 또는 `$skill-name`으로 명시 호출	Codex 문서 기준 표준 경로
`.codex/skills/{name}/SKILL.md`	동일	OpenSpec이 기본 생성하는 경로

2. 커스텀 동작

여기서부터는 Claude Code나 Codex의 공식 기본 사용법이 아니라, OpenSpec이 생성한 기본 구조와 추가로 적용한 설정을 구분해 다룬다.

OpenSpec 기본 설정 (`openspec init`이 생성)

opsx:* 공통 어휘

OpenSpec은 opsx:apply, opsx:archive, opsx:explore, opsx:propose 같은 공통 어휘를 사용한다. 사용자가 어느 도구에서든 같은 이름으로 워크플로우를 실행할 수 있게 하기 위해서다. 호출 문법 차이는 아래 "플랫폼별로 남는 차이" 테이블 참고.

생성되는 파일 구조

OpenSpec 초기화 시 Claude Code용 commands + skills, Codex용 skills를 모두 생성한다:

.claude/commands/opsx/
├── apply.md
├── archive.md
├── explore.md
└── propose.md

.claude/skills/openspec-*/
├── openspec-apply-change/SKILL.md
├── openspec-archive-change/SKILL.md
├── openspec-explore/SKILL.md
└── openspec-propose/SKILL.md

.codex/skills/openspec-*/
├── openspec-apply-change/SKILL.md
├── openspec-archive-change/SKILL.md
├── openspec-explore/SKILL.md
└── openspec-propose/SKILL.md

정책 배치 기준: 3층 분리

공통 규칙을 어디에 둘지는 다음 기준으로 나뉜다.

정책 층	무엇을 두나	기준 소스	양쪽 도달 방식
저장소 전역 규칙	언어 정책, 코드 품질, 매핑 테이블 등	`AGENTS.md`	Claude: CLAUDE.md에서 읽도록 지시 / Codex: 자동 로드
OpenSpec schema 규칙	기술 스택, artifact 생성 제약, GRAY-AREAS 분류	`openspec/config.yaml`	`openspec instructions`가 양쪽 모두에 공통 주입
도구별 워크플로우 지시	사용자 입력 수집 방식, 단계 진행 순서, 분기/검증 규칙	`.claude/commands/opsx/.md` / `.codex/skills//SKILL.md`	각 도구가 자기 진입점만 읽음

공통 정책은 위 두 층으로 올리고, command/skill에는 도구별 행동 차이만 남기는 것이 유지보수에 유리하다. 다만 Codex skill에 언어 정책 등을 다시 적는 경우가 있는데, 이는 기술적으로 필수가 아니라 워크플로우 실행 시 해당 규칙을 더 강하게 상기시키기 위한 선택적 강화다.

추가로 대응한 것

OpenSpec 기본 설정 위에 추가한 대응:

Codex 호출 매칭 보조

Claude Code는 커맨드 이름과 파일 경로가 1:1로 대응된다
Codex는 모델이 문맥을 해석해 스킬을 찾기 때문에, AGENTS.md에 opsx:* → openspec-* 매핑 테이블을 추가했다

| 명령            | Codex skill               |
|----------------|---------------------------|
| `opsx:apply`   | `openspec-apply-change`   |
| `opsx:archive` | `openspec-archive-change` |

커스텀 스킬 추가

OpenSpec이 기본 제공하지 않는 스킬을 새로 만들 때는 Claude Code와 Codex 양쪽에 파일을 만들어야 한다. discuss를 추가한 예:

Claude Code: .claude/commands/opsx/discuss.md 작성
Codex: .codex/skills/openspec-discuss/SKILL.md 작성
스킬 본문의 실행 단계는 동일하게 작성
호출 문법만 플랫폼에 맞춤 (/opsx:discuss vs opsx:discuss)
AGENTS.md 매핑 테이블에 opsx:discuss → openspec-discuss 추가

3. 다음에 할 것들

지금까지는 두 도구에서 동일한 워크플로우를 일관되게 실행하는 데 초점을 맞췄다. 하지만 실제로 써보면 각 도구에 더 잘 맞는 역할이 따로 있는 것 같다.

Claude Code: opsx 명령을 통한 대화형 스펙 작성, 탐색, 설계 논의
Codex: 문서 검증, 코드 리뷰 등 — 할 일이 명확하면 깊이 들어가서 전문가처럼 작업하는 경향

도구마다 더 잘 맞는다는 느낌이 드는 방식으로 계속 사용하게 된다. 그렇다면 매번 두 도구의 설정을 하나하나 똑같이 맞추는 대신, 도구별 전문성에 맞게 역할을 나누는 게 더 나을 수 있다.

하지만 그렇게 하려면 "어떤 도구에 어떤 작업을 맡길 때 효과적인가"에 대한 판단 근거가 필요하다. 객관적인 근거 없이 특정 도구의 사용을 제한한다면, 이는 주관적인 기호에 치우친 결정이 될 수 있다.

OpenSpec 워크플로우에서 Codex + skills + 현재 지시 세트와 Claude Code + slash command + 현재 지시 세트 중 어떤 조합이 어떤 작업에 더 효과적인지 궁금하다. 다음에는 이 질문을 어떻게 비교할 수 있을지, 판단 근거를 세울 방법이 있는지부터 찾아보려 한다.