Upkeep 동작 방식

문제

저장소에는 드리프트가 쌓입니다. 함수가 리팩터링되어도 doc block은 그대로 남아 있습니다. 명세는 세 스프린트 전에 변경된 동작을 여전히 설명하고 있습니다. 번역된 README는 영어 원본보다 한 버전 뒤처집니다. 아이콘 파일이 교체되었지만 이전 파일은 계속 커밋된 채로 남습니다. 이 중 어느 것도 CI를 실패시키지 않습니다 — 그저 문서로 기록된 모든 것의 신뢰도를 소리 없이 갉아먹을 뿐입니다.

주기적인 인간 리뷰로 일부를 잡아낼 수 있지만, 모든 에셋의 맥락을 동시에 머릿속에 유지해야 합니다. 그것이 바로 전문화된 AI 리뷰어 팀이 잘할 수 있는 일입니다.

파이프라인: fan-out → 종합 → 보고

Upkeep에는 동일한 엔진을 공유하는 세 가지 통합 경로가 있습니다. CI용 재사용 가능한 workflow_call workflow, 익숙한 step 문법을 선호하는 경우를 위한 Marketplace composite action(- uses: wei18/upkeep@v2, 동일한 엔진과 입력이지만 reviewer가 병렬이 아니라 차례로 실행됨), 그리고 로컬에서 실행하는 Claude Code skill / plugin(또는 순수 스크립트)입니다. 어느 쪽이든 파이프라인은 동일한 다섯 단계입니다. Discovery, Consolidate, Report는 결정적(LLM 없음)이며, 병렬 reviewers와 Synthesis가 LLM 기반 단계입니다.

1. 탐색(Discovery)

탐색 단계에서 저장소를 순회하여 구조화된 파일 인벤토리를 생성합니다. 소스 파일, 문서, 명세, 다이어그램, 이미지, 아이콘, 로케일 파일, 컨벤션 파일(CLAUDE.md, .claude/skills, workflow 정의)이 포함됩니다. 이 인벤토리는 모든 리뷰어의 공통 입력값입니다.

2. 병렬 리뷰어(fan-out)

활성화된 각 리뷰어는 격리되어 실행됩니다 — CI에서는 독립 matrix job으로, 로컬에서는 병렬 claude -p 서브프로세스로 실행됩니다. 병렬로 실행되며 내결함성을 갖습니다 — 하나의 리뷰어가 실패해도 나머지 리뷰어는 계속 진행됩니다. 각 리뷰어는 파일 인벤토리와 자신의 전담 역할을 전달받아 결과를 구조화된 출력으로 기록합니다.

3. 종합(Synthesis)

단일 종합 단계에서 모든 리뷰어 결과를 읽고 공통 주제를 식별합니다. 예를 들어, 특정 디렉터리에 집중된 컨벤션 드리프트 패턴이나 여러 리뷰어가 서로 다른 이유로 동일한 파일을 독립적으로 지적하는 경우입니다. 리뷰어별 세부 내용과 함께 총괄 요약(executive summary)을 생성합니다.

4. 통합(Consolidate)

결정적 단계에서 여러 리뷰어가 동일 파일에 대해 제기한 중복 findings를 병합하고, 심각도가 가장 높은 대표 항목을 남기며, reviewers와 관련 파일을 합집합으로 묶고, 심각도순으로 정렬합니다. LLM은 개입하지 않습니다.

5. 보고(Report)

결정적 보고 단계에서 모든 내용을 독립 실행형 HTML 파일(외부 의존성 없음)로 렌더링합니다. CI에서는 추가로 단일 GitHub 추적 이슈를 upsert하며, 여러 실행에 걸쳐 재사용되므로 이슈 트래커가 깔끔하게 유지됩니다. 로컬 실행 시에는 대신 요약을 터미널/chat에 출력하며 GitHub를 전혀 건드리지 않습니다.

리뷰어

리뷰어	검사 항목
docs_staleness	코드와 어긋난 문서; 기준 언어 버전과 동기화가 깨진 다국어 README 및 번역 문서
code_hygiene	데드 코드 경로, 미사용 export, 영구적으로 남겨진 주석 처리 블록
spec_flow	실제 구현과 내용이 더 이상 일치하지 않는 명세, 아키텍처 다이어그램, 플로우차트
visual_icon	오래되었거나 불일치하거나 현재 UI 또는 브랜딩과 맞지 않는 이미지 및 아이콘
duplicate_orphan	중복 파일(다른 이름/경로 하에 동일하거나 거의 동일한 내용) 및 커밋은 되어 있지만 어디서도 참조되지 않는 고아 에셋
convention	저장소가 선언한 컨벤션에서의 이탈 — CLAUDE.md 규칙, .claude/skills 패턴, workflow 표준
i18n	로케일/번역 파일 간 일관성 (기본값 비활성; .claude/audit.yml을 통해 활성화)

정답을 가정하지 않음

두 에셋이 서로 다를 때 — 예를 들어, 명세는 동작 X를 설명하지만 코드는 동작 Y를 구현하는 경우 — Upkeep은 어느 쪽이 오래된 것인지 자동으로 판단하지 않습니다. 어느 에셋이든 최신이 아닐 수 있습니다. 대신, 각 파일의 git 최신성, 다른 파일에서 발견된 상호 참조, 명시적 버전 정보 등 근거와 함께 불일치를 보고합니다. 무엇을 수정할지는 사람이 결정합니다.

보고만 하며, 수정하지 않음

Upkeep은 저장소 콘텐츠에 대한 쓰기 권한이 없습니다. 파일을 읽고, 단일 GitHub 이슈를 생성하거나 업데이트할 뿐입니다. 저장소의 어떤 파일도 수정, 이름 변경, 삭제하지 않습니다.

출력

HTML 보고서 — CI에서는 매 실행 시 report-html workflow artifact로 업로드됩니다. 로컬에서는 지정한 경로(기본값 ./upkeep-report.html)에 기록됩니다. 독립 실행형이므로 서버 없이 로컬에서 열 수 있습니다. 총괄 요약, 리뷰어별 결과, 각 결과에 인용된 근거가 포함됩니다.

GitHub 추적 이슈(CI 전용) — 첫 실행 시 생성되고 이후 매 실행마다 업데이트(upsert)됩니다. 기본적으로 audit 레이블이 붙습니다. 중복 항목으로 이슈 트래커를 오염시키지 않으면서 현재 저장소 상태에 대한 지속적이고 링크 가능한 기록을 제공합니다. 로컬 실행 시에는 이 단계를 건너뛰고 대신 요약을 출력합니다.