README(설명서 파일)
코드를 받아 열었을 때 제일 먼저 읽는 문서예요. 이게 뭐고, 어떻게 켜고, 무엇을 조심해야 하는지를 한 장에 적어 둔 안내문이라, 이 한 장이 있고 없고가 다음 사람이 쓰는 시간을 하루와 사흘로 갈라요.
쉽게 말하면
가게를 하루 맡기고 나가면서 계산대 옆에 붙여 두는 쪽지예요. 셔터 올리는 법, 포스 켜는 순서, 냉장고 세 번째 칸은 손대지 말 것. 이 쪽지 한 장이 있으면 처음 온 사람도 문을 열어요. 없으면 아무리 성실한 사람도 전화를 열 번 걸어요. README 가 딱 그 쪽지예요. 코드 폴더 맨 앞에 놓여서, 받은 사람이 아무것도 묻지 않고 시작할 수 있게 해 줘요.
README 는 코드 폴더의 첫 장에 놓이는 한 장짜리 안내문이에요. 파일 하나고, 특별한 프로그램 없이 메모장으로도 열려요.
이름을 전부 대문자로 쓰는 건 오래된 약속이에요. 파일 목록에서 맨 위로 올라오게 하려고요. 코드를 올려 두는 곳에서는 폴더를 열자마자 이 문서가 저절로 펼쳐져 보여요.
새로 맡은 사람이 첫날을 통째로 파악에만 써요. 그 시간이 그대로 견적에 붙어요.
삼십 분 안에 화면이 뜨고, 물어볼 것은 진짜 물어봐야 할 것만 남아요.
여기에 뭘 적나
적을 것은 정해져 있어요. 일곱 줄이면 충분하고, 이 일곱 줄이 빠짐없이 있으면 그 README 는 제 역할을 다한 거예요.
| 적는 항목 | 무엇을 적나 | 빠지면 생기는 일 |
|---|---|---|
| 이게 뭔가 | 무슨 서비스인지 두세 줄. 어느 가게의 어떤 화면인지까지 적어요 | 받은 사람이 코드를 읽어서 용도를 추측해요. 추측이 틀리면 엉뚱한 것을 고쳐요 |
| 어떻게 켜나 | 받은 다음 무엇을 순서대로 실행하면 화면이 뜨는지 그대로 적어요 | 가장 많이 빠지고 가장 비싼 항목이에요. 이거 하나 없어서 이틀이 날아가요 |
| 무엇이 필요한가 | 미리 깔려 있어야 하는 것과 그 버전을 적어요 | "제 컴퓨터에선 되는데요"가 여기서 나와요. 버전이 달라서 안 도는 거예요 |
| 채워야 할 값 | 주소·열쇠처럼 사람마다 다르게 채워야 하는 칸의 목록이에요 | 실행은 되는데 결제나 메일만 조용히 안 돼요. 원인 찾기가 제일 오래 걸리는 종류예요 |
| 폴더 지도 | 화면은 어디, 장부는 어디에 있는지 큰 덩어리만 다섯 줄로 | 고쳐 달라고 한 곳을 못 찾아서 되묻는 연락이 반복돼요 |
| 손대면 안 되는 것 | 자동으로 만들어지는 폴더, 건드리면 안 되는 설정을 이름으로 적어요 | 지워도 되는 줄 알고 지워요. 되돌리는 데 반나절이에요 |
| 막히면 누구에게 | 담당자와 연락 방법, 그리고 참고할 문서 주소예요 | 급할 때 물어볼 곳을 못 찾아 손님 응대가 같이 늦어져요 |
두 번째 줄이 전부예요
일곱 개 중 하나만 남기라면 어떻게 켜나예요. 받은 사람이 화면 하나를 띄우는 순간부터는 나머지를 스스로 알아낼 수 있어요. 그 전까지는 아무것도 못 해요. README 를 처음 쓴다면 이 줄부터 적으세요.
적는 순서
잘 쓴 README 를 만드는 방법은 글솜씨가 아니에요. 직접 따라 해 보는 것이에요. 순서가 있어요.
- 1한 줄 소개부터 적어요. "우리 가게 예약을 받는 화면이에요" 정도면 충분해요. 길게 쓰면 아무도 안 읽어요.
- 2켜는 순서를 적어요. 지금 자기가 켤 때 하는 행동을 그대로, 빠뜨리지 말고 번호를 붙여요. 머릿속에 있는 것도 다 적어요.
- 3적은 대로 처음부터 따라 해 봐요. 여기서 대부분의 구멍이 드러나요. 미리 깔아 둔 게 있었다는 걸 이 단계에서 알게 돼요.
- 4채워야 할 값의 이름만 적어요. 값 자체는 절대 적지 않아요. 이름과 어디서 받는지만 적어요. 환경변수 쪽에 이유가 있어요.
- 5고칠 때마다 한 줄씩 갱신해요. 켜는 순서가 바뀌었는데 문서가 그대로면, 있는 것이 없는 것보다 나빠요. 틀린 안내는 사람을 엉뚱한 데로 보내요.
여기에 절대 적지 않는 것
비밀번호·결제 열쇠·손님 명단은 README 에 적지 않아요. 이 파일은 코드와 함께 통째로 복사되고 공개되기도 해요. 한 번 적혀 나가면 지워도 옛 기록에 남아요. 필요한 건 값이 아니라 "이런 칸을 채워야 한다"는 안내예요.
기획서와 뭐가 달라요
이름이 비슷한 문서가 여럿이라 자주 섞여요. 갈라 보면 읽는 시점과 읽는 사람이 전부 달라요.
| 문서 | 언제 읽나 | 누가 읽나 |
|---|---|---|
| 기획서 | 만들기 전에 | 만들어 줄 사람. 무엇을 만들지 합의하려고 읽어요 |
| README | 코드를 받은 직후에 | 고칠 사람. 켜고 손대려고 읽어요 |
| 인수인계 자료 | 사람이 바뀔 때 | 이어받는 사람. 계정·비용·계약까지 통째로 넘겨받으려고 읽어요 |
| 이용약관과 도움말 | 서비스를 쓰는 동안 | 손님. 코드 이야기는 한 줄도 안 나와요 |
그래서 기획서가 있다고 README 를 안 써도 되는 게 아니에요. 기획서는 무엇을 만들지를 적고, README 는 만들어진 것을 어떻게 켜는지를 적어요. 겹치는 부분이 거의 없어요.
확인해 보세요
외주 개발자에게 코드를 넘겨받았어요. README 에서 제일 먼저 확인할 줄은?
실제로 겪는 장면
장면 1 · 코드를 받았는데 열리지 않는다
“파일은 다 받았는데 뭘 눌러야 화면이 뜨는지 모르겠어요. 폴더만 200개예요.”
켜는 순서가 안 적혀 있는 거예요. 코드가 잘못된 게 아니라 안내가 없는 상태라, 새로 맡은 사람이 파악에만 며칠을 써요. 그 며칠이 다음 견적에 그대로 붙어요. 넘겨받는 날 할 일은 하나예요. 그 자리에서 README 를 열어 적힌 대로 따라 하고, 화면이 뜨는 것까지 같이 확인하는 거예요. 안 뜨면 그날 고쳐 달라고 하면 돼요. 사람이 떠난 뒤에는 이 부탁을 못 해요.
장면 2 · 반년 만에 내가 만든 것을 다시 열었다
“제가 만든 건데 어떻게 켜는지 기억이 안 나요.”
README 를 가장 많이 읽는 사람은 남이 아니라 반년 뒤의 자기 자신이에요. 만들 때는 전부 머릿속에 있어서 적을 필요를 못 느껴요. 그런데 그 기억은 몇 주면 흐려져요. 다섯 줄 적는 데 십 분이 들고, 안 적어 두면 다시 알아내는 데 반나절이에요. 이 계산은 혼자 만들 때도 똑같이 성립해요.
두 장면의 교훈이 같아요. README 는 만드는 사람을 위한 문서가 아니라 여는 사람을 위한 문서예요. 그래서 다 만든 뒤에 쓰는 게 아니라, 켤 수 있게 된 날 바로 적어 두는 게 맞아요.
자주 묻는 것
- Q. 코드를 볼 줄 모르는데 README 를 알아야 하나요?
- 쓰는 건 AI나 개발자가 해요. 사장님이 할 일은 받을 때 있는지 확인하고, 적힌 대로 켜지는지 그 자리에서 보는 것이에요. 이 확인 하나가 나중에 다른 사람에게 맡길 때 드는 값을 크게 줄여요. 계약서에 "README 를 포함해 넘긴다"는 한 줄을 넣어 두는 것도 좋아요. 외주 맡기기 쪽에 다른 항목도 있어요.
- Q. 얼마나 길게 써야 하나요?
- 한 화면을 넘기지 않는 게 좋아요. 길어지면 안 읽히고, 안 읽히면 없는 것과 같아요. 자세한 이야기는 따로 문서를 만들고 README 에서는 주소만 걸어 두세요. README 는 목차 겸 출발점이에요.
- Q. 파일 이름이 꼭 README 여야 하나요?
- 그렇게 두는 게 좋아요. 코드를 올려 두는 곳들이 이 이름을 알아보고 폴더를 열자마자 펼쳐서 보여 줘요. 이름이 다르면 그냥 파일 하나가 돼서 아무도 안 열어 봐요. 뒤에 붙는 .md 는 굵은 글씨나 목록 같은 간단한 꾸밈을 쓸 수 있는 글 형식이라는 표시예요.
- Q. 바이브캠퍼스에서 만든 것도 README 가 필요한가요?
- 만드는 동안에는 필요 없어요. 필요해지는 건 코드를 내보내 내 손에 두거나 다른 사람에게 맡길 때예요. 받은 폴더에 안내 문서가 이미 들어 있으면 그걸 바탕으로 내 사정에 맞게 고쳐 쓰고, 없으면 위의 표대로 일곱 줄을 채우면 돼요.
- Q. 내용이 바뀌면 매번 고쳐야 하나요?
- 전부는 아니고 켜는 순서와 채워야 할 값이 바뀌었을 때만요. 이 둘은 틀리면 바로 사람을 막아요. 폴더 지도나 소개는 조금 낡아도 큰 피해가 없어요. 어차피 다 못 고칠 거라면 이 둘만 최신으로 지키세요.
- Q. AI에게 써 달라고 해도 되나요?
- 네, 그게 빠르고 결과도 괜찮아요. 다만 켜는 순서만은 사람이 직접 따라 해 보고 확인해야 해요. AI는 코드를 보고 일반적인 순서를 적어 주는데, 이 컴퓨터에서만 필요한 준비물은 알 수 없어요. 따라 해 보면 그 차이가 바로 드러나요.
하나 더
README 에 적으면 안 되는 것은 어느 쪽일까요?
직접 해보기
지금 만들고 있는 것의 안내문을 받아 보세요
스튜디오에서 이렇게 말해 보세요. "지금 만든 것을 처음 받는 사람이 읽을 안내문을 한 장으로 써 주세요. 이게 뭔지, 어떻게 켜는지, 채워야 할 값이 무엇인지 순서대로요." 돌아온 글에서 켜는 순서가 몇 줄인지 세어 보면, 이 문서가 말한 일곱 줄 중 몇 개가 채워졌는지 바로 보여요.
스튜디오 열기더 깊이 (안 읽어도 괜찮아요)
왜 하필 글 형식이 .md 인가 · README 뒤에 붙는 .md 는 마크다운이라는 아주 단순한 글 형식이에요. 별표 두 개로 굵게, 앞에 짧은 줄을 붙여 목록으로 만드는 정도의 꾸밈만 있어요. 워드 파일처럼 프로그램이 있어야 열리는 게 아니라 메모장으로도 그대로 읽혀요. 꾸밈이 적어서 십 년 뒤에도 열리고, 코드와 나란히 두고 무엇이 바뀌었는지 줄 단위로 비교할 수 있어요. 안내문에 필요한 성질은 화려함이 아니라 이 두 가지예요.
여는 사람은 위에서 세 줄만 읽어요 · 받은 사람이 README 를 정독한다는 가정은 대개 틀려요. 위에서 몇 줄 읽고 켜는 순서를 찾아 바로 내려가요. 그래서 배치가 내용만큼 중요해요. 소개는 세 줄 안에 끝내고, 켜는 순서를 첫 화면 안에 두고, 나머지는 아래로 밀어요. 잘 쓴 README 와 못 쓴 README 의 차이는 정보의 양이 아니라 필요한 줄이 위에 있느냐인 경우가 많아요.
안내문이 코드와 같이 다니면 생기는 일 · README 를 따로 메일이나 메신저에 두지 않고 코드 폴더 안에 넣는 데는 이유가 있어요. 코드를 복사하면 안내문도 같이 복사되고, 커밋으로 함께 기록에 남아요. 그래서 반년 전 판을 꺼내 보면 그때의 켜는 순서도 같이 나와요. 메신저에 적어 둔 안내는 사람이 나가면 같이 사라지고, 어느 시점의 이야기인지도 알 수 없어요. 안내문을 코드 옆에 두는 습관 하나가 넘겨받을 때 다툼을 크게 줄여요.
이것만 기억하세요
- ·README 는 코드 폴더 맨 앞에 붙여 두는 한 장짜리 안내 쪽지예요
- ·일곱 줄이면 충분하고, 그중 하나만 남기라면 켜는 순서예요
- ·적은 뒤 직접 따라 해 봐야 빠진 준비물이 드러나요
- ·비밀번호와 열쇠 값은 적지 않아요. 채울 칸의 이름까지만 적어요
- ·가장 많이 읽는 사람은 남이 아니라 반년 뒤의 자기 자신이에요