agent-docs-sync

agent-docs-sync — 멀티 에이전트 호환 지침·스킬 동기화

⚠ 실행 전 필수 게이트 — 정본 방향 확정 (건너뛰면 정본 파괴)

이 스킬의 단 하나의 전제: `CLAUDE.md` + `.claude/skills/`가 정본(canonical)이고, `AGENTS.md` + `.agents/skills/`는 생성물(derived)이다. 이 방향이 거짓인 환경에서 실행하면, 동기화가 진짜 정본을 "고아"로 판단해 삭제한다. 워크플로우의 어떤 단계보다 먼저 아래 게이트를 통과해야 한다.

위반의 글자 = 위반의 정신. "이 정도면 정본이 맞겠지"라는 추정으로 게이트를 건너뛰는 것은 게이트를 어기는 것이다. 방향은 추정하지 말고 아래 명령으로 매번 확정한다.

게이트 1 — 스킬 방향 (가장 위험: 데이터 손실)

find <루트>/.claude/skills -maxdepth 1 -type l    # symlink 스킬 목록 (있으면 의심)

• •.claude/skills/의 항목 다수가 symlink이고 그 대상이 .agents/skills/(또는 외부 경로)이면 → 정본 방향이 역전된 환경이다. .agents/skills/가 실제 정본이고 .claude/skills/는 그쪽으로 거는 미러다.
• •이 경우 스킬 미러링을 절대 실행하지 마라. 이유: iter_source_skill_files()의 os.walk(followlinks=False)가 symlink 스킬 내부를 누락 → 스크립트가 "정본엔 스킬이 거의 없다"고 오인 → 고아 정리(sync_skills)가 .agents/skills/의 실제 스킬 파일을 전부 삭제한다.
• •판정: 역전 감지 시 미러링 단계를 건너뛰고 사용자에게 보고한다. 애초에 불필요하기도 하다 — Codex·Antigravity는 이미 .agents/skills/를 직접 읽으므로, 정본이 그 표준 위치에 있으면 만들 생성물이 없다.

게이트 2 — 문서 방향 (symlink-trap)

find <루트> -name AGENTS.md -type l               # AGENTS.md가 CLAUDE.md를 가리키는 symlink면 정본 오염

• •AGENTS.md가 CLAUDE.md를 가리키는 symlink(또는 반대 방향)이면 쓰기가 링크를 따라가 정본을 덮어쓴다(최신 스크립트는 write_text 진입부 가드로 자동 치유하지만, 구버전 사본은 위험).
• •목적지 실효성도 확인: 사용자 글로벌 지침을 다른 에이전트에 노출하려면 보통 ~/.codex/AGENTS.md나 홈 ~/AGENTS.md가 목적지다. ~/.claude/AGENTS.md는 다른 에이전트가 자동으로 읽지 않는다.

Red Flags — STOP, 정본 방향부터 확인

• •.claude/skills/ 안에 ->(symlink)가 보인다
• •--check가 removed N (예정)으로 대량 삭제를 예고한다 (정상 동기화는 [갱신]/[최신] 위주)
• •동기화 대상이 프로젝트 워크스페이스가 아니라 ~/.claude 같은 에이전트 홈이다 (정본·플러그인 캐시·외부 symlink가 한 트리에 섞임)
• •"내가 만든 스킬이니 환경은 내가 안다"

위 신호 중 하나라도 있으면 미러링을 멈추고 방향을 실측 확인하라.

실측 근거 (이 게이트가 생긴 이유)

2026-06-05, 작성자 본인의 환경(~/.claude)에서 스킬 48개 중 45개가 `.agents/skills/`로의 symlink였다(k-skill-setup이 agentskills.io 표준 위치에 실파일을 두고 .claude/skills/에서 역방향 링크). 게이트가 없던 탓에 에이전트가 미러링 실행 직전까지 갔고, 수동 진단으로만 "고아 정리가 실제 스킬 45개를 삭제"하는 결과를 사전에 막았다. 스킬을 만든 사람조차 자기 환경을 오인했다 — 그래서 추정이 아니라 위 명령으로 확정한다.

무엇을 하는가

Claude Code는 CLAUDE.md와 .claude/skills/를 읽지만, Codex·Antigravity·Gemini CLI 같은 다른 코딩 에이전트는 각자 다른 위치를 본다. 이 스킬은 하나의 정본(`CLAUDE.md` + `.claude/skills/`)에서 다른 에이전트가 네이티브로 인식하는 생성물을 만들어, 같은 작업 공간을 여러 에이전트가 동일한 컨텍스트로 공유하게 한다.

핵심 기제는 검증된 단방향 동기화 스크립트 scripts/sync_agent_docs.py다. 정본 → 생성물 한 방향으로만 흐르며, 생성물은 "빌드 산출물"로 취급한다.

왜 하위 폴더까지? Codex·Antigravity는 작업 디렉터리에서 위로 올라가며 AGENTS.md를 계층 병합한다. 하위 폴더에 CLAUDE.md만 있고 AGENTS.md가 없으면, 그 폴더에서 작업하는 에이전트는 루트 AGENTS.md만 보고 하위 scoped 지침을 놓친다. 그래서 모든 CLAUDE.md 옆에 형제 AGENTS.md를 둔다.

왜 GEMINI.md는 안 만드나? Antigravity·Gemini CLI 계열도 AGENTS.md를 읽는다. 굳이 세 번째 파일을 늘리지 않는다(필요하면 스크립트의 동기화 쌍에 한 줄 추가 가능).

빠른 사용 (이미 셋업된 프로젝트)

정본을 수정한 뒤 생성물을 다시 만들 때:

cd <프로젝트 루트>
python sync_agent_docs.py            # 동기화 (발산한 AGENTS.md만 건너뛰고 나머지는 모두 반영)
python sync_agent_docs.py --check    # 드라이런: 무엇이 바뀔지만 출력
python sync_agent_docs.py --force    # 발산 경고를 무시하고 발산 파일도 정본 기준으로 덮어쓰기

종료 코드: 0 전부 최신/반영(발산·검증 경고 없음) · 2 발산 파일을 건너뛰었거나 스킬 frontmatter 검증 경고가 있음(나머지는 정상 동기화 — 확인 필요, 실패 아님) · 1 기타 오류.

발산이 떠도 내 변경은 반영된다. 한 폴더의 AGENTS.md가 발산해도 실행 전체가 멈추지 않는다. 스크립트는 발산한 그 파일 하나만 건너뛰고(경고 출력) 나머지 모든 CLAUDE.md→AGENTS.md와 스킬을 정상 동기화한 뒤, 마지막에 [요약] 한 줄로 건너뛴 파일을 모아 보여주고 종료 코드 2를 낸다. 즉 무관한 다른 폴더의 묵은 발산 때문에 방금 고친 `CLAUDE.md`의 미러링이 막히는 일은 없다. --force 없이 그냥 실행하면 된다(--force는 그 발산 파일까지 정본으로 덮고 싶을 때만).

스크립트는 자기 위치(Path(__file__).parent)를 프로젝트 루트로 삼으므로, 루트에 둔 사본을 그 자리에서 실행하면 된다.

신규 프로젝트 셋업 워크플로우

처음 적용하는 프로젝트라면 아래 순서로 진행한다. 1회성 셋업이며, 기존 내용을 덮어쓰지 않도록 가드를 지킨다.

1. 전제 확인

• •프로젝트 루트에 CLAUDE.md가 있는가? 없으면 사용자에게 먼저 /init 등으로 만들 것을 안내한다(이 스킬은 빈 프로젝트를 채우지 않는다).
• •.claude/skills/가 있는가? 없어도 된다(있으면 스킬도 미러링, 없으면 문서만 동기화).
• •단일 프로젝트인가, 컨테이너인가? 루트가 하나의 프로젝트가 아니라 여러 독립 저장소·별개 프로젝트를 담은 컨테이너일 수 있다(CLAUDE.md가 루트 외 여러 하위에 흩어져 있고 하위마다 자체 .git이 있으면 컨테이너 신호). 컨테이너라면 셋업 전에 적용 범위를 사용자에게 확인한다(전체 일괄 vs 특정 하위만). 전체로 가면 하위 저장소마다 AGENTS.md가 생기고, 그 저장소가 Public이면 커밋·푸시 시 공개된다: 사용자에게 알리고, 특정 repo에서 빼려면 그 repo .gitignore에 AGENTS.md를 넣는 선택지를 제시한다.
• •ROOT 밖을 가리키는 junction/심링크 점검: 있으면 스크립트가 따라가 프로젝트 밖에도 AGENTS.md를 쓴다(실행 시 [외부] 경고로 표시됨). 아래 "junction·심링크 주의" 참조.

2. CLAUDE.md 상단에 에이전트 중립 호환 블록 삽입

루트 CLAUDE.md 맨 위(H1 제목 바로 아래)에 호환 안내 블록을 넣는다. 템플릿과 채우는 법은 references/templates.md의 "① 에이전트 중립 호환 블록" 참조. 이미 비슷한 블록이 있으면 새로 넣지 말고 사용자에게 알린다.

이 블록은 프로젝트마다 미세하게 다르다(서브에이전트·MCP 구성). 폴더명·CLAUDE.md 본문·.claude/agents/·.mcp.json을 읽어 해당 프로젝트에 맞게 채운다.

3. CLAUDE.md에 동기화 규칙 한 줄 추가

스킬 섹션(또는 적절한 위치) 앞에 "정본을 수정하면 python sync_agent_docs.py를 실행해 생성물을 재생성한다"는 규칙을 넣는다. 템플릿은 references/templates.md의 "② 동기화 규칙" 참조.

4. 스킬 색인(스킬_요약.md) 생성 — .claude/skills/가 있을 때만

.claude/skills/를 스캔해 각 스킬의 SKILL.md 프런트매터(name·description)와 .claude/agents/·.mcp.json을 읽어, 가시성 높은 루트에 스킬_요약.md(또는 SKILLS.md) 색인을 만든다. 구조는 references/templates.md의 "③ 스킬 색인" 참조. 이 파일은 .claude/ 밖에 두어 어떤 에이전트든 쉽게 발견하게 한다.

5. 스크립트를 루트에 복사하고 실행

cp "<이 스킬 경로>/scripts/sync_agent_docs.py" "<프로젝트 루트>/sync_agent_docs.py"
cd "<프로젝트 루트>"
python sync_agent_docs.py --check    # 먼저 미리보기
python sync_agent_docs.py            # 실제 실행

스크립트를 루트에 두는 이유: 사용자가 이후 정본을 고칠 때마다 Claude 없이도 python sync_agent_docs.py 한 줄로 직접 재생성할 수 있게 하기 위함이다(스킬은 셋업·개선 시에만 필요).

6. 검증

python sync_agent_docs.py --check    # 재실행 시 모두 "[최신]"이어야 멱등성 OK

• •1차 검증은 멱등성: --check 재실행에서 모두 [최신]이면 본문이 형제 CLAUDE.md와 일치한다는 가장 강한 증거다. 개수 대조(find 등)는 보조로만 쓴다: junction/심링크가 있으면 도구마다(find vs 스크립트의 os.walk) 카운트가 어긋날 수 있으므로, 불일치가 보이면 멱등성 결과를 신뢰하고 junction 여부부터 확인한다.
• •각 AGENTS.md 상단에 자동생성 배너 + <!-- SYNC-BODY-START --> 마커가 있고, 본문이 형제 CLAUDE.md와 일치하는지 확인.

junction·심링크 주의 (ROOT 밖 외부 쓰기)

스크립트의 os.walk는 하위 폴더가 junction/심링크여도 따라간다. 그 link가 ROOT(프로젝트 루트) 밖(다른 드라이브·Google Drive 동기화 폴더 등)을 가리키면, 그 안의 CLAUDE.md를 정본으로 보고 프로젝트 트리 밖에 `AGENTS.md`를 생성/갱신한다(특히 Windows junction에서 흔함).

이를 막지는 않는다(외부 폴더를 일부러 link 해 함께 동기화하려는 경우가 있으므로). 대신 가시화한다: 실행 시 해당 경로에 [외부] … 는 junction/symlink 로 ROOT 밖을 가리킵니다 → <실제 경로> 경고를 출력한다(종료 코드는 바꾸지 않으므로 매번 동기화해도 노이즈가 되지 않는다). 이 경고가 보이면 판단한다:

• •의도한 동기화면 그대로 둔다.
• •그 link 너머가 자체 `sync_agent_docs.py`를 갖는 별도 프로젝트면, 두 동기화가 같은 파일을 건드려 충돌·중복이 난다 → 그 폴더명을 스크립트의 DOC_EXCLUDE_DIRS에 추가하거나 link를 정리해 제외한다.

신규 셋업인데 외부 junction 너머에 이미 동형 AGENTS.md가 있으면 [생성]이 아니라 [갱신]으로 나온다(그 폴더도 과거 동기화 흔적). 발산으로 오인하지 말 것.

발산(divergence) 처리

AGENTS.md가 직전 동기화 이후 손으로 수정됐거나 관리 밖에서 만들어졌으면, 스크립트는 본문 해시로 감지해 경고하고 그 파일만 건너뛴다(mtime은 Google Drive에서 못 믿으므로 쓰지 않는다). 흔한 사례: 과거 다른 에이전트(Codex 등)가 그 폴더에서 AGENTS.md를 따로 만들어 둔 경우.

판단 기준:

• •`CLAUDE.md`가 최신·정본이 맞다 → --force로 정본 기준 덮어쓴다.
• •`AGENTS.md` 쪽에 살릴 내용이 있다 → 먼저 그 내용을 CLAUDE.md로 옮긴 뒤 일반 실행한다(--force 없이).

--force는 발산 경고만 무시할 뿐, 보호 대상(자격증명·_GENERATED.md)은 건드리지 않는다.

스킬 frontmatter 검증 (validate_skills)

미러링과 별개로, 스크립트는 정본 각 .claude/skills/<스킬>/SKILL.md의 frontmatter가 Codex·Antigravity가 쓰는 엄격한 `agentskills.io` YAML 파서에서 깨지지 않는지 매 실행마다 점검한다. 동기화 자체는 차단하지 않고, 문제가 있으면 stderr에 [스킬 검증 경고]를 띄운 뒤 종료 코드 2(확인 필요)를 낸다.

왜 필요한가. Claude Code의 frontmatter 파서는 관대해서 약간 깨진 YAML도 그냥 로드한다. 그래서 정본만 보면 멀쩡해 보이지만, 같은 파일을 미러링한 .agents/skills/를 Codex가 읽을 때만 조용히 스킬이 누락되거나 warning이 난다. 이 검증은 그 "한쪽에서만 깨지는" 상황을 정본 단계에서 미리 잡는다.

무엇을 잡나 (PyYAML이 있으면 정식 파싱, 없으면 휴리스틱 폴백 — 어느 쪽이든 아래는 잡는다):

• •frontmatter(--- 블록) 부재 또는 닫는 --- 누락
• •YAML 파싱 실패 — 가장 흔한 함정은 description이 plain scalar인데 값 안에 … 사용: 키워드처럼 `: `(콜론+공백)이 있는 경우. 엄격한 파서는 이를 중첩 매핑으로 오인해 mapping values are not allowed here로 실패한다.
• •name이 폴더명과 불일치 (표준은 일치 요구)
• •description 비어 있음 또는 1024자 초과

해법(=작성 규칙). description에 콜론·따옴표 등이 들어갈 수 있으므로 항상 block scalar(`>-`)로 감싼다:

---
name: 내-스킬            # 폴더명과 정확히 일치
description: >-
  한 줄 요약. 다음 키워드가 포함된 요청에 사용: A, B, C.   # 콜론이 있어도 block scalar라 안전
---

한글 `name`은 의도적으로 허용한다. 표준은 name을 lowercase ASCII + 폴더명 일치로 권장하지만, 한글 호출명(/스킬)을 유지하는 프로젝트에서는 한글 폴더명=한글 name으로 두고, Antigravity는 name 미준수 시 폴더명으로 폴백한다. 그래서 검증은 한글 여부를 문제로 보지 않고, 실제로 깨지는 것(파싱 실패·frontmatter 부재·name↔폴더명 불일치)만 잡는다. 영문 slug로 컴파일하는 방식도 가능하나, 정본↔생성물 폴더명 불일치·매핑 유지보수 비용 때문에 기본값은 단순 미러링이다.

보안: 무엇이 동기화되지 않는가

스킬 미러링은 자격증명·캐시·OS 잡파일을 의도적으로 제외한다(노출면·회전 부담 2배 방지): credentials/·accounts.json·*token*.json·client_secret*.json·*.key·*.pem·__pycache__ 등. 따라서 .agents/skills/에는 비밀이 새지 않는다.

주의: CLAUDE.md 본문에 API 키 같은 비밀을 인라인으로 적으면, 전문 복제물인 AGENTS.md에도 그대로 들어간다. 키는 별도 설정 파일/환경변수로 분리하는 것을 권한다.

스크립트 동작 원리 (요약)

• •ROOT = Path(__file__).resolve().parent — 스크립트 위치가 곧 프로젝트 루트. 복사만 하면 어디서든 동작.
• •문서 동기화: CLAUDE.md 본문에 배너를 붙여 AGENTS.md 생성. 본문 일치/직전 정본 해시로 최신·발산 판정.
• •하위 폴더 walk 시 DOC_EXCLUDE_DIRS(.claude·.agents·.git·__pycache__·node_modules·.venv·.idea)는 가지치기. junction/심링크가 ROOT 밖을 가리키면 따라가되 [외부] 경고(위 "junction·심링크 주의").
• •고아 정리: 대응 CLAUDE.md가 사라지고 배너 마커를 가진(=우리가 만든) AGENTS.md만 안전 삭제. 수동 파일은 보존.
• •상태는 .agent-docs-sync.json에 정본 본문 해시로 저장. 루트 상태키는 "AGENTS.md", 하위는 POSIX 상대경로.
• •스킬 검증(validate_skills)은 미러링과 독립적으로 매 실행 정본 SKILL.md frontmatter를 점검한다(위 "스킬 frontmatter 검증" 참조).

세부 구현은 scripts/sync_agent_docs.py의 docstring과 주석 참조.