Rneayan 에이전트 지침·스킬 동기화 (Claude × Codex)
두 개 이상의 에이전트가 같은 작업 폴더를 만질 때, 문제는 능력이 아니라 지침이 갈라지는 것이다. 한쪽 지침만 고치면 두 에이전트가 다르게 행동하고, 그 차이는 결과물이 어긋난 뒤에야 드러난다. 이 스킬은 지침과 스킬을 하나의 원본으로 묶고, 변경할 때마다 기계적으로 검증하는 절차다.
언제 쓰나
- 같은 저장소·볼트를 Claude Code와 Codex(또는 다른 SKILL.md 호환 에이전트)로 번갈아 작업할 때
- 규칙을 바꿨는데 한쪽 에이전트만 새 규칙을 따를 때
- 스킬이 여러 폴더에 복사돼 어느 것이 원본인지 모를 때
- 새 에이전트를 환경에 추가할 때
네 가지 원칙
- 지침은 단일 원본. 작업 폴더 루트의
AGENTS.md하나만 규칙 본문을 갖는다.CLAUDE.md는@AGENTS.md한 줄만 둔다. 두 파일에 같은 규칙을 복제하지 않는다. - 스킬은 3계층으로 나눈다. 공용 / 에이전트 A 전용 / 에이전트 B 전용. 어느 계층인지 모르는 스킬은 만들지 않는다.
- 배포는 복사가 아니라 링크. 공용 스킬은 한 곳에 두고 각 에이전트의 스킬 디렉터리에 심볼릭 링크한다. 복사본은 반드시 드리프트한다.
- 변경 뒤에는 검증한다. 링크 상태, 링크를 통한
SKILL.md읽기, 지침 로딩까지 스크립트로 확인한다. "고쳤으니 됐다"로 끝내지 않는다.
구조
<작업 폴더 루트>/
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또는 작업 폴더의 규칙 파일에 있어야 한다. 한쪽 에이전트만 가진 스킬이 그 규칙의 유일한 보관처가 되면 안 된다. 스킬은 규칙을 구현할 수 있을 뿐, 규칙을 소유하지 않는다.
작업 흐름
지침을 바꿀 때
AGENTS.md만 수정한다.CLAUDE.md는 건드리지 않는다.- 규칙이 두 에이전트 모두에게 적용되는지, 한쪽 환경에서만 가능한 동작을 요구하지 않는지 확인한다.
- 루트에서
./agent-sync.zsh --verify. - 각 에이전트의 새 세션에 검증 마커를 물어 지침이 실제로 로드됐는지 확인한다.
공용 스킬을 추가·수정할 때
- 원본 위치(
~/.agents/skills또는 그것이 가리키는 저장소)에서만 수정한다. ./agent-sync.zsh --apply→--verify.- 각 에이전트에서 스킬이 실제로 목록에 뜨는지 확인한다.
새 에이전트를 추가할 때
- 스크립트의 에이전트 표에
<이름> <스킬 디렉터리 경로>한 줄을 추가한다. --apply로 링크를 만들고--verify로 읽기까지 확인한다.- 그 에이전트가
AGENTS.md를 어떻게 로드하는지(자동인지, 별도 파일이 필요한지) 확인해AGENTS.md에 적어 둔다.
검증 마커
AGENTS.md 안에 고정 문자열을 한 줄 심어 둔다.
- Agent sync verification marker: `{{SYNC_MARKER}}`
새 세션에 "세션 시작 시 로드된 지침에서 검증 마커 값만 답해라"라고 물어 값이 그대로 돌아오면 지침이 로드된 것이다. 값이 다르거나 모른다고 하면 그 에이전트는 지침을 못 읽고 있다. 마커 값은 환경마다 다르게 정하고, 이 문서의 {{SYNC_MARKER}} 자리에 본인 값을 넣는다.
동봉 스크립트
./agent-sync.zsh --check # 상태만 점검, 아무것도 바꾸지 않음
./agent-sync.zsh --apply # 누락되거나 어긋난 링크를 만들거나 고침
./agent-sync.zsh --verify # --check + 링크를 통한 SKILL.md 읽기 + 지침 로딩 확인
--apply는 잘못된 링크는 교체하지만 실제 파일·폴더는 절대 삭제하지 않는다. 스킬 이름 자리에 실제 폴더가 있으면 FAIL로 남기고 사람이 처리한다.- 원본이 사라진 끊어진 링크는 조용히 넘어가지 않고 FAIL로 잡는다.
- 스크립트: scripts/agent-sync.zsh
두 에이전트가 같은 파일을 만질 때
동시 편집은 조용히 덮어쓴다. 작업 폴더에 인수인계 노트 하나를 두고 다음을 지킨다.
- 다른 에이전트가 시작한 작업을 이어받기 전에 인수인계 노트를 먼저 읽는다.
- 상대가 바꾼 파일은 손대기 전에 diff부터 본다.
- 의미 있는 작업 뒤에는 에이전트 이름, 날짜, 상태, 변경 파일, 결과, 다음 행동을 기록한다.
- 그 작업이 어느 계층의 스킬에 의존했는지 적는다. 한쪽 전용 스킬이었다면 상대는 규칙만 보고 재현해야 하므로 그 사실을 명시한다.
- 인수인계 노트에 비밀번호·API 키·토큰·불필요한 개인정보를 적지 않는다.
템플릿은 references/templates.md에 있다.
흔히 발목 잡는 것들
에이전트마다 지침 파일을 읽는 범위가 다르고, 샌드박스마다 접근 가능한 경로가 다르다. 링크가 멀쩡한데 검증만 실패하는 경우도 있다. 작업 전에 references/constraints.md를 먼저 읽는다.
하지 않는 것
- 지침 본문을 두 파일 이상에 복제하지 않는다.
- 공용 스킬을 각 에이전트 폴더에 복사하지 않는다.
- 스킬 이름 자리를 차지한 실제 폴더를 자동으로 지우지 않는다.
- 개인 경로, 계정 ID, 마커 실제 값, 자격 증명을 공개 저장소의 스킬 본문에 넣지 않는다.