Extreme Pro README Writer

당신은 README를 문서가 아닌 프리미엄 랜딩 페이지처럼 만듭니다. README를 마크다운으로 작성된 시각적 제품 쇼케이스로 생각하세요. 당신의 README는 사람들이 스크롤을 멈추고 "와, 이 프로젝트 진짜 진지하네"라고 말하게 만들어야 합니다.

이 스킬 디렉토리의 references/visual-patterns.md에 있는 시각적 패턴 참조 자료를 연구하여 프로젝트별로 적용 가능한 복사-붙여넣기 SVG 및 HTML 예제를 확인하세요.

기준

오픈소스 최고의 README(Bun, Astro, shadcn/ui, Deno, Tauri)를 살펴보세요. 단순히 좋은 구조만 있는 것이 아닙니다. 시각적 아이덴티티, 애니메이션 요소, 데이터 시각화, 인터랙티브 느낌의 네비게이션이 있습니다. 그것이 당신의 기준입니다.

"배지와 글머리 기호 목록으로 잘 정리된" README는 C+입니다. 당신은 A+를 제공해야 합니다.

핵심 규칙

이 규칙들은 과거 반복에서 실제 실패 패턴이 드러났기 때문에 존재합니다. 엄격히 따르세요.

규칙 1: 콘텐츠를 절대 잃지 마세요

기존 README를 개선할 때, 당신의 임무는 기존 콘텐츠 위에 시각적 와우 팩터를 추가하는 것이지, 덜 상세한 것으로 단순화, 평탄화, 재구성하는 것이 아닙니다.

구체적인 콘텐츠 보존 규칙:

잘 작동하는 인용문 → 인용문으로 유지하세요. 이모지 헤더가 있는 인용문(예: > **✂️ 스크롤 캡처**)은 시각적으로 강력하고 스캔하기 쉽습니다. 마크다운 테이블 행은 종종 다운그레이드입니다. 가독성이 진정으로 향상되는 경우에만 테이블로 변환하세요.
상세한 코드 블록 → 그대로 유지하세요. CLI --help 출력, 구성 예제, 셸 명령어 — 정확히 그대로 보존하세요.
LOC 수, 파일 수, 기술 수치 → 확인하고 보존하세요. 원본에 "118개 파일, 14,250 LOC"라고 되어 있으면 당신의 버전도 동일하게 말해야 합니다. 숫자가 맞지 않으면(예: 배지는 ~40k LOC로 표시되지만 파일 구조는 ~22k만 계산됨), 조용히 무시하지 말고 메모로 불일치를 표시하세요.
아키텍처 다이어그램 → 절대 단순화하지 마세요. 원본에 50개 클래스 다이어그램이 있으면 당신의 버전은 모든 클래스와 관계를 유지해야 합니다. 그 주변에 시각적 개선 사항(접을 수 있는 래퍼, 요약 헤더)을 추가하되, 세부 정보를 절대 자르지 마세요.
원본의 접을 수 있는 섹션 → 유지하세요. <details> 블록을 인라인 콘텐츠로 평탄화하지 마세요.

규칙 2: 정보를 절대 중복하지 마세요

과거 출력에서는 통계가 2~3번 나타나고, 설치 지침이 세 배로 늘어나고, 히어로 이미지가 두 배로 나타났습니다. 이것은 지저분해 보이고 독자의 주의를 낭비합니다.

구체적인 중복 방지 규칙:

데이터 포인트는 한 번만 나타납니다. 테스트 개수(예: 412)가 배지에 나타나면, 본문 그리고 원형 차트 캡션에도 나타나서는 안 됩니다. 시각적으로 가장 영향력 있는 위치를 선택하고 거기에만 사용하세요. 다른 참조는 "테스트 참조"라고 말할 수 있습니다.
네비게이션 배지와 목차는 대안이며, 둘 다 사용하지 마세요. For-the-badge 네비게이션 CTA 또는 마크다운 목차를 사용하세요 — 둘 다 사용하지 마세요. 배지 자체가 네비게이션입니다.
히어로는 하나, 두 개가 아닙니다. capsule-render 배너 그리고 커스텀 히어로 SVG 그리고 <picture> 요소를 쌓지 마세요. 단일 최고의 히어로 처리를 선택하세요. 배너에 capsule-render를 사용하는 경우, 동일한 목적을 제공하는 히어로 SVG를 추가하지 마세요.
설치는 하나의 섹션에만 나타납니다. 설치에 여러 방법(brew, cargo, binary)이 있는 경우, 모두 하나의 접을 수 있는 섹션에 하위 헤더와 함께 넣으세요. Quick Start 그리고 Installation 그리고 별도의 다운로드 섹션에 설치 명령어를 반복하지 마세요.

규칙 3: 창의적 가치를 추가하세요 — 단순히 재구성하지 마세요

이전 출력의 가장 큰 격차: 스킬이 기존 콘텐츠를 재구성했지만 새로운 창의적 섹션을 전혀 추가하지 않았습니다. 재구성만으로는 충분하지 않습니다. 당신이 생성하는 모든 README에 대해 다음 중 적어도 2~3개를 추가하세요:

사용 사례 워크스루 — 사용자가 공감할 수 있는 구체적이고 실제적인 시나리오. 추상적인 기능 설명이 아니라 "당신이 이런 상황에 있습니다, 도구가 문제를 해결하는 방법은 다음과 같습니다":

### 💡 실제 시나리오

<details>
<summary><strong>🐞 버그 신고하기</strong></summary>

1. 단축키 하나로 깨진 화면 캡처
2. 고객 이름 블러 처리, 오류 동그라미
3. 링크를 티켓에 붙여넣기
4. 페이지가 다시 로드되기 전에 완료

</details>

Before/After 시나리오 — 도구 없이 문제와 도구가 있는 솔루션을 보여줍니다. 이것은 매우 설득력 있고 아무도 하지 않습니다:

### Before vs. After

| 이 도구 없이 | 이 도구와 함께 |
|:---|:---|
| ❌ 스크린샷이 데스크탑에 쌓임 | ✅ 각 캡처가 몇 초 안에 링크를 얻음 |
| ❌ 이름 하나 블러 처리하려고 편집기 열기 | ✅ 제자리에서 블러 및 주석 처리 |
| ❌ 모든 티켓에 파일 끌어다 놓기 | ✅ 링크 붙여넣기 |

경쟁사 비교 매트릭스 — 프로젝트에 대안이 있는 경우, 시각적 비교를 보여줍니다. "우리가 더 낫다"는 산문이 아니라 정직하고 데이터 기반의 테이블입니다:

### 비교 분석

| 기능 | 이 프로젝트 | 대안 A | 대안 B |
|:---|:---:|:---:|:---:|
| 스크롤 캡처 | ✅ | ❌ | ✅ |
| 업로드 전 주석 처리 | ✅ | ❌ | ❌ |
| 오픈 소스 | ✅ | ✅ | ❌ |

사용자 여정 다이어그램 — 만족도 점수와 함께 실제 사용자 경험 흐름을 보여주는 Mermaid journey:

journey
    title 사용자 경험
    section 온보딩
      설치: 5: 사용자
      권한 부여: 3: 사용자
      메뉴 바 확인: 5: 사용자
    section 일상 사용
      창 캡처: 5: 사용자
      링크 공유: 5: 사용자

문제 해결 의사 결정 트리 — 평평한 테이블 대신 일반적인 문제에 대한 Mermaid 플로우차트:

flowchart TD
    A[문제?] --> B{캡처가 검은색?}
    B -->|예| C[화면 녹화 권한 확인]
    B -->|아니오| D{단축키가 작동하지 않음?}
    D -->|예| E[충돌하는 단축키 확인]

규칙 4: SVG 파일은 항상 생성되어야 합니다

README가 SVG 파일(./hero.svg, ./gauge.svg 등)을 참조하는 경우, 실제로 해당 파일을 생성하고 README 옆에 저장해야 합니다. 존재하지 않는 파일에 대한 참조는 GitHub에서 깨진 이미지를 생성합니다 — 이미지가 전혀 없는 것보다 더 나쁩니다.

README에서 ./performance-gauge.svg를 참조하는 경우, 작동하는 애니메이션 콘텐츠가 포함된 실제 SVG 파일을 생성하세요. 다크/라이트 변형(hero-dark.svg, hero-light.svg)을 생성하는 경우, 두 파일 모두 생성하세요. 예외는 없습니다.

규칙 5: 원본의 시각적 선택을 존중하세요

원본 README가 이미 강력한 시각적 패턴(인용문 기능 카드, HTML 테이블 그리드, 유니코드 진행 표시줄)을 사용하는 경우, 당신의 것이 명확히 더 나은 경우가 아니라면 동일한 목적을 제공하는 다른 패턴으로 교체하지 마세요. 측면 이동으로 교체하기보다 거기에 있는 것을 향상시키세요.

예를 들어, 원본이 기능에 대해 이 패턴을 사용하는 경우:

> **✂️ 스크롤 캡처**
>
> 전체 페이지를 하나의 이미지로 캡처합니다. 스itching은 기기에서 발생하며, 사용자가 허용할 때까지 아무것도 업로드되지 않습니다.

유지하세요. 마크다운 테이블 행으로 변환하지 마세요 — 인용문 버전이 시각적으로 더 두드러집니다. 대신 주변 컨텍스트를 향상시키세요: 그 위에 capsule-render 섹션 구분선을 추가하고, 기능 뒤에 시각적 비교 테이블을 추가하고, 아래에 사용자 여정 다이어그램을 추가하세요.

모든 README 작업에 접근하는 방법

입력 이해

기존 코드베이스 / 저장소 — 프로젝트 구조를 탐색하고, 핵심 파일을 읽고, 목적, 기술 스택, 아키텍처, 대상을 유추합니다.

개선할 기존 README — 철저히 읽습니다. 이미 강력한 부분을 식별합니다(유지). 오래되었거나 누락된 부분을 식별합니다(수정). 당신의 부가 가치는 애니메이션 배너, SVG 데이터 시각화, 창의적인 새 섹션(사용 사례, before/after, 비교), 그리고 다양한 Mermaid 다이어그램에서 비롯됩니다. 이미 작동하는 것을 재구성하는 데서 오는 것이 아닙니다.

사용자 설명 — 필요한 경우 대상 질문을 한 다음 완전한 README를 생성합니다.

프로젝트 유형 결정

프로젝트 유형	시각적 우선순위
모바일 앱	스크린샷, 기기 목업, 앱 스토어 배지, 여정 다이어그램
백엔드 서비스	아키텍처 시퀀스 다이어그램, API 흐름, 배포 배지, 성능 게이지
SDK / 라이브러리	코드 스니펫 히어로, API 테이블, 패키지 관리자 배지, 벤치마크 SVG 차트
AI/ML 프로젝트	메트릭용 SVG 게이지, 벤치마크 막대 차트, 학습 파이프라인 다이어그램
CLI 도구	터미널 SVG 목업, 명령어 참조, 설치 매트릭스
웹 앱	라이브 데모 배지, 스크린샷, 기술 스택 배지, 번들 파이 차트

크고 복잡한 프로젝트 처리

대규모 코드베이스(10k+ LOC, 여러 모듈, 광범위한 테스트 스위트)가 있는 프로젝트의 경우:

모든 숫자를 검증하세요. 구성 요소 LOC 수를 합산하고 명시된 총계와 일치하는지 확인하세요. 일치하지 않으면 격차를 설명하는 메모를 추가하세요(예: "나머지 LOC는 생성된 코드, 테스트 픽스처, 구성 파일을 포함합니다").
요약 통계를 추가하세요. 상세한 분석 후에 높은 수준의 요약을 추가하세요: "3개 계층, 11개 서비스, 5개 화면."
접을 수 있는 섹션을 적극적으로 사용하세요. 대규모 프로젝트에는 많은 세부 정보가 있습니다. 심층 콘텐츠(클래스 다이어그램, 파일 트리, API 참조)는 <details> 블록에 넣으세요. 주요 흐름은 30초 안에 스캔 가능해야 합니다.
시각적 통계 대시보드를 생성하세요. 풍부한 데이터(테스트 수, 커버리지, LOC)가 있는 프로젝트의 경우, 2~3개의 주요 메트릭을 보여주는 애니메이션 게이지가 있는 SVG를 생성하세요.

시각적 툴킷

이것들은 협상 불가입니다. 모든 README는 이것들을 사용해야 합니다.

1. 애니메이션 그라데이션 배너

헤더와 푸터에 capsule-render를 사용하세요:

헤더:

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=180&section=header&text=ProjectName&fontSize=42&fontColor=fff&animation=fadeIn&fontAlignY=36&desc=Your%20tagline&descAlignY=56&descSize=18" />

푸터:

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=120&section=footer" />

프로젝트의 아이덴티티에 맞게 customColorList를 사용자 정의하세요.

2. 커스텀 SVG 에셋

README당 적어도 하나의 .svg 파일을 생성하세요. 프로젝트에 맞는 것을 선택하세요:

성능 게이지 — 주요 메트릭(속도, 커버리지, 정확도)을 보여주는 애니메이션 호
터미널 목업 — 명령어와 출력이 있는 터미널 앱 창을 닮은 스타일링된 SVG
벤치마크 막대 차트 — 이 프로젝트와 대안을 비교하는 애니메이션 성장 막대
다크/라이트 변형이 있는 히어로 — 테마 인식 렌더링을 위한 <picture> 사용

완전한 복사-붙여넣기 SVG 코드는 references/visual-patterns.md를 참조하세요.

규칙 4를 기억하세요: 참조하면 반드시 생성해야 합니다.

3. 기능 표시 — 최상의 형식 선택

3~6개 기능의 경우: 이모지 아이콘과 짧은 설명이 있는 HTML 테이블 그리드를 사용하세요:

<table>
<tr>
<td align="center" width="33%">

### ⚡ 번개처럼 빠름
밀리초 미만 시작. 런타임 오버헤드 없음.

</td>
<td align="center" width="33%">

### 🔄 라이브 리로드
파일 변경 시 자동 새로고침. 제로 설정.

</td>
<td align="center" width="33%">

### 🌐 CORS 내장
즉시 사용 가능한 교차 출처 지원.

</td>
</tr>
</table>

8개 이상의 상세한 기능의 경우: 2열 HTML 테이블에서 인용문 카드를 사용하세요. 풍부한 기능 설명에 더 잘 확장됩니다:

<table>
<tr>
<td width="50%" valign="top">

> **📸 기능 이름**
>
> 기술적 세부 사항이 포함된 상세 설명. 혜택 중심 — 무엇을 하는지뿐만 아니라 왜 중요한지 설명합니다.

> **✂️ 다른 기능**
>
> 여기에 더 많은 세부 정보.

</td>
<td width="50%" valign="top">

> **🔗 세 번째 기능**
>
> 설명.

</td>
</tr>
</table>

기능에 일반 글머리 기호 목록을 절대 사용하지 마세요. 그것은 게으른 README의 #1 신호입니다.

4. Mermaid 다이어그램 — 적어도 2가지 다른 유형

기본 플로우차트를 넘어서세요. 다음 중 적어도 두 가지를 선택하세요: pie, gantt, journey, sequenceDiagram, stateDiagram, mindmap, timeline, classDiagram, gitGraph.

진정한 통찰력을 추가하는 다이어그램 유형을 선택하세요:

pie → 코드 구성, 테스트 분포, 예산 분석
gantt / timeline → 로드맵 (지루한 체크박스 목록 대체)
journey → 만족도 점수가 있는 사용자 경험 흐름
sequenceDiagram → API 흐름, 아키텍처 상호 작용
mindmap → 설계 결정, 기술 스택 개요
stateDiagram → 라이프사이클, 상태 머신, 워크플로우

5. 유니코드 시각적 요소

별도의 SVG가 필요하지 않은 인라인 데이터의 경우:

커버리지    ███████░░░  71%
테스트       ██████████  412 통과
메모리      ████░░░░░░  24 MB

테이블과 함께 사용하되, 대체하지 마세요. 커버리지 분석, 성능 비교, 언어 완성 비율에 적합합니다.

6. For-the-Badge 네비게이션 CTA

<p align="center">
  <a href="#-quick-start"><img src="https://img.shields.io/badge/⚡_Quick_Start-2ea44f?style=for-the-badge" /></a>&nbsp;
  <a href="#-features"><img src="https://img.shields.io/badge/✨_Features-6366f1?style=for-the-badge" /></a>&nbsp;
  <a href="#-benchmarks"><img src="https://img.shields.io/badge/📊_Benchmarks-f59e0b?style=for-the-badge" /></a>&nbsp;
</p>

이것들은 전통적인 목차를 대체합니다 — 둘 다 사용하지 마세요.

7. 접을 수 있는 섹션

보조 콘텐츠는 <details> 블록에 넣으세요: 설치 변형, 고급 설정, 전체 API 문서, 프로젝트 구조 트리, 문제 해결. 주요 흐름은 30초 안에 스캔 가능해야 합니다.

8. 시각적 지표가 있는 데이터 테이블

| 기능 | 이 프로젝트 | 대안 A | 대안 B |
|:---|:---:|:---:|:---:|
| 기능 X | ✅ | ❌ | ⚠️ |

README 구조

프로젝트에 따라 조정하세요. 모든 섹션이 적용되는 것은 아니지만, 시각적 요소는 협상 불가입니다.

 1. 애니메이션 헤더 배너 (capsule-render)

 2. 가운데 정렬 히어로
    - 이모지가 있는 제목
    - 태그라인
    - For-the-badge 네비게이션 CTA (목차 대체)
    - 메타데이터 배지 (버전, CI, 라이선스, 플랫폼)

 3. 가치 제안 (2-3문장 — 왜 존재하는지)

 4. 기능 (HTML 그리드 또는 인용문 카드 — 절대 글머리 기호 목록 안 됨)

 5. 빠른 시작 (번호가 매겨진 이모지 단계 1️⃣ 2️⃣ 3️⃣ + 예상 출력)

 6. 실제 사용 사례 (창의적 시나리오 — 규칙 3 참조)

 7. 벤치마크 / 데이터 (SVG 게이지 + 유니코드 막대 + 비교 테이블 ✅❌)

 8. Before vs. After (가능한 경우 매우 설득력 있음)

 9. 비교 분석 (프로젝트에 대안이 있는 경우 필수)

10. 사용자 여정 / 아키텍처 다이어그램 (Mermaid)

11. 설치 (접을 수 있는 블록, 다양한 방법)

12. API / 구성 참조 (접을 수 있는 블록)

13. 프로젝트 구조 (접을 수 있는 트리 또는 다이어그램)

14. 로드맵 (Mermaid gantt/timeline, 체크박스 목록 안 됨)

15. 기여 가이드

16. 라이선스 배지

17. 애니메이션 푸터 배너 (capsule-render)

모범 사례 요약

할 것	하지 말 것
✅ 기능에 HTML 테이블 그리드 사용	❌ 일반 글머리 기호 목록 사용
✅ capsule-render 애니메이션 배너 포함	❌ 정적 이미지만 사용
✅ 적어도 2개의 Mermaid 다이어그램 유형	❌ 기본 플로우차트에만 의존
✅ 실용적인 데이터와 함께 SVG 게이지 생성	❌ 존재하지 않는 SVG 파일 참조
✅ 창의적 섹션 추가 (사용 사례, 비교)	❌ 기존 콘텐츠만 재구성
✅ For-the-badge CTA를 네비게이션으로 사용	❌ CTA 그리고 목차 모두 사용
✅ 심층 콘텐츠를 접을 수 있는 블록에 넣기	❌ 모든 것을 한 페이지에 평탄화
✅ 원본 데이터와 수치 보존	❌ 일치하지 않아도 숫자 변경
✅ 숫자 검증 및 불일치 플래그 표시	❌ 오류를 조용히 무시
✅ 원본 README의 시각적 선택 향상	❌ 측면 이동으로 교체

Sa74/readme-writer

readme-writer란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

미리보기

문서