README 엔지니어링 및 기술 문서 가이드
세계적 수준의 인간 친화적인 GitHub 저장소 README를 만들기 위한 엄격한 프레임워크입니다. 독자의 시간을 존중하고, 기술적 가치를 명확하게 전달하며, 일반적인 마케팅성 내용을 제거합니다.
1. 핵심 철학: 30초 규칙
개발자와 사용자는 문서를 처음부터 끝까지 '읽지' 않습니다. 빠른 속도로 스캔합니다. 새벽 2시에 우연히 당신의 저장소를 발견한 지친 개발자의 입장이 되어 보세요.
당신의 README는 30초 안에 세 가지 질문에 답해야 합니다:
- 이게 뭔가요? (마케팅 수사가 전혀 없는 명확한 한 문장 정의)
- 왜 신경 써야 하나요? (해결하는 실제 문제와 대체하는 답답한 해결 방법)
- 지금 당장 어떻게 실행하나요? (3단계로 복사-붙여넣기 가능하며 테스트된 명령어)
2. 명확하고 근거 있는 글쓰기 가이드라인
문서는 종종 부풀려진 기업 홍보 문구로 변질되기 쉽습니다. 고품질 오픈소스 프로젝트는 이러한 어조를 완전히 피합니다.
2.1 금지 단어 및 클리셰 사전
| ❌ 금지된 유행어 / 클리셰 | ✔️ 명확하고 근거 있는 대안 |
|---|---|
| "오늘날의 빠르게 변화하는 디지털 환경에서..." | (완전히 삭제하세요. 문제로 바로 들어가세요). |
| "손쉽게 전송 / 완벽하게 통합..." | "브라우저에서 파일을 드롭하면 휴대폰에 나타납니다." |
| "혁신적이고 최첨단 플랫폼..." | "가볍고 자체 호스팅되는 개인 중계기." |
| "생산성을 새로운 차원으로 끌어올립니다..." | "링크를 자신에게 이메일로 보내는 수고를 덜어줍니다." |
| "현대 개발의 증거..." | (삭제하세요. 엔지니어처럼 말하고 PR 대행사처럼 말하지 마세요). |
| "거대한 히어로 배너 완전 제거..." | (내부 리팩토링에 대해 절대 자랑하지 마세요. 지금 UI가 제공하는 것을 명시하세요). |
| "방어적 웹 사인인 아키텍처..." | "HttpOnly SameSite 쿠키와 CSRF 토큰을 사용한 보안 로그인." |
| "제로-스켈레톤 SWR 캐시..." | "즉시 로딩: 빈 흰색 화면 없이 받은 편지함을 엽니다." |
2.2 진정성 있는 글쓰기 규칙
- '화요일 커피' 테스트: 초안을 소리 내어 읽어보세요. 사려 깊은 소프트웨어 엔지니어가 동료에게 커피를 마시며 자신이 가장 좋아하는 도구를 설명하는 것처럼 들리나요? 기업 마케팅 브로셔처럼 들린다면 다시 작성하세요.
- 뱃지 규율: 뱃지는 3~6개의 의미 있는 지표(릴리스, 빌드/CI 상태, 라이선스, 핵심 스택)로 제한하세요. 프로젝트를 산만하게 만드는 장식용 방패 15개를 쌓지 마세요.
- 선결 조건 불명확 금지:
docker compose up또는npm start를 작성할 때 선결 조건과 환경 자격 증명의 출처를 절대 나열하지 않고 쓰지 마세요.
3. 이중 독자 구조
훌륭한 문서는 명확성을 희생하지 않으면서 두 개의 뚜렷한 독자층을 연결합니다:
flowchart TD
Audience["저장소 방문자"]
Audience --> HomeUser["1. 일반인 / 일상 사용자<br>(자신의 문제를 해결하는지 알고 싶어함)"]
Audience --> Sysadmin["2. 엔지니어 / 시스템 관리자 / 개발자<br>(아키텍처, 보안, 스택을 알고 싶어함)"]
HomeUser --> PlainSection["'이게 왜 존재하나요?' 섹션<br>- 실제 상황 (더 이상 텍스트 봇이나 이메일 첨부 파일 없음)<br>- 3단계 개념적 워크플로우<br>- 개인정보 보호 및 자체 호스팅 이점"]
Sysadmin --> TechSection["'작동 방식' 섹션<br>- 아키텍처 다이어그램 (Mermaid)<br>- 컴포넌트 책임<br>- 보안 및 토큰 모델<br>- 저장소 및 데이터베이스 메커니즘"]
3.1 일반 사용자를 위한 평이한 영어
공감할 수 있는 실제 불편함으로 시작하세요:
"링크를 자신에게 이메일로 보내거나, Telegram이나 WhatsApp의 봇에 메시지를 보내 텍스트를 휴대폰에 복사하거나, 단일 PDF를 옮기기 위해 클라우드 드라이브 동기화를 기다린 적이 있나요? Vault는 이러한 해결 방법을 여러분만의 개인 드롭박스로 대체합니다."
3.2 개발자를 위한 근거 있는 기술적 깊이
정확한 아키텍처와 구현 세부 사항으로 이어집니다:
- API 엔진: ASP.NET Core 10 Minimal APIs가 파일을 최대 100MB까지 디스크에 직접 스트리밍하며 실시간 SHA-256 검증 (RAM 부담 제로).
- 웹 SPA: SameSite HttpOnly 쿠키, CSRF 토큰, 키보드 단축키(
/검색)를 사용하는 React 19 + TypeScript. - 모바일 클라이언트: WorkManager 오프라인 아웃박스 큐와 Android
FileProvider통합을 갖춘 기본 Kotlin Jetpack Compose. - 데이터베이스: 메타데이터와 14일 슬라이딩 세션 토큰을 저장하는 PostgreSQL 18.
4. 시각적 쇼케이스 및 UI 레이아웃
애플리케이션에 시각적 인터페이스(웹, 모바일 또는 CLI 출력)가 있다면, 소개 후 즉시 표시하세요.
4.1 반응형 쇼케이스 테이블 패턴
<table align="center" width="100%">
<tr>
<th width="33%" align="center">📱 모바일 받은 편지함</th>
<th width="33%" align="center">⚙️ 기기 허브</th>
<th width="34%" align="center">🔐 원활한 페어링</th>
</tr>
<tr>
<td align="center" valign="top">
<img src="docs/assets/mobile-inbox.png" alt="모바일 받은 편지함" width="260px" />
<br/>
<sub><i>즉시 로컬 캐시, 라이브 검색, 원터치 작업.</i></sub>
</td>
<!-- 나머지 열 -->
</tr>
</table>
4.2 스크린샷 규칙:
- 정보 제공 캡션: 사용자가 보기에서 무엇을 할 수 있는지 설명하는 캡션을 사용하고, 유행어를 나열하지 마세요.
- 실제 스크린샷: 가짜 노트북 프레임이 있는 일반적인 목업 템플릿보다는 항상 실제 제품 UI의 선명한 캡처를 사용하세요.
5. 완벽한 퀵스타트 설계
퀵스타트는 문제 해결 없이 재현 가능해야 합니다.
표준 3단계 설정:
### 1. 로컬 인증서 및 자격 증명 생성
```bash
./scripts/setup-local.sh # 또는 ./scripts/setup-local.ps1
설명: .local/tls/에 신뢰할 수 있는 localhost TLS 인증서를 생성하고 .env에 무작위 부트스트랩 비밀번호를 기록합니다.
2. 스택 시작
docker compose up -d
3. 작업 공간 열기
브라우저에서 **https://localhost:8080**으로 이동하세요:
- 사용자 이름:
[email protected](또는owner) - 비밀번호:
.env파일에 있는 부트스트랩 비밀번호
---
## 6. 표준 README 구조 체크리스트
기술 저장소 README를 구성할 때 이 체크리스트를 사용하세요:
- [ ] **1. 헤더 및 제목:** 로고/아이콘, 제목, 한 문장 기능 태그라인.
- [ ] **2. 집중된 뱃지:** 릴리스 버전, 빌드 상태, 핵심 플랫폼, 라이선스.
- [ ] **3. 존재 이유:** 평이한 영어로 된 일상적인 문제, 해결 방법, 3단계 워크플로우.
- [ ] **4. 시각적 둘러보기:** 실용적인 캡션이 있는 웹, 모바일 또는 CLI 인터페이스 스크린샷.
- [ ] **5. 핵심 기능:** 실제 작업별로 구성된 사용자 중심 기능 목록.
- [ ] **6. 작동 방식 (기술):** Mermaid 아키텍처 다이어그램 + 간결한 컴포넌트 분석 (API, 클라이언트, DB, 인증/보안).
- [ ] **7. 퀵스타트 (도커 / 로컬):** 선결 조건, 단계별 명령어, 자격 증명 위치.
- [ ] **8. 모바일 / 클라이언트 설정 (해당하는 경우):** 직접 다운로드 링크, 페어링 지침, LAN 테스트 가이드.
- [ ] **9. 자동화된 테스트 및 검증:** 로컬에서 백엔드 및 프론트엔드 테스트 스위트를 실행하는 명령어.
- [ ] **10. 저장소 맵 및 기여:** 깔끔한 ASCII 폴더 트리, 가이드라인 링크, MIT/Apache 라이선스.
---
## 7. 참조 오픈소스 저장소
구조적 및 시각적 영감을 위해 축하받는 오픈소스 README를 살펴보세요:
- **`matiassingers/awesome-readme`**: GitHub 전반의 최고 README를 선별한 디렉토리.
- **`othneildrew/Best-README-Template`**: 모듈식, 고영향 저장소 템플릿의 업계 표준.
- **`charmbracelet/bubbletea` & `charmbracelet/gum`**: 뛰어난 터미널 쇼케이스, GIF 사용법, 스캔 가능한 코드 블록.
- **`supabase/supabase`**: 명확한 시스템 아키텍처 다이어그램과 빠른 온보딩을 갖춘 탁월한 이중 독자 균형.
- **`fastapi/fastapi`**: 마찰 없는 퀵스타트, 실제 코드 예제, 명확한 가치 제안의 마스터클래스.