CodexでREADMEを作る

作ったものをしばらく後に開いて、「どう動かすんだっけ」と迷ったことはありませんか。READMEは、プロジェクトの目的や使い始め方を残す案内書です。Codexに実際のファイルを読んでもらい、確認できる内容から作れます。

この記事では、小さな静的ページを例に、初めて開く人が迷わないREADMEを作る依頼と、内容の確かめ方を紹介します。

READMEに何を残すか

最初は次の六つがあると、使い始める順番が伝わります。

• 何をするプロジェクトか。
• 使う前に何が必要か。
• どのフォルダーで、何を開く・実行するか。
• 文章や見た目をどのファイルで変更するか。
• 正しく動いたかをどう確かめるか。
• まだできないこと、未確認のこと。

READMEはMarkdownという、見出しや箇条書きを記号で表せる文章形式で書けます。README.md としてプロジェクトの入口に置くのが一般的です。既存のREADMEがあるなら、内容を確認して更新する部分を絞ります。

小さな静的ページの例

ここでは、index.html と styles.css を同じフォルダーに置いた案内ページを使います。HTMLをブラウザーで開く形式で、サーバーやビルドは使わない例です。

guide-sample/
  index.html
  styles.css

Codexには次のように頼めます。

このプロジェクトに初めて触れる人向けのREADME.mdを作ってください。
先に既存ファイルを読み、実装で確認できる内容を基にしてください。

目的、必要な準備、開き方、編集場所、確認方法、制限を含めてください。
既存READMEがあれば、内容を読んで必要な箇所だけ更新してください。
存在しないコマンドや機能は追加せず、未確認の手順は未確認と書いてください。
README以外のファイルは変更しないでください。

書き始める前に読む段階を置くのがポイントです。よくあるひな形だけから書くと、実際にはない npm run dev などのコマンドが入り込むことがあります。

この例は練習用の案内ページ一式をダウンロードして試せます。ZIPを展開すると、HTML・CSS・READMEが同じフォルダーに入っています。元の素材を残したコピーで練習してください。作成時にEdgeで見出し・ページ内リンク・CSS・幅320/360/1280pxの表示を確認しました。これは素材自体の確認で、Codexによる作成操作の実測ではありません。

各段階で確認してから、次の操作へ進みます。

1. 1実物を読むファイルと既存の案内を確認
2. 2案内を書く目的・準備・入口・確認方法を記載
3. 3上から試す記載したファイルと操作を確かめる
4. 4更新して残す未確認と制限を分け、次の人へ渡す

具体的な依頼と、結果の確かめ方は本文にあります。

READMEを保存して終わりにせず、書かれた入口から一度使ってみます。文章の自然さと手順の正しさを両方確かめます。

READMEの見本

この静的ページなら、次のような短い案内から始められます。実際のプロジェクトへそのまま当てはめず、ファイルと一致する部分を使ってください。

# 案内ページ

イベントの概要と参加方法を載せる、小さな静的ページです。

## 準備
Webブラウザーを使います。追加パッケージは不要です。

## 開き方
index.htmlとstyles.cssを同じフォルダーに置きます。
index.htmlをブラウザーで開きます。

## 編集する場所
- 文章と見出し：index.html
- 色と余白：styles.css

## 確認方法
「イベントのご案内」という見出しが表示されるか確認します。
ページ内の「参加方法」リンクで、その見出しへ移動するか確認します。
ブラウザーの幅を狭くし、文章が画面からはみ出さないか確認します。

## 制限
申し込み内容を送信する機能はありません。
このファイルを開くだけでは、インターネットには公開されません。

準備が不要な例では「追加パッケージは不要」と説明できます。一方、実際のプロジェクトに依存関係があるなら、必要な実行環境とインストール手順を確認して書きます。

手順を上から試す

次の三点を、READMEを読む人と同じ順番で確認します。

1. 記載されたファイルやコマンドが存在するか。
2. 書かれた場所で操作して、期待する画面や出力になるか。
3. 成功の判定が具体的で、初めての人にも分かるか。

「起動してください」だけなら、起動する場所と手順が不足しています。「動けば成功」だけなら、何が見えればよいかを補います。エラーが出る場合は、その場で原因を調べるか、未確認として範囲を明記します。

既存のREADMEを更新するとき

既存READMEの説明、ライセンス、注意点を一括で削るのは避け、古くなった手順を実装と照合します。「新しい起動手順だけを修正し、ほかの節は保ってください」と対象を明示すると差分を確認しやすくなります。

修正後はGitの基本や差分の確認を使って、README以外に意図しない変更がないかを確認します。戻す場合も今回の差分だけを対象にします。

よくある不足を補う

まず構成を知りたい場合はプロジェクトの読み解き方へ進めます。Codexに守ってほしい作業ルールはAGENTS.mdで扱い、人が使い始める案内と役割を分けられます。

このREADMEは説明用の静的ページに対応した見本です。外部サービスへの公開や、本番アプリの起動確認を行った報告ではありません。