/brag-more
만들었으니, 이제 저장소도 자랑하게 하세요. README는 GitHub에서 누구나 가장 먼저 보는 것입니다. 이를 5초 안에 프로젝트를 팔고 낯선 사람이 1분 안에 실행해 볼 수 있게 만드는 프론트 페이지로 바꾸세요.
프로젝트가 무엇이든, 결과물은 사랑받는 오픈소스 프로젝트의 README처럼 느껴져야 합니다: 자신감 있고, 훑어보기 쉽고, 시각적이며, 진실해야 합니다. 페이지에 자리를 차지할 가치가 없는 것은 없어야 합니다.
사용법: /brag-more [옵션]. 옵션 (플래그 또는 일반 언어):
| 옵션 | 기본값 |
|---|---|
--style clean|bold|minimal|showcase | 프로젝트에서 유추 (스타일 참조) |
--preview | 꺼짐: README.md를 제자리에 씁니다. 켜짐: brag-output/repo/에만 쓰고 README.md는 건드리지 않습니다 |
--no-banner | 배너 켜짐 |
--no-video | 꺼짐: 프로젝트에 브래그 비디오가 없으면 먼저 만듭니다 (비디오 참조) |
--no-demo | 보여줄 것이 있을 때 데모 켜짐 |
작업 파일은 brag-output/repo/에 들어갑니다 (brag-output/가 이미 있고 이번 실행에서 생성된 것이 아니면 brag-output-YYYY-MM-DD-HHmmss/repo/에 타임스탬프가 찍힙니다). README가 참조하는 자산은 저장소의 .github/readme/에 들어가 함께 배포됩니다.
1. 검사
오래된 README뿐만 아니라 프로젝트를 읽으세요:
- 기존 README, 모든 줄. 사용자가 작성한 것입니다. 사실이고 유용한 내용(설치 단계, 구성 표, 크레딧, 라이선스 정보, 스폰서 링크, 감사 인사)은 유지하고 스타일을 다시 지정하세요. 버리지 마세요.
- 정체성: 스타일시트나 테마 구성에서 정확한 브랜드 색상과 글꼴, 로고 또는 파비콘, 기존 히어로 이미지 또는 OG 이미지.
- 무엇인지: 패키지 매니페스트 (
package.json,pyproject.toml,Cargo.toml,go.mod, ...)에서 이름, 설명, 버전, 라이선스, 바이너리 및 스크립트를 확인합니다. 실제 기능을 위한 진입점과 주요 경로 또는 명령어. - 실행 방법: 매니페스트 스크립트,
Makefile,justfile, Dockerfile 또는 CI 워크플로우의 실제 설치 및 시작 명령어. 프로젝트가 고정한 런타임 버전을 기록하세요. - 배지 신호:
LICENSE,.github/workflows/*, 패키지가 게시되었는지 여부 (npm, PyPI, crates.io — 매니페스트의 이름과private플래그 확인), Git 리모트 (git remote get-url origin)에서owner/repo확인. - 기존 브래그 출력:
brag-output*/brag.mp4와brag.jpg가 있다면, 이 기계에서 가장 좋은 데모 자료입니다. 가장 최신 것을 사용하세요. 없으면 다음 단계에서 만듭니다.
빌드 출력, 잠금 파일, .git/, env 및 비밀 파일 (.env, .env.*), 키 및 자격 증명 자료, 그리고 .gitignore가 이러한 이유로 제외하는 모든 것은 건너뛰세요.
쓰기 전에 답하세요: 그것은 무엇인가 (낯선 사람이 이해할 수 있는 한 문장)? 누구를 위한 것인가? 대안보다 더 잘하는 한 가지는 무엇인가? 시각적 훅 — 스크린샷, GIF, 또는 배너 중 사람들이 스크롤을 멈추게 만드는 것은 무엇인가? 3~5가지 실제 기능은 무엇인가? 클론에서 실행까지 가장 짧은 경로는 무엇인가?
README는 공개됩니다. 절대 비밀, 토큰, 내부 호스트 이름, 실제 고객 또는 사용자 이름, 이메일 주소 또는 기타 개인 데이터를 README나 이미지에 포함시키지 마세요. 스크린샷에 그러한 데이터가 표시되면 그럴듯한 가상의 대체 데이터로 바꾸세요.
비디오 (계획 전, 아직 없을 때)
README의 최고의 데모는 프로젝트의 런칭 비디오이므로, brag-more는 없을 때 만듭니다. --no-demo 또는 --no-video가 설정되었거나 brag-output*/brag.mp4가 이미 존재하면 이 단계를 건너뜁니다.
/brag스킬이 설치되어 있으면 (스킬 목록 확인), Skill 도구를 통해 이 프로젝트에 대해 실행하고--tone또는 형식 희망 사항을 전달합니다. 사용자에게 "런칭 비디오가 아직 없어서 /brag로 먼저 만들고 있어요."라고 한 줄로 알립니다.- 그렇지 않으면
<skill-dir>/video.md(여기에 번들된 brag-slim의 간결한 비디오 워크플로우)를 읽고 따릅니다. 기계에 이미 있는 도구만 필요합니다. - 완료되면 비디오, 포스터 및 공유 복사본이
brag-output/에 있습니다. 데모로 사용하여 README 작업을 계속합니다.
비디오 만들기가 실패하거나 사용자가 기다리지 않으려면, 비디오 없이 계속하고 데모 아래의 대체 자료를 사용합니다.
2. 계획
brag-output/repo/readme-plan.md를 작성합니다: 한 줄짜리 설명, 선택한 스타일, 섹션 순서, 만들 시각 자료와 각각이 보여줄 내용, 정당화된 배지 (및 각각의 증거), 그리고 기존 README에서 유지할 내용.
형태: 템플릿이 아닌 시작 형태입니다. 비어 있거나 채울 내용이 없는 섹션은 버리세요.
- 히어로 — 애니메이션 SVG 히어로 (빌드 참조), 그 다음 가운데 정렬: 한 줄짜리 설명, 짧은 배지 행, 링크 탐색 줄 (데모 · 설치 · 문서 · ...).
- 데모 — 사용 중인 제품, 히어로 바로 아래, 프레임 처리됨: 브래그 비디오 루프, 실제 UI의 GIF, 또는 터미널 녹화. 하나의 큰 시각 자료.
- 왜 — 2
4 문장: 사용자를 위해 무엇을 하는지, 차별점은 무엇인지, 프로젝트 자체의 언어로 설명합니다. 개발자 도구의 경우, 단락보다는 그 자체가 피치인 35줄의 코드 블록이 더 효과적입니다 (bun run index.tsx # TS와 JSX를 기본 지원). - 기능 쇼케이스 — 3~6개의 실제 기능, 각각 자체 작은 시각 자료: 실제 UI의 잘린 스크린샷, 명령별 터미널 GIF, 또는 코드 스니펫과 그 출력. 시각 자료가 있는 것은 나란히 카드로 배치합니다 (빌드 참조). 텍스트 전용 기능은 굵은 소개와 한 줄을 사용합니다.
- 퀵스타트 — 복사하여 붙여넣을 수 있고, 순서대로, 모든 명령어가 프로젝트에 대해 검증됨. 사전 요구 사항을 먼저 제시합니다.
- 사용법 — 한두 개의 실제 예제: 명령어와 그 출력, 코드 스니펫, 또는 구성 블록.
- 작동 방식 — 선택 사항. 아키텍처가 흥미로운 부분일 때 짧은 단락 또는 Mermaid 다이어그램.
- 기존 README의 나머지 모든 것 — 구성, FAQ, 로드맵, 기여, 크레딧 — 정리하고, 길면
<details>로 접습니다. - 푸터 — 라이선스 줄, 그리고 닫는 아트 스트립 (빌드 참조).
README 법칙
- 진실. 모든 주장, 숫자, 기능 및 배지는 프로젝트에 의해 뒷받침되어야 합니다. 지어낸 별, 다운로드 수, 벤치마크, 사용 후기 또는 "사용처" 로고는 없습니다. 배지는 가리키는 대상이 존재할 때만 나타납니다 (게시된 패키지, 실제 워크플로우, 라이선스 파일).
- 실행 가능. 퀵스타트와 사용법의 모든 명령어는 작성된 그대로 프로젝트에 존재합니다. 안전하게 실행할 수 있다면 (설치, 빌드,
--help, 테스트), 실행하세요. 단계에 비밀 또는 유료 서비스가 필요하면 숨기지 말고 솔직하게 말하세요. - 5초 테스트. 트윗에서 저장소를 방문한 사람이 그것이 무엇인지 알고, 작동하는 모습을 보며, 첫 화면을 스크롤하지 않고 설치 명령어를 찾을 수 있습니다.
- 제품을 보여주세요. 데모는 로고 애니메이션이나 추상적인 아트가 아닌 실제 제품이 사용 중인 모습을 보여줍니다. 실제 UI, 실제 CSS, 실제 카피를 재사용하세요.
- 저장소가 무엇인지 말하세요. 저장소가 제품의 웹사이트, 랜딩 페이지 또는 데모라면 한 줄짜리 설명에 그렇게 말하세요. 사람들이 저장소가 제공하지 않는 앱을 다운로드하거나 패키지를 설치할 수 있다고 암시하지 마세요.
- 구체적. 정확히 이 프로젝트를 위해 작성된 느낌이 들어야 합니다. "번개처럼 빠른", "매끄러운", "차세대", "워크플로우 간소화"는 프로젝트가 측정 가능하게 입증하지 않는 한 금지됩니다.
- 훑어보기 쉽게. 짧은 단락, 의미 있는 제목, bullet 당 하나의 아이디어. 제목의 이모지는 프로젝트 자체의 어조가 사용하는 경우에만, 그리고 드물게 사용하세요 (
showcase스타일은 예외: 섹션 제목당 하나의 이모지, 설계상). - 두 테마 모두. GitHub 독자는 라이트 모드와 다크 모드를 사용합니다. 모든 이미지는
#ffffff와#0d1117모두에서 올바르게 보여야 합니다: 보이는 가장자리가 있는 투명 PNG, 또는 테마당prefers-color-scheme소스가 있는<picture>. - 열에 맞게. README 열은 데스크탑에서 약 830px 너비이고, 전화에서는 훨씬 좁습니다. 배너 텍스트는 전화 너비로 조정될 때도 읽기 쉬워야 합니다. 표는 열이 적어야 합니다. 모바일에서 깨지는 넓은 원시 HTML 레이아웃은 없습니다.
- 모든 링크가 작동합니다. 상대 링크는 존재하는 파일을 가리킵니다. 앵커는 실제 제목과 일치합니다.
스타일
| 스타일 | 느낌 | 사용 시기 |
|---|---|---|
clean | 절제된 움직임의 애니메이션 히어로, 프레임 처리된 데모, 깔끔한 카드 | 대부분의 프로젝트; 기본값 |
bold | 브랜드 색상의 전체 너비 히어로, 더 큰 애니메이션 모멘트, 강력한 한 줄짜리 설명, 데모가 전면 중앙에 | 소비자 앱, 장난기 있는 프로젝트, 런칭 |
minimal | 작은 애니메이션 로고 조합 + 이름 + 한 줄짜리 설명, 평범한 섹션 | 라이브러리, CLI, 인프라, 진지한 도구 |
showcase | 밀도 높은, 이모지 섹션으로 구성된 기술 README (수상 경력의 해커톤 또는 연구 프로젝트 생각): 상단에 제품의 실제 스크린샷, 수상 또는 상태 줄, 그 다음 주제당 하나의 이모지가 앞에 오는 섹션 | 해커톤, 연구, ML, 데이터 또는 과학 프로젝트; 보여줄 실제 깊이가 있는 모든 것. 사용자가 "Find My Shark 같은 것" 또는 상세한 문서 스타일의 README를 요청할 때 선택하세요 |
showcase 레시피
소유자의 Find-My-Shark README에서 모델링했습니다. 작동하게 만드는 요소를 유지하고, 작동하지 않는 요소를 수정하세요:
- 하나의 이모지가 있는 제목과 그 아래 성과 줄 ("NASA Space Apps 2025, Galactic Impact Winner"), 프로젝트가 실제로 획득한 경우에만. 기존 README에서 묻거나 읽으세요. 절대 지어내지 마세요.
- 제목 바로 아래의 실제 스크린샷 또는 데모 GIF, 프레임 처리됨 (데모, 프레임 처리됨 참조). 애니메이션 히어로는 무언가를 추가할 때만 유지하세요. 여기서는 실제 제품이 주인공입니다.
- 2~3줄의 피치와 "왜 중요한지" 줄, 그 다음 각각 하나의 이모지로 시작하는 섹션: 기능, 지역/범위 또는 입력, 데이터 소스 (표), 작동 방식 또는 수학적 모델, 빠른 시작 (설치, 기본 사용법, API 사용법), 프로젝트 구조 (주석이 달린 트리), 구성 (실제 구성), 출력 파일, 명령줄 옵션, 배경, 향후 확장, 테스트, 로깅, 마무리 태그라인.
- 프로젝트에 실제 내용이 있는 섹션만 포함하세요. 해커톤 수준의 깊이가 포인트이므로, 구체적인 내용(매개변수, 공식, 임계값, 데이터 세트 이름 및 프로젝트 트리)을 유지하세요.
- 일반적인 실수 수정: 실제 클론 URL 사용 (절대
your-username사용 금지), 프로젝트 트리 코드 블록의 오래된 항목을 실제 존재하는 것으로 교체, 섹션이 6개 이상이면 목차 또는 빠른 링크 행 추가, 긴 참조 섹션 (CLI 옵션, 전체 구성, 과학적 배경)을<details>로 감싸기, 실제 스택에 대한 배지 추가 (Python 버전, 라이선스, 주요 라이브러리), 두 테마를 위한<picture>또는 프레임 처리된 스크린샷, 그리고 전달 시 저장소 설명과 주제 설정. - 이모지가 있는 앵커: GitHub는 제목의 슬러그에서 이모지를 제거하지만 하이픈은 유지하므로
## 🚀 Quick Start는#quick-start가 아닌#-quick-start가 됩니다. 모든 탐색 링크와 배지 링크를 그런 방식으로 작성하고 각각이 제목과 일치하는지 확인하세요.<details>요약은 제목이 아니며 앵커가 없습니다. - 여전히 모든 README 법칙 (진실, 실행 가능, 두 테마)과 확인 단계를 따르세요.
3. 빌드
GitHub에서 가장 좋은 README(Excalidraw, Scalar, Supabase, Charm, Rich, Bun)는 몇 가지 공통된 움직임을 공유합니다. 모두 사용하세요. 이것이 이 README가 스크롤을 멈추게 만드는 이유입니다.
히어로: 애니메이션 SVG
이것이 시그니처입니다. 정적 배너는 템플릿처럼 읽힙니다. 프로젝트 고유의 색상, 글꼴 및 UI로 움직이는 히어로는 이 프로젝트를 위해 만들어진 것으로 읽힙니다. GitHub는 CSS @keyframes가 실행되는 <img> 태그에서 SVG를 렌더링하므로, 히어로는 GIF의 밴딩이나 무게 없이 애니메이션될 수 있습니다.
.github/readme/hero.svg를 빌드하세요 (viewBox 약 1600×800, width="100%"로 렌더링):
- 장면은 제품입니다. 프로젝트의 실제 히어로 또는 주요 화면을 SVG 모양으로 재현하세요: 배경 이미지, 자체 글꼴의 헤드라인, 그리고 작업을 수행하는 실제 UI 요소 하나 (카드 스와이프, 명령어 입력, 차트 그리기, 토스트 표시). 하나의 아이디어, 하나의 루프.
- 모션: SVG 내부
<style>블록의 CSS@keyframes,transform과opacity에만 사용하고, 크기 조정 또는 회전하는 모든 것에transform-box: fill-box; transform-origin: center를 사용하세요. 6~10초 루프로 시작 프레임으로 원활하게 돌아오고, 입장은 시간차를 두고, 모든 텍스트 줄은 읽을 수 있을 만큼 오래 정착됩니다. 배경에 느린 드리프트를 추가하세요 (루프 동안 1.0 → 1.05 스케일). 프레임이 결코 정지된 느낌을 주지 않도록 합니다. CSStransform은 요소의 SVGtransform속성을 대체하므로, 외부<g transform=…>으로 요소를 배치하고 내부 요소를 애니메이션하세요. - 모션 감소: 키프레임을
@media (prefers-reduced-motion: no-preference)로 감싸서, 옵트아웃한 독자는 완료되고 정착된 프레임을 보게 합니다. 정착된 프레임은 자체적으로 게시 가능해야 하고 제품을 보여줘야 하므로, 루프 중간에만 나타나는 모든 것 (매치 오버레이, 토스트)은opacity="0"속성으로 숨겨진 상태로 시작하고 키프레임에 의해서만 드러나야 합니다. - 자체 포함.
<img>를 통해 로드된 SVG는 아무것도 가져올 수 없습니다: URL로 웹 폰트, 외부 이미지, 스크립트 없음. 글꼴을 base64@font-face로 포함시키거나 (Google Fonts의latin파일은 이미 ~20 KB이며 전체를 포함시킬 수 있음;pyftsubset … --text="…" --flavor=woff2로 다른 글꼴을 서브셋팅하며, 최신 fontTools 필요), 텍스트를 경로로 변환하세요. 사진을 base64 JPEG로 포함시키고, 히어로에 필요한 크기로 조정하세요.<foreignObject>는 피하세요 (Safari가<img>내부에서 렌더링하지 않음). 파일을 ~1.5 MB 미만으로 유지하세요. - 두 테마 모두. 히어로가 전체 너비이고 불투명하면 두 테마에서 모두 작동합니다. 그렇지 않으면
hero-dark.svg도 만들고<picture>또는#gh-dark-mode-only/#gh-light-mode-onlyURL 조각으로 전환하세요. - 텍스트: 프로젝트 이름과 한 줄짜리 설명, 크게 (히어로는 전화에서 ~40%로 축소됨). 다른 것은 없습니다.
<p align="center">
<a href="<사이트 또는 데모 링크>"><img src=".github/readme/hero.svg" alt="<프로젝트> — <한 줄짜리 설명>" width="100%"></a>
</p>
또한 저장소의 소셜 카드용으로 정착된 프레임을 1280×640으로 .github/readme/social-preview.png (불투명)에 캡처하세요. 모션 감소를 켠 상태에서 헤드리스 브라우저에서 SVG를 렌더링하세요.
프로젝트에 애니메이션할 가치가 있는 시각적 정체성이 없는 경우 (UI가 없는 라이브러리), 대신 애니메이션 워드마크를 만드세요: 적합한 글꼴의 이름, 그것이 무엇을 하는지 말해주는 하나의 모션 (파이프를 통해 흐르는 값, 포맷되는 텍스트, 초록색으로 변하는 테스트).
데모, 프레임 처리됨
선호도 순서:
- 브래그 비디오. 검사 단계에서 찾거나 비디오 단계에서 만든 것.
brag.mp4가 있다면, 가장 강력한 4~8초에서 반복 미리보기 GIF 또는 애니메이션 WebP를 만드세요.