프로젝트 폴더를 열거나 깃허브 저장소에 처음 들어갔을 때 가장 먼저 눈에 들어오는 파일이 있다. 대문자로 적힌 README다. 압축 파일을 풀었을 때도, 오픈소스 라이브러리를 내려받았을 때도, 누군가 만든 게임 빌드를 실행하려 할 때도 이 파일이 목록 맨 위에 놓여 있다. 이름 그대로 "먼저 읽어 달라(read me)"는 뜻을 담은 안내문이다.
그런데 이 파일이 왜 생겼는지, 정확히 어떤 역할을 하고 무엇을 담아야 하는지를 설명할 수 있는 사람은 의외로 많지 않다. 단순히 깃허브가 요구하는 형식적 장식처럼 여기는 경우도 흔하다. 오픈소스 개발자 오마르 압델하피스는 "새 프로젝트를 시작할 때마다 README.md는 가장 마지막에 작성하는 파일이며, 무엇을 적어야 할지 늘 망설이게 만드는 파일"이라고 고백한 바 있다. 많은 개발자가 공감하는 지점이다.
하지만 README는 50년 가까이 이어져 온 개발 관습이자, 자유 소프트웨어와 오픈소스 문화의 핵심 장치였다. 그리고 최근에는 바이브코딩(vibe coding) 흐름 속에서 AI에게 프로젝트의 맥락을 전달하는 문서로 다시 주목받고 있다. 이 문서에서는 README.txt가 등장한 역사적 배경과 흥미로운 유래 일화, 파일에 담기는 표준 구성 요소, 그리고 깃과 깃허브를 거쳐 AI 코딩 시대에 이르기까지 README의 의미가 어떻게 확장돼 왔는지를 사실 기반으로 정리한다.
1. README의 정의와 기본 역할
README 파일은 어떤 디렉터리나 압축 파일 안에 들어 있는 다른 파일들에 대한 설명 정보를 담은 문서다. 위키백과의 정의에 따르면 그 범위는 디렉터리 안의 파일들에 그치지 않고 하위 디렉터리, 때로는 전체 디렉터리 트리에까지 이른다.
해커 문화를 집대성한 자곤 파일(Jargon File)은 README를 더 멋지게 표현한다. "유닉스 소스 배포본의 최상위 디렉터리에 관례적으로 포함되는 해커의 시선에서 본 입문서로, 더 상세한 문서로 가는 포인터, 크레딧, 잡다한 개정 이력, 메모 등을 담는다." 즉 README는 코드 전체를 읽지 않아도 방향을 잡게 해 주는 지도이자 첫 관문이다.
1.1. README가 맡는 핵심 기능
- 프로젝트가 무엇이고 어떤 문제를 해결하는지 첫인상으로 전달한다.
- 설치·실행·설정 방법을 안내해 사용자가 막히지 않게 한다.
- 라이선스, 연락처, 기여 방법 같은 협업·법적 정보를 모아 둔다.
- 새로 합류한 사람이 코드 전체를 읽지 않아도 구조와 의도를 파악하게 돕는다.
깃허브 공식 문서는 README의 목적을 "다른 사람에게 이 프로젝트가 왜 유용한지, 무엇을 할 수 있는지, 어떻게 사용하는지를 알려 주는 것"이라고 설명한다. 한마디로 README는 프로젝트의 얼굴이자 첫 번째 문서다.
핵심 포인트: README는 폴더나 저장소를 처음 마주한 사람을 위한 안내문이다. 무엇인지, 어떻게 쓰는지, 누가 만들었는지를 한곳에 모아 두는 것이 본질적 역할이며, 형식보다 이 목적을 충족하는지가 품질을 가른다.
2. README.txt는 언제, 왜 생겼을까
README를 포함하는 관습은 1970년대 중반에 시작된 것으로 알려져 있다. 다만 그 기원이 100% 명확하지는 않다. 일부 자료는 1974년경 PDP-10 시절까지 거슬러 올라간다고 보고, 더 이른 시기를 지목하는 견해도 있다.
구체적인 흔적이 디지털 아카이브에 남아 있다. PDP-10 DECUS 프로젝트에는 1974년 11월 27일자 readme.txt가 존재하며, SPICE·SINC·SLIC라는 회로 분석 프로그램의 운영법을 담고 있다. 이 파일에는 "이 페일세이프 테이프에는 회로 분석 프로그램이 들어 있다"는 설명과 함께, 당시 SPICE가 약 47K 메모리에서 실행되며 FORTRAN-10 버전 4가 필요하다는 기술적 요구사항, 그리고 "행운을 빈다(Good luck!)"는 작성자 애슐리 그레이슨의 인사까지 적혀 있다. 1975년 3월 27일자 UCI LISP 시스템의 read.me도 비슷한 형태로 남아 있다.
이후 README는 초기 유닉스 곳곳에 등장한다. 1977년 프로그래머스 워크벤치의 lex 소스, 1979년 유닉스 7판의 /usr/doc/README, 1980년 초기 32비트 BSD의 usr/doc/README가 대표적이다. 더 거슬러 올라가면 1960년대 천공카드 시절의 증언도 있다. 당시에는 천공카드 묶음에 종이 한 묶음(reem)을 붙이고 그 위에 README라고 인쇄해, 카드의 사용법과 적재 순서, 디버깅을 위한 천공 방식 출력물까지 담았다는 것이다.
2.1. 왜 하필 전부 대문자였을까
- 유닉스에서는 대부분의 파일 이름이 소문자였기 때문에 대문자가 시각적으로 도드라졌다.
- ASCII 정렬에서 대문자(65~90)는 소문자(97~122)보다 앞에 온다.
- 그래서
README는 파일 목록에서 다른 소스 코드보다 위쪽에 정렬돼 가장 먼저 보였다. - 사용자의 시선을 끌고 "먼저 읽어라"는 신호를 주려는 의도적 명명이었다.
흥미로운 점은 이름의 유래에 대한 해커 문화권의 해석이다. 1978년 자곤 파일은 README 관습을 루이스 캐럴의 소설 "이상한 나라의 앨리스"에 빗댄다. 작품 속에서 앨리스가 "날 먹어(Eat Me)"와 "날 마셔(Drink Me)"라고 적힌 마법의 음식과 음료를 마주하는 유명한 장면이 있는데, 해커들에게 README가 무엇이냐고 물으면 "한결같이" 이 장면을 떠올린다는 것이다. "날 읽어(Read Me)"라는 명령형 이름에는 이런 위트가 담겨 있다. 명령형 라벨이 호기심을 자극하고 행동을 유도한다는 점에서, 앨리스의 음식과 README는 같은 화법을 쓴다.
3. README.txt에 들어가는 표준 구성 요소
README의 가장 큰 특징은 표준이 없다는 점이다. 위키백과도 "표준화가 없어 형식과 내용이 극적으로 다르다"고 명시한다. 이 자유로움이 다양한 확장을 가능하게 했지만 동시에 품질 편차를 낳았다. 그럼에도 오랜 관습과 깃허브·오픈소스 커뮤니티의 권장 사항을 종합하면 공통된 뼈대가 보인다. 아래 표는 소프트웨어 README에 자주 포함되는 항목과 목적을 정리한 것이다.
| 구성 요소 | 목적 | 비고 |
|---|---|---|
| 프로젝트 제목·로고 | 무엇을 하는 프로젝트인지 첫인상으로 전달 | 종종 로고 포함 |
| 프로젝트 설명 | 목적과 만든 이유, 주요 사용 사례 요약 | 한두 문단 |
| 설치 방법 | 필요한 도구·라이브러리와 단계별 안내 | 길면 INSTALL로 분리 |
| 사용 예시 | 가장 단순한 사용법을 짧게 시연 | npm run build 등 인라인 표기 |
| 만든 이유 | 어떤 문제를 풀고 기존 대안과 무엇이 다른지 | 비교 우위 설명 |
| 문서 링크 | 상세 문서나 위키로 연결 | 큰 프로젝트일수록 분리 |
| 라이선스 | 사용·배포 권리 정보 | MIT, Apache 등 |
| 변경 이력 | 버전별 변경 요약 | 길면 CHANGELOG로 분리 |
| 기여 방법 | 협업 절차·규칙 안내 | CONTRIBUTING로 분리 가능 |
| 크레딧·연락처 | 제작자·후원자·문의 경로 | 길면 CREDITS로 분리 |
README 외에 정보를 나누어 담는 관습도 자리 잡았다. 기여자는 AUTHORS, 감사 인사는 THANKS, 상세 변경 이력은 CHANGELOG, 사용자용 변경 요약은 NEWS, 설치는 INSTALL, 라이선스는 COPYING이나 LICENSE, 알려진 버그는 BUGS, 기여 안내는 CONTRIBUTING, 자주 묻는 질문은 FAQ, 계획은 TODO에 분리해 둔다. 이들 역시 공식 표준이 아니라 Gnits 표준과 GNU Autotools 같은 관행이 만든 약속이다. GNU 코딩 표준은 README에 최소한 "패키지에 대한 전반적인 개요"를 담을 것을 권장한다.
3.1. 연구로 확인된 README의 실제 구성
실제 README가 무엇을 담는지에 대한 학술 연구도 있다. 2018~2019년 발표된 "깃허브 README 파일의 내용 분류" 연구는 무작위로 선정한 393개 README의 4,226개 섹션을 사람이 직접 분류했다. 그 결과 README 내용은 크게 여덟 가지 범주, 즉 "What(무엇)", "Why(왜)", "How(어떻게)", "When(이력·상태)", "Who(기여·연락)", "References(참조)", "Contribution(기여 안내)", "Other(기타)"로 나뉘었다. 이 연구는 209회 이상 인용되며, README 작성에서 "무엇을·왜·어떻게"를 명확히 전달하는 것이 핵심임을 데이터로 뒷받침했다.
4. 깃·깃허브가 README의 위상을 바꾼 과정
README가 단순한 안내문에서 프로젝트의 대문으로 격상된 결정적 계기는 깃허브다. 깃허브는 저장소 최상위 디렉터리에 README가 있으면 저장소 첫 페이지에 자동으로 렌더링해 보여 준다. 방문자가 코드를 살펴보기 전에 README부터 마주하게 되는 구조다.
여기에 마크다운(Markdown)이 결합하면서 표현력이 크게 확장됐다. 마크다운은 2004년 존 그루버가 만든 텍스트 기반 마크업 언어로, 쉽게 쓰고 읽으면서 HTML로 변환된다. 깃허브는 README.md를 깃허브 플레이버드 마크다운으로 처리해 제목·목록·표·코드 블록·이미지를 깔끔하게 렌더링한다. 여기에 빌드 상태, 버전, 다운로드 수, 라이선스 등을 작은 라벨로 보여 주는 배지(badge) 문화가 더해졌다. shields.io 같은 서비스가 수백 가지 서비스의 배지를 SVG로 제공하면서, README 상단에 배지를 나열하는 것이 사실상 관행이 됐다. 이 때문에 오늘날 다수 프로젝트가 평문 README.txt 대신 README.md를 사용한다.
4.1. README.txt와 README.md의 관계
.txt는 평문 텍스트로, 운영체제를 가리지 않고 어디서나 그대로 열린다..md는 마크다운 확장자로, 깃허브 등에서 서식이 적용되어 보인다.- 둘 다 먼저 읽어 달라는 README의 본질적 역할은 동일하다.
- 깃 환경에서는 렌더링 이점 때문에
.md가 사실상 표준처럼 쓰인다.
초기 유닉스 README와 현대 깃허브 README를 비교하면 변화의 방향이 분명해진다.
| 항목 | 초기 유닉스 README | 현대 깃허브 README |
|---|---|---|
| 주된 독자 | 같은 시스템을 쓰는 동료 개발자 | 전 세계 불특정 사용자·기여자 |
| 형식 | 평문 텍스트(.txt) | 마크다운(.md), 배지·이미지 포함 |
| 핵심 내용 | 파일 목록·실행법·주의사항 | 개요·설치·사용법·라이선스·기여 |
| 표시 방식 | 직접 열어서 읽음 | 저장소 첫 페이지에 자동 렌더링 |
| 작성 시점 인식 | 배포 직전 마지막에 작성 | 설계 단계부터 작성 권장(RDD) |
주목할 만한 개발문화 흐름이 README 주도 개발(README Driven Development, RDD)이다. 깃허브 공동 창업자이자 전 사장이었던 톰 프레스턴워너가 2010년 8월에 제안한 방식으로, 핵심은 단 한 문장으로 요약된다. "README를 먼저 써라(Write your Readme first)." 그는 코드, 테스트, 스토리, 그 무엇보다 먼저 README를 쓰라고 강조했다.
프레스턴워너는 "잘못된 명세를 완벽하게 구현해도 가치가 없다"며, 거대한 폭포수식 명세와 명세 부재 사이의 현실적 중간 지대로 README를 위치시켰다. RDD는 문서 주도 개발(DDD)의 제한된 형태로, 설계 문서를 README 한 파일로 묶어 과도한 명세를 스스로 억제하게 만든다. 그가 든 이점은 네 가지다. 코드를 바꾸는 부담 없이 공개 인터페이스와 구조를 미리 사고할 수 있고, 의욕이 가장 높은 초기에 자연스럽게 문서가 남으며, 팀원들이 인터페이스를 미리 알고 병행 작업할 수 있고, 글로 적힌 안을 두고 논의하기가 훨씬 쉽다는 것이다. 그는 "README를 코드베이스에서 가장 중요한 단 하나의 문서로 여기고, 그것을 먼저 쓰는 것이 마땅하다"고 끝맺었다.
핵심 포인트: 깃허브의 자동 렌더링과 마크다운·배지 문화가 결합하면서 README는 열어 보는 안내문에서 프로젝트의 첫 화면으로 위상이 바뀌었다. RDD처럼 README를 설계의 출발점으로 삼는 흐름은 이 파일이 단순 문서가 아니라 사고의 도구임을 보여 준다.
5. 바이브코딩 시대, README가 다시 중요해진 이유
바이브코딩은 개발자가 자연어로 원하는 기능을 설명하면 AI가 코드를 생성하도록 유도하는 새로운 개발 방식이다. 사람이 한 줄씩 직접 타이핑하기보다, AI에게 의도와 맥락을 전달하고 결과를 검증·조율하는 흐름에 가깝다. 이 패러다임에서 가장 중요한 자원이 바로 컨텍스트(맥락)이며, README는 그 컨텍스트를 담는 그릇으로 재조명되고 있다.
AI 코딩 도구들은 프로젝트 구조와 규칙을 이해하기 위해 별도의 안내 파일을 참조한다. 대표적으로 CLAUDE.md는 대화를 시작할 때 자동으로 컨텍스트에 포함되는 파일로, 자주 쓰는 명령이나 프로젝트 규칙을 적어 두기에 적합하다. 커서(Cursor)의 규칙 파일(.cursor/rules/)도 같은 맥락이다. AI 에이전트가 시간이 지나면 규칙을 잊거나 무시하는 현상이 자주 보고되는데, 이런 안내 파일은 그 일관성을 잡아 주는 장치다.
특히 주목할 표준이 AGENTS.md다. 공식 사이트는 이를 "에이전트를 위한 README"라고 직접 부른다. 2025년 등장한 이 형식은 OpenAI Codex, 구글의 Jules, 커서, Amp, Factory 등 여러 진영의 협업으로 만들어진 개방형 표준이며, 현재 리눅스 재단 산하 Agentic AI Foundation이 관리한다. 발표 시점 기준 6만 개 이상의 오픈소스 프로젝트가 이 파일을 채택했고, OpenAI의 메인 저장소 한 곳에만 88개의 AGENTS.md가 들어 있을 정도다.
AGENTS.md를 README와 굳이 분리한 이유도 분명하다. README.md는 빠른 시작, 프로젝트 설명, 기여 가이드처럼 사람을 위한 문서인 반면, AGENTS.md는 빌드 단계, 테스트 명령, 코드 컨벤션처럼 사람 기여자에게는 잡음이 될 수 있지만 에이전트에게는 필수인 상세 맥락을 담는다. 거대한 모노레포에서는 하위 패키지마다 AGENTS.md를 두고, 에이전트가 수정 중인 파일에서 가장 가까운 파일을 우선 읽도록 설계돼 있다.
5.1. 바이브코딩에서 README·컨텍스트 파일이 하는 일
- 프로젝트의 목적·구조·기술 스택을 AI에게 한 번에 전달한다.
- 코딩 규칙과 컨벤션을 명시해 AI가 일관된 코드를 만들게 한다.
- 빌드·테스트·실행 명령을 적어 두어 반복 설명을 줄인다.
- 사람과 AI가 같은 맥락을 공유해 협업의 어긋남을 막는다.
바이브코딩 실습 가이드들은 게임이나 앱을 만들 때 README를 먼저 작성해 AI에게 구조와 의도를 알려 주라고 권한다. 다만 처음부터 과도하게 설계하지 말고 기본 수준에서 시작해 반복적으로 다듬으라고 조언한다. "기본적이어도 괜찮다, 목표는 AI에게 구조와 의도에 대한 맥락을 주는 것"이라는 것이다. 이는 톰 프레스턴워너의 RDD 정신과 정확히 맞닿아 있다. 차이가 있다면, 이제 README의 독자에 사람뿐 아니라 AI 에이전트가 추가되었다는 점이다.
최근에는 "컨텍스트 엔지니어링이 새로운 바이브코딩"이라는 말이 나올 만큼, AI에게 무엇을 어떻게 전달하느냐가 결과 품질을 좌우한다는 인식이 자리 잡았다. README와 그 계열 안내 파일은 이 컨텍스트 전달의 출발점이다. 1970년대에 사람에게 "먼저 읽어 달라"고 외쳤던 파일이, 이제는 AI에게 "먼저 읽혀야 하는" 파일로 역할을 넓힌 셈이다.
핵심 포인트: 바이브코딩에서 README와 AGENTS.md·CLAUDE.md는 사람과 AI가 공유하는 컨텍스트의 핵심 문서다. 사람용 안내는 README가, 에이전트용 상세 맥락은 AGENTS.md가 맡는 식으로 역할이 나뉘며, 코드를 짜기 전에 먼저 정리해 두면 AI 협업의 정확도가 올라간다.
6. 마무리
위에서 살펴본 README.txt의 핵심 내용을 정리하면 다음과 같습니다.
핵심 요약:
- README는 폴더·프로젝트의 첫 안내문으로, 무엇인지·어떻게 쓰는지·누가 만들었는지를 한곳에 모은 문서다.
- 1970년대 중반 유닉스 관습에서 출발했으며, 1974년 PDP-10 readme.txt가 대표적 흔적이고 천공카드 시절까지 거슬러 올라간다는 증언도 있다.
- 대문자 이름은 ASCII 정렬상 앞에 오고 소문자 사이에서 도드라져 가장 먼저 보이도록 한 의도였으며, 이상한 나라의 앨리스의 Eat Me·Drink Me에서 유래했다는 해커 일화가 전해진다.
- 표준이 없어 형식은 다양하지만, 개요·설치·사용법·라이선스·기여·연락처가 공통 뼈대를 이루며 학술 연구도 What·Why·How를 핵심으로 꼽았다.
- 깃허브의 자동 렌더링과 마크다운·배지 문화로 README는 프로젝트의 첫 화면이 되었고, RDD는 코드보다 README를 먼저 쓰는 설계 도구로 활용한다.
- 바이브코딩 시대에는 6만 개 이상이 채택한 AGENTS.md와 CLAUDE.md 같은 에이전트용 안내 파일로 확장되어, 사람과 AI가 맥락을 공유하는 핵심 문서가 되었다.
새 프로젝트를 시작한다면 코드를 짜기 전에 README부터 가볍게 적어 보는 것을 권한다. 프로젝트의 목적과 사용법을 한 문단으로 정리하는 것만으로도 방향이 잡히고, 그 문서는 사람 동료와 AI 에이전트 모두에게 가장 먼저 읽히는 안내서로 두고두고 쓰인다.
자주 묻는 질문
- README.txt와 README.md는 무엇이 다른가요?
둘 다 먼저 읽어 달라는 README의 역할은 같습니다. 차이는 확장자에 있습니다. .txt는 평문 텍스트로 어떤 환경에서나 그대로 열리고, .md는 마크다운 형식이라 깃허브 같은 곳에서 제목·표·이미지·배지가 서식대로 렌더링됩니다. 깃 환경에서는 표현력과 자동 렌더링 이점 때문에 README.md가 사실상 표준처럼 쓰입니다.
- README는 정확히 언제 처음 생겼나요?
README를 포함하는 관습은 1970년대 중반에 시작된 것으로 알려져 있습니다. 디지털 아카이브에 남은 가장 이른 흔적은 1974년 11월 27일자 PDP-10 DECUS 프로젝트의 readme.txt로, 회로 분석 프로그램의 운영법을 담고 있습니다. 1977년 프로그래머스 워크벤치, 1979년 유닉스 7판에도 등장하며, 1960년대 천공카드 시절까지 거슬러 올라간다는 증언도 있습니다.
- README는 왜 전부 대문자로 쓰나요?
두 가지 이유가 겹칩니다. 유닉스에서는 대부분의 파일 이름이 소문자라 대문자가 시각적으로 도드라졌고, ASCII 정렬에서 대문자(65~90)는 소문자(97~122)보다 앞에 옵니다. 그래서 README가 파일 목록 맨 위에 정렬되어 가장 먼저 눈에 띄게 됩니다. 사용자의 시선을 끌려는 의도적 명명입니다.
- README가 이상한 나라의 앨리스에서 유래했다는 게 사실인가요?
확정된 어원은 아니지만 해커 문화권에서 널리 전해지는 일화입니다. 1978년 자곤 파일에 따르면, 해커들에게 README의 유래를 물으면 한결같이 루이스 캐럴의 이상한 나라의 앨리스에서 앨리스가 Eat Me, Drink Me라고 적힌 마법의 음식과 음료를 마주하는 장면을 떠올린다고 합니다. Read Me라는 명령형 이름이 그 화법과 닮았다는 것입니다.
- README에는 보통 무엇을 담아야 하나요?
정해진 표준은 없지만 일반적으로 프로젝트 제목과 설명, 만든 이유, 설치 방법, 사용 예시, 문서 링크, 라이선스, 변경 이력, 기여 방법, 크레딧과 연락처를 담습니다. 깃허브 README 393개를 분석한 연구도 What(무엇)·Why(왜)·How(어떻게)를 핵심 범주로 꼽았습니다. 항목이 길어지면 INSTALL, CHANGELOG, CONTRIBUTING 같은 별도 파일로 분리하기도 합니다.
- README 주도 개발(RDD)이란 무엇인가요?
깃허브 공동 창업자 톰 프레스턴워너가 2010년 제안한 방식으로, 코드나 테스트보다 README를 먼저 작성하는 개발 접근법입니다. 그는 잘못된 명세를 완벽하게 구현해도 가치가 없다며, README를 먼저 쓰면 코드 변경 부담 없이 인터페이스와 구조를 미리 사고할 수 있고, 의욕이 높은 초기에 문서가 남으며, 팀원이 병행 작업하기 쉽고 논의가 수월해진다고 설명했습니다.
- 바이브코딩에서 README와 AGENTS.md는 어떤 역할을 하나요?
바이브코딩은 자연어로 의도를 설명하면 AI가 코드를 만드는 방식이라 맥락 전달이 결과 품질을 좌우합니다. README.md는 사람을 위한 안내를 담고, AGENTS.md는 빌드·테스트 명령과 코드 컨벤션 같은 에이전트용 상세 맥락을 담습니다. AGENTS.md는 OpenAI Codex, 커서, 구글 Jules 등이 함께 만든 개방형 표준으로 6만 개 이상의 프로젝트가 채택했으며, 에이전트를 위한 README라고도 불립니다.