dual-agent-instruction-synclisted

# 에이전트 지침·스킬 동기화 (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에서는" 같은 표현과