랜딩 사이트 — 목적, UX 및 디자인 기준
정문은 site/ (Vite + React + Tailwind, 다크 모드 전용)이며 vigiles.sh에 배포됩니다. 이 스킬은 모든 변경 사항이 준수해야 하는 표준입니다. 이 기준이 존재하는 이유는 반복되는 실패, 즉 요소를 제거하는 대신 추가하는 행위를 막기 위함입니다. 이는 페이지를 템플릿처럼(tilda 스타일) 혼잡하게 만들어 현대적이지 않게 만듭니다.
다른 모든 규칙 위에 있는 단 하나의 규칙: 의심스러우면 제거하라. 빼기로 디자인하라. 요소를 삭제해도 의미가 손실되지 않는다면 삭제하십시오. 상자, 캡션, 두 번째 버튼 또는 안심 문구를 _추가_하는 변경은 필요성이 입증될 때까지 의심스럽습니다.
목적 (사이트의 용도)
- 최우선 목표 — 실제로
npx vigiles audit를 실행하는 방문자의 비율을 극대화하라. 이것은 모든 디자인 결정이 따르는 유일한 전환 지표입니다. CTA는 훌륭해야 합니다(마찰이 없고, 명확하며, 항상 도달 가능해야 함). 변경 사항이 누군가가 명령어를 실행하는 데 도움이 되지 않는다면, 그 자리를 차지할 가치가 없습니다. - 대상 독자: 이미 에이전틱 코딩 도구(Claude Code, Codex, Cursor)에 익숙한 개발자입니다. 그들은 회의적이며 휴대폰에서 빠르게 훑어봅니다.
- 와우 포인트는 등급 보고서입니다. — 메커니즘을 설명하지 말고 결과를 보여주세요.
- 정문 약속: "내 에이전트 하네스를 위한 Lighthouse" — 한 번의 명령어, 제로 설정, 아무것도 업로드하지 않고 Skills/훅/서브에이전트/참조를 평가합니다.
- 데모 프레임은 동시에 네 가지 역할을 수행합니다. — 네 가지 모두를 위해 설계하고, 하나가 다른 것을 밀어내지 않도록 하십시오. (1) 소개 — 한눈에 vigiles가 무엇인지 알려줍니다(등급 보고서 자체가 핵심 메시지). (2) 데모 — 노력 없이 즉시 실제 등급을 보여줍니다(내장된
FEATURED칩). (3) 브라우저 내 실행 — 라이브로 입력하여 공개 저장소를 평가합니다(GitHub 익명 API, 공개 저장소만 해당). (4) 나머지를 위한 명령어 복사 — 비공개 또는 로컬 저장소는 브라우저에서 실행할 수 없으므로, 여기서의 역할은npx vigiles audit의 깔끔하고 명확한 복사입니다(명령어 핸드오프, 가짜 브라우저 내 실행이 아님). 두 가지 명확성 규칙이 도출되며 매우 중요합니다: (a) 프레임은 항상 어떤 저장소가 표시되고 있는지, 그리고 그것이 사전 정의된 예제(칩)인지 아니면 사용자가 직접 입력한 것인지 명확히 해야 합니다. — 절대 모호하지 않게; (b) 비공개 저장소 경로는 문장에 끼워넣은 부차적인 것이 아니라 일급 기능입니다. — 390px에서 검증된 깔끔하게 레이블이 지정된 명령어 복사여야 합니다. 명령어를 세 줄로 나란히 표시하지 마십시오(이미 이름을 지정하고 있는 강조된 칩 위에$ vigiles audit <슬러그>를 표시하는 헤더는 정보 과잉입니다. 헤더의 역할은 평가된 저장소와 그 출처를 식별하는 것이지 명령어를 다시 인쇄하는 것이 아닙니다). - 카피: 교활함보다 구체적으로, 그리고 독자가 원래 가지고 있지 않았던 의심을 절대 심지 마십시오. 이 규칙이 막는 두 가지 실제 실수: (1) 난해하게 읽히는 교활한 헤드라인 ("'Valid' is not 'true.'") — 구체적인 문제로 시작하십시오 ("Valid config. Broken agent."), 아래 카드들이 뉘앙스를 전달하도록 두십시오; (2) 독자가 알아차리지 못한 약점을 부각시키는 방어적인 FAQ ("Is it stable enough to adopt?"는 무서운 버전 번호로 시선을 끕니다) — 의심을 심는 문구를 회의론자가 실제로 묻는 자신감을 키우는 문구로 바꾸십시오 ("Does anything leave my machine?", "Can I grade a private repo?"). 각 문장을 냉담한 회의론자로서 테스트하십시오: 이 문장이 명령어를 실행할 가능성을 높입니까, 낮춥니까? 낮춘다면, 삭제하거나 다시 구성하십시오.
- 신뢰도: 데모 보고서는 실제 스캔만을 표시합니다. — 결과를 절대 조작하지 마십시오. 브랜드는 "측정되었지, 주장되지 않았다"이므로, 보고서에 하드코딩되거나 가짜인 숫자가 하나라도 있으면 모든 실제 발견에 대한 신뢰를 사후적으로 무효화합니다. 진정으로 여기서 실행할 수 없는 것(모델 기반 트리거율)에 대한 정직한 플레이스홀더(숫자 없이 대시 "실행하면 채워짐")가 있는 잠금 티저는 괜찮습니다. — 아무것도 위조하지 않습니다. 도구가 실제로 계산하는 것에 대한 조작된 "결과"는 허용되지 않습니다. — 실제 계산된 결과를 보여주거나 보고서 프레임 외부의 정직한 설명 카드로 유지하십시오.
- 시도해보는 마찰을 낮추십시오: 인기 있는 오픈 소스 저장소를 미리 채워서 원클릭 "평가" 칩으로 제공하여 방문자가 직접 입력하거나 자신의 저장소가 없어도 실제 보고서를 볼 수 있게 하십시오. 구현 완료 —
DemoAudit의FEATURED칩은 즉시 실제 보고서를 렌더링합니다. - 모든 결과 표면에는 공유 기능과 안정적인 링크가 포함되어야 합니다. 팀원에게 전달할 수 없는 등급은 막다른 골목이므로: (1) 완료된 모든 등급은 로드 시 자동으로 감사를 실행하는 복사 가능한 딥 링크(
vigiles.sh/?repo=소유자/저장소#try)입니다. — URL 자체가 공유 단위입니다; (2) 모든 결과는 원탭 공유를 제공합니다(모바일에서는 네이티브 공유 시트, 그 외에는 링크 복사 —DemoAudit의ShareRow); (3) 딥 링크는 입력/칩이 사용하는 것과 동일한 슬러그이므로 공유 링크, 입력된 저장소 및 칩이 모두 하나의 코드 경로로 확인됩니다. 새로운 결과 표면은 반드시 이 두 가지를 모두 제공해야 합니다. 구현 완료 — 계속 작동하도록 유지하십시오. (이것이 작동하는 평판 규칙 — 공유는 옵트인, 거절은 자유, 사람이 아닌 평가 결과물 — 은 루트CLAUDE.md의gate-first-adoption규칙에 있습니다. 여기서 반복하지 마십시오.) - 전환을 측정하십시오: 퍼널에 대한 분석(명령어 복사, 입력 제출, 칩 시도, 재평가, 공유 클릭). 사이트는 Vercel이 아닌 GitHub Pages에 있으므로 Vercel Analytics는 적용되지 않습니다. 정적 호스팅을 위한 가볍고 프라이버시 친화적이며 스크립트 태그 기반의 분석 도구를 사용하십시오: Plausible / Fathom / GoatCounter. 퍼널은 이미 계측되었습니다. —
track()(site/src/lib/track.ts)은demo_*이벤트를 발생시키며 제공자가 연결될 때까지 안전하게 아무 일도 하지 않습니다. 남은 작업:index.html에 제공자 스크립트 태그를 추가하고 이벤트가 정상적으로 전송되는지 확인하십시오. 분석은 결과 종류만 전달하며 입력된 슬러그는 절대 전달하지 않습니다(비공개 저장소 이름이 유출되어서는 안 됨).
방향 — 결정 사항 기록 (최신 상태 유지; 여기에 방향이 저장됩니다)
현재 사이트 뒤에 있는 전략적 결정입니다. 방향이 변경되면 이 섹션을 업데이트하십시오. — 이것은 디자인 문서이지 스타일 가이드가 아닙니다. 각 결정은 실제 반복을 거쳐 도달한 것이므로 하나를 조용히 되돌리지 마십시오.
- 기본 데모는 반드시 문제점을 보여주어야 합니다. — A 등급의 벽이 아닌 실제 낮은 등급으로 시작하십시오.
FEATURED칩은 인식 가능한 저장소를 대상으로 한 진정한 F → C → B → A 척도입니다(현재 davila7/claude-code-templates F, disler/claude-code-hooks-mastery C, madappgang B, obra/superpowers A). 이것이 반드시 이렇게 되어야 하는 이유: 실제 인기 있는 플러그인은 대부분 브라우저가 실행할 수 있는 결정론적 축에서 A/B 등급입니다. — 극적인 실패(스킬이 실행되지 않음, 설명 충돌 등)는 브라우저가 실행할 수 없는 모델 기반 트리거율 계층에 있습니다. — 따라서 깔끔해 보이는 기본값은 도구에 반대되는 주장을 합니다("모든 게 괜찮은데, 이게 왜 필요하지?"). 기본값은 진정으로 손상된 저장소여야 와우 포인트(보고서)가 vigiles가 무언가를 잡아내는 것을 보여줄 수 있습니다. 낮은 등급 기본값 새로 고침 (저장소는 시간이 지나면서 수정됨):git clone https://github.com/<슬러그>후node dist/cli.js audit <dir> --json으로 스윕하십시오 (참고:codeload/api.github.com은 클라우드 환경에서 프록시로 차단됩니다. —git clonevia github.com은 작동합니다). (a) 인식 가능하고, (b) 객관적이고 한 줄로 수정 가능한 문제(죽은 도구, 보이지 않는skills/디렉토리, 죽은 훅 이벤트 — 당황스럽도록 설계된 것이 아님)가 있어 공개 등급이 공정한 저장소를 선택하십시오(Lighthouse 모델은 공개 아티팩트의 공개 등급입니다). 보고서를site/src/demo/reports/에 저장하고FEATURED에 연결하십시오. 모델 계층의 발견은 브라우저 데모에서 제외하십시오. — 설계상 결정론적 전용이므로(아래 브라우저 내 데모 불변 규칙 참조), 이에 대한 정직한 표면은LockedRow티저이지 조작된 결과가 아닙니다. - 이름만 나열하고 설명하지 않는 것은 카피 실패의 가장 큰 원인입니다. — 모든 개념을 설명하거나 삭제하십시오. 냉담한 방문자는 "linter", "reference", "enforce", "spec" 또는 카테고리 이름이 무엇을 의미하는지 모릅니다. 모든 개념은 첫 사용 시 일반 영어로 설명되거나 삭제됩니다. 전문 용어를 남용하지 마십시오(이전 README가 이것을 배웠습니다. — "처음 사용 시 HARNESS를 정의하십시오"; 사이트는 퇴보했다가 다시 배워야 했습니다). vigiles에 대해 들어본 적 없는 냉담한 Claude Code/Codex 사용자로서 각 문장을 테스트하십시오.
- 에코를 보고서에 통합하십시오. — 독립적인 설명 카드를 추가하지 마십시오. 보고서 자체가 와우 포인트입니다. 브라우저가 표시할 수 없는 개념(모델 기반 트리거율, 로컬 구성을 필요로 하는 linter 교차 참조)은 보고서 내부에 점선으로 표시된 CLI 전용 행(
report-view/src/Report.tsx의LockedRow/CliRulesRow)이어야 하며, 프레임 아래에 떠 있는 카드가 아닙니다. 사이트가 보고서를 두 군데에서 설명한다면, 에코를 삭제하십시오(이것이 Wedge의 다섯 가지 범주 스트립과 독립형 "Your rules → enforced" 카드가 제거된 이유입니다. — 보고서가 이미 둘 다 전달하고 있습니다). - 한 번에 하나의 입력 수단만 제공하십시오. — 공개/비공개 탭, 쌓아 올리지 않음. 히어로 입력은 입력 + "public API" 캡션 + 비공개 명령어 핸드오프 + 개인정보 보호 문구가 모두 쌓여 있었습니다(혼잡). 이제는
DemoAudit의 공개 | 비공개 탭입니다: 공개 = 라이브 타입-어-레포 콤보박스; 비공개 =npx vigiles audit명령어 복사. 한 번에 하나의 입력 수단만 표시됩니다. - 정직한 티저, 절대 흐리게/가짜로 표시하지 않음 (이전의 "흐리게 렌더링" 메모를 대체합니다). 모델 기반 행은 대시 플레이스홀더를 사용합니다(
recall — · precision —), 흐릿한 가짜 숫자가 아닙니다. 흐리게 표시는 렌더링 버그이자 페이월 다크 패턴으로 읽히며, 숫자를 조작하는 것은 "측정되었지, 주장되지 않았다"를 위반합니다. — 주장된 숫자를 조롱하는 카피 근처에 있으면 이중으로 잘못된 것입니다. 더 강력한 티저가 필요하다면,example레이블이 있는 실제 측정된 숫자를 사용하고 조작되거나 흐릿한 숫자는 절대 사용하지 마십시오.
UX 요구 사항
- 명령어 우선.
npx vigiles audit는 보편적인 작업입니다(모든 OS, 모든 터미널에서 작동). 이것은 주요 CTA입니다. 다른 모든 것은 부차적입니다. - Claude Code 딥링크 (
claude-cli://)는 데스크톱 전용 개선 사항이며, 절대 기본 경로가 아닙니다. — 모바일 / CC Web / CC 없는 데스크톱에서 조용히 작동하지 않습니다. 작동할 수 있는 곳에서만 렌더링하십시오; 아무 작업도 수행하지 않는 버튼을 절대 제공하지 마십시오. - 모바일에서 정직하십시오. 죽은 버튼을 만들지 마십시오. 데스크톱 전용 작업을 실행할 수 없는 경우, 명확히 말하고 실제 작업(명령어)을 대신 제공하십시오.
- 화면당 하나의 기본 작업. 보조 작업은 조용해야 합니다. — 텍스트 링크 또는 가벼운 알약 형태여야 하며, 기본 작업과 경쟁하는 두 번째 무거운 전체 너비 버튼이 아니어야 합니다.
- 하네스 중립적. "Claude Code 또는 Codex"라고 말하고, Claude Code로 시작하지 마십시오. — 그것은 구현 세부 사항일 뿐, 헤드라인이 아닙니다. 내부 구조를 지나치게 설명하지 마십시오.
- 낮은 마찰 + 환영하는 분위기. 빠르게 훑어보는 방문자가 한 화면 내에서 그것이 무엇이고 어떻게 시도해볼 수 있는지 이해할 수 있어야 하며, 긴 글을 읽을 필요가 없어야 합니다.
디자인 기준 — 모던 & 미니멀 (혼잡 방지 규칙)
Linear / Vercel / Raycast의 느낌을 참고하십시오: 자신감 있는 어두운 색상, 넉넉한 공간, 적은 단어, 섹션당 하나의 명확한 초점. 기능이 가득한 템플릿이 아닙니다.
- 모든 요소는 그 자리를 차지할 만한 가치가 있어야 합니다. 다른 요소를 반복하는 요소(스크린샷을 반복하는 캡션; 두 번 말한 신뢰 문구; 중복된 부제목)는 제거하십시오.
- 다른 요소가 이미 암시하는 레이블은 삭제하십시오. GitHub/별표 링크가 있을 때 "free & open source" 배지는 중복됩니다; "Grade a specific repo" 제목 위에 "AUDIT A SPECIFIC REPO" 배치는 그것을 다시 말하는 것입니다. 문맥이 이미 독자에게 알려준다면, 레이블은 노이즈입니다.
- 모든 링크/CTA는 실행 가능하고 구체적이어야 합니다. 독자는 클릭 시 정확히 어떤 일이 일어날지 알아야 합니다. 모호하거나 수동적인 보조 링크는 없어야 합니다("Have Claude Code?…"). 보조 경로가 명확하고 구체적인 행동의 가치가 없다면, 삭제하거나(또는 내비게이션으로 이동하십시오. 지속적인 링크가 약한 폴드 링크보다 낫습니다).
- 섹션당 하나의 초점. 시선이 가장 먼저 한 곳에 머물러야 합니다.
- 박스보다 여백과 타이포그래피. 3개 이상의 전체 너비 테두리 박스를 쌓지 마십시오. 그 반복이 혼잡해 보이는 원인입니다. 테두리보다는 유형 계층과 공간을 선호하십시오. 그러나 여백은 _의도적_이어야 합니다. — 거의 빈 뷰포트 공간도 허용되지 않습니다.
- 안심은 한 번, 한 줄로. 신뢰 카피("nothing uploaded")는 한 번만 간결하게 나타납니다. — 절대 3줄 단락으로, 섹션당 반복되지 않습니다.
- 일관성. 히어로(배지 + 헤드라인 + 부제목 + 비주얼)는 하나의 아이디어로 읽혀야 하며, 각 부분은 새로운 정보를 추가해야 합니다. 부제목이 스크린샷이 이미 보여주는 것을 말할 뿐이라면, 삭제하거나 날카롭게 하십시오.
- 색상/강조에서 절제. 하나의 악센트, 항상 _의미_가 있는 의미론적 밴드 색상(등급 밴드). 포인트당 한 구절만 굵게 표시하고 모든 절을 굵게 표시하지 마십시오. 장식용 이모지 폭죽은 없습니다.
- 일관된 간격 척도. 리듬을 깨는 일회성 여백을 수동으로 조정하지 마십시오.
안티 패턴 (여기서 잘못된 것들)
- 입력 + 큰 버튼 + 3줄 신뢰 문구 + 구분선 + 명령어 + 캡션 + 다른 버튼을 한 폴드에 쌓는 것. (해결책: ~3개의 요소만 유지하고 나머지는 삭제하십시오.)
- 제품 샷 아래에 제품 샷을 다시 설명하는 캡션.
- 흐름을 다시 생각하는 대신 문제 당 공지/버튼을 추가하는 것.
- 계층 구조 없이 두 개의 경쟁하는 기본 CTA(딥링크 + 명령어).
- 헤드라인 안심 문구로 CC 우선 프레이밍("runs in your own Claude Code…").
- 데스크톱 전용 흐름(Claude Code
claude-cli://딥링크)이 모바일에서 대체 수단으로 표시되어 다른 섹션에서 이미 보여주는 명령어를 반복하는 것 — 휴대폰에서 연속된 섹션에 동일한npx vigiles audit블록. (해결책: 데스크톱 전용 섹션 전체를hidden sm:block처리하십시오; 히어로 + CTA가 이미 그것을 전달합니다.)
브라우저 내 데모 (구현 완료 — 유지해야 할 불변 규칙)
라이브 "저장소 평가" 데모가 구축되었습니다(DemoAudit.tsx + site/src/demo/에 위치): 공개 저장소를 입력하거나 추천 칩을 탭하면 클라이언트 측에서 하네스 파일을 가져와 CLI가 사용하는 것과 동일한 컴파일된 엔진을 실행합니다. 아래 규칙은 이제 미래 방향이 아닌 보존해야 할 불변 규칙입니다.
- 모든 결과는 공유 가능합니다(위의 공유 가능성 목표 참조). 완료된 등급은 원탭 공유 + 안정적인 자동 실행
?repo=딥 링크를 제공합니다. 이것은 데모의 필수 요구 사항이지 있으면 좋은 기능이 아닙니다. — 이것 없이는 결과 표면을 출시하지 마십시오. - 브라우저 내에서 실행되며, 호스팅되지 않습니다. 감사 계산은 방문자의 브라우저에서 완전히 클라이언트 측에서 실행됩니다(GitHub API를 통해 저장소 파일을 가져오고 JS로 순수 탐지기를 실행합니다). → "아무것도 당신의 기계를 떠나지 않는다"는 점을 강화합니다; 백엔드/비용이 전혀 없습니다. 유일한 "호스팅"은 vigiles.sh의 정적 파일 제공입니다.
- FEATURED 칩은 사전 계산되며, 공개 등급입니다. 각
FEATURED배지 뒤에는site/src/demo/reports/의 정적 JSON 보고서 스냅샷이 있습니다. 이것들은 vigiles CLI 자체로 실행된 실제 과거 감사입니다. — 절대 수동으로 편집/가짜 데이터를 넣지 마십시오. 데모는 계산된 결과를 보여주며, 주장된 결과를 보여주지 않습니다. - 입력 창은 GitHub 공개 저장소만 수용합니다. 데모는 GitHub 익명 API를 사용합니다. — 다른 Git 호스팅(gitlab, bitbucket, self-hosted)을 지원하지 않으며 비공개 저장소를 지원하지 않습니다. 비공개/기타 저장소는 명령어로 리디렉션됩니다.
- 딥 링크는
?repo=소유자/이름#try형식입니다. (원래는#해시 경로였지만, GitHub Pages 리디렉션 문제로 인해 쿼리 매개변수로 변경되었습니다.) 자동 실행은 로드 시 트리거됩니다. — 방문자가 링크를 클릭하면 딥 링크 된 저장소가 즉시 감사됩니다. - 로딩 및 오류 상태가 완전히 처리되어야 합니다. 진행률 표시, 속도 저하 경고(큰 저장소의 경우), API 속도 제한/GitHub 오류에 대한 우아한 오류 메시지.
- 모델 계층(trigger_rate 등)은 생략되며
LockedRow로 표시됩니다. 브라우저 내 엔진은 결정론적 검사만 실행합니다. — 의도적인 설계 결정입니다. OS별 또는 모델별 검사는 CLI 전용입니다. 브라우저 데모는 스킬 정의 오류, 데드 훅, 보이지 않는 디렉토리 등을 포착합니다. FEATURED데이터는 영원히 지속되지 않습니다. — 유지 관리 전략이 필요합니다. 시간이 지남에 따라 저장소가 수정되면 등급이 변경됩니다. 새 스냅샷으로 업데이트하는 프로세스(위 참조). 오래되거나 제거된 저장소를 정기적으로 확인하십시오.
성능 예산 (site/)
사이트는 정적이며 GitHub Pages에 있으므로 LCP 및 TBT를 최소화하는 것이 중요합니다. 의식적으로 최적화되지 않은 모든 번들러 기본 설정은 이 예산을 초과하는 경향이 있습니다.
- Lighthouse 성능 점수 ≥ 95 (모바일). 느린 3G/중간급 휴대폰에서 테스트. — Vite가 일반적으로 도움이 되지만, 지나친 애니메이션/큰 종속성은 성능을 저하시킵니다.
- 초기 로드 시 상호 작용까지의 시간 < 3초 (느린 3G, 중간급 휴대폰). 모든 감사 로직은 레이지 로딩됩니다. —
DemoAudit는 동적import()를 사용합니다. 지속적인 개선:FEATURED보고서 JSON은 초기 번들에 포함되지 않고site/src/demo/reports/에서 가져옵니다.
이것은 site/ 디렉토리에 대한 표준입니다. 질문이 있다면 vigiles.sh 자체를 확인하십시오.