karix-ai/readme-that-sells

README that sells

README는 문서가 아닙니다. git 레포지토리에 우연히 살게 된 랜딩 페이지입니다. 방문자는 약 15초 안에 별표를 누를지, 사용해볼지, 떠날지 결정합니다. 접히는 부분 위의 모든 내용은 별표를 얻기 위해 노력해야 합니다. 설명서는 접히는 부분 아래나 docs/에 둡니다.

15초 테스트

무엇이든 쓰기 전에, 다음 질문에 각각 한 줄로 답하세요. 답할 수 없다면 README도 답할 수 없습니다.

1. 무엇인가요? 형용사 없이 한 문장. "Zig로 작성된 AI 에이전트용 헤드리스 브라우저."
2. 왜 존재하나요? 사용자의 말로 표현한, 제거하는 고통. "Chrome은 탭당 500MB를 먹습니다. 에이전트는 50개의 탭이 필요합니다."
3. 작동 증명. 데모 GIF, 벤치마크 숫자, 또는 전후 비교. 기능 목록이 아닙니다.
4. 한 명령어로 어떻게 시도하나요? npx ..., pip install ..., curl ... | sh, docker run ....

구조 (이 순서대로, 예외 없음)

# 프로젝트-이름
한 문장 피치. (무엇 + 누구를 위한 + 훅)

[데모 GIF 또는 스크린샷 — 10초 미만, 설정이 아닌 결과를 보여줌]

## 설치           ← 한 명령어, 복사-붙여넣기 가능, 숨은 전제 조건 없음
## 이유           ← 3~5줄: 고통, 기존 대안, 이것이 다른 점
## 사용법         ← 가장 일반적인 사례, 실행 가능한 예제로
## 기능           ← 선택 사항, 짧은 불릿 목록, 마케팅 형용사 없음
## 작동 원리      ← 선택 사항, 한 문단 또는 하나의 다이어그램
## 비교           ← 선택 사항, 2~3개 대안과의 표, 장단점을 솔직하게
## 기여 / 라이선스

규칙

• 피치 라인: ≤ 15 단어. 카테고리와 차별점을 명시하세요. "엄청 빠른", "강력한", "간단하면서도" 같은 표현은 피하세요. 숫자가 있다면 숫자를 사용하세요: "Claude Code 토큰 사용량을 40% 줄입니다."
• 데모 우선, 글자는 그 다음. GIF나 스크린샷은 피치 바로 아래에 배치하세요. 아직 데모가 없다면 출시 전에 만드세요(demo-gif 스킬 참조). 데모가 없는 README는 데모가 있는 것에 비해 전환율이 훨씬 낮습니다.
• 설치는 하나의 블록, 하나의 명령어. API 키나 설정 파일이 필요하다면 같은 블록에 함께 보여주세요. 숨은 전제 조건은 클론 후 사람들이 떠나는 #1 이유입니다.
• '이유'는 이미 솔루션이 있는 사람을 위해 작성하세요. 대안의 이름을 명시하세요. 그들이 잘하는 점을 말하세요. 그런 다음 이것이 그들이 하지 못하는 한 가지를 말하세요. 독자는 경쟁자에게 공정한 README를 신뢰합니다.
• 제목에 이모지는 사용하지 마세요. 프로젝트가 의도적으로 장난스럽지 않은 한. 피치 위에 배지는 없음(배지 벽은 방문자가 가장 먼저 스크롤 지나치는 부분입니다). 피치 아래에 2~3개의 배지는 괜찮습니다: 빌드 상태, 버전, 라이선스.
• 하나의 실제 예제가 열 개의 기능 불릿보다 낫습니다. 입력 → 출력을 보여주세요. 독자가 실제로 실행할 만한 것으로 만드세요.
• 아닌 것을 말하세요. 솔직한 범위 한 줄("Playwright를 대체하지 않음; 아직 JS 렌더링 없음")은 Hacker News의 첫 적대적 댓글을 예방합니다.
• 가지고 있는 사회적 증거를 링크하세요. "X에서 사용", 벤치마크, Show HN 스레드. 꾸며내지 마세요.
• 상위 60줄에는 처음 방문자에게 필요하지 않은 것은 두지 마세요. 아키텍처, 로드맵, FAQ, 변경 로그: 모두 아래 또는 다른 곳에.

전환을 죽이는 안티 패턴

• 배경 또는 역사 문단으로 시작하기.
• 페이지 첫 번째 요소로 목차.
• '설치'보다 앞선 '기능'.
• 사용을 위한 도구임에도 '먼저, 레포지토리를 클론하세요'로 시작하는 설치 안내.
• 결과 대신 설정 파일의 스크린샷.
• 마케팅 어조("혁신적인", "차세대", "손쉽게").
• 죽은 플레이스홀더("TODO: 데모 추가").

절차

1. 현재 README(있는 경우)와 코드의 진입점을 읽으세요. 15초 테스트에서 네 가지 답변을 추출하세요.
2. 피치 라인을 초안하세요. 세 가지 변형을 쓰고, 가장 구체적인 명사와 가장 적은 형용사가 있는 것을 고르세요.
3. 설치, 사용법, 이유 순서로 작성하세요. Install의 모든 명령어를 깨끗한 디렉토리에서 실행하여 작동하는지 확인하세요.
4. 피치 아래에 데모를 삽입하세요. 아직 없으면 TODO(demo) 표시를 추가하고 사용자에게 출시를 막는다고 알리세요.
5. 접히는 부분 위에서 "낯선 사람이 결정하는 데 필요한가?"라는 질문에 실패하는 모든 것을 삭제하세요.
6. 상위 60줄을 회의적인 엔지니어의 눈으로 읽으세요. 탭을 닫게 만들 첫 번째 것을 수정하세요.

출력

전체 README.md를 반환하세요. 그런 다음, 5개 불릿 이하로 무엇을 변경했고 사용자가 여전히 제공해야 할 것(데모 GIF, 벤치마크 숫자, 실제 사용자 인용)을 나열하세요.