Jazztinn/dontreadme

해커톤 README 빌더

일반 프로젝트 README와 달리, 해커톤 README의 유일한 임무는 이기는 것입니다. 심사위원은 수십 개의 리포지토리를 몇 분 만에 훑어보고, 종종 휴대폰으로도 확인하며, 어떤 프로젝트를 열어볼 가치가 있는지 결정합니다. README는 프로젝트의 첫인상이며, 심사위원이 점수를 매기기 전에 읽는 유일한 산출물인 경우가 많습니다. 따라서 목표는 '코드 문서화'가 아니라, 바쁘고 회의적인 심사위원이 프로젝트를 빠르게 이해하고 믿게 만드는 것, 그리고 모든 주장을 쉽게 검증 가능하게 하는 것입니다.

이 스킬은 풍부한 제출형 README를 생성하며, 간결한 스타일이 아닙니다. 참고 레이아웃은 references/readme-template.md에 있습니다. 작성 전에 반드시 읽어보세요. 이 템플릿에는 하우스 스타일(가운데 정렬된 배지 행, 데모 배지 버튼, 표, 실제 프로젝트 항목 기반 설명, 프로젝트 트리, 명시적인 심사 하이라이트 블록)이 포함되어 있습니다. references/badges.md에는 복사-붙여넣기 가능한 shields.io 스니펫이 있습니다.

아래 단계를 순서대로 수행하되, 대화체를 유지하세요. 양식을 작성하는 것이 아니라 지친 개발자가 마무리할 수 있도록 돕는 것입니다.

1단계 — 심사 기준에 기준점 설정 (먼저 수행할 것)

이것이 가장 효과가 높은 작업이며, 이 스킬이 존재하는 이유입니다. 대부분의 README는 일반 템플릿에 맞춰 작성되지만, 승리하는 README는 심사 기준에 맞춰 작성됩니다. 무엇보다 먼저 질문하세요:

"이벤트의 심사 기준이나 루브릭이 있나요? (예: '혁신성, 기술적 난이도, 영향력, 완성도', 또는 점수표/제출 페이지 안내) 있다면 붙여넣어 주세요. 각 기준이 눈에 띄게 반영되도록 하겠습니다. 없다면 강력한 기본값을 사용하겠습니다."

먼저 질문하는 이유: 루브릭이 '실제 영향력'에 가중치를 둔다면, 생생한 문제와 대상 사용자로 시작하세요. '기술적 난이도'에 가중치를 둔다면, 아키텍처와 어려운 부분을 앞에 배치하세요. 이후 README 끝 부분에 심사 하이라이트 섹션을 추가하여 각 기준을 명명하고 프로젝트가 이를 어떻게 충족하는지 설명합니다. 이렇게 하면 루브릭 기준이 시각적으로 드러나며, 심사위원이 자신의 작업을 대신해 주기 때문에 선호합니다. 체크리스트를 유지하세요: 모든 기준이 README에 포함되어야 합니다.

루브릭이 없는 경우, 거의 모든 이벤트에서 사용하는 네 가지 기준을 기본값으로 사용하세요: 혁신성/독창성, 기술적 실행, 영향력/유용성, 완성도/세련됨

또한 이벤트의 성격을 파악하세요. 이에 따라 선택 섹션(4단계 참조)이 달라집니다:

• 학술/연구/테크스프린트 (예: ACM 이벤트): AI 사용 공개, 윤리/데이터 보호 주의사항, 참고문헌/인용, 때로는 UN SDG 정렬이 필요합니다. 이를 포함하세요.
• 제품/스타트업/일반 주말 해커톤: 간결하게 유지 — SDG, 윤리, 인용은 프로젝트가 실제로 데이터 수집이나 입증이 필요한 주장을 포함하지 않는 한 생략하세요.

확실하지 않으면 질문하거나, 가벼운 세트를 포함하고 다른 옵션이 가능하다고 언급하세요.

2단계 — 리포지토리를 스캔하여 사실에 기반

심사위원은 README가 코드와 일치하지 않거나 설정 단계가 작동하지 않으면 즉시 신뢰를 잃습니다. 따라서 작성 전에 실제로 무엇이 있는지 확인하세요. 하우스 스타일은 실제 파일 경로를 참조하고 실제 명령어와 예상 출력을 보여줍니다. 이는 리포지토리를 읽어야만 가능합니다.

• 스택 및 언어: 매니페스트 파일에서 유추 — package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile. 프레임워크(React, Next, Vite, FastAPI, Flask, Three.js…)를 기록하세요. 이는 배지 행과 기술 스택 표에 직접 매핑됩니다.
• 실행 방법: package.json의 scripts, Makefile, docker-compose.yml, Procfile, .env.example을 읽으세요. 실행 섹션은 프로젝트가 실제로 시작되는 방식(환경 변수 및 실제 개발 포트 포함)과 일치해야 합니다. 예상 출력을 추론할 수 있으면 보여주세요. 작동한다는 신호입니다.
• 구조 및 진입점: 최상위 디렉토리와 주요 진입 파일을 훑어보아 프로젝트 트리와 작동 방식 단계가 실제 파일(src/lib/check.js, app/main.py)을 인용할 수 있도록 하세요. 예시처럼.
• 이미 존재하는 것: 부분적인 README, LICENSE, assets//docs//public/의 스크린샷, 구성의 배포 URL, CI 워크플로우. 이를 재사용하세요.

리포지토리에 접근할 수 없는 경우(사용자가 프로젝트를 설명만 하는 경우), 스캔을 건너뛰고 인터뷰에 의존하며, 설정 명령어와 파일 경로는 실제로 확인해야 할 자리 표시자임을 명시하고 정확한 것을 지어내지 마세요.

3단계 — 코드로 알 수 없는 정보 인터뷰

리포지토리는 사실을 제공하고, 빌더는 스토리와 증거를 제공합니다. 하나의 친근한 배치로 다음을 요청하고, 건너뛰어도 된다고 알리세요:

• 한 줄 피치 → 태그라인 인용 블록으로 사용.
• 문제/영감 → 구체적이고 인간적인, 이상적으로는 특정 순간.
• 라이브 데모 + 비디오 → 가장 많이 클릭되는 자산. 상단 근처에 배지 버튼으로 표시. 비디오가 없으면 2분짜리가 큰 도움이 된다고 부드럽게 언급.
• 스크린샷/GIF/마스코트 또는 로고 → 하나의 이미지도 인지된 완성도를 높임; 예시는 마스코트/미리보기 이미지를 상단에 중앙 정렬.
• 어려운 부분 → 기술적으로 까다로웠거나 자랑스러운 점; 기술 실행 점수와 '작동 방식'에 금상첨화.
• 주요 결과/지표 → 프로젝트가 측정한 것이 있다면 작은 결과 표가 매우 설득력.
• 팀 → 이름 + 역할 (및 링크)로 팀 표 구성.
• 다음 단계 → 로드맵/확장은 비전을 보여줌.
• 이벤트 추가 사항(1단계에 따라 관련된 경우에만) → 사용된 AI 도구, 데이터/동의 세부사항, 인용.

답변 없이 진행하지 마세요. 시간이 부족하면 <!-- TODO: add demo link -->와 같이 명확히 표시된 자리 표시자로 초안을 작성하여 중요한 내용이 조용히 누락되지 않도록 하세요. 데모 URL, 지표, 팀원을 절대 지어내지 마세요.

4단계 — README 작성

프로젝트 루트(또는 사용자가 원하는 위치)에 단일 README.md 파일을 생성하고, references/readme-template.md를 따르세요. 전체 구조는 해당 파일에 있습니다. 여기서는 형태와 핵심 vs. 선택 사항을 설명합니다.

핵심 (거의 항상 포함):

1. 제목 + 선택적 가운데 정렬 로고/마스코트 이미지
2. 가운데 정렬 기술 배지 행 (references/badges.md에서)
3. 이벤트/제출 라인 + 태그라인 인용 블록
4. 데모 + 비디오 배지 버튼 (데이터셋/Colab 링크가 있으면 포함)
5. 팀 표
6. 문제 (또는 "이것이 중요한 이유")
7. 해결책 / 기능
8. 작동 방식 — 실제 파일을 인용하는 번호 단계
9. 기술 스택 표
10. 로컬 실행 — 검증된 명령어, 가능하면 예상 출력 포함
11. 프로젝트 구조 트리
12. 로드맵 / 다음 단계
13. 심사 하이라이트 — 기준당 하나의 글머리 기호, 프로젝트가 각 기준을 충족하는 방법
14. 라이선스

선택 사항 (이벤트 성격과 실제 내용에 따라 포함):

• 히어로 아래 앵커 링크 내비게이션 바 (3~6개 주요 섹션) — 긴 스크롤을 휴대폰에서 심사위원이 한 번의 탭으로 볼 수 있게 함.
• 주요 결과/지표 표 + 오류/분석 표 (데이터 프로젝트); 원시 데이터 또는 재현 명령어 링크를 통해 숫자를 재실행 가능하게 함.
• 전후 50/50 표 — 프로젝트가 현 상태를 개선할 때 (더 빠름, 더 저렴, 더 적은 단계) 승리를 시각적으로 보여줌.
• 히어로 아래 통계 상자 ASCII — 하나의 강력한 숫자가 있는 프로젝트용.
• > [!IMPORTANT] / > [!NOTE] GitHub 경고 콜아웃 — 훑어보는 심사위원이 놓치지 말아야 할 한 가지 주의사항이나 핵심 사실을 강조 (드물게 사용).
• Mermaid 파이프라인 다이어그램 (다단계 시스템)
• 데모 흐름 / "오프라인에서 작동하는 것" 스타일 워크스루
• AI 사용 공개 (학술 이벤트)
• 데이터 보호/개인정보/윤리 (사람이나 데이터를 다루는 프로젝트)
• UN SDG 정렬 (영향 중심 학술 이벤트)
• 참고문헌 및 인용, 감사의 말
• 현재 상태 체크리스트 + 사전 심사 완성도 할 일

1단계 루브릭에 따라 강조와 순서를 조정하세요: 가장 중요한 기준이 가장 먼저 나타나야 합니다. 불필요한 내용은 넣지 마세요. 모든 섹션은 자리를 차지할 가치가 있어야 합니다. 간결한 제품 해커톤은 핵심 세트만 사용할 수 있고, 연구 테크스프린트는 선택 사항 대부분을 사용할 수 있습니다. 체크리스트가 아닌 프로젝트에 맞추세요.

심사에 중요한 스타일 노트:

• 가장 강력한 것으로 시작 — 혁신, 엔지니어링, 영향력 중 후크에 해당하는 것.
• 보여주라, 말하지 마라 — 데모 배지 버튼, GIF, 단일 명령어 설정, 예상 출력 블록이 형용사보다 낫습니다. 모든 인상적인 주장은 검증 가능해야 합니다. 전후 비교 표, 통계 상자, 재현 가능한 벤치마크는 주장을 심사위원이 보거나 재실행할 수 있는 증거로 바꿉니다.
• 히어로가 작업하게 하라 — 가운데 정렬 제목, 선택적 로고/마스코트, 배지 행, 하나의 날카로운 태그라인으로 심사위원이 스크롤하기 전에 이것이 무엇이고 왜 좋은지 파악할 수 있게 합니다. 데모/비디오 버튼을 여기 첫 번째 클릭 위치에 두세요.
• 모든 것을 리포지토리에 기반 — 실제 파일 경로, 실제 명령어, 실제 개발 포트. 이것이 README를 신뢰할 수 있게 만드는 요소이며, 예시 스타일의 일관된 흐름입니다.
• 정직하라 — 존재하지 않는 기능을 주장하지 마세요. 심사위원은 테스트하며, 깨진 주장은 누락된 기능보다 더 큰 손해입니다. 완료되지 않은 작업은 '다음 단계' 또는 상태 체크리스트 아래에 표시하고, 완료된 것으로 표시하지 마세요.
• 훑어보기 쉽게 유지 — 짧은 문단, 의미 있는 헤더, 긴 글 대신 표, 휴대폰에서 2분 안에 위에서 아래로 읽을 수 있게.

5단계 — 루브릭에 대해 마무리 점검

전달하기 전에 1단계의 각 기준을 가져와 심사 하이라이트 섹션(및 본문)이 이를 다루는지 확인하세요. 어떤 기준이라도 자리가 없으면 추가하세요. 그런 다음 사용자에게 무엇을 했는지 알리세요 — 예: "귀하의 루브릭은 영향력과 기술적 난이도에 가중치를 두었습니다. 영향력을 위해 문제로 시작하고 '왜 어려웠는지'를 작동 방식 아래에 추가했으며, 심사 하이라이트 블록은 네 가지 기준을 모두 명명합니다." 마지막으로 남은 자리 표시자(데모 링크, 스크린샷, 지표)를 나열하여 제출 전에 무엇을 채워야 하는지 정확히 알 수 있게 하세요.