README Generator은(는) 무엇을 하나요?
내부/회사 코드 저장소를 위한 정돈되고 포괄적인 README.md 파일을 생성합니다. 실제 코드베이스를 분석하고 필요한 명확화 질문을 통해 정보를 수집합니다.
이 스킬이 존재하는 이유
좋은 README는 코드베이스의 정문입니다. 특히 내부 프로젝트의 경우, README가 없거나 부실하면 새 팀원이 프로젝트의 목적, 실행 방법, 코드 구조를 파악하는 데 수시간을 허비하게 됩니다. 이 스킬은 이러한 수고를 자동화합니다. 코드를 읽고 추론 가능한 것은 추론하며, 알 수 없는 것은 질문하여 개발자가 빠르게 생산성을 낼 수 있도록 README를 생성합니다.
워크플로우
1단계: 코드베이스 분석
사용자에게 질문하기 전에 구조화된 4단계 분석을 실행하여 최대한 많은 컨텍스트를 수집합니다. 이는 사용자의 부담을 줄여줍니다. 사용자는 빈틈만 채우면 되고, 이미 확인할 수 있는 내용을 설명할 필요가 없습니다.
모든 정보는 다음과 같은 신뢰도 레벨로 태깅합니다: [confirmed] (소스에서 읽음), [inferred-high] (강력한 증거), [inferred-low] (부분적 증거), [unknown]. 낮은 신뢰도와 알 수 없는 항목은 2단계의 명확화 질문이 됩니다.
자세한 도구 액션, grep 패턴, 추출 체크리스트, 레코드 템플릿은 references/analysis-phases.md를 참조하세요.
1단계 — 프로젝트 메타데이터 스캔: 패키지 매니저 파일(pyproject.toml, package.json 등), env 템플릿, Dockerfile, CI/CD 설정, 툴체인 파일을 글로브(glob)하여 각 파일을 읽습니다. 추출 항목: 프로젝트 이름/버전, 언어, 의존성(용도별 분류), 스크립트/명령어, 환경 변수(필수 vs 선택), CI 단계, 라이선스.
2단계 — 아키텍처 스캔: 모든 소스 파일을 글로브하여 디렉터리 구조를 매핑합니다. 진입점 마커(if __name__, main() 등)를 grep하고 각 진입점을 읽습니다. 모든 소스 파일에서 import 문을 grep하여 import 그래프를 구축합니다. 모듈을 핵심(높은 진입차수), 리프, 오케스트레이터로 분류합니다. 지표 체크리스트를 사용하여 아키텍처 패턴(파이프라인, MVC, 계층형, 마이크로서비스, 이벤트 기반, CLI, 모놀리식)을 식별합니다. 런타임 설정 파일을 찾기 위해 설정 로딩 패턴을 grep합니다.
3단계 — 딥 모듈 분석: 각 주요 소스 파일을 (우선순위: 핵심 → 진입점 → 가장 큰 파일 → 나머지 순) 읽습니다. 각 파일에서 다음을 추출합니다: 목적(한 문장), 주요 익스포트와 시그니처, 설계 노트(비명백한 결정, 엣지 케이스, 규칙), 내부 의존성. 주 워크플로우를 import 그래프를 따라 종단 간 추적하며 모듈 간에 흐르는 데이터 타입에 레이블을 붙입니다. 소스 파일이 8개 이상인 코드베이스는 의존성 클러스터별로 병렬 서브 에이전트를 분배합니다.
4단계 — 지원 인프라 스캔: 테스트 파일과 픽스처를 글로브합니다. 각 테스트 파일의 처음 30-50줄을 읽어 테스트-모듈 매핑을 구축합니다. 사용자 정의 예외 클래스와 raise 문을 grep하여 오류 계층을 매핑합니다. 템플릿, 에셋, 기존 문서를 스캔합니다. 트러블슈팅 표를 위한 일반적인 오류 시나리오를 추출합니다.
2단계: 명확화 질문
분석 후, 확실하게 추론할 수 없었던 항목에 대해 사용자에게 질문합니다. 이미 알고 있는 내용은 묻지 말고 집중하세요. 일반적인 누락 항목은 다음과 같습니다:
- 프로젝트 목적: 이 프로젝트는 어떤 문제를 해결하나요? 누가 사용하나요? (코드에서 명확하지 않은 경우)
- 설정 시 주의사항: 명확하지 않은 전제 조건, VPN 요구 사항, 내부 패키지 레지스트리, 데이터베이스 설정 단계 등이 있나요?
- 주요 워크플로우: 개발자가 이 프로젝트에서 가장 자주 하는 2-3가지 작업은 무엇인가요?
- 배포: 어디에/어떻게 배포되나요? (CI/CD 설정에서 명확하지 않은 경우)
- 팀 규칙: 명명 규칙, 브랜칭 전략, 강조할 패턴이 있나요?
- 연락처: 이 프로젝트를 소유/관리하는 사람은 누구인가요? (이름 + 이메일, 연락처 섹션용)
질문은 간결하게 제시하세요. 코드베이스가 간단하고 분석에 자신이 있다면 질문은 1-2개 또는 없을 수도 있습니다. 판단력을 사용하세요.
3단계: README.md 생성
아래 구조와 가이드라인을 사용하여 README를 작성하세요.
README 구조
다음을 템플릿으로 사용하세요. 모든 섹션을 포함하되, 프로젝트의 복잡성에 맞게 깊이를 조정하세요. 각 주요 섹션 사이에 시각적 여백을 위해 --- 수평선을 사용하세요.
# 프로젝트 이름
  
간결하고 명확한 설명. 주요 기술이나 제품 유형을 **굵게** 강조하세요.
---
## 목차
모든 ## 및 ### 제목을 포함하는 자세한 중첩 목차를 생성하세요. 하위 섹션은 상위 섹션 아래에 들여쓰기하여 독자가 전체 구조를 한눈에 볼 수 있도록 하세요. 긴 README에서 특히 중요합니다. 목차는 탐색 도구이자 문서 전체 개요 역할을 합니다.
예상 깊이의 예:
- [개요](#개요)
- [아키텍처](#아키텍처)
- [고수준 아키텍처](#고수준-아키텍처)
- [폴더 구조](#폴더-구조)
- [모듈 의존성 그래프](#모듈-의존성-그래프)
- [시작하기](#시작하기)
- [전제 조건](#전제-조건)
- [설치](#설치)
- [테스트 실행](#테스트-실행)
- [환경 변수](#환경-변수)
- [사용법](#사용법)
- [예제: 주요 사용 사례](#예제-주요-사용-사례)
- [예제: 보조 사용 사례](#예제-보조-사용-사례)
- [API 참조](#api-참조)
- [리소스 A](#리소스-a)
- [리소스 B](#리소스-b)
- [트러블슈팅](#트러블슈팅)
- [연락처](#연락처)
- [라이선스](#라이선스)
문서의 모든 ### 제목이 해당 ## 제목 아래에 들여쓰기된 항목으로 나타나야 합니다. 하위 섹션을 건너뛰지 마세요. 철저한 목차의 핵심은 독자가 문서의 어느 부분으로든 직접 이동할 수 있도록 하는 것입니다.
---
## 개요
설명을 확장하세요. 핵심 용어는 **굵게** 표시하세요. 여러 단계 프로세스에는 번호가 매겨진 목록을 사용하세요.
---
## 아키텍처
### 고수준 아키텍처
```mermaid
graph TD
...
```
폴더 구조
project-root/
├── src/ # 간단한 주석
├── tests/ # 간단한 주석
└── ...
[데이터 흐름 / 파이프라인 / 모듈 의존성 — 추가 다이어그램]
...
시작하기
전제 조건
설치
테스트 실행
환경 변수
| 변수 | 필수 | 설명 |
|---|---|---|
DB_URL | 예 | PostgreSQL 연결 문자열 |
사용법
가장 일반적인 2-3개 작업에 대한 실제 코드 예제.
API 참조
트러블슈팅
| 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
오류 메시지 | 무엇이 잘못되었는지 | 어떻게 고치는지 |
연락처
질문이나 지원이 필요하시면 연락주세요:
- 이름 — [email protected]
라이선스
내부 전용 – 회사명 독점 소프트웨어. © [년도] [회사]. All rights reserved.
Shields.io 배지
# 제목 바로 뒤에 항상 shields.io 배지(언어, 프레임워크, 주요 라이브러리, 패키지 매니저, 데이터베이스, 인프라를 다루는 3-6개)를 포함하세요. 형식, 예제, 카테고리별 색상 제안은 references/badge-reference.md를 참조하세요.
Mermaid 다이어그램 가이드라인
Mermaid 다이어그램을 적극적으로 사용하세요. 아키텍처, 데이터 흐름, 프로세스를 즉시 이해할 수 있게 해줍니다. 일반적인 README에는 3-6개의 다이어그램, 복잡한 프로젝트(데이터 파이프라인, 다중 서비스 시스템)는 6-10개 이상이 적합합니다. 각 다이어그램 유형을 언제 사용해야 하는지, 모범 사례, 프로젝트 유형별 권장 사항은 references/mermaid-guidelines.md를 참조하세요.
작성 가이드라인
- 일반적이기보다 구체적으로 작성하세요. "
npm run dev실행"이 "개발 서버 시작"보다 낫습니다. 실제 명령어, 파일 경로, 변수 이름을 포함하세요. - 새 팀원을 위해 작성하세요. 일반적인 공학 기술을 가정하지만 프로젝트 컨텍스트는 전혀 없다고 가정하세요.
- 첫 언급과 개요에서 핵심 용어와 제품 이름을 굵게 표시하세요. 독자가 스캔하는 데 도움이 됩니다.
- 순차적 프로세스에는 번호가 매겨진 목록을 사용하세요. "1. 추출 X에서 데이터를 가져옵니다. 2. 변환합니다. 3. 로드 Y에 넣습니다." — 동사를 굵게 표시하세요.
- 코드 예제는 실행 가능해야 합니다. 가능하면 실제 코드베이스에서 복사하세요.
- 환경 변수 표는 절대 빠뜨리지 마세요. 모든 변수를 나열하세요.
- 트러블슈팅은 표 형식(증상 | 가능한 원인 | 해결 방법)으로 — 스캔하기 쉽고 일관적입니다.
- 폴더 구조 주석은 간결하게. 디렉터리당 짧은 구문 하나.
- 항상 연락처 섹션을 포함하세요. 사용자에게 프로젝트 유지 관리자를 물어보세요. 형식:
**이름** — [email protected]. - 모든 주요 섹션 사이에
---수평선을 사용하여 시각적 구조를 만드세요.
출력
README를 저장소 루트(또는 저장소 루트를 식별할 수 없는 경우 현재 작업 디렉터리)에 README.md로 저장하세요. README.md가 이미 존재하는 경우 사용자에게 덮어쓰기 전에 확인하세요. 사용자가 기존 내용의 일부를 유지하고 싶을 수 있습니다.