dx-roaster
GitHub 저장소의 개발자 경험을 평가합니다. roast.md, action-plan.md, ideal-readme.md, score.json의 네 가지 파일을 생성합니다. Show HN, Product Hunt 등 처음 5분이 중요한 런칭을 준비하는 OSS 관리자와 데브툴 창업자를 위해 만들어졌습니다.
중요한 규칙 (매 실행 전 읽을 것)
-
점수를 매기기 전에 세 가지 참고 파일을 모두 읽으십시오.
references/scoring-rubric.md,references/roast-voice-guide.md,references/readme-template.md. 루브릭은 변경할 수 없습니다. 정확히 10가지 차원을 사용하십시오. -
모든 차원을 0–10 척도로 평가하십시오. 절대 건너뛰지 마십시오. 데이터 누락 = 점수 0. '해당 없음'으로 처리하지 않습니다.
-
평가는 구체적인 발견을 인용해야 합니다. 문제가 있는 줄을 그대로 인용하십시오. 파일 경로를 참조하십시오. 가능하면 줄 번호를 인용하십시오. '문서가 더 좋을 수 있습니다'와 같은 일반적인 진부한 표현은 절대 사용하지 마십시오.
-
어조가 중요합니다. 기본값은
honest(솔직한)입니다.references/roast-voice-guide.md에 따라 어조를 전환하십시오.brutal(냉소적)은 재미있어야 하지만 개인적이지 않아야 합니다.kind(친절한)은 격려하지만 여전히 구체적이어야 합니다. -
행동 계획은 심각도 순이 아닌 영향 순으로 정렬됩니다.
impact × (1 / effort)공식을 사용하십시오. 10점을 올리는 5분 수정이 12점을 올리는 2시간 수정보다 위에 있습니다. -
URL을 절대 임의로 만들지 마십시오.
ideal-readme.md를 작성할 때는 누락된 링크에<placeholder>구문을 사용하십시오. 평가는 관리자가 채우도록 알려줍니다. -
관리자나 기여자의 이름을 절대 언급하지 마십시오. 작업을 평가하고 사람을 평가하지 마십시오.
-
정확히 네 개의 파일을
dx-roast/에 출력하십시오. 다른 위치에 쓰지 마십시오. 파일을 건너뛰지 마십시오.
1단계: 입력
필수:
repo— 로컬 경로(기본값.) 또는https://github.com/owner/repoURL
선택 사항:
| 매개변수 | 기본값 | 설명 |
|---|---|---|
tone | honest | brutal / honest / kind |
output_dir | dx-roast/ | 4개의 출력 파일을 쓸 위치 |
compare_to | 없음 | 벤치마크 비교를 위한 선택적 두 번째 저장소 URL |
repo가 URL인 경우: git clone <url> /tmp/dx-roast-<short-hash>를 사용하여 임시 디렉터리에 클론합니다. 거기서 스캔합니다. 실행 후 임시 디렉터리를 삭제합니다.
repo가 . 또는 로컬 경로인 경우: 해당 위치에서 스캔하고 아무것도 수정하지 않습니다.
2단계: 검색
다음 파일들을 읽습니다(각각 없을 수 있음 — 부재를 기록):
README.md— 전체 내용, 구조(헤딩), 코드 블록, 이미지 참조, 배지 URLCONTRIBUTING.md,CODE_OF_CONDUCT.md.github/ISSUE_TEMPLATE/,.github/PULL_REQUEST_TEMPLATE.md,.github/CODEOWNERSpackage.json(설명, 홈페이지, 저장소, 라이선스, 스크립트),pyproject.toml,Cargo.toml,go.modLICENSE(존재 여부 + 유형)docs/폴더 내용 (파일 이름 + 크기만)examples/또는samples/또는cookbook/폴더.github/workflows/*.yml(이름 + 간단한 CI 존재 여부 확인만)
repo가 URL인 경우 gh를 통해 다음도 가져옵니다:
gh api repos/<owner>/<repo> --jq '{stars: .stargazers_count, forks: .forks_count, watchers: .subscribers_count, pushed_at, description, homepage, topics, default_branch}'
gh api repos/<owner>/<repo>/commits --jq '.[0].commit.author.date' | head -1
gh api repos/<owner>/<repo>/contributors --paginate --jq '[.[] | .login] | length'
GitHub 호출이 실패하면 잡아내고 계속 진행합니다.
3단계: 10가지 차원 점수 매기기
references/scoring-rubric.md의 10가지 차원 각각에 대해 {score: 0–10, evidence: [...]}를 출력합니다. 여기서 evidence는 발견한 내용을 인용하는 1–3개의 짧은 문자열 목록입니다.
예시:
"visual_proof": {
"score": 4,
"evidence": [
"89번째 줄에서 스크린샷 1개 발견 (아래쪽)",
"애니메이션 데모 / GIF 없음",
"비디오 없음"
]
}
점수를 합산 → 총점 (0–100) → 등급 (루브릭 기준 A/B/C/D/F).
다음 정확한 형태로 dx-roast/score.json에 저장합니다:
{
"repo": "<owner/repo 또는 로컬 경로>",
"scanned_at": "<ISO 8601 타임스탬프>",
"dimensions": {
"time_to_first_success": { "score": 7, "evidence": ["..."] },
"what_is_this_clarity": { "score": 5, "evidence": ["..."] },
"visual_proof": { "score": 4, "evidence": ["..."] },
"install_simplicity": { "score": 9, "evidence": ["..."] },
"runnable_quick_start": { "score": 8, "evidence": ["..."] },
"documentation_depth": { "score": 6, "evidence": ["..."] },
"examples": { "score": 5, "evidence": ["..."] },
"community_signals": { "score": 3, "evidence": ["..."] },
"trust_signals": { "score": 7, "evidence": ["..."] },
"marketing_signals": { "score": 4, "evidence": ["..."] }
},
"total": 58,
"grade": "D",
"tone": "honest"
}
4단계: 평가 작성하기
references/roast-voice-guide.md를 읽습니다. 요청된 어조를 적용합니다. 250–500 단어를 dx-roast/roast.md에 작성합니다.
필수 구조:
# DX 평가: <저장소 이름>
**등급: <문자> (<총점>/100)** · 어조: <어조>
<첫 번째 문단: 평결. 잘하는 점 + 큰 격차.>
<두 번째 문단: 파일 참조와 함께 2개의 구체적인 발견 인용.>
<세 번째 문단: 2개의 추가 발견을 인용하고 차원 점수와 연결.>
<네 번째 문단(선택 사항): 마지막 반전 또는 알려진 좋은 저장소와의 비교.>
<마무리 문단: 향후 경로를 위해 `action-plan.md`를 참조하도록 안내.>
모든 평가는 score.json 증거 배열에서 최소 3개의 구체적인 발견을 참조해야 합니다.
5단계: 행동 계획 생성
각 후보 수정에 대해 priority = impact / effort_minutes를 계산합니다. 상위 5–10개를 선택합니다. 우선순위 내림차순으로 정렬합니다.
각 수정에 대해 dx-roast/action-plan.md에 작성:
### N. <명령형으로 수정 사항을 한 줄로>
**이유:** <한 문장으로 정당화. 어떤 차원을 개선하는지 참조.>
**영향:** +<X>점 · **노력:** <5분 / 30분 / 2시간 / 반나절>
**방법:**
1. <구체적인 단계 1>
2. <구체적인 단계 2>
3. <구체적인 단계 3>
<정확한 변경 사항을 보여주는 선택적 코드/마크다운 스니펫>
action-plan.md를 다음으로 시작:
# 행동 계획 — <저장소 이름>
현재 등급: <문자> (<총점>/100)
영향 × 노력으로 순위가 매겨진 상위 수정 사항. 순서대로 진행하세요.
---
6단계: 이상적인 README 생성
references/readme-template.md를 읽습니다. '채우기 규칙' 섹션에 따라 템플릿을 채웁니다. dx-roast/ideal-readme.md에 작성합니다.
누락된 값에는 <homepage_url> 등의 플레이스홀더를 사용합니다. 길이 제한: 100줄.
7단계: 터미널 요약
사용자에게 다음 정확한 형식을 출력합니다:
DX 평가 완료 — 등급: <문자> (<총점>/100)
영향 순 상위 3개 수정:
1. <수정 1> +<X>점 · <노력>
2. <수정 2> +<X>점 · <노력>
3. <수정 3> +<X>점 · <노력>
파일:
→ dx-roast/roast.md (공유 가능한 평결)
→ dx-roast/action-plan.md (우선순위 수정)
→ dx-roast/ideal-readme.md (목표 상태)
→ dx-roast/score.json (원시 점수)
compare_to가 제공된 경우 비교 줄을 추가합니다:
벤치마크: <다른 저장소> 점수 <X>/100 (등급 <Y>) — <차이>점 차이.
자체 QA (매 실행 시, 터미널 요약을 출력하기 전)
-
score.json의 모든 10가지 차원에 점수 + 증거가 있음 - 총점이 차원의 합과 일치함
- 등급 문자가 루브릭 임계값에 따라 총점과 일치함
- 평가가 score.json에서 최소 3개의 증거 항목을 참조함
- 평가에서 관리자/기여자의 이름을 언급하지 않음
- 행동 계획에 5–10개 항목이 있고 우선순위 내림차순으로 정렬됨
- 이상적인 README가 100줄 미만임
- 이상적인 README에서 스캔에서 찾을 수 없는 URL에
<placeholder>를 사용함 - 4개의 파일 모두 output_dir에 존재함
- roast.md 또는 action-plan.md에
<TBD>/<TODO>플레이스홀더가 없음
어느 검사라도 실패하면 해당 단계를 수정하고 다시 실행합니다.
오류 처리
다음 네 가지 실패 모드는 명시적으로 처리됩니다. — 스킬이 원인을 표시하지 않고 부분 출력을 조용히 생성하지 않도록 합니다.
| 경우 | 동작 |
|---|---|
repo가 존재하지 않거나 클론할 수 없거나 읽을 수 없음 | Repo not found or inaccessible: <repo> 메시지와 함께 즉시 종료합니다. 출력 파일을 쓰지 마십시오. |
README.md 누락 | 그래도 실행합니다. what_is_this_clarity, visual_proof, runnable_quick_start, marketing_signals를 0에 가깝게 점수 매깁니다. 평가의 도입부로 부재를 사용합니다("README가 없다는 것은 그 자체로 하나의 진술입니다"). |
| 저장소가 비공개이고 GitHub 인증을 사용할 수 없음 | 로컬 클론 시도(git clone <url>); 실패하면 Repo is private and no authentication is available 메시지와 함께 종료합니다. 사용자에게 GITHUB_TOKEN을 설정하거나 로컬 경로를 전달하도록 제안합니다. |
compare_to URL 실패(네트워크, 404, 비공개 등) | 벤치마크 없이 계속합니다. 평가에 한 줄을 추가합니다: 참고: <compare_to>에 대한 요청된 벤치마크를 가져올 수 없었습니다. 터미널 요약에서 Benchmark: 줄을 생략합니다. |
2단계 메타데이터 가져오기 중 GitHub API 오류(속도 제한, 일시적 5xx)는 잡아내고 score.json의 trust_signals.evidence 아래에 "github metadata unavailable"로 기록됩니다. 나머지 실행은 계속됩니다.
예시
좋은 호출:
"내 저장소 https://github.com/myorg/mytool 을 평가해줘 — 어조: brutal."
→ 스킬이 클론, 스캔, 점수 매기고 4개의 파일을 dx-roast/에 작성하고 요약을 출력합니다. 일반적인 저장소의 경우 총 실행 시간 <60초.
좋은 비교:
"현재 디렉터리에서 DX 감사를 실행해. https://github.com/vercel/next.js 와 비교해줘."
→ 둘 다 스캔하고, 현재 저장소에 점수를 매기고, 평가와 요약에 벤치마크 줄을 포함합니다.
이 스킬이 하지 않는 일
- 대상 저장소를 수정하지 않음(읽기 전용 스캔)
- 보안 감사 또는 종속성 스캔을 실행하지 않음
- 마케팅 카피를 생성하지 않음(행동 항목은 구체적이며 "어조에 맞게 다시 작성"이 아님)
- 이미지나 자산을 생성하지 않음(플레이스홀더만)
- 소셜 미디어에 게시하지 않음(공유 가능한 텍스트만 작성)