polish

polish는 UI 코드를 위한 자체 호스팅 리뷰 CLI 및 MCP 서버입니다. 사용성, 디자인 완성도, 접근성, 인터페이스 문안을 0-100점으로 평가하며, 파일 단위 발견 사항과 구체적인 수정 방안을 제공합니다. 로컬에서 실행하고, 자신의 API 키를 연결하고, 리뷰 루프를 워크플로 안에 유지하세요.

실제 UI 코드를 리뷰하는 디자이너와 엔지니어를 위해 만들어졌습니다.

실제로 보기: https://tomiabe.github.io/polish/

왜 필요한가

호스팅형 디자인 리뷰 도구는 유용하지만 할당량과 월간 한도에 묶여 있습니다. polish는 자체 API 키와 가벼운 Node CLI를 사용하여 리뷰 루프를 로컬에서 유지합니다. UI 파일을 가리키면 루브릭과 함께 LLM으로 전송하고, 점수와 심각도, 카테고리, file:line, 구체적인 수정 방안이 포함된 발견 사항을 반환합니다.

Related MCP server: @gridwork/siteaudit

기능

• 계층형 루브릭으로 리뷰: 사용성 휴리스틱, 디자인 완성도, 인터페이스 문안, 접근성. 시각적 및 상호작용 코드와 함께 제목, 설명, 라벨, 도움말 텍스트를 검사합니다. 루브릭은 단순한 데이터이므로 어떤 디자인 철학으로도 교체할 수 있습니다.

• Polish 가중치 점수. 치명적(critical) 발견 사항은 22점 차감, 심각(serious) 발견 사항은 9점 차감, 보통(moderate) 발견 사항은 3점 차감합니다. 심각도 상한은 없습니다.

• Groq, OpenAI, Anthropic, Gemini, OpenRouter 프로바이더 지원, 그리고 baseUrl을 통한 모든 OpenAI 호환 엔드포인트 지원.

• 선택적 프로바이더 폴백 체인으로 여러 API를 순서대로 시도할 수 있습니다.

• 하나의 엔진이 CLI와 MCP 서버를 모두 구동하므로 터미널 사용자와 AI 에이전트가 동일한 결과를 얻습니다.

• polish init-agent는 안전한 저장소 로컬 AGENTS.md를 작성하여 코딩 에이전트에게 UI 변경 시점에 리뷰하는 방법, 영수증을 인식하는 방법, 수정 사항을 검증하는 방법을 가르칩니다.

• 검증 모드는 전체 리뷰 비용의 일부로 업데이트된 파일에 대해 이전 발견 사항을 재확인하고 새로운 잔여 이슈 점수를 반환합니다.

• 치명적 발견 사항이 있으면 코드 1로 종료하므로 pre-commit 또는 CI 게이트로 사용할 수 있습니다.

설치

git clone https://github.com/tomiabe/polish.git
cd polish
npm link          # makes `polish` available in every project

셸 프로필에 API 키 하나를 설정하세요:

export GROQ_API_KEY=...        # or:
export OPENAI_API_KEY=...      # or:
export ANTHROPIC_API_KEY=...   # or:
export GEMINI_API_KEY=...      # or:
export OPENROUTER_API_KEY=...

사용법

polish                                   # audit files matched by config globs
polish src/components src/pages/*.tsx    # audit specific files or directories
polish --verify findings.json           # re-check that previous findings are fixed
polish --dry-run                        # preview what would be sent, no API call
polish --json                           # machine-readable receipt + findings, for CI or agents
polish init-agent                       # add the Polish workflow to AGENTS.md

구성

프로젝트 루트에 .polish.json을 생성하세요. 모든 항목은 선택 사항입니다:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "providers": ["gemini", "groq"],
  "include": ["src/**/*.{ts,tsx,css}"],
  "exclude": ["src/generated/**"],
  "rubric": ["usability", "craft", "accessibility"],
  "maxFiles": 20,
  "maxFileBytes": 100000
}

• provider - openai, anthropic, openrouter, groq 또는 gemini. 존재하는 환경 변수 키에서 자동 감지됩니다.

• providers - 순서가 있는 폴백 목록. 설정하면 polish는 성공할 때까지 각 프로바이더를 순서대로 시도합니다.

• model - 기본값은 gpt-4o-mini, claude-sonnet-4-20250514, openai/gpt-4o-mini(OpenRouter), llama-3.3-70b-versatile(Groq), gemini-2.5-flash입니다.

• baseUrl - 프록시 또는 자체 호스팅 게이트웨이용 API 엔드포인트를 재정의합니다.

• include / exclude - **, *, ?, {a,b}를 사용하는 글로브 패턴. node_modules와 .git은 항상 건너뜁니다.

• rubric - 사용할 루브릭 레이어. usability(핵심 휴리스틱), craft(타이포그래피, 색상, 간격, 모션, 컴포넌트, 문안), accessibility(대비, 키보드, 시맨틱, 폼, 터치 대상, reduced motion). 세 가지 모두 기본 활성화되어 있으며, 대규모 리뷰에서 토큰 비용을 줄이려면 일부만 선택할 수 있습니다.

• maxFiles / maxFileBytes - 큰 파일이 토큰 예산을 초과하지 않도록 하는 안전 상한. 모든 실행은 예상 토큰 수를 출력합니다.

루브릭과 맞춤 설정

기본 루브릭은 세 개의 레이어로 구성됩니다:

• usability - 10가지 핵심 휴리스틱: 시스템 상태의 가시성, 현실 세계와의 일치, 사용자 제어와 자유, 일관성과 표준, 오류 방지, 인식보다 회상, 유연성과 효율성, 심미적이고 미니멀한 디자인, 오류 진단과 복구, 도움말과 문서.

• craft - 디자인 시스템 규율: 시각적 완성도(동심원 반경, 광학 정렬, 매직 넘버 금지, 일반적인 AI 기본 스타일링 금지), 색상과 토큰, 타이포그래피, 간격과 레이아웃, 모션, 컴포넌트 구성, 문안.

• accessibility - 확인 가능한 요구사항: 대비, 키보드 지원, 시맨틱 요소, 폼, 터치 대상, reduced motion.

루브릭은 데이터 구조입니다. 자신의 철학으로 교체하려면 .polish.json에 principles 배열을 넣으세요:

{
  "principles": [
    {
      "id": "D1",
      "name": "Your design principles",
      "rules": [
        "A concrete rule the model can verify in code",
        "Another concrete rule"
      ]
    }
  ]
}

규칙은 모델이 확인할 수 있는 방식으로 표현할 때 가장 잘 작동합니다("버튼에 로딩 상태가 표시된다"), 미학적 느낌이 아니라.

점수

• 100에서 시작합니다. 각 발견 사항은 Polish 가중치에 따라 차감됩니다: critical -22, serious -9, moderate -3.

• 점수는 0 아래로 내려가지 않습니다.

모든 리뷰 실행은 polishApplied: true, 실행 ID, 점수, 리뷰된 파일이 포함된 영수증도 생성합니다. 사람 모드에서 polish는 점수 앞에 그 영수증을 출력합니다. --json 모드에서는 에이전트가 일반 텍스트 출력을 파싱하지 않고도 동일한 영수증을 읽을 수 있습니다.

검증 모드

polish > findings.json
# fix the issues
polish --verify findings.json

검증 모드는 현재 파일 내용에 대해 플래그된 발견 사항만 다시 실행하고 각각에 대해 FIXED 또는 STILL PRESENT를 보고합니다. 또한 남은 발견 사항을 기반으로 새 점수와 전체 리뷰와 동일한 형태의 영수증을 생성합니다. --json을 추가하면 검증 점수, 영수증, 상태를 기계가 읽을 수 있는 JSON으로 얻을 수 있습니다.

MCP 서버

polish는 stdio를 통한 MCP 서버로도 실행되므로 AI 에이전트가 도구로 호출할 수 있습니다. 제공하는 도구:

• polish_review_files - 콘텐츠로 UI 파일을 리뷰하고 점수, 영수증, 발견 사항을 반환합니다

• polish_verify_fixes - 업데이트된 콘텐츠에 대해 발견 사항을 재확인하고 새 점수, 영수증, 상태를 반환합니다

• polish_usage - 사용 상태, 항상 무제한이며 자체 호스팅입니다

MCP를 지원하는 모든 클라이언트에 등록하세요. opencode의 경우 ~/.config/opencode/opencode.json:

{
  "mcp": {
    "polish": {
      "type": "local",
      "command": ["node", "/absolute/path/to/polish/mcp-server.js"],
      "enabled": true,
      "environment": {
        "GROQ_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop은 ~/Library/Application Support/Claude/claude_desktop_config.json을 읽고, Codex는 ~/.codex/config.toml을 읽습니다. 세 경우 모두 node의 절대 경로(예: /usr/local/bin/node)를 사용하세요. GUI 앱은 셸 PATH를 상속하지 않으며, GUI 앱은 셸 프로필을 로드하지 않으므로 서버 환경에 API 키를 전달하세요.

에이전트 지침

MCP 서버를 등록한 후 프로젝트 루트에서 polish init-agent를 실행하세요. UI 변경에 대한 리뷰 루프가 포함된 AGENTS.md를 생성합니다. 이 명령은 --force를 전달하지 않는 한 기존 파일을 교체하지 않습니다.

개발

npm test          # node --test: unit tests plus a mock-server end-to-end test
node scripts/demo.mjs            # before/after demo, no API key needed
node scripts/mcp-handshake.mjs   # manual MCP handshake test

데모

node scripts/demo.mjs는 모의 OpenAI 호환 서버에 대해 전체 파이프라인(구성, 프롬프트, LLM 호출, 점수, 검증)을 실행하므로 API 키가 필요 없습니다. 접근성 차단 요소와 디자인 시스템 누수가 있는 컴포넌트 demo/ProfileCard.before.jsx를 리뷰한 다음, 수정된 쌍둥이 demo/ProfileCard.after.jsx(그리고 스타일시트 demo/profile.css)를 리뷰하고, 마지막으로 before 발견 사항이 after 코드에서 해결되었는지 검증합니다. 모의 서버는 결정적입니다: 39/100에서 97/100, 8/8 발견 사항 수정을 기대하세요.

API 키가 설정되면 동일한 명령이 실제 모델에 대해 실행되며 판정은 실제입니다. Groq(llama-3.3-70b-versatile)에서 기록된 실제 실행은 카드 데모를 before 62/100, after 78/100로, 폼 데모를 before 43/100, after 66/100로 평가했습니다. 판정은 모델과 실행에 따라 달라지므로 자신의 코드를 평가하려면 실제 실행을 사용하세요:

polish demo/ProfileCard.before.jsx
polish demo/ProfileCard.after.jsx demo/profile.css
polish demo/SettingsForm.before.jsx
polish demo/SettingsForm.after.jsx demo/settings-form.css

파일

bin/polish.js        CLI entry, output rendering, exit codes
mcp-server.js        MCP server (stdio) wrapping the review engine
lib/rubric.js        default rubric layers (usability, craft, accessibility), swap for your own
lib/config.js        config loading, glob expansion, defaults
lib/llm.js           LLM provider callers and JSON extraction
lib/prompt.js        review and verify prompt builders
lib/review.js        shared review and verify engine, used by CLI and MCP
lib/agent.js         repo-local instructions for coding agents
lib/scoring.js       weighted scoring and summaries
demo/                before/after demo components (ProfileCard, SettingsForm)
test/                unit and integration tests
scripts/             manual test scripts

토큰 비용에 관한 참고 사항

polish는 줄 번호가 매겨진 전체 파일 내용을 모델에 전송합니다. 예상 토큰 수는 각 실행 전에 출력됩니다. maxFiles와 maxFileBytes를 빡빡하게 유지하고, 전체 저장소보다는 변경에서 건드리는 화면을 감사하세요.