Upkeep

English · 繁體中文 · 简体中文 · 日本語 · 한국어

skill로 설치하는, 당신의 저장소를 위한 AI 감사 팀입니다. Upkeep은 전문화된 AI 리뷰어를 병렬로 실행해 드리프트 — 오래된 문서, 코드와 더 이상 맞지 않는 명세, 고아 에셋, 깨진 컨벤션 — 를 잡아내고, 누적되기 전에 근거와 함께 보고합니다.

💳 별도의 API 청구가 없습니다. Upkeep은 기존 Claude Pro/Max 구독으로 동작합니다 — 로컬에서는 로그인된 claude CLI, CI에서는 claude setup-token을 통한 OAuth를 사용합니다. Anthropic API 키 불필요, 토큰 과금 없음. 또한 출력 전용으로, 드리프트를 근거와 심각도와 함께 보고하지만 파일을 편집하거나 삭제하지 않습니다.

설치

Claude Code — plugin으로 설치합니다:

/plugin marketplace add wei18/upkeep
/plugin install upkeep@upkeep

다른 agent (Cursor, Copilot, 그리고 skills가 지원하는 70개 이상의 agent):

npx skills add wei18/upkeep --skill upkeep-audit

요구 사항: 로그인된 claude CLI (Pro/Max), Node 20+, git — 어떤 설치 방식이든 엔진은 당신의 머신에서 실행됩니다.

그다음 아무 세션에서나 이렇게 요청하세요:

Run an upkeep audit on /path/to/repo

첫 실행 시 skill이 Upkeep 엔진을 ~/.cache/upkeep에 자동으로 clone하고 의존성을 설치합니다. 심각도별로 그룹화된 발견 사항을 채팅에서 받고, 독립 실행형 HTML 보고서도 함께 생성됩니다.

주요 기능

• 저장소를 스캔하고 전문화된 AI 리뷰어 팀을 병렬로 실행합니다.
• 코드와 어긋난 오래된 문서, 구현과 맞지 않는 명세, 중복·고아 파일, 컨벤션 위반, 동기화가 깨진 번역 문서를 탐지합니다.
• 근거와 함께 불일치를 보고합니다 — 어느 한 쪽이 항상 정답이라고 가정하지 않습니다.
• 파일을 수정하거나 삭제하지 않습니다 — 출력 전용입니다.
• 독립 실행형 HTML 보고서를 생성합니다 — CI에서 실행하면 지속적인 GitHub 추적 이슈(upsert 방식, 중복 없음)도 생성됩니다.

다른 도구와의 차이

Upkeep은 linter도 PR bot도 아닌, 저장소 전체를 대상으로 하는 의미적 드리프트 감사 도구입니다. 역할이 다릅니다:

	Upkeep	Danger	Copilot / Cursor PR review
검사 범위	저장소 전체 — 문서, 명세, 에셋, 컨벤션	PR의 diff	PR의 diff
찾는 것	의미적 드리프트(README는 X라는데 코드는 Y)	직접 작성한 규칙 위반	diff 내 코드 문제
기준	저장소 자체 컨벤션	사용자 정의 규칙	일반 코드 지식
주기	예약 또는 온디맨드, 저장소 전체	PR마다	PR마다
코드를 수정하나요?	절대 안 함 — 출력만	안 함	변경 제안
비용	당신의 Claude Pro/Max 플랜	무료(로직 직접 작성)	Copilot/Cursor 구독

스크립트로 실행

agent가 아예 없다면? 같은 파이프라인을 독립 실행형 스크립트로 실행할 수 있습니다:

git clone --depth 1 https://github.com/wei18/upkeep ~/.cache/upkeep
cd ~/.cache/upkeep && npm ci
./scripts/local-audit.sh /path/to/repo --out ~/upkeep-report.html

플래그	기본값	대응 CI input
--model	claude-opus-4-8	model
--rubric-lang	en	rubric_lang
--max-turns	30	max_turns
--out	./upkeep-report.html	report artifact

요구 사항: 로그인된 claude CLI (Pro/Max 구독; setup-token도 GitHub 접근 권한도 필요 없음), Node 20+, git.

출력: 동일한 독립 실행형 HTML 리포트(기본값 upkeep-report.html)와 터미널 요약. 로컬 실행은 GitHub issue를 만들지 않습니다.

skill을 수동으로 설치하고 싶다면 skills/upkeep-audit/를 ~/.claude/skills/에 복사하세요.

CI에서 자동화

같은 감사 팀을 일정에 따라 실행합니다. 저장소에 .github/workflows/audit.yml을 생성합니다.

name: repo audit
on:
  schedule:
    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC
  workflow_dispatch:        # also run manually

permissions:
  contents: read
  issues: write
  id-token: write

jobs:
  audit:
    uses: wei18/upkeep/.github/workflows/audit.yml@v2
    with:
      model: claude-opus-4-8     # optional
      issue_label: audit         # optional; default: audit
      rubric_lang: en            # optional; reviewer language: en | zh-TW
    secrets:
      claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

사전 요구 사항

• CLAUDE_CODE_OAUTH_TOKEN라는 이름의 저장소 secret — 로컬에서 claude setup-token을 실행하여 생성하십시오(Claude Pro/Max 구독 필요, 사용량은 구독에서 차감됩니다).
• 위에 표시된 permissions 블록 (contents: read + issues: write + id-token: write).

출력

• audit 레이블이 붙은 GitHub 이슈 — 매 실행마다 동일한 이슈가 업데이트됩니다(upsert). 중복 생성되지 않습니다.
• report-html workflow artifact로 업로드되는 독립 실행형 HTML 보고서. 추적 이슈에서 바로 링크됩니다. 그 외에는 해당 run의 Artifacts(Actions → 해당 run)에서 찾거나 gh run download <run-id> -n report-html으로 받을 수 있습니다. GitHub artifact는 다운로드 가능한 zip이며, 저장소의 보존 설정에 따라 만료됩니다.

아직 @v1을 사용 중인가요? 계속 동작하지만 동결되었습니다 — 태그를 @v2로 바꾸세요. 인터페이스는 동일합니다.

또는 Marketplace action으로

익숙한 - uses: step 문법을 선호하거나 Upkeep을 GitHub Marketplace에 노출하고 싶다면? 대신 Upkeep Audit action을 사용하세요 — 동일한 엔진, 동일한 입력이지만 리뷰어가 병렬이 아니라 차례로 실행됩니다(위 reusable workflow가 기본 경로인 이유는 docs/why-reusable-workflow.md 참조):

name: repo audit
on:
  schedule:
    - cron: '0 3 * * 1'   # weekly, Monday 03:00 UTC
  workflow_dispatch:

permissions:
  contents: read
  issues: write
  id-token: write

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: wei18/upkeep@v2
        with:
          model: claude-opus-4-8               # optional
          issue_label: audit                    # optional; default: audit
          rubric_lang: en                       # optional; reviewer language: en | zh-TW
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

위와 동일한 요구 사항입니다: CLAUDE_CODE_OAUTH_TOKEN라는 이름의 저장소 secret(claude setup-token으로 생성)과 permissions 블록. step action은 자체적으로 permissions를 선언할 수 없으므로, 이번에는 job 자체에 지정합니다.

리뷰어

이름	기본값	검사 항목
docs_staleness	활성	코드와 어긋난 문서; 동기화가 깨진 다국어 README 및 번역 문서
code_hygiene	활성	데드 코드, 미사용 export, 영구적으로 남겨진 주석 처리 블록
spec_flow	활성	구현과 더 이상 일치하지 않는 명세, 다이어그램, 플로우차트
visual_icon	활성	오래되었거나 불일치하는 이미지 및 아이콘
duplicate_orphan	활성	중복 파일 및 커밋은 되어 있지만 참조되지 않는 고아 에셋
convention	활성	저장소 자체 컨벤션 위반 (CLAUDE.md, .claude/skills, workflow)
i18n	비활성	로케일 파일 간 국제화 일관성

설정

설정은 의도적으로 두 개의 독립된 영역으로 나뉩니다:

• Workflow 입력(위 caller의 with: 블록; 로컬에서는 이에 대응하는 스크립트 플래그)은 엔진을 어떻게 실행할지를 제어합니다: model, max_turns, issue_label, rubric_lang.
• .claude/audit.yml(감사 대상 repo에 커밋)은 무엇을 감사할지를 제어합니다: 어떤 리뷰어를 활성화할지, per-reviewer rubric 재정의, report.minSeverity. 리뷰어 활성화 여부는 workflow 입력이 아니라 여기에 있습니다 — repo마다 정해지고 repo와 함께 진화해야 하는 정책이기 때문입니다.

모든 설정은 선택 사항입니다. 예를 들어 기본적으로 꺼져 있는 i18n 리뷰어를 켜려면:

# .claude/audit.yml
reviewers:
  i18n:
    enabled: true

전체 스키마와 옵션은 docs/design.md를 참고하세요.

문서

• docs/overview.md — 파이프라인 동작 방식
• docs/design.md — 전체 설계 참고 문서
• docs/why-reusable-workflow.md — 왜 CI 계층은 step 액션이 아니라 reusable workflow인가