README 스크린샷
작동 중인 프로젝트를 문서화되고 시각적인 프로젝트로 변환하세요: 앱을 실행하고, 실제 화면의 스크린샷을 캡처한 후, 이를 중심으로 생동감 있고 깔끔한 README.md를 작성합니다. 결과물은 잘 관리되는 오픈소스 프로젝트의 랜딩 페이지처럼 읽혀야 합니다.
플랫폼에 관계없이 지켜야 할 필수 규칙:
- 스크린샷은 실행 중인 앱의 실제 캡처여야 합니다. 절대 이미지를 그리거나, 목업을 만들거나, 가짜를 사용하지 마십시오.
- 스크린샷은 리포지토리(
docs/screenshots/)에 저장되며, README는 상대 경로를 사용하여 참조해야 GitHub에서 올바르게 렌더링됩니다. - 파괴적인 작업 금지: 스크린샷을 찍기 위해 프로젝트의 소스 코드를 절대 수정하지 마십시오. 필요하다면 런타임에 데모 상태를 주입하고, 그 사실을 명시하십시오.
워크플로우
1단계 — 플랫폼 감지
프로젝트 루트에서 다음과 같은 신호를 찾아 references/에서 해당 런북을 로드합니다:
| 신호 | → 런북 |
|---|---|
dev/start 스크립트가 있는 package.json, 또는 index.html, 또는 src/public 폴더의 순수 웹 프론트엔드 | references/web.md |
manifest.json (WebExtension/MV3/V2) | references/web.md (확장 프로그램 섹션) |
Android: build.gradle(.kts), AndroidManifest.xml, settings.gradle, Kotlin/Java 앱 소스 | references/android.md |
iOS: *.xcodeproj, *.xcworkspace, Info.plist, Swift 앱 코드 | references/ios.md |
Flutter: flutter:와 lib/main.dart가 있는 pubspec.yaml | references/flutter.md |
| 여러 플랫폼 (예: Flutter + 네이티브, 또는 모노레포) | 주력 UI 플랫폼을 먼저 문서화하고, 다른 플랫폼은 README에 표기 |
플랫폼이 명확하지 않은 경우, 사용자에게 한 번 질문하고 확인된 리포지토리의 최선의 분석 결과를 제시하십시오. 프로젝트에 사용자에게 보이는 인터페이스가 없다면(순수 라이브러리/CLI), 가짜 UI 샷을 만들지 말고 대신 터미널 데모, 정제된 다이어그램, 또는 생성된 배너를 사용하여 훌륭한 README를 만드십시오.
2단계 — 런북에 따라 앱 실행
각 런북은 다음을 알려줍니다:
- 이 머신에 이미 설치되어 있어야 하는 것 (툴체인 확인, 반복 가능한 한 줄 명령어).
- UI가 렌더링되도록 앱을 부팅하는 방법.
- 실제로 픽셀을 캡처하는 방법 (
scripts/의 번들 스크립트 또는 네이티브 캡처 명령어). - 화면이 비어 있을 때 복구하는 방법 ("렌더링을 기다리는 것"이 "맹목적으로 재시도하는 것"보다 나음).
3단계 — 캡처
모든 플랫폼에 적용되는 규칙:
<repo>/docs/screenshots/디렉토리에 저장하며, 파일 이름은 케밥-케이스(kebab-case)로 캡처한 순간을 설명하도록 합니다 (예:hero-dashboard.png,settings-screen.png). 절대 도구 이름을 사용하지 마십시오 (예:screenshot-2026-01-04-14-22.png).- 각 화면을 그 자연스러운 크기로 캡처합니다: 다이얼로그/팝업은 원래 크기, 페이지는 1280×800 또는 전체 페이지. 휴대폰의 경우, 기기 화면을 그대로 캡처합니다 (기기 고유 해상도도 이야기의 일부입니다).
- 앱에 다크 모드가 있다면 히어로 샷에는 다크 모드를 선호합니다 — 다크 UI는 README에서 돋보입니다. 단, 실제 다크 테마가 있을 때만 사용하고 강제로 적용하지 마십시오.
- 데모 상태를 단계적으로 주입하는 것은 허용됩니다 (빈 카운터, "로딩 중…" 플레이스홀더는 마케팅 샷에서 부서져 보입니다). 단, 반드시 런타임에 주입해야 하며, 프로젝트 코드에 작성해서는 안 되며, 요약에서 사용자에게 이 사실을 알려야 합니다.
- 빈 화면이나 깜빡이는 프레임은 타이밍 버그일 뿐 앱의 잘못이 아닙니다: 로드 + 폰트/아이콘/트랜지션을 위한 여유 시간을 기다린 후, 더 긴 대기 시간으로 한 번 재시도하십시오.
4단계 — README 작성
리포지토리 루트에 README.md를 작성(또는 재작성)합니다. 이미 풍부한 README 콘텐츠가 있다면 (git-readme.md, 산문 파일, 문서 등), 모든 사실을 가져와서 — 프레젠테이션을 업그레이드하고 정보를 절대 삭제하지 마십시오.
목표 구조 (자유롭게 조정하되, 훑어보기 쉽게 유지):
# <프로젝트 이름>
<p align="center"><img src="docs/screenshots/hero.png" width="…"></p>
> 성격이 담긴 한 줄 소개.
배지: 라이선스, 언어, 설치 링크
## 존재 이유 ← 문제점, 2-4줄, 실제 숫자면 굵게 표시
## 하는 일 ← ✨ 간결한 기능 목록 (+ 기능 옆에 스크린샷)
## 스크린샷 둘러보기 ← 한 줄 캡션이 있는 갤러리
## 작동 방식 ← 평문으로 설명한 아키텍처; 산문보다 표 선호
## 설치 방법 ← 번호가 매겨진, 복사-붙여넣기 가능한 명령어
## 설정 ← 앱에 설정이 있다면 파라미터 표
## 개인정보 / 안전 ← 의미 있을 때만
## 라이선스
스타일 규칙:
- 히어로 샷은 접기 위에 배치하고, 명시적인 너비를 지정합니다 (휴대폰 샷은
width="400", 데스크탑은 약 728px 미만) — GitHub에서 잘 배치되도록. - 섹션당 하나의 아이디어; 짧은 문단; 스캔을 돕는 용도로만 굵게 표시합니다.
- 호환성 매트릭스와 설정에는 표를 사용하세요 — 산문보다 낫습니다.
- 헤더에 최소한의 세련된 이모지(⏱ 🎨 🚀)는 괜찮습니다. 모든 줄에 사용하지 마십시오.
- 항상 상대 이미지 경로와 대체 텍스트(alt text)를 사용합니다.
- README에서 스크린샷 촬영 과정을 절대 서술하지 마십시오. 마치 프로젝트 자체가 작성한 것처럼 읽혀야 합니다.
5단계 — 검증
- README의 모든 이미지 경로가 실제 존재하는 파일을 가리키는지 확인합니다.
- 어떤 스크린샷도 약 1.5MB를 넘지 않아야 합니다. 더 크면 압축합니다 (PNG → WebP 또는 해상도 축소).
- 사용자에게 알립니다: README의 위치, 생성된 스크린샷 목록, 데모가 주입된 값이 있는 스크린샷이 있다면 알리고, 히어로 선택, 테마 또는 순서를 변경할 의향이 있는지 묻습니다.
툴체인 정책 (누락된 의존성 처리)
이 스킬은 머신에 이미 존재하는 툴체인을 사용하며, 절대 자동으로 플랫폼 SDK를 설치하지 않습니다 (Android SDK, Xcode, Android 에뮬레이터 — 사용자가 동의해야 하는 GB 단위 다운로드). 런북의 툴체인 확인이 실패하면, 정확히 다음과 같은 형태로 깔끔하게 중단합니다:
[플랫폼] 스크린샷을 찍으려면 [도구]가 필요하지만, 설치되어 있지 않습니다. 활성화하려면:
<정확한 설치 명령어 또는 단계>. 설치한 후 "재시도"라고 말씀해 주시면 계속 진행합니다 — 지금까지 수행된 작업(감지, README 스켈레톤)은 저장됩니다.
iOS는 특별한 경우입니다: 호스트가 macOS가 아니라면, 한 문장으로 알리고 건너뜁니다 — Windows/Linux에서는 재시도로 활성화할 수 없습니다. 사용자에게 직접 캡처한 스크린샷을 제공할 수 있는 옵션을 제안합니다.