context-sync

코드베이스의 실제 상태와 컨텍스트 문서를 대조해 낡은 내용을 찾아내고 수정한다.

컨텍스트 문서 = 코드를 바꾸기 전에 읽는 것들: AGENTS.md(루트·패키지), INDEX.md, contributing/(커밋된 결정 기록), .work/(로컬 작업 로그). docs/는 여기 해당하지 않는다 — VitePress 사용자 문서는 /write-docs가 담당한다. 이름이 doc-sync였을 때 두 스킬이 같은 단어를 쓰면서 서로 겹치지 않는 대상을 가리켰고, 그중 진짜 docs/는 한쪽뿐이었다.

절차

1. 인벤토리 수집

아래 파일들을 모두 읽는다:

• 루트 AGENTS.md
• packages/*/AGENTS.md (각 패키지)
• INDEX.md (존재하는 경우)
• contributing/*.md — 커밋된 결정 기록. .work/의 공개 짝이고 같은 부패 위험을 진다.
• .work/*.md (archive 제외, 진행 중인 파일만)

2. 코드 현황 파악

문서와 대조할 실제 상태를 확인한다:

• packages/*/package.json — 현재 의존성 목록
• packages/relay/src/types.ts — 현재 메시지 타입 정의
• packages/dashboard/lib/types.ts — 현재 프론트엔드 타입 정의
• packages/agent-core/src/ — 현재 인터페이스 정의
• ls packages/*/src/ — 실제로 존재하는 소스 파일 목록
• git log --oneline -20 — 최근 변경 흐름 파악

3. 감사 (Audit)

각 문서에 대해 아래 항목을 체크한다:

존재 정합성

• 문서가 언급하는 파일·모듈이 실제로 존재하는가? (삭제된 파일 참조)
• 커밋되는 문서가 gitignore된 .work/ 안의 파일을 링크하지 않는가? 기여자에게는 없는 경로라 링크가 끊긴 채로만 보인다. 디렉터리·규약 언급(.work/reviews/<branch>.md)은 해당 없고, 특정 파일을 가리키는 링크만 대상이다. 남길 값어치가 있으면 링크가 아니라 승격(/promote-decision)이다.
• 문서가 언급하는 패키지·의존성이 package.json에 있는가?
• 문서가 언급하는 메시지 타입이 relay/types.ts에 있는가?

내용 최신성

• HOW/HOW NOT 규칙이 현재 코드 구조와 맞는가?
• Compound 섹션의 코드 스니펫이 현재 인터페이스와 일치하는가?
• Phase·로드맵 관련 표현이 현재 진행 상황을 반영하는가?

패키지 간 정합성

• 동일 개념이 여러 AGENTS.md에 다르게 설명되어 있지 않은가?
• 한 패키지의 HOW가 다른 패키지의 HOW NOT과 충돌하지 않는가?
• relay/types.ts와 dashboard/lib/types.ts의 타입이 문서 설명과 일치하는가?

contributing/ 정합성

• 새 기록이 contributing/README.md 표와 루트 INDEX.md 양쪽에 등재돼 있는가? (scripts/__tests__/contributingIndexed.test.mjs가 강제하므로 보통은 여기서 걸리지 않는다.)
• 표의 그룹 배치가 문서 내용과 맞는가 — 새 기록이 "일단 아무 그룹"에 들어가 있지 않은가?

.work 상태 확인

• status: done인데 archive로 이동하지 않은 파일이 있는가?
• status: in-progress인 파일의 체크리스트가 코드 현황과 맞는가?

4. 수정

발견된 문제를 심각도 순으로 수정한다:

즉시 수정: 존재하지 않는 파일·모듈·타입 참조, 삭제된 패키지 언급 내용 갱신: 낡은 패턴 설명, 변경된 인터페이스와 맞지 않는 스니펫 표현 조율: 패키지 간 동일 개념의 불일치 표현 건너뜀: 미래 계획·로드맵 표현 (의도적으로 미래를 가리킬 수 있음)