개발 생산성 도구 기초집LESSON 15

문서화 기초: README, 설치 방법, 실행 방법, 결정 기록 남기기

난이도초급

예상 시간40분

선수지식14강 반복 작업 자동화

15강. 문서화 기초: README, 설치 방법, 실행 방법, 결정 기록 남기기

1. 이번 강의에서 해결할 문제

한 달 뒤 프로젝트를 열었을 때 설치 도구, 실행 위치, 검증 명령을 다시 찾아야 하면 시간이 낭비됩니다. 모든 메모를 거대한 한 파일에 쌓지 않고 독자가 필요한 정보를 빠르게 찾게 해야 합니다.

2. 학습 목표

3. 핵심 개념

README는 프로젝트의 입구입니다. 목적, 요구 버전, 시작 명령, 테스트 방법, 문서 링크를 담습니다. 오류 대응 절차는 Runbook, 오래 영향을 주는 기술 선택은 ADR(Architecture Decision Record)처럼 분리하면 README가 읽기 쉬워집니다.

버전은 실제 --version 결과를 기록하고 설치 화면이나 확장 기능이 달라질 수 있으면 공식 문서 확인일을 함께 남깁니다. 비밀번호·토큰·개인정보는 문서에 쓰지 않습니다.

4. 단계별 실습

Markdown · 파일 경로: README.md

README.md
# Productivity Lab

작은 점수 규칙을 테스트하며 개인 개발 워크플로를 연습하는 프로젝트입니다.

## 필요 도구
- Windows 11
- Node.js: `node --version`으로 확인한 버전
- Git: 상세 학습은 `/docs/developer-tools/git-github/` 참고

## 실행
PowerShell에서 프로젝트 루트로 이동한 뒤:

```powershell
npm.cmd test
```

## 기본 검증
```powershell
npm.cmd run check
```

## 관련 문서
- `docs/test-checklist.md`
- `docs/bugs/`
- `docs/decisions/`

Markdown · 파일 경로: docs/decisions/001-use-node-built-in-test.md

docs/decisions/001-use-node-built-in-test.md
# 001. Node.js 기본 테스트 도구 사용

- 상태: 채택
- 배경: 작은 실습에 새 의존성을 추가하지 않으려 한다.
- 결정: 현재 과정에서는 `node:test`를 사용한다.
- 결과: 설정은 단순하지만 브라우저 UI 테스트는 별도로 수행한다.

PowerShell · 실행 위치: D:\Projects\productivity-lab

Get-Content .\README.md
npm.cmd run check

예상 결과: 새 사용자가 README 순서만으로 검사 명령을 실행할 수 있습니다.

5. 도구와 설정이 동작하는 이유

README가 변하지 않는 진입점을 제공하고 세부 기록을 링크하면 독자가 필요한 깊이까지만 읽을 수 있습니다. 결정 기록은 “무엇을 선택했는가”뿐 아니라 당시 제약과 대가를 보존해 같은 논의를 반복하지 않게 합니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ