개발자초급·2026.03.08

코드만 보고 README 초안 — 한국어 + 영어

저장소/스크립트를 던지면 설치·사용법·아키텍처·기여 가이드를 한국어와 영어로.

프롬프트 본문

당신은 오픈소스 프로젝트의 메인테이너입니다.

다음 코드/스크립트를 분석해 README 초안을 작성하세요.
```
[코드 또는 패키지 구조]
```

요구 사항:
1. 한국어 README + 영어 README 두 버전 모두
2. 섹션 구성:
   - 한 줄 설명 (badge 자리 포함)
   - 무엇을 해결하는가 (왜 만들었는가)
   - 빠른 시작 (3줄 안으로 끝나는 설치/실행)
   - 사용 예시 (실제 코드 + 결과)
   - 주요 API/명령 (표 형식)
   - 아키텍처 한 줄 다이어그램 (ASCII)
   - 기여 방법
   - 라이선스
3. "혁신적인", "차세대" 같은 마케팅 표현 금지. 사실만.
4. 코드 블록의 언어 태그(예: ```bash, ```ts) 정확히 명시

ⓘ 대괄호 [ ] 부분을 본인 상황에 맞게 채운 뒤 쓰세요. 그대로 복사하기보다 아래 사용 예시·실패 예시·수정 팁을 먼저 읽으면 결과가 크게 달라집니다.

실전 사용 팁

1."빠른 시작이 3줄 안에 안 끝나면 줄이라"는 제약을 명시하면 첫 인상이 훨씬 깔끔해진다.
2.한국어 README와 영어 README의 정보량을 똑같이 맞추려면 한쪽 끝내고 "이 한국어 버전을 그대로 영어로 옮겨줘"가 더 안정적.

사용 예시 (이렇게 나옵니다)

CSV를 받아 중복 행을 제거하는 작은 CLI 스크립트를 입력했을 때 나오는 한국어 README 초안 일부입니다.

dedup-csv

[badge 자리] CSV 파일에서 중복 행을 빠르게 걷어내는 단일 파일 CLI.

무엇을 해결하는가

엑셀로 열기엔 너무 큰 CSV에서 중복 행을 지우려고 매번 스크립트를 새로 짜는 일을 없애려고 만들었습니다. 특정 열 기준 중복 제거를 한 줄 명령으로 처리합니다.

빠른 시작

npm i -g dedup-csv
dedup-csv input.csv --key email > output.csv

주요 옵션

--key: 중복 판단 기준 열 이름 (없으면 전체 행 비교)
--keep: first 또는 last, 어느 행을 남길지 (기본 first)

아키텍처

stdin/파일 → 파서 → 해시 집합 기반 dedup → stdout. 메모리에 키 집합만 들고 있어 큰 파일도 스트리밍으로 통과합니다.

영어 README 버전은 같은 섹션 구조로 별도 생성됩니다. 정보량을 맞추려면 한국어 버전을 확정한 뒤 그대로 번역 요청하는 방식이 더 안정적입니다.

이 프롬프트 200% 활용법

왜 이 프롬프트가 결과를 끌어올리나

"당신은 오픈소스 프로젝트의 메인테이너입니다"라는 역할을 먼저 박고 시작합니다. 그래서 모델이 코드를 단순 설명하는 게 아니라 "처음 보는 사람이 이걸 쓰게 만들려면 뭐가 필요한가"의 관점으로 움직여요. 핵심은 대괄호 변수 하나입니다. 코드 블록 안의 [코드 또는 패키지 구조] 자리에 실제 소스나 디렉터리 트리를 그대로 붙이면, 나머지 8개 섹션이 그 코드에서 사실만 길어 올립니다. 섹션 순서도 잘 짜여 있어요. 한 줄 설명 → 무엇을 해결하는가 → 빠른 시작 → 사용 예시 → 주요 API/명령(표) → ASCII 다이어그램 → 기여 방법 → 라이선스. 위에서부터 읽으면 "이게 뭐고 왜 쓰고 어떻게 까는가"가 자연스럽게 흐릅니다.

효과적인 제약이 셋 있습니다. 빠른 시작은 3줄 안으로 끝내라는 제한, "혁신적인", "차세대" 같은 마케팅 표현 금지, 그리고 코드 블록마다 bash·ts 같은 언어 태그를 정확히 명시하라는 요구. 이 셋이 "AI가 쓴 듯 부풀린 README"를 막고 복붙해서 바로 돌아가는 문서를 만듭니다.

이럴 땐 안 맞아요 / 한계

코드를 안 주고 "내 프로젝트 README 써줘"라고만 하면, 출발점인 [코드 또는 패키지 구조] 변수가 비어버려서 모델이 일반적인 README 골격만 지어냅니다. 사실 기반이 깨지는 순간이죠. 한국어와 영어 두 버전을 동시에 뽑게 되어 있어, 거대한 모노레포 전체를 한 번에 던지면 양쪽 다 분량이 길어지고 정보량이 어긋나기 쉽습니다. 정밀한 설치 절차나 환경별 트러블슈팅처럼 코드만 봐서는 알 수 없는 내용은 추측으로 채워질 수 있으니, 그 부분은 사람이 확인하세요.

변수만 바꿔 쓰는 변형

이건 개발자의 문서화·요약 작업에 맞춘 프롬프트입니다. 같은 골격에서 [코드 또는 패키지 구조] 자리에 무엇을 넣느냐로 용도를 갈아끼우면 됩니다.

단일 CLI 스크립트: 예시 결과의 dedup-csv처럼 옵션 표(--key, --keep)와 stdin→파서→dedup→stdout 한 줄 다이어그램이 잘 나옵니다. "주요 API/명령" 섹션을 "주요 옵션"으로 읽으면 그대로 들어맞아요.
라이브러리/패키지: 트리 대신 export하는 함수 시그니처를 붙이고, "주요 API/명령(표)" 섹션을 함수·인자·반환값 표로 활용합니다.
사내용/비공개 도구: 영어 README가 필요 없으면 "한국어 버전만"이라 덧붙이고, "기여 방법" 자리를 사내 배포·운영 절차로 바꿔 요청합니다.

흔히 놓치는 부분과 교정

가장 잦은 실수는 한국어와 영어 README를 한 번에 같이 뽑으라고 하는 겁니다. 그러면 두 버전의 정보량이 미묘하게 달라져요. 팁대로 한국어를 먼저 확정한 뒤 "이 한국어 버전을 그대로 영어로 옮겨줘"라고 두 단계로 가면 훨씬 안정적입니다. 둘째, 빠른 시작이 3줄을 넘기는데 그냥 두는 경우가 많은데 "3줄 안에 안 끝나면 줄여라"를 명시해야 첫 인상이 깔끔해집니다. 셋째, 코드 블록 언어 태그를 비워두면 깃허브에서 하이라이트가 깨지니, bash·ts 같은 태그를 명시하라는 요구를 지웠는지 꼭 확인하세요. 검증은 Claude와 ChatGPT 기준입니다.

#README#문서화#오픈소스