# Dual Agent Instruction Sync

> Claude Code와 Codex(GPT) 같은 코딩 에이전트를 두 개 이상 함께 쓸 때, 공용 지침(AGENTS.md)과 스킬을 단일 원본으로 유지하고 심볼릭 링크로 배포·검증할 때 사용한다. 지침을 복제하거나 한쪽 에이전트에만 규칙을 두지 않는다.

- Skill: `rneayan/dual-agent-instruction-sync` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add rneayan/dual-agent-instruction-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rneayan/dual-agent-instruction-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Rneayan (https://skillmd.com/u/rneayan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rneayan/dual-agent-instruction-sync

---


# 에이전트 지침·스킬 동기화 (Claude × Codex)

두 개 이상의 에이전트가 같은 작업 폴더를 만질 때, 문제는 능력이 아니라 **지침이 갈라지는 것**이다. 한쪽 지침만 고치면 두 에이전트가 다르게 행동하고, 그 차이는 결과물이 어긋난 뒤에야 드러난다. 이 스킬은 지침과 스킬을 하나의 원본으로 묶고, 변경할 때마다 기계적으로 검증하는 절차다.

## 언제 쓰나

- 같은 저장소·볼트를 Claude Code와 Codex(또는 다른 SKILL.md 호환 에이전트)로 번갈아 작업할 때
- 규칙을 바꿨는데 한쪽 에이전트만 새 규칙을 따를 때
- 스킬이 여러 폴더에 복사돼 어느 것이 원본인지 모를 때
- 새 에이전트를 환경에 추가할 때

## 네 가지 원칙

1. **지침은 단일 원본.** 작업 폴더 루트의 `AGENTS.md` 하나만 규칙 본문을 갖는다. `CLAUDE.md`는 `@AGENTS.md` 한 줄만 둔다. 두 파일에 같은 규칙을 복제하지 않는다.
2. **스킬은 3계층으로 나눈다.** 공용 / 에이전트 A 전용 / 에이전트 B 전용. 어느 계층인지 모르는 스킬은 만들지 않는다.
3. **배포는 복사가 아니라 링크.** 공용 스킬은 한 곳에 두고 각 에이전트의 스킬 디렉터리에 심볼릭 링크한다. 복사본은 반드시 드리프트한다.
4. **변경 뒤에는 검증한다.** 링크 상태, 링크를 통한 `SKILL.md` 읽기, 지침 로딩까지 스크립트로 확인한다. "고쳤으니 됐다"로 끝내지 않는다.

## 구조

```text
<작업 폴더 루트>/
  AGENTS.md            # 공용 지침의 유일한 원본
  CLAUDE.md            # "@AGENTS.md" 한 줄
  agent-sync.zsh       # 링크 생성·점검 스크립트

~/.agents/skills/      # 공용 스킬 원본 (또는 저장소를 가리키는 디렉터리 링크)
~/.claude/skills/      # 공용 스킬로 가는 심볼릭 링크 + 해당 에이전트 전용 스킬
~/.codex/skills/       # 공용 스킬로 가는 심볼릭 링크 + 해당 에이전트 전용 스킬
```

공용 스킬을 GitHub 저장소로 관리한다면 `~/.agents/skills/<name>` 을 저장소 안 스킬 폴더로 가는 **디렉터리 링크**로 두는 편이 낫다. 저장소가 원본이고 `~/.agents`는 경유지가 된다. 대신 저장소 위치를 옮기면 링크가 한꺼번에 끊기므로, 옮긴 직후 반드시 `--apply`를 다시 돌린다.

## 스킬 계층 판단

| 질문 | 결과 |
|------|------|
| 두 에이전트가 모두 이 동작을 해야 하나? | 공용 — `~/.agents/skills` 에 두고 링크 |
| 특정 에이전트의 관리 화면·전용 도구에 묶여 있나? | 그 에이전트 전용 |
| 그 에이전트에만 있는 실행 환경이 필요한가? | 그 에이전트 전용 |

공용 스킬 본문은 **호스트 중립**으로 쓴다. "Codex에서는", "Claude Code에서는" 같은 표현과 특정 호스트 전용 경로를 넣지 않는다.

> **핵심 규칙:** 두 에이전트가 공유해야 하는 동작은 `AGENTS.md` 또는 작업 폴더의 규칙 파일에 있어야 한다. 한쪽 에이전트만 가진 스킬이 그 규칙의 **유일한** 보관처가 되면 안 된다. 스킬은 규칙을 구현할 수 있을 뿐, 규칙을 소유하지 않는다.

## 작업 흐름

### 지침을 바꿀 때
1. `AGENTS.md`만 수정한다. `CLAUDE.md`는 건드리지 않는다.
2. 규칙이 두 에이전트 모두에게 적용되는지, 한쪽 환경에서만 가능한 동작을 요구하지 않는지 확인한다.
3. 루트에서 `./agent-sync.zsh --verify`.
4. 각 에이전트의 **새 세션**에 검증 마커를 물어 지침이 실제로 로드됐는지 확인한다.

### 공용 스킬을 추가·수정할 때
1. 원본 위치(`~/.agents/skills` 또는 그것이 가리키는 저장소)에서만 수정한다.
2. `./agent-sync.zsh --apply` → `--verify`.
3. 각 에이전트에서 스킬이 실제로 목록에 뜨는지 확인한다.

### 새 에이전트를 추가할 때
1. 스크립트의 에이전트 표에 `<이름> <스킬 디렉터리 경로>` 한 줄을 추가한다.
2. `--apply`로 링크를 만들고 `--verify`로 읽기까지 확인한다.
3. 그 에이전트가 `AGENTS.md`를 어떻게 로드하는지(자동인지, 별도 파일이 필요한지) 확인해 `AGENTS.md`에 적어 둔다.

## 검증 마커

`AGENTS.md` 안에 고정 문자열을 한 줄 심어 둔다.

```markdown
- Agent sync verification marker: `{{SYNC_MARKER}}`
```

새 세션에 "세션 시작 시 로드된 지침에서 검증 마커 값만 답해라"라고 물어 값이 그대로 돌아오면 지침이 로드된 것이다. 값이 다르거나 모른다고 하면 그 에이전트는 지침을 못 읽고 있다. 마커 값은 환경마다 다르게 정하고, 이 문서의 `{{SYNC_MARKER}}` 자리에 본인 값을 넣는다.

## 동봉 스크립트

```bash
./agent-sync.zsh --check    # 상태만 점검, 아무것도 바꾸지 않음
./agent-sync.zsh --apply    # 누락되거나 어긋난 링크를 만들거나 고침
./agent-sync.zsh --verify   # --check + 링크를 통한 SKILL.md 읽기 + 지침 로딩 확인
```

- `--apply`는 잘못된 링크는 교체하지만 **실제 파일·폴더는 절대 삭제하지 않는다.** 스킬 이름 자리에 실제 폴더가 있으면 FAIL로 남기고 사람이 처리한다.
- 원본이 사라진 끊어진 링크는 조용히 넘어가지 않고 FAIL로 잡는다.
- 스크립트: [scripts/agent-sync.zsh](scripts/agent-sync.zsh)

## 두 에이전트가 같은 파일을 만질 때

동시 편집은 조용히 덮어쓴다. 작업 폴더에 인수인계 노트 하나를 두고 다음을 지킨다.

- 다른 에이전트가 시작한 작업을 이어받기 전에 인수인계 노트를 먼저 읽는다.
- 상대가 바꾼 파일은 손대기 전에 diff부터 본다.
- 의미 있는 작업 뒤에는 에이전트 이름, 날짜, 상태, 변경 파일, 결과, 다음 행동을 기록한다.
- 그 작업이 **어느 계층의 스킬에 의존했는지** 적는다. 한쪽 전용 스킬이었다면 상대는 규칙만 보고 재현해야 하므로 그 사실을 명시한다.
- 인수인계 노트에 비밀번호·API 키·토큰·불필요한 개인정보를 적지 않는다.

템플릿은 [references/templates.md](references/templates.md)에 있다.

## 흔히 발목 잡는 것들

에이전트마다 지침 파일을 읽는 범위가 다르고, 샌드박스마다 접근 가능한 경로가 다르다. 링크가 멀쩡한데 검증만 실패하는 경우도 있다. 작업 전에 [references/constraints.md](references/constraints.md)를 먼저 읽는다.

## 하지 않는 것

- 지침 본문을 두 파일 이상에 복제하지 않는다.
- 공용 스킬을 각 에이전트 폴더에 복사하지 않는다.
- 스킬 이름 자리를 차지한 실제 폴더를 자동으로 지우지 않는다.
- 개인 경로, 계정 ID, 마커 실제 값, 자격 증명을 공개 저장소의 스킬 본문에 넣지 않는다.