【コード哲学エッセイ】 README は玄関だ。 〜 プロジェクトの第一印象を設計する 〜
コードの前に扉がある
リポジトリに入るとき、多くの人の視線は最初、コードタブに飛びません。
README が、いちばん前に出てくる。
かつての僕は、そこを「あとでいい」と思っていました。
動くものを先に。
説明は、気が向いたら。
でも、引き継ぎで他人の倉庫の扉を開けた日、思い知らされました。
中身がどれほど丁寧でも、玄関が暗い家は入る前に不安になる。
README が空に近いと、「ここ、本当に使っていいの？」と足がすくむ。
逆に、長大な仕様書が最初から貼ってあると、「入る前に試験があるの？」と息が詰まる。
どちらも出迎えの失敗なのだと思います。
玄関は、家のすべてを語らなくていい。
ここは誰の家でどんな礼儀で入ればいいかを、一目で伝える場所です。
玄関に置くものと、 奥に回すもの
僕が README に求めるのは、豪華な内装の一覧ではありません。
このプロジェクトは何のためか。
誰が読む前提か。
動かすには、最低限何が要るか。
それだけが、扉の横に立っていれば、客人は靴を脱げます。
細部の設計図や例外だらけの運用履歴は、奥の部屋に置けばいい。
リンク一本でつながっていれば、迷子にはなりにくい。
「全部を README に書かなきゃ」は、玄関に家具を積み込むのと同じです。
通れなくなるのは、来客のほうです。
第一印象は機能より先に届く
フリーランスで渡すものは、コードだけではありません。
信頼の温度も一緒に渡っている。
README が雑だと、相手の心のなかではこう翻訳されがちです。
「この人は、引き継ぎの順番を知らないのかもしれない」
「自分しか読めない前提で書いているのかもしれない」
逆に短くて整った README は、こう聞こえることがあります。
「入り口から迷わせたくない」
「あなたの時間を、無駄にしたくない」
技術力は、ファイルの奥に眠っていてもいい。
でも、最初の一秒で伝わるのは、文章の態度なのです。
いちばん最初の客人は、 未来の自分
他人を想定して README を書くほど、助かるのは半年後の僕でした。
「あのとき、何をしようとしていたんだっけ」
「このリポジトリ、どう立ち上げるんだっけ」
記憶は更新される。
でも README は、当時の自分が残した看板のまま残る。
だから玄関は、来客のためだけじゃない。
未来の自分を迷わせないための、過去の自分からの手紙でもあるのです。
コメントやコミットログが部屋の中のメモだとしたら、README は表札に近い。
家の名前と扉の開け方だけ、外から読めるようにしておく。
玄関を整えるのは、 飾りではなく礼儀だ
完璧な README を、今日から書けとは言いません。
ただ空っぽの玄関に気づいたら、一行だけ足してみる。
「これは何か」
「どう動かすか」
「どこを読めばわかるか」
それだけで、プロジェクトの顔つきが変わります。
コードは、静かな実装の連続です。
README は、その前に立つ小さな挨拶。
僕はいま、README を後回しの欄ではなく、第一印象を設計する場所として扱うようにしています。
あなたのリポジトリの扉の前に、立ってみてください。
そこに、ちゃんと「おかえり」と書いてあるでしょうか。
ひとりごと
README を厚くしすぎた時期もあれば、逆に何も書かなかった恥ずかしいリポジトリもあります。
どちらも、玄関の使い方を誤っていただけなのだと、今は思います。
完璧な看板より、まず迷子を減らす一行から。
そんな気持ちで、今日もエディタを開いています。
あわせて読みたい
▼ リポジトリの最初の一歩をもっと丁寧に踏みたいときに
README を含む最初に目を向ける場所の話とつながります。
出会い方の温度をそろえて読めます。
▼ コード横の手紙の書き方を深めたいときに
README が玄関なら、コメントは部屋の中の短い手紙。
役割の分け方の参考になります。
▼ 履歴に「なぜ」を残す感覚を拾い直したいときに
玄関の先で物語が続いていくとき、日記としてのコミットが支えになります。
次の一歩を一緒に決める 「作戦会議室」 へ
README やドキュメントは、コードと同じく誰に届けるかで形が変わります。
フリーランスの現場では、短い README が信頼になることもあれば、長い契約では別の置き方が必要になることもあります。
作戦会議室では、そうした引き渡しの設計や習慣づくりも、現場の言葉で分け合える場所にしたいです。
必要なときだけ、覗いてみてください。
