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に全コマンドを書く必要はありません。日常的に使うものだけに絞ります。
例：
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ではなく以下の場所に逃がしたほうが、READMEが入口として機能し続けます。
/docs/- Notion
- 社内Wiki
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は完全なドキュメントではなく、迷わず動くための入口として割り切るほうが長く機能します。
