Codex용 AGENTS.md와 Claude용 CLAUDE.md를 분리하여 운영한 메모

Codex와 Claude Code를 동일한 리포지토리(Repository)에서 사용하면, 처음에는 AGENTS.md와 CLAUDE.md에 같은 내용을 쓰고 싶어집니다.

하지만 두 에이전트(Agent)는 읽는 파일명, 특기 작업, 로컬에서 사용하는 hook이나 skill의 위치가 조금 다릅니다. 공통 규칙을 억지로 하나의 파일로 모으면, 한쪽에게만 관계있는 설명까지 매번 읽게 만들게 됩니다.

이 기사에서는 기사 리포지토리에서 AGENTS.md와 CLAUDE.md를 분리하고, 공통 규칙은 .claude/rules/에 모은 운영 방식을 정리합니다.

이렇게 구성했습니다.

.
├── AGENTS.md # Codex용. Codex 측의 hook과 skill도 작성
├── CLAUDE.md # Claude Code용. Claude 측의 설정을 중심으로 작성
...

공통 집필 규칙은 양쪽 루트 파일에서 동일한 파일을 참조합니다.

## 규칙
@.claude/rules/topic-policy.md
@.claude/rules/writing-style.md
...

Codex와 Claude Code에게 동일한 기사 리포지토리를 다루게 하면 다음과 같은 차이가 발생했습니다.

• Codex는 .agents/skills/를 보지만, Claude Code는 .claude/skills/를 본다.
• Codex 측의 hook은 .codex/hooks.json, Claude 측의 hook은 .claude/settings.json이다.
• 리뷰 의뢰 방향이 "Codex 작성이라면 ClaudeCode로", "ClaudeCode 작성이라면 Codex로" 바뀌게 된다.
• 한쪽에만 필요한 로컬 설정을 너무 많이 쓰면, 다른 쪽의 기동 컨텍스트(Context)가 무거워진다.

처음에는 CLAUDE.md를 기준으로 삼아 Codex에게도 읽히면 된다고 생각했습니다. 하지만 Codex 측에는 AGENTS.md와 .agents/skills/라는 문맥(Context)이 있습니다. Claude Code 측의 상세 내용을 그대로 읽히면, 실행할 수 없는 명령어 나 불필요한 디렉토리 설명이 섞이게 됩니다.

분리한 이유는 공통 규칙과 에이전트 고유의 실행 환경을 동일한 입도(Granularity)로 다루지 않기 위해서입니다.

이 리포지토리에서 기사 방침이나 비밀 유지 의무, 공개 전 리뷰는 공통 규칙입니다. 반면 hook이나 skill의 실체는 에이전트마다 다릅니다.

AGENTS.md에서는 Codex 측의 실체를 명시하고 있습니다.

## Hook
`articles/*.md`를 저장하면, 문체 규칙 위반어를 경고하는 PostToolUse hook이 실행된다.
- Codex 측: `.codex/hooks.json` → `.codex/hooks/check-article-style.sh`
...

Codex 측의 hooks.json에서는 Windows 환경에서 hook 스크립트를 안정적으로 호출하기 위해 풀 경로(Full path)를 지정하는 경우가 있습니다. 기사에서는 "어떤 설정 파일이 어떤 스크립트를 호출하는가"를 주제로 하고 있기 때문에, 디렉토리 구성으로서 상대 경로로 나타내고 있습니다.

CLAUDE.md에서는 Claude Code 측의 설정을 중심으로 하며, 최신 인수인계로서 CLAUDE_CODE_HANDOFF.md를 읽도록 하고 있습니다.

## 최신 인수인계
기사 후보와 Codex/ClaudeCode 연계의 최신 메모는 `CLAUDE_CODE_HANDOFF.md`를 참조한다.

양쪽에 완전히 똑같은 문장을 쓰는 것이 아니라, 동일한 목적을 각각의 실행 환경에 맞춰 나누어 쓰는 형태입니다.

이 구성에서는 공통 규칙의 업데이트 누락에 주의해야 합니다.

예를 들어 writing-style.md의 문체 NG어를 업데이트했는데, hook 측의 grep 패턴을 업데이트하지 않으면 저장 시의 검출과 리뷰 시의 검출이 어긋나게 됩니다.

AGENTS.md와 CLAUDE.md를 나누는 것만으로는 규칙의 이중 관리가 줄어들지 않습니다. 공통 규칙의 본체를 별도 파일로 모으고, 루트 파일은 입구와 에이전트 고유의 차이점으로 한정하는 것이 포인트입니다.

또 다른 주의점은 개인 설정을 섞지 않는 것입니다. CLAUDE.local.md와 같은 개인용 파일은 gitignore에 두고, 공개 리포지토리에 올리는 루트 파일에는 로컬 절대 경로 나 개인 정보를 쓰지 않도록 합니다.

Codex와 Claude Code를 동일한 리포지토리(repository)에서 사용할 때는, AGENTS.md와 CLAUDE.md를 억지로 통합하지 않는 것이 관리하기 더 쉬워졌습니다.

• 공통 규칙은 .claude/rules/ 쪽으로 모은다
• 에이전트 고유의 hook / skill / handoff 동선은 진입 파일(entry file)에 나누어 작성한다
• 개인 설정은 공개되는 루트 파일(root file)에 섞지 않는다

동일한 규칙을 지키게 하는 것과, 동일한 파일을 읽게 하는 것은 별개의 문제였습니다.

• harness17/zenn-articles - 본 기사에서 다룬 기사 리포지토리
• AGENTS.md - Codex용 진입 파일
• CLAUDE.md - Claude Code용 진입 파일
• Claude Code의 CLAUDE.md를 @import로 분할하여 토픽별 규칙으로 정리했다 -
  CLAUDE.md 분할 자체의 상세한 운용