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

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

언제 쓰나

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

네 가지 원칙

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

구조

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

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

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

스킬 계층 판단

공용 스킬 본문은 호스트 중립으로 쓴다. "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 안에 고정 문자열을 한 줄 심어 둔다.

- 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 키·토큰·불필요한 개인정보를 적지 않는다.
• 기록 제목은 ### YYYY-MM-DD [HH:mm] — 작업 제목 (에이전트) 형식으로 쓰고, 날짜는 실제로 작업한 날(사용자 시간대) 로 적는다. 이렇게 두면 인수인계 노트가 그대로 "그날 AI와 한 일" 기록이 되어 일지 자동화(obsidian-journal)가 가져갈 수 있다.
• 짧은 대화라도 파일을 만들었거나 결정이 난 작업은 한 줄 기록을 남긴다. 기록이 없으면 그 일은 나중에 없었던 일이 된다.

템플릿은 references/templates.md에 있다.

흔히 발목 잡는 것들

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

하지 않는 것

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