READMEは、プロジェクトを「聞かずに動かす」ための入口です。
ところが現場では、READMEがこうなりがちです。
-
- 情報が増えすぎて、誰も読まない
- 古い手順が残っていて、むしろ混乱する
- 結局「詳しい人に聞く」が最短になる
READMEは「全部を書く場所」ではありません。
迷わず動けるための最低限だけに絞ったほうが、実際は運用が安定します。
この記事では、Windows / Mac 混在でも破綻しにくい「READMEに書くべき最小セット」をまとめます。
結論：READMEに書くべきものは「4つ」だけ
READMEに必要なのは、基本この4つです。
- 前提（必要なツール / バージョン）
- セットアップ手順（コピペで動く）
- よく使うコマンド（dev / build / test など）
- ルール（最低限。CIと矛盾しない）
この4つが揃っていれば、新しく入った人も、久々に触る人も「聞かずに動ける」状態になります。
1. 前提を書く（ここは曖昧にしない）
最初に「何が必要か」を明記します。ここが曖昧だと、環境差で詰まります。
例：
- Node.js：
20.x（.node-versionなどを参照） - パッケージマネージャ：
npm - 依存関係の導入：通常は
npm ci
前提は箇条書きで十分です。長い説明は不要です。
2. セットアップ手順を書く（コピペで動く形）
READMEは「読ませる」より、コピペで動くことが大事です。
例（最小）：
# 依存関係を導入（lockfile通りに再現）
npm ci
# 開発サーバ
npm run devポイントは次の2つです。
- 「どこで、何を叩けばいいか」が一目で分かる
- 説明よりもコマンドを先に置く
3. よく使うコマンドを書く（“全部”は要らない）
READMEに全コマンドを書く必要はありません。日常的に使うものだけでOKです。
例：
npm run dev # 開発
npm run build # ビルド
npm test # テスト
npm run lint # lintこれだけでも「新規参加」「久々の再開」「別PCでの復旧」がかなり楽になります。
4. ルールを書く（最小でよい）
READMEのルールは、増やすほど守られません。実際に機能するレベルまで削ります。
依存関係の運用ルール（例）
- 依存関係を追加・更新するときは
npm install - それ以外（通常作業・CI）は
npm ci package-lock.jsonは必ずコミットする
Nodeの運用ルール（例）
- Nodeのバージョンは
.node-version（または同等の定義ファイル）を正とする - 複数の方法でNodeを管理しない（OS直入れ / 別ツール混在を避ける）
このくらいで十分です。
「書かない」ほうがいいこと
READMEが読まれなくなる原因は、たいていここにあります。
- 長い背景説明
- すぐ変わる細かい手順（手動ビルドの手順など）
- 特定環境だけの例外（個人端末依存の話）
- 何ページにもわたる運用ポリシー
書きたくなったら、READMEではなく
/docs/- Notion
- 社内Wiki
に逃がしたほうが、READMEが“入口”として生き続けます。
READMEのゴールは「聞かなくても動ける」こと
READMEを整備する目的は、情報を網羅することではなく
- 迷いを減らす
- 手戻りを減らす
- 新規参加の摩擦を下げる
この3点です。
READMEは最小限でいい。最小限だからこそ、読まれて使われます。
私はそう考えています。
付録：READMEテンプレ（最小構成）
そのままコピペで使える、最小テンプレです。
# Project Name
## 前提
- Node.js：18.x 以上
- パッケージマネージャ：npm
## セットアップ
```bash
npm ci
npm run dev
```
## よく使うコマンド
```bash
npm run dev # 開発
npm run build # ビルド
npm test # テスト
npm run lint # lint
```
## ルール
- 依存関係の変更は `npm install`
- 通常作業・CI は `npm ci`
- `package-lock.json` は必ずコミットする
## ディレクトリ構成（概要）
```text
├─ src/ # フロントエンドの実装（主に触る）
├─ dist/ # ビルド成果物（生成物・直接編集しない）
├─ docker/ # Docker 設定
├─ tasks/ # 画像圧縮タスクなど
├─ .vscode/ # エディタ設定
├─ .node-version # Node.js バージョン管理
├─ webpack.config.js # webpack 設定
├─ package.json
└─ README.md
```
基本的に編集するのは `src/` 以下です。
`dist/` はビルド時に自動生成されるため、直接編集しません。READMEは「完全なドキュメント」ではなく、迷わず動くための“入口”として割り切るほうが、長く機能します。