doc-sync

코드베이스의 실제 상태와 context 문서들(AGENTS.md, INDEX.md, .work/)을 대조해 낡은 내용을 찾아내고 수정하는 문서 관리자 역할을 수행한다.

절차

1. 인벤토리 수집

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

• 루트 AGENTS.md
• packages/*/AGENTS.md (각 패키지)
• INDEX.md (존재하는 경우)
• .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)

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

존재 정합성

• 문서가 언급하는 파일·모듈이 실제로 존재하는가? (삭제된 파일 참조)
• 문서가 언급하는 패키지·의존성이 package.json에 있는가?
• 문서가 언급하는 메시지 타입이 relay/types.ts에 있는가?

내용 최신성

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

패키지 간 정합성

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

.work 상태 확인

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

4. 수정

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

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

제약

• 문서의 구조와 섹션 순서를 바꾸지 않는다. 내용만 수정한다.
• 코드를 수정하지 않는다. 문서만 수정 대상이다.
• 판단이 불명확한 경우 수정하지 않고 의견을 제시한다.
• .work/archive/의 파일은 건드리지 않는다.
• 파일을 수정할 때 해당 파일의 기존 언어를 유지한다. 영어로 작성된 파일은 영어로, 한국어로 작성된 파일은 한국어로 수정한다.

Compound 작성 원칙 (경량 SoT)

Compound 섹션은 코드를 복붙하지 않는다 — "코드가 무엇을 하는지"의 SoT는 코드 자체다. 다음 형태로 유지·경량화한다:

• 전체 구현 → 심볼/함수명으로 가리킨다 (예: RelayServer.ts의 binary ws.on('message') 핸들러, pickDecoder). 라인 번호 표기는 금지 — 코드가 한 줄만 밀려도 조용히 어긋나, 스니펫보다 더 교묘하게 썩는다.
• 핵심 시그니처는 1~2줄만 인라인한다 (인터페이스는 잘 변하지 않는다).
• WHY · 제약 · non-obvious 결정을 인라인한다 — 이것이 코드에 없는 진짜 자산이며 컨텍스트에 항상 보여야 한다.

기존 Compound에 전체 구현 스니펫이 복붙돼 있으면 위 형태로 경량화한다. 단 코드에 없는 사양(stdin 바이트 레이아웃, 와이어 프로토콜 포맷, 테스트 셋업 순서 등)은 그대로 둔다 — 이건 문서가 SoT다.