README + 명령 하나로 돌리기
깔끔한 배치와 진짜 테스트가 있어요. 마지막 구간은 검토자가 실제로 가장 먼저 부딪히는 부분이에요: README와 그것을 돌리는 명령 하나. 시작하는 데 10분을 추측해야 하는 프로젝트는 작동해도 망가진 느낌이에요. 복제해서 한 줄로 돌릴 수 있는 프로젝트는 작아도 전문적인 느낌이에요. 같은 코드 -> 완전히 다른 인상.
README는 계약이에요. 읽는 사람은 위에서 아래로 훑고, 예측할 수 있는 모양을 기대해요: 제목으로 프로젝트 이름, 그다음 설치 방법, 그다음 사용 방법, 그다음 테스트 방법. 구체적으로, 좋은 README에는 최상위 제목 줄(# Something)이 있고, 그다음 이 섹션들이 이 순서로 있어요:
# Triage Copilot
## Setup
pip install -e . # editable install
cp .env.example .env # then paste your real key into .env
## Usage
python -m triage # the one-command run
## Tests
pytest
읽는 사람이 단계로 따라가니 순서가 중요해요. Setup 앞의 Usage는 헷갈려요 -> 설치하지 않은 걸 쓸 수는 없어요. 그래서 # 제목이 나오고, 그 뒤에 ## Setup, 그다음 ## Usage, 그다음 ## Tests가 각각 앞의 것 뒤에 나올 때만 True를 돌려주는 확인기 validate_readme(text)를 써요. 빠진 섹션이나 순서가 뒤바뀐 섹션은 False를 돌려줘요. 요령: 줄을 한 번 돌며 지금 어디 있는지 "커서"를 두고, 각 섹션이 커서 뒤 위치에 나오도록 요구하세요.
명령 하나로 돌리기. 위의 ## Usage 줄이 명령 하나라는 걸 보세요. 그게 make run 같은 Makefile이나 justfile 대상의 목표예요 -> 아무도 전체 호출을 기억할 필요가 없도록 프로젝트를 띄우는 기억하기 쉬운 명령 하나. 프로젝트에 대해 그 명령 문자열을 돌려주는 make_run(name)을 쓰세요. 예: python -m triage(또는 make run). 패키지 디렉터리와 같은 방식으로 정규화한 프로젝트 이름이 들어가야 하니, 다른 프로젝트는 다른 명령을 내요.
진짜 저장소를 위한 솔직한, 채점하지 않는 메모 두 개. 첫째, 비밀: cp .env.example .env 단계가 있는 건 진짜 API 키가 .env에 들어가기 때문이에요. 그 파일은 .gitignore에 더하고 결코 커밋하지 마세요. 커밋하는 건 .env.example뿐이에요 -> 자리 표시자 값으로 된 설정의 모양. 공개 저장소에 키를 흘리는 건 포트폴리오 프로젝트의 고전적인 실수예요. 둘째, 이걸 배포하기: 온라인에 올리려면 작은 Dockerfile을 쓰고(저장소를 복사하고, pip install 하고, 실행 명령을 진입점으로 정해요) Render, Railway, Fly 같은 PaaS로 밀어 올려요. 그 부분은 브라우저에서 돌리거나 채점할 수 없어요 -> 공개할 때 여러분이 할 일이에요. Run을 눌러 완전한 README를 검증하고 실행 명령을 출력하세요.
좋은 README의 결정적인 두 조각을 쓰세요. validate_readme(text)는 최상위 # 제목이 나오고, 그다음 ## Setup, 그다음 ## Usage, 그다음 ## Tests가 각각 앞의 것 뒤에 나올 때 그리고 그때만 True를 돌려줘요(빠진 섹션이나 순서가 뒤바뀐 섹션 -> False). make_run(name)은 패키지 디렉터리처럼 정규화한 프로젝트 이름이 든 명령 하나짜리 실행 문자열(예: python -m <pkg>나 make run)을 돌려줘서, 다른 이름은 다른 명령을 내요.
이 연습은 곧 열려요
앞의 레슨을 마치면 이 레슨이 열려요. 강좌 전체가 무료이고 계정도 필요 없으며, 이 레슨은 지금 바로 읽을 수 있어요.
이 브라우저가 learn.floati.life의 쿠키를 막고 있어서, 여기서 마친 레슨들이 순서대로 열리지 않아요. 이 사이트의 쿠키를 허용하고 새로고침하세요.