codebase-sync— agent skill

이 스킬이 하는 일

코드와 그것을 설명하는 문서(README, CLAUDE.md, docs 등) 사이의 간극을 찾아 닫는다. 큰 변경 이후 문서가 뒤처지거나, 코드에 방치된 찌꺼기가 쌓였을 때 가장 유용하다.

인자로 범위를 받으면 그 범위에 집중하고, 없으면 전체를 훑는다.

범위별 동작

docs (또는 "문서만")

문서와 코드의 불일치에만 집중한다. 코드는 건드리지 않는다.

• README, CLAUDE.md, docs/*.md에 언급된 파일·명령·모듈·구조가 실제로 존재하는가
• 삭제·이름 변경된 것이 문서에 남아 있지 않은가
• 최근 추가된 기능이나 구조 변경이 반영됐는가

code (또는 "코드만")

코드 품질에만 집중한다. 문서는 건드리지 않는다.

• 미사용 파일·모듈
• 방치된 TODO/FIXME
• 빌드·린트 에러 (가능한 경우)

전체 (기본값)

docs + code 모두. 파악 후 사용자가 어느 쪽을 먼저 처리할지 선택한다.

진행 흐름

1단계: 맥락 파악

프로젝트를 빠르게 파악한다. 목표는 "어디서 간극이 생겼을지"를 감잡는 것이다.

• 최근 커밋 이력 (git log --oneline -15) — 어떤 변경이 있었는지
• 프로젝트 구조 (최대 3단 깊이) — 실제 모듈·파일 구성
• 문서 파일 목록 — 어떤 문서가 있는지

명령을 기계적으로 전부 실행하는 게 아니라, 이 세 가지 질문에 답하는 데 필요한 것만 실행한다.

2단계: 불일치·개선 포인트 도출

파악한 내용을 바탕으로 실제로 어긋난 부분을 찾는다. 범위가 docs면 문서만, code면 코드만, 전체면 둘 다.

중요한 판단 기준: "고치지 않으면 다음 사람(또는 미래의 나)이 혼란스러울 것인가?" 사소한 오타나 스타일 차이보다 실질적으로 틀린 정보를 우선한다.

3단계: 결과 보고 후 대기 [STOP]

찾은 내용을 체크리스트로 정리해서 보여준다:

## 파악 결과

### 문서 불일치
- [ ] README: `app` 모듈 언급 → 실제 삭제됨 (5/27 커밋에서 제거)
- [ ] CLAUDE.md: 빌드 명령 `./gradlew assembleDebug` → 현재는 `./gradlew :composeApp:assembleDebug`

### 코드 정리
- [ ] src/legacy/ — 마지막 수정 3개월 전, 참조 없음

어떤 항목을 수정할까요?

항목이 0개면 "현재 불일치 없음"을 보고하고 종료한다.

4단계: 수정 실행

사용자가 동의한 항목만 수정한다.

• 문서 수정: 기존 구조·톤·형식을 유지한다. 틀린 부분만 최소한으로 고친다 — 전체 재작성 금지.
• 코드 수정: 삭제·리팩토링은 커밋 전 빌드가 통과해야 한다. 확신 없으면 수정 전에 한 번 더 확인한다.

5단계: 수정 완료 후 확인 [STOP]

수정한 내용을 diff 수준으로 간략히 보여주고, 커밋 진행 여부를 확인한다.

문제없으면 common:commit 스킬로 커밋한다.

6단계: PR (선택)

사용자가 PR을 요청하거나 변경이 문서 1~2개를 넘어서면 common:create-pr 스킬을 쓴다. 단순 문서 수정이면 커밋만으로 충분하다고 제안한다.

하지 말아야 할 것

• 범위 초과 금지: 불일치 수정이 목적이다. 이 기회에 리팩토링하거나 새 기능을 추가하지 않는다. 발견하면 메모해두고 별도 작업으로 제안한다.
• 과잉 재작성 금지: 문서 전체를 새로 쓰고 싶어도 참는다. 틀린 부분만 고친다.
• 자동 삭제 금지: 파일이나 코드를 삭제할 때는 반드시 사용자에게 먼저 확인한다.