From 2db8fcc8246ed92f0dc151051f1181897a12c098 Mon Sep 17 00:00:00 2001 From: Hyeongseob91 Date: Sat, 27 Jun 2026 23:39:46 +0900 Subject: [PATCH] chore(repo): make docs/ team-private and untrack internal artifacts docs/ holds team-private material (WIGTN brand logos, PPT templates & data, internal PRD/PLAN/migration notes) that should not ship in this public Apache-2.0 plugin. A teammate had committed some of it by accident. - gitignore docs/ so new private material never gets staged - untrack already-committed docs (PRD/PLAN/migration); files kept on disk - document a "Repository Hygiene" rule in CLAUDE.md as the backstop for ignore rules (which don't catch already-tracked files) Quality Score: 95/100 Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01VDvYizKVU4qf57HJjzN6iY --- .gitignore | 3 + CLAUDE.md | 15 + docs/opus-4-8-migration.ko.md | 108 ----- docs/prd/PRD_auto-pr-reviewer.md | 568 ------------------------ docs/todo_plan/PLAN_auto-pr-reviewer.md | 65 --- 5 files changed, 18 insertions(+), 741 deletions(-) delete mode 100644 docs/opus-4-8-migration.ko.md delete mode 100644 docs/prd/PRD_auto-pr-reviewer.md delete mode 100644 docs/todo_plan/PLAN_auto-pr-reviewer.md diff --git a/.gitignore b/.gitignore index 48c1c50..a88210e 100644 --- a/.gitignore +++ b/.gitignore @@ -21,5 +21,8 @@ memory-lake/ .claude/ PLANNING/ +# Team-private assets (brand logos, ppt templates & data) — not for the public plugin +docs/ + # WIGTN brand logo binaries bundled for wigtn-ppt (team-only; README stays, *.png ignored) plugins/wigtn-plugins/skills/wigtn-ppt/assets/logo/*.png diff --git a/CLAUDE.md b/CLAUDE.md index 5cb5fa0..ecb27ae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -113,3 +113,18 @@ Coordinators support both instruction-based orchestration (default) and native A - Parallel coordinators include sequential fallback for graceful degradation - Hooks run asynchronously to avoid blocking the main workflow - Commands can be used without plugin prefix (e.g., `/prd` instead of `wigtn-plugins:prd`) + +## Repository Hygiene — team-private artifacts (NEVER commit) + +This is a **public** plugin repo (Apache-2.0). The following are **team-private** and must never be staged or committed. They are `.gitignore`d, but ignore rules don't catch already-tracked files — so this rule is the backstop: + +| Path | What | Why private | +|------|------|-------------| +| `docs/` | Brand logos, PPT templates & data, internal PRD / PLAN / migration notes | Internal working artifacts, not part of the published plugin | +| `docs/images/*.png` | WIGTN brand logo binaries | Brand assets, team-only | +| `plugins/wigtn-plugins/skills/wigtn-ppt/assets/logo/*.png` | Bundled WIGTN logos for the skill | Brand assets, team-only (only `README.md` is committed) | + +**Rules for any agent/contributor:** +- Before committing, run `git status` and confirm nothing under `docs/` or any brand `*.png` is staged. Never `git add docs/` or `git add -A` without checking. +- If you find such files already **tracked** (a teammate added them by accident), untrack with `git rm -r --cached ` (keeps the file on disk) — do **not** commit them. +- WIGTN logos are obtained out-of-band by team members (see `skills/wigtn-ppt/assets/logo/README.md`); `wigtn-ppt` falls back to a CSS/SVG wordmark when binaries are absent, so the public plugin stays fully functional without them. diff --git a/docs/opus-4-8-migration.ko.md b/docs/opus-4-8-migration.ko.md deleted file mode 100644 index 727d895..0000000 --- a/docs/opus-4-8-migration.ko.md +++ /dev/null @@ -1,108 +0,0 @@ -# Opus 4.8 대응 — wigtn-plugins 수정 방향 (확정본) - -> 대상 모델: **Claude Opus 4.8** (`claude-opus-4-8`, 2026-05-28 출시) -> 상태: 코드 검증 완료 → 실행 항목 적용됨. #3·#4는 검토 후 드롭. -> 결론 요약: **실행 4건(#1 모델테이블+버전/카운트 동기화, #2 effort, #5·#6 설계, #7 백로그), 드롭 2건(#3·#4).** - ---- - -## 0. 배경 — 4.8 변경 중 플러그인에 실제로 닿는 것 - -| 변경 | 영향 | -|---|---| -| **Effort가 주 레버** (low/medium/high/xhigh/max, 4.8 기본 = high) | 예전엔 프롬프트 scaffolding이 하던 일을 effort가 함. 코딩은 xhigh 권장 | -| **Adaptive thinking이 유일 모드** | 수동 `thinking:{budget_tokens}`는 400 에러. → 우리 코드엔 없음(점검 완료) | -| **Honesty 업그레이드** | 자기 코드 결함 4배 덜 통과 + 불확실하면 거부/플래그 | -| **Dynamic Workflows** (research preview) | CC 네이티브 병렬 서브에이전트(≤16 동시/≤1000 총). v2.1.154+, Max/Team/Ent | -| **Mid-conversation system messages** | 실행 중 지시 주입을 캐시 안 깨고. API/SDK 레벨 | -| **temperature/top_p/top_k 제거**, **1M 컨텍스트 기본**, **fast mode 저렴** | — | - -> 점검 결과: 하드코딩 model ID(추천 테이블 제외)·수동 thinking·sampling 파라미터 **없음**. 런타임 breakage 0. - ---- - -## 1. [완료] 모델 ID + 버전/카운트 동기화 - -**1-A. ai-agent.md 추천 테이블 갱신 (전 프로바이더).** -구버전 `gpt-4o`·`claude-sonnet-4`·`gemini-2.0-flash`(2026-06-01 종료) 등이 전 프로바이더에서 깨져 있었음. 갱신: -- 빠름/저비용 → `claude-haiku-4-5` / `gpt-5.5-instant` / `gemini-3.5-flash` -- 균형 → `claude-sonnet-4-6` / `gpt-5.5` / `gemini-3.5-flash` -- 고정밀 → `claude-opus-4-8` / `gpt-5.5-pro` / `gemini-3.5-pro` -- 추천 테이블에 **"시점 예시 — 배포 시점 최신으로 교체"** 주석 추가 (재staleness 방지) - -**1-B. 버전 0.1.7로 통일.** 기존: CLAUDE.md 2.0.0 / 루트 plugin.json 2.0.0 / marketplace.json 2.1.0 혼재 → 전부 `0.1.7`. wigtn-plugins plugin.json에 version 필드 신규 명시. - -**1-C. 카운트 드리프트 동기화.** agents 12→13, 루트 매니페스트 설명의 "3 commands/3·4 skills/12+ styles" → "5 commands/5 skills/20 styles", README.cn Skills 4→5. - -> 적용 파일: `agents/ai-agent.md`, `CLAUDE.md`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `plugins/wigtn-plugins/.claude-plugin/plugin.json`, `README{,.ko,.cn}.md`. - ---- - -## 2. [완료] Effort 보정 — 13개 에이전트 - -전 13개가 `model: inherit` + effort 0건이라 세션 기본(high)으로 균일 동작했음. 성격별 보정: - -| effort | 에이전트 | 근거 | -|---|---|---| -| **xhigh** | code-reviewer, prd-reviewer, pr-reviewer | 판단·재현율 헤비, 4.8 honesty 시너지 | -| **xhigh** | architecture-decision, backend-architect | 설계 추론 | -| **xhigh** | frontend-developer, mobile-developer, ai-agent | 코딩은 xhigh 시작 권장 | -| **high** | design-discovery | 탐색·옵션 생성 | -| **high** | parallel-digging-coordinator, parallel-review-coordinator, team-build-coordinator | 오케스트레이션·합성 판단 (헤비 작업은 서브에이전트에 위임) | -| **low** | code-formatter | 기계적, 토큰 절약 | - -> 검증: 설치된 CC 버전에 따라 effort frontmatter 활성 여부가 다를 수 있음. 미지원 시 무시(graceful)되어 위험 낮음. 실제 Task 호출로 반영 여부 관찰 권장. (트래킹: anthropics/claude-code #31536) - ---- - -## 3. [드롭] ~~auto-commit 80점 임계값 재보정~~ - -검토 결과 **active task에서 제외**. 이유: -- 80은 애초에 4.7로도 경험적 보정된 값이 아님(라운드 넘버) → 보정 기준선이 허상. -- 점수는 모델 주관값. 4.8이 엄격해져 더 막으면 calibration 붕괴가 아니라 **게이트가 정확해진 것**. -- adaptive thinking으로 점수 노이즈 → 10~20 PR 표본 분포는 정보량 낮음. -- 과차단은 4.8 첫 실사용에서 바로 드러남 → 사전 측정 스터디 불필요. - -또한 원안의 "확신 강제 문구 완화"는 **대상이 코드에 0건**(grep 확인)이라 할 일 없음. - -> **남은 것(watch only):** 4.8 전환 후 auto-commit pass율을 실사용에서 관찰, 눈에 띄게 과차단되면 그때만 임계값 손댄다. 절차적 must(`config 먼저`·`보안 다운그레이드 금지`)는 유지. - ---- - -## 4. [드롭] ~~부정→긍정 프레이밍~~ - -완전 제외. 이유: #3이 "유지하라"고 한 절차적 must(`포맷 충돌 절대 금지`·`보안 절대 다운그레이드`)와 **충돌**하고, frontend/mobile 핵심 지침은 **이미 긍정형**. 가치 대비 노이즈. - ---- - -## 5. [설계 회의] 병렬 코디네이터 vs Dynamic Workflows - -대상: `parallel-digging-coordinator`, `parallel-review-coordinator`, `team-build-coordinator`. -DW가 동일 작업을 네이티브로 하지만 **research preview + v2.1.154+ + Max/Team/Ent 게이트** → 지금 제거 불가(폴백 필요). - -방향: **(1)** 지금 뜯지 않음 **(2)** 커스텀 fan-out·동시성·재시도를 *더* 정교화하지 않음(플랫폼이 흡수) **(3)** 코디네이터 책임을 wigtn 고유 가치로 재정의(도메인 분해·SHARED_CONTEXT·품질게이트·한국어 UX) **(4)** 능력 감지 후 DW 위임 / 폴백 분기 **(5)** GA 모니터링. - ---- - -## 6. [설계 회의] SHARED_CONTEXT vs Mid-conversation System Messages - -Mid-conversation system message는 **API/SDK 레벨** → 플러그인 .md frontmatter로 설정 불가. -방향: **(1)** 플러그인에서 손수 흉내내지 않음 **(2)** 현실 레버 = Hooks로 근사 **(3)** DW에 fan-out 위임하면 캐시 보존형 중간 주입 이점을 *공짜로* 수혜 **(4)** SDK 경로는 현재 범위 밖. - ---- - -## 7. [백로그] 1M 컨텍스트 기본 - -4.8 기본 1M. 우리 컨텍스트 전략(Phase 0 디스커버리, 스킬 분할)은 200k 가정으로 보수적 → 과도한 분할만 점진 완화. - ---- - -## 실행 체크리스트 - -- [x] **#1** ai-agent 모델 테이블 + 버전 0.1.7 통일 + 카운트 드리프트 동기화 -- [x] **#2** 에이전트 13개 effort 보정 -- [ ] **#3** ~~드롭~~ → watch only (4.8 전환 후 pass율 관찰) -- [ ] **#4** ~~드롭~~ -- [ ] **#5** 설계 회의 — 코디네이터 DW 폴백 구조 재설계 -- [ ] **#6** 설계 회의 — SHARED_CONTEXT를 hooks/DW 경유로 -- [ ] **#7** 백로그 — 1M 기준 컨텍스트 분할 완화 diff --git a/docs/prd/PRD_auto-pr-reviewer.md b/docs/prd/PRD_auto-pr-reviewer.md deleted file mode 100644 index bfb2ae7..0000000 --- a/docs/prd/PRD_auto-pr-reviewer.md +++ /dev/null @@ -1,568 +0,0 @@ -# Auto PR Reviewer PRD - -> **Version**: 1.0 -> **Created**: 2026-03-26 -> **Status**: Draft -> **Scale Grade**: Startup - -## 1. Overview - -### 1.1 Problem Statement - -WIGTN 조직에서 여러 repo에 PR이 올라오면 리뷰어가 수동으로 확인해야 한다. 리뷰 대기 시간이 길어지고, 리뷰 품질이 리뷰어의 컨디션과 시간에 따라 들쭉날쭉하다. 이미 `wigtn-plugins` 플러그인에 100점 품질 체계 기반의 `pr-reviewer` 에이전트가 있지만, 이를 수동으로 `/review-pr`을 실행해야만 동작한다. - -**핵심 문제**: PR이 올라오면 자동으로 리뷰가 시작되는 시스템이 없다. - -### 1.2 Goals - -- WIGTN org의 모든 GitHub repo에 PR이 열리면 자동으로 코드 리뷰 수행 -- 100점 품질 체계 기반으로 점수에 따라 자동 Approve / Request Changes / Comment -- Discord로 리뷰 결과 실시간 알림 전송 -- GCP + Docker로 항상 켜져있는(always-on) 서비스 운영 -- OMC(Oh My Claude Code)를 활용한 Claude Code 연동 - -### 1.3 Non-Goals (Out of Scope) - -- 자동 코드 수정 (리뷰만, fix는 하지 않음) -- PR 자동 머지 (Approve까지만, 머지는 사람이) -- GitHub 외 다른 Git 호스팅 지원 (GitLab, Bitbucket 등) -- WhatsApp/Slack 연동 (Discord만, 추후 확장 가능) -- 비공개 repo의 코드를 외부에 전송 (모든 처리는 GCP 내부) - -### 1.4 Scope - -| 포함 | 제외 | -|------|------| -| WIGTN org 전체 repo PR 자동 리뷰 | 다른 org/개인 repo | -| GitHub Webhook 수신 서버 | GitHub App 마켓플레이스 배포 | -| Discord 알림 봇 | Slack/WhatsApp 연동 | -| 100점 품질 체계 리뷰 | 자동 코드 수정/머지 | -| GCP Docker 배포 | 멀티 클라우드 | -| OMC + Claude Code 리뷰 엔진 | 다른 AI 모델 지원 | - -## 2. User Stories - -### 2.1 PR 작성자 - -As a **WIGTN 조직의 개발자**, I want to **PR을 올리면 자동으로 코드 리뷰를 받고** so that **리뷰 대기 시간 없이 즉시 피드백을 받을 수 있다**. - -### 2.2 리뷰어 (동료 개발자) - -As a **WIGTN 조직의 리뷰어**, I want to **AI가 먼저 리뷰한 결과를 확인하고** so that **명백한 이슈는 AI가 잡아주고 나는 설계/비즈니스 로직에 집중할 수 있다**. - -### 2.3 팀 리드 - -As a **팀 리드**, I want to **Discord에서 전체 PR 리뷰 현황을 실시간으로 확인하고** so that **코드 품질 추이와 병목을 파악할 수 있다**. - -### 2.4 Acceptance Criteria (Gherkin) - -```gherkin -Scenario: PR이 열리면 자동 리뷰 시작 - Given WIGTN org의 repo에 webhook이 설정되어 있고 - And Auto PR Reviewer 서비스가 실행 중일 때 - When 개발자가 PR을 열면 - Then 30초 이내에 리뷰가 시작되고 - And Discord에 "리뷰 시작" 알림이 전송된다 - -Scenario: 리뷰 완료 후 자동 판단 - Given PR 리뷰가 완료되었을 때 - When 품질 점수가 90점 이상이면 - Then PR에 자동으로 Approve 리뷰가 등록되고 - And Discord에 "Approved (92/100)" 알림이 전송된다 - -Scenario: Security Critical 이슈 발견 - Given PR 리뷰 중 Security Critical 이슈가 발견되면 - When 점수와 무관하게 - Then PR에 Request Changes 리뷰가 등록되고 - And Discord에 긴급 알림(@here)이 전송된다 - -Scenario: PR이 업데이트되면 재리뷰 - Given 이미 리뷰된 PR에 새 커밋이 푸시되면 - When synchronize 이벤트가 발생하면 - Then 변경된 파일에 대해 재리뷰를 수행한다 -``` - -## 3. Functional Requirements - -| ID | Requirement | Priority | Dependencies | -|----|------------|----------|--------------| -| FR-001 | GitHub Webhook 수신 서버: PR `opened`, `synchronize`, `reopened` 이벤트 처리 | P0 (Must) | - | -| FR-002 | WIGTN org 전체 repo에 대한 Organization Webhook 설정 | P0 (Must) | FR-001 | -| FR-003 | PR diff 가져오기 및 변경 파일 분석 | P0 (Must) | FR-001 | -| FR-004 | OMC + Claude Code 기반 코드 리뷰 실행 (`pr-reviewer` 에이전트) | P0 (Must) | FR-003 | -| FR-005 | 100점 품질 체계 기반 점수 산출 (5-Category) | P0 (Must) | FR-004 | -| FR-006 | 점수 기반 자동 GitHub 리뷰 제출 (Approve / Request Changes / Comment) | P0 (Must) | FR-005 | -| FR-007 | Critical/Major 이슈에 대한 인라인 코멘트 | P0 (Must) | FR-005 | -| FR-008 | Discord 알림: 리뷰 시작/완료/긴급 | P0 (Must) | FR-005 | -| FR-009 | Webhook Secret 기반 요청 검증 (HMAC-SHA256) | P0 (Must) | FR-001 | -| FR-010 | 리뷰 큐잉: 동시 다수 PR 요청 시 순차 처리 | P1 (Should) | FR-001 | -| FR-011 | Repo별 리뷰 설정 오버라이드 (`.github/auto-review.yml`) | P1 (Should) | FR-004 | -| FR-012 | 리뷰 결과 로그 저장 (SQLite/JSON) | P1 (Should) | FR-005 | -| FR-013 | Draft PR 스킵 (옵션) | P1 (Should) | FR-001 | -| FR-014 | 특정 라벨이 붙은 PR 스킵 (`no-ai-review`) | P1 (Should) | FR-001 | -| FR-015 | 리뷰 재요청 트리거: PR 코멘트에 `/re-review` 입력 시 재리뷰 | P2 (Could) | FR-001 | -| FR-016 | 주간/월간 리뷰 통계 Discord 리포트 | P2 (Could) | FR-012 | - -## 4. Non-Functional Requirements - -### 4.0 Scale Grade - -**Startup (소규모 서비스)** - -| 지표 | 예상치 | -|------|--------| -| WIGTN org repo 수 | 10-50개 | -| 일일 PR 수 | 10-100건 | -| 동시 리뷰 요청 | 1-5건 | -| 월간 리뷰 총량 | 300-3,000건 | - -### 4.1 Performance SLA - -| 지표 | 목표값 | -|------|--------| -| Webhook 응답 시간 | < 1초 (202 Accepted) | -| 리뷰 시작까지 지연 | < 30초 | -| 리뷰 완료 시간 (Level 2) | < 5분 / PR | -| Discord 알림 지연 | < 5초 | -| 큐 처리량 | 10 PR/시간 (순차) | - -### 4.2 Availability SLA - -| 항목 | 값 | -|------|-----| -| Uptime 목표 | 99% (월 7.3시간 다운타임 허용) | -| 장애 시 동작 | Webhook 미처리 PR은 수동 `/review-pr`로 대체 | -| 자동 복구 | Docker restart policy: `unless-stopped` | - -### 4.3 Data Requirements - -| 항목 | 값 | -|------|-----| -| 리뷰 로그 크기 | 월 ~50MB (JSON 로그) | -| 보존 기간 | 6개월 | -| 코드 데이터 | 디스크에 저장하지 않음 (메모리에서만 처리) | - -### 4.4 Recovery - -| 항목 | 값 | -|------|-----| -| RTO (복구 시간) | 1시간 | -| RPO (복구 시점) | 리뷰 로그 손실 허용 (재리뷰 가능) | -| 백업 | Docker volume의 리뷰 로그만 | - -### 4.5 Security - -| 항목 | 구현 | -|------|------| -| Webhook 검증 | HMAC-SHA256 (GitHub Secret) | -| GitHub 인증 | GitHub App 또는 PAT (fine-grained) | -| Claude API 키 | 환경변수 (Secret Manager 권장) | -| Discord Bot Token | 환경변수 (Secret Manager 권장) | -| 네트워크 | GCP 방화벽: 443/HTTPS만 인바운드 | -| 코드 보안 | PR diff는 메모리에서만 처리, 디스크 미저장 | -| 감사 로그 | 모든 리뷰 요청/결과 로깅 | - -## 5. Technical Design - -### 5.1 System Architecture - -``` -┌──────────────────────────────────────────────────────────────────┐ -│ GitHub (WIGTN Org) │ -│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ -│ │ Repo A │ │ Repo B │ │ Repo C │ ... │ -│ └────┬────┘ └────┬────┘ └────┬────┘ │ -│ └───────────┼───────────┘ │ -│ │ Organization Webhook │ -│ │ (PR opened/synchronize/reopened) │ -└───────────────────┼─────────────────────────────────────────────┘ - │ HTTPS POST - ▼ -┌──────────────────────────────────────────────────────────────────┐ -│ GCP (Docker) │ -│ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ Webhook Server (Node.js / Express) │ │ -│ │ - HMAC-SHA256 검증 │ │ -│ │ - 이벤트 파싱 & 필터링 │ │ -│ │ - 리뷰 큐에 등록 │ │ -│ └──────────────────────┬─────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ Review Queue (BullMQ + Redis) │ │ -│ │ - FIFO 순서 보장 │ │ -│ │ - 재시도 (3회) │ │ -│ │ - 동시성 제어 (concurrency: 2) │ │ -│ └──────────────────────┬─────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ Review Worker │ │ -│ │ │ │ -│ │ 1. gh pr diff → diff 가져오기 │ │ -│ │ 2. OMC + Claude Code 실행 │ │ -│ │ → pr-reviewer 에이전트 호출 │ │ -│ │ → 100점 품질 체계 평가 │ │ -│ │ 3. 결과 파싱 │ │ -│ │ 4. gh pr review → GitHub에 리뷰 제출 │ │ -│ │ 5. Discord 알림 전송 │ │ -│ │ 6. 리뷰 로그 저장 │ │ -│ └────────────┬───────────────────────┬───────────────────────┘ │ -│ │ │ │ -│ ▼ ▼ │ -│ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ GitHub API │ │ Discord Bot │ │ -│ │ (gh CLI / REST) │ │ (Webhook/Bot) │ │ -│ └──────────────────┘ └──────────────────┘ │ -│ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ Review Log Store (SQLite) │ │ -│ │ - PR 메타데이터, 점수, 이슈 목록, 타임스탬프 │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ -└──────────────────────────────────────────────────────────────────┘ -``` - -### 5.2 Component Details - -#### 5.2.1 Webhook Server - -| 항목 | 값 | -|------|-----| -| Runtime | Node.js 22+ | -| Framework | Express (또는 Hono) | -| Port | 3000 (내부) → 443 (외부, HTTPS) | -| 인증 | HMAC-SHA256 webhook secret 검증 | - -#### 5.2.2 Review Queue - -| 항목 | 값 | -|------|-----| -| Queue | BullMQ | -| Backend | Redis (GCP Memorystore 또는 Docker Redis) | -| Concurrency | 2 (동시 리뷰 2개) | -| Retry | 3회, exponential backoff | -| Timeout | 10분 / job | - -#### 5.2.3 Review Worker - -| 항목 | 값 | -|------|-----| -| 실행 방식 | OMC CLI → Claude Code CLI 호출 | -| 리뷰 엔진 | `wigtn-plugins` 플러그인의 `pr-reviewer` 에이전트 | -| 리뷰 레벨 | Level 2 (Standard) 기본, repo별 오버라이드 가능 | -| 출력 | 구조화된 리뷰 결과 (JSON) | - -#### 5.2.4 Discord Bot - -| 항목 | 값 | -|------|-----| -| 방식 | Discord Webhook (단순 알림) + Bot (명령 응답) | -| 채널 | `#pr-reviews` (리뷰 결과), `#pr-alerts` (긴급) | -| 명령 | `/review-stats` (통계), `/re-review ` (재리뷰) | - -### 5.3 API Specification - -#### `POST /webhook/github` - -**Description**: GitHub Organization Webhook 수신 엔드포인트 - -**Authentication**: HMAC-SHA256 (X-Hub-Signature-256 헤더) - -**Headers**: -| Header | Required | Description | -|--------|----------|-------------| -| X-Hub-Signature-256 | Yes | HMAC-SHA256 서명 | -| X-GitHub-Event | Yes | 이벤트 타입 (pull_request) | -| X-GitHub-Delivery | Yes | Delivery ID (중복 방지) | -| Content-Type | Yes | application/json | - -**Request Body** (GitHub PR event payload): -```json -{ - "action": "opened | synchronize | reopened", - "number": 123, - "pull_request": { - "title": "Add user authentication", - "user": { "login": "developer" }, - "head": { "ref": "feat/user-auth", "sha": "abc123" }, - "base": { "ref": "main" }, - "draft": false, - "labels": [{ "name": "enhancement" }], - "additions": 234, - "deletions": 12, - "changed_files": 5 - }, - "repository": { - "full_name": "wigtn/repo-name", - "clone_url": "https://github.com/wigtn/repo-name.git" - }, - "organization": { - "login": "wigtn" - } -} -``` - -**Response 202 Accepted**: -```json -{ - "status": "queued", - "jobId": "review-123-abc", - "message": "PR review queued" -} -``` - -**Error Responses**: -| Status | Code | Message | Description | -|--------|------|---------|-------------| -| 400 | INVALID_PAYLOAD | Invalid webhook payload | 페이로드 파싱 실패 | -| 401 | INVALID_SIGNATURE | Signature verification failed | HMAC 검증 실패 | -| 422 | SKIPPED | PR skipped (draft/label) | Draft PR 또는 no-ai-review 라벨 | -| 500 | INTERNAL_ERROR | Internal server error | 서버 오류 | - -#### `GET /health` - -**Description**: 헬스 체크 엔드포인트 - -**Response 200 OK**: -```json -{ - "status": "healthy", - "uptime": 86400, - "queue": { - "waiting": 2, - "active": 1, - "completed": 150, - "failed": 3 - }, - "lastReview": "2026-03-26T10:30:00Z" -} -``` - -### 5.4 Review Decision Matrix - -| 점수 | 등급 | GitHub Action | Discord 알림 | -|------|------|--------------|-------------| -| 90-100 | A+/A | `--approve` | `:white_check_mark: Approved (92/100)` | -| 80-89 | B+/B | `--approve` + suggestions | `:white_check_mark: Approved with suggestions (85/100)` | -| 70-79 | C+/C | `--comment` | `:warning: Needs improvement (74/100)` | -| 60-69 | D | `--request-changes` | `:x: Changes requested (65/100)` | -| < 60 | F | `--request-changes` | `:x: Significant changes needed (48/100)` | -| Security Critical | - | `--request-changes` (강제) | `:rotating_light: @here Security issue!` | - -### 5.5 Discord Message Format - -#### 리뷰 시작 - -``` -🔍 PR 리뷰 시작 -━━━━━━━━━━━━━━━━━━━━ -📦 wigtn/repo-name #123 -📝 Add user authentication -👤 @developer -📊 5 files (+234, -12) -⏳ 리뷰 중... -``` - -#### 리뷰 완료 - -``` -✅ PR 리뷰 완료 -━━━━━━━━━━━━━━━━━━━━ -📦 wigtn/repo-name #123 -📝 Add user authentication -👤 @developer - -📊 Quality Score: 85/100 (B+) -┌──────────────────┬───────┐ -│ Readability │ 18/20 │ -│ Maintainability │ 16/20 │ -│ Performance │ 15/20 │ -│ Testability │ 18/20 │ -│ Best Practices │ 18/20 │ -└──────────────────┴───────┘ - -✅ Decision: APPROVED -⚠️ 1 Major issue, 2 Minor suggestions - -🔗 https://github.com/wigtn/repo-name/pull/123 -``` - -#### 긴급 알림 - -``` -🚨 @here Security Issue Detected! -━━━━━━━━━━━━━━━━━━━━ -📦 wigtn/repo-name #123 -📝 Add user authentication -👤 @developer - -🔴 Critical: SQL injection vulnerability - 📄 src/api/auth.ts:45 - -❌ Decision: CHANGES REQUESTED -📊 Score: 59/100 (Security Override) - -🔗 https://github.com/wigtn/repo-name/pull/123 -``` - -### 5.6 Repo-Level Configuration (`.github/auto-review.yml`) - -```yaml -# .github/auto-review.yml (repo별 오버라이드) -auto-review: - enabled: true # false로 비활성화 - level: 2 # 리뷰 레벨 (1-4) - auto-approve: true # 자동 Approve 활성화 - auto-approve-threshold: 90 # 자동 Approve 최소 점수 - skip-draft: true # Draft PR 스킵 - skip-labels: # 스킵할 라벨 - - no-ai-review - - wip - paths-ignore: # 리뷰 제외 경로 - - "docs/**" - - "*.md" - - ".github/**" - discord: - channel: "pr-reviews" # 알림 채널 (기본) - mention-on-critical: true # Critical 시 @here -``` - -### 5.7 Database Schema (SQLite) - -```sql -CREATE TABLE reviews ( - id TEXT PRIMARY KEY, -- UUID - pr_number INTEGER NOT NULL, - repo_full_name TEXT NOT NULL, -- wigtn/repo-name - pr_title TEXT NOT NULL, - pr_author TEXT NOT NULL, - head_sha TEXT NOT NULL, - - -- Scores - score_total INTEGER, - score_readability INTEGER, - score_maintainability INTEGER, - score_performance INTEGER, - score_testability INTEGER, - score_best_practices INTEGER, - grade TEXT, -- A+, A, B+, B, C+, C, D, F - - -- Decision - decision TEXT NOT NULL, -- APPROVE, COMMENT, REQUEST_CHANGES - security_override BOOLEAN DEFAULT FALSE, - - -- Issues - issues_critical INTEGER DEFAULT 0, - issues_major INTEGER DEFAULT 0, - issues_minor INTEGER DEFAULT 0, - issues_info INTEGER DEFAULT 0, - - -- Meta - review_level INTEGER DEFAULT 2, - duration_ms INTEGER, - created_at TEXT DEFAULT (datetime('now')), - - -- Status - status TEXT DEFAULT 'completed' -- queued, in_progress, completed, failed -); - -CREATE INDEX idx_reviews_repo ON reviews(repo_full_name); -CREATE INDEX idx_reviews_created ON reviews(created_at); -``` - -## 6. Implementation Phases - -### Phase 1: MVP (Core Pipeline) - -**목표**: PR이 올라오면 리뷰하고 GitHub에 결과를 남기는 최소 파이프라인 - -- [ ] 프로젝트 초기화 (Node.js + TypeScript) -- [ ] Webhook 서버 구현 (Express, HMAC 검증) -- [ ] GitHub API 연동 (PR diff 가져오기, 리뷰 제출) -- [ ] OMC + Claude Code 리뷰 실행 워커 -- [ ] 점수 기반 자동 판단 로직 (Approve / Request Changes / Comment) -- [ ] 인라인 코멘트 (Critical/Major) -- [ ] Docker 컨테이너화 -- [ ] GCP 배포 (Cloud Run 또는 GCE) - -**Deliverable**: WIGTN org에 webhook 연결, PR 시 자동 리뷰 + GitHub 코멘트 - -### Phase 2: Queue + Discord - -**목표**: 안정적인 큐잉과 Discord 알림 - -- [ ] Redis + BullMQ 큐 시스템 -- [ ] 동시성 제어 (concurrency: 2) -- [ ] 재시도 로직 (3회, exponential backoff) -- [ ] Discord Webhook 알림 (시작/완료/긴급) -- [ ] Draft PR / 라벨 기반 스킵 -- [ ] 헬스 체크 엔드포인트 - -**Deliverable**: 안정적인 큐 처리 + Discord 실시간 알림 - -### Phase 3: Configuration + Logging - -**목표**: Repo별 커스터마이징과 로그 분석 - -- [ ] `.github/auto-review.yml` 파싱 및 적용 -- [ ] SQLite 리뷰 로그 저장 -- [ ] `/re-review` 코멘트 트리거 -- [ ] Duplicate 요청 방지 (Delivery ID 체크) -- [ ] Docker Compose (서버 + Redis + 워커) - -**Deliverable**: Repo별 설정, 리뷰 이력 조회 가능 - -### Phase 4: Analytics + Polish - -**목표**: 통계와 안정성 개선 - -- [ ] 주간/월간 리뷰 통계 Discord 리포트 -- [ ] Discord Bot 명령어 (`/review-stats`) -- [ ] 에러 알림 (리뷰 실패 시 Discord 알림) -- [ ] GCP 모니터링 (Cloud Logging, Uptime Check) -- [ ] 문서화 (README, 설정 가이드) - -**Deliverable**: 운영 가능한 완성 서비스 - -## 7. Success Metrics - -| Metric | Target | Measurement | -|--------|--------|-------------| -| 리뷰 자동 처리율 | > 95% PR 자동 리뷰 | 리뷰 로그 / 전체 PR 수 | -| 리뷰 완료 시간 | < 5분 (Level 2) | 리뷰 로그 duration_ms | -| 리뷰 정확도 | Critical 이슈 미탐율 < 5% | 사람 리뷰와 비교 | -| 가용성 | 99% uptime | GCP Uptime Check | -| Discord 알림 지연 | < 5초 | 로그 타임스탬프 비교 | -| 개발자 만족도 | > 4/5점 | 월간 설문 | - -## 8. Tech Stack Summary - -| Component | Technology | -|-----------|-----------| -| Language | TypeScript (Node.js 22+) | -| Web Framework | Express (또는 Hono) | -| Queue | BullMQ + Redis | -| Review Engine | OMC + Claude Code CLI + wigtn-plugins pr-reviewer | -| GitHub | gh CLI + GitHub REST API (Octokit) | -| Discord | Discord.js (Bot) + Webhook (알림) | -| Database | SQLite (better-sqlite3) | -| Container | Docker + Docker Compose | -| Hosting | GCP (Cloud Run 또는 GCE e2-medium) | -| CI/CD | GitHub Actions | -| Secrets | GCP Secret Manager | -| Monitoring | GCP Cloud Logging + Uptime Check | - -## 9. Cost Estimate (Monthly) - -| Item | Estimated Cost | -|------|---------------| -| GCP GCE e2-medium (2 vCPU, 4GB) | ~$25/month | -| GCP Memorystore Redis (basic, 1GB) | ~$35/month (또는 Docker Redis: $0) | -| Claude API (Anthropic) | ~$50-200/month (PR 양에 따라) | -| Domain + SSL (Let's Encrypt) | $0-12/year | -| **Total** | **~$60-260/month** | - -> Docker Redis를 사용하면 GCP 비용을 $25/month로 줄일 수 있음. -> Claude Max subscription 사용 시 API 비용 절감 가능. diff --git a/docs/todo_plan/PLAN_auto-pr-reviewer.md b/docs/todo_plan/PLAN_auto-pr-reviewer.md deleted file mode 100644 index 4cb3962..0000000 --- a/docs/todo_plan/PLAN_auto-pr-reviewer.md +++ /dev/null @@ -1,65 +0,0 @@ -# Task Plan: auto-pr-reviewer - -> **Generated from**: docs/prd/PRD_auto-pr-reviewer.md -> **Created**: 2026-03-26 -> **Status**: pending - -## Execution Config - -| Option | Value | Description | -|--------|-------|-------------| -| `auto_commit` | true | 완료 시 자동 커밋 | -| `commit_per_phase` | true | Phase별 중간 커밋 (별도 서비스이므로) | -| `quality_gate` | true | /auto-commit 품질 검사 | - -## Phases - -### Phase 1: MVP (Core Pipeline) -- [ ] 프로젝트 초기화 (Node.js + TypeScript + ESLint + Prettier) -- [ ] Webhook 서버 구현 (Express, HMAC-SHA256 검증) -- [ ] PR 이벤트 필터링 (opened/synchronize/reopened) -- [ ] GitHub API 연동 (gh CLI wrapper: diff 가져오기, 리뷰 제출) -- [ ] OMC + Claude Code 리뷰 실행 워커 (child_process spawn) -- [ ] 리뷰 결과 파싱 (100점 → 판단 매핑) -- [ ] 인라인 코멘트 생성 (Critical/Major) -- [ ] Dockerfile + docker-compose.yml -- [ ] GCP 배포 스크립트 - -### Phase 2: Queue + Discord -- [ ] Redis 컨테이너 추가 (docker-compose) -- [ ] BullMQ 큐 시스템 (Producer/Consumer) -- [ ] 동시성 제어 (concurrency: 2) + 재시도 (3회) -- [ ] Discord Webhook 알림 (시작/완료/긴급) -- [ ] Discord Embed 메시지 포맷팅 -- [ ] Draft PR / 라벨 기반 스킵 로직 -- [ ] 헬스 체크 엔드포인트 (`GET /health`) -- [ ] Delivery ID 중복 방지 - -### Phase 3: Configuration + Logging -- [ ] `.github/auto-review.yml` 파싱 (repo별 설정) -- [ ] SQLite 스키마 생성 + 리뷰 로그 저장 -- [ ] `/re-review` 코멘트 이벤트 처리 (issue_comment webhook) -- [ ] 리뷰 이력 조회 API (`GET /reviews/:repo`) -- [ ] Docker Compose 통합 (서버 + Redis + 워커) - -### Phase 4: Analytics + Polish -- [ ] 주간/월간 리뷰 통계 집계 로직 -- [ ] Discord Bot: `/review-stats` 명령 -- [ ] 에러 알림 (리뷰 실패 시 Discord 알림) -- [ ] GCP Cloud Logging 연동 -- [ ] GCP Uptime Check 설정 -- [ ] README + 설정 가이드 문서 - -## Progress - -| Metric | Value | -|--------|-------| -| Total Tasks | 0/30 | -| Current Phase | - | -| Status | pending | - -## Execution Log - -| Timestamp | Phase | Task | Status | -|-----------|-------|------|--------| -| - | - | - | - |