
【無料】Codexに頼む前の30の質問|「作って」と頼む前に20分で仕様を固めるチェックリスト
Codex で作る小さな道具の失敗は、ほとんどがコードを書く前に起きています。
「毎週の注文 CSV をきれいにして」とだけ頼むと、どの行を残すか、どの列を消すか、空欄をどう扱うかを Codex が推測するしかありません。推測のずれは、あとで出力を見たときに見つかります。
この無料チェックリストは、頼む前に書いて答えておく30の質問です。20分ほどで答えられて、答えがそのまま仕様になります。
Gumroad で無料配布している PDF(23ページ)と同じ中身を、note で全文読めるようにしました。印刷して使いたい人は PDF 版もどうぞ: Codexに頼む前の30の質問(PDF・無料)
このガイドの使い方
Codex で作る小さな道具がつまずくとき、原因の多くはコードができる前にあります。頼んだのは「毎週の注文 CSV をきれいにして」の一言だけ。残りは Codex が推測するしかありません。
どの行を数えるのか。どの列を残すのか。空欄は何を意味するのか。全角の「SKU-104」と半角の「SKU-104」は同じ商品なのか。Codex はもっともらしく推測します。その推測に気づくのは、出力を見たあとです。
このチェックリストは、その判断をいちばん安く済む場所へ移します。Codex を開く前に書く、1枚の答えです。質問は 30、6つの部に分かれています。
第1部 そもそも道具を作る価値があるかを決めます。
第2部〜4 仕事を Input → Rules → Output で書きます。
第5部 道具が正しいことを、どう確かめるかを決めます。
第6部 データを守り、手入れを続ける形を決めます。
印刷して、書いて答える
終わりの「1ページ版」を印刷するか、道具を置く予定のフォルダにテキストファイルを1つ作ります。仕事を1つだけ選び(3つではなく1つ)、すべての質問に書いて答えます。
書くことに意味があります。頭の中の答えは、いつもはっきりして聞こえます。紙に書くと、「おかしい行は除く」がどの行のことか、一度も言っていないと気づきます。
20 分だけかける
毎週やっている仕事なら、1回目はおよそ 20 分で書けます。途中で調べものはしません。分からなければ「不明」と書いて次へ進みます。それよりずっと長くかかるなら、その仕事は感じているほど決まっていません。
「いいえ」の意味
具体的に書けない答えは、すべて「いいえ」と数えます。「場合による」「見れば分かる」、空欄も同じです。
具体的に書けた|意味: 準備ができている|すること: 仕様書に写す
第1部 で「いいえ」|意味: 作る価値が薄いかも|すること: 買う・待つ・やめる
第2部〜6 で「いいえ」|意味: 穴であって結論ではない|すること: 先に埋める
後ろの部の「いいえ」は宿題です。たいていは、ファイルを1つ保存する、手で1つ計算する、という 10 分ほどの作業で埋まります。
ポイント 飛ばした質問にも、必ず誰かが答えます。いま自分が書いて答えるか、あとで Codex が推測で答えるかのどちらかです。
このガイドで使う例
回答例はすべて、1つの架空の仕事です。ネットショップを1人で運営していて、毎週月曜に注文の CSV を書き出し、Excel で商品コード(SKU)ごとの個数と売上をまとめて、仕入先への発注を決めています。
店は BASE でも STORES でも Shopify でもかまいません。列名は order_id・sku・qty のような仮の名前です。本当の列名は、自分の店の書き出しの1行目を写します。仕事が違っても、よい答えの形は変わりません。
自分の仕事でやってみる
いま、仕事を1つ選びます。この7日のうちにやっていて、来週もまたやるものです。答えを書く紙の一番上に、その仕事の名前と今日の日付を書きます。
第1部 作る価値があるか
Codex のおかげで、道具を作るのは安くなりました。それでも、持ち続けるのはただではありません。止まったときに直すのは自分です。この部の6つの質問で、その仕事に道具を作る価値があるかを、説明に一晩かける前に決めます。
1. この仕事はどれくらいの頻度で発生しますか?
頻度は、ほかのすべてに掛け算で効きます。毎日 10 分の作業は、年に2回の3時間の作業より価値があります。記憶ではなく、カレンダーや送ったメールから本当の回数を数えます。
回答例:「毎週月曜と、月末締めの集計。年に 64 回ほど。」
2. 1回に何分かかりますか? 推測ではなく、計った時間で。
次の本番でストップウォッチを使います。手を動かすだけの時間と、考えている時間を分けてメモします。道具で消せるのは、手を動かすだけの時間です。それを質問1の回数に掛けると、年に何時間かが出ます。
回答例:「先週の月曜は 35 分。そのうち 30 分は、CSV を開いて並べ替え、コピーして足すだけ。30 分 × 64 回 = 1,920 分で、年に 32 時間。」
3. 1回間違えると、何を失いますか?
間違いの重さで、確認の仕組みがどれだけ要るかが決まります。サムネイルの大きさを間違えても、作り直せば済みます。取引先に送る請求書の合計を間違えれば、信用を失います。間違いが高くつくなら、第5部 で確認を強くし、最後に人が目で見る段階を残します。
回答例:「個数を間違えると、発注が遅れて1週間ほど品切れになるか、数万円分の余分な在庫を抱える。」
4. どこがルールで、どこが判断ですか?
ルールは、新しく来た人に紙1枚で渡せる手順です(「キャンセルされた注文は数えない」)。判断は「なんとなくおかしくないか見る」ことです。プログラムはルールが得意です。判断は、印を付けて人に回すところまでにします。
回答例:「商品コードごとの合計はルール。何をいくつ発注するかは自分が決める。」
5. この仕事はあと何年続きますか?
道具が元を取るのは、コードの寿命ではなく、仕事が続く期間です。店を別のサービスに移す、仕入先が変わる、報告の形が変わる。そんな予定があるなら、2か月で消える手順のための道具かもしれません。
回答例:「少なくとも2年。店を移す予定も、仕入先を変える予定もない。」
6. いま使っている道具で、もうできませんか?
店の管理画面のレポート、Excel のピボットテーブルや保存したフィルター、会計ソフトの集計を先に確かめます。保存したフィルター1つで済むなら、手入れの要る自作の道具より安くつきます。何を確かめ、何が足りなかったかを書きます。
回答例:「店の売上レポートは商品名ごとで、商品コードごとにまとめられず、返金も除けない。10月12日に確認。」
ヒント 質問1と2を掛けても年に数時間にしかならず、質問6で使える方法が見つかったら、ここでやめます。それで一晩が浮きます。
自分の仕事でやってみる
次の本番をストップウォッチで計ります。質問1と2の答えを計った数字に書き換え、年に何時間になるかを紙の一番上に書きます。
第2部 Input を決める
Codex は、説明された入力に合わせて道具を作ります。記憶で説明すれば、記憶に合わせて作ります。この部の5つの質問で、入力を本物のファイル1つに固定します。
7. 入力は正確には何ですか?
ファイルの種類、文字コード、区切り文字、1行が何を表すかを書きます。列名は打ち直さず、自分の書き出しの1行目をそのまま写して貼ります。列名を1文字間違えるだけで、最初の本番で止まる道具ができます。「注文番号」のような日本語の列名も、そのまま写します。
文字コードは、日本の仕事で特につまずく所です。同じ CSV でも Shift_JIS のものと UTF-8 のものがあり、違う方で読むと文字化けします。VS Code のように文字コードを表示できるエディタで開いて確かめ、その名前を書きます。
回答例:「orders_export.csv。Shift_JIS、カンマ区切り。注文の明細1つが1行で、11列(本物の1行目を下に貼る)。」
8. どこから来て、どうやって手元に届きますか?
誰が、どの設定で書き出し、どこに保存するか。ファイルが届くまでの道筋で、道具が受け取るものが決まります。
回答例:「毎週月曜の9時に、店の管理画面から自分で書き出す。ダウンロードフォルダから input/ へ移す。」
9. 本物のサンプルを1つ保存しましたか?
本物のファイルは、どんな説明にも勝ります。ルールを1行でも書く前に、手を加えていない書き出しを1つ、プロジェクトのフォルダに保存します。お客さまの名前・住所・電話番号・メールが入っているなら、その値だけ架空のものに置き換え、ほかは書き出したままにします。
回答例:「tests/fixtures/orders_2026-10-05.csv。実際の1週間分。名前は『テスト太郎』、メールは a@example.com に置き換え済み。」
10. 毎回変わるものと、変わらないものは何ですか?
毎回変わるのは、行数、日付、新しい商品コードなど。変わってはいけないのは、列名、列の順、ファイルの種類、文字コードなどです。前の一覧は道具が対応すべきことを、後ろの一覧は処理の前に確かめるべきことを、Codex に伝えます。
回答例:「変わる:行数は 150〜400、期間、新しい商品コード。1年は変わらない:11列の名前と順、Shift_JIS。」
11. 悪い入力はどんな形をしていますか?
悪いファイルは、たぶんもう受け取ったことがあります。それを書き出します。どれも、分かるエラーメッセージか例外の報告にします。黙って間違った結果を出させません。
回答例:「注文ゼロの週の、1行目しかないファイル。間違えて先月分を書き出したもの。Excel で保存し直して、日付が 2026/10/5 になり、文字コードも変わったもの。sku が空の行。」
注意 CSV を Excel で開いて保存すると、中身が変わることがあります。日付の形が変わり、00412 のような商品コードの先頭の 0 が消え、文字コードが変わることもあります。サンプルは、書き出したファイルをそのまま保存します。
自分の仕事でやってみる
今日、本物の入力ファイルを1つ、書き出したままの形で tests/fixtures/ フォルダに保存します。その1行目を質問7の答えの下に貼り、実際に受け取ったことのある悪いファイルを3つ書きます。
第3部 Rules を書く
ここは、多くの人が飛ばす部です。ルールが当たり前に感じるからです。当たり前なのは、自分にとってだけです。Codex はその仕事をしたことがありません。
この部の6つの質問で、手が覚えている習慣を、初めての人でも守れるルールに変えます。
12. すべての手順をルールとして書けますか?
ルールには、列・条件・すること、の3つが入ります。「変な注文は消しておく」は願いです。「status が cancelled の行を除く」はルールです。ルールには番号を振り、行う順に並べます。順番で結果が変わるからです。
手作業で無意識にやっている直しも、ルールにします。たとえば、ときどき全角で入ってくる「SKU-104」を、Excel で目で見て半角に直しているなら、それも1つのルールです。書かなければ、道具は「SKU-104」と「SKU-104」を別の商品として数えます。
回答例:「ルール2:status が cancelled の行を除く(完全一致。大文字・小文字は区別しない)。ルール4:sku の全角英数字と全角のハイフンを半角にし、前後の空白を取る。」
13. 例外は何で、それぞれどう扱いますか?
本物のデータには、どのルールにも当てはまらない行が必ずあります。種類ごとに、実行を止める・その行を飛ばして報告する・決めておいた既定値を使う、のどれか1つを選びます。道具に黙って決めさせません。
回答例:「sku が空 → 理由『sku なし』を付けて例外ファイル(exceptions_日付.csv)に出し、集計には入れない。」
14. 2つのルールが同じ行に当てはまるとき、どちらが先ですか?
ルールの重なりは、どこにでも隠れています。sku が空で、しかもキャンセルされた行は、除外にも例外にもなりえます。どちらにするかで数が変わります。どのルールを先に行うかを書きます。
回答例:「除外が先、例外の確認が後。sku が空でキャンセルされた行は除外し、例外には出さない。全角を半角にそろえるのは、空欄の確認と集計より前。」
15. 人に残すものは何ですか?
道具が決めてはいけないことを書きます。それで Codex は、どこで止まればよいかが分かります。道具は数を出し、印を付けるまで。決めるのは人です。
回答例:「発注の数と、例外ファイルを見て判断することは自分。道具は数えて足すだけ。」
16. 単位は何で、どこで端数を処理しますか?
金額・個数・日付には、隠れた選択が入っています。円の金額なら、税込か税抜か、消費税 10% と 8% が混ざるか、端数を1行ごとに処理するか合計で処理するかを書きます。
1行ごとと合計とでは、1円ずれることがあります。それだけで、請求書や会計ソフトの数字と合わなくなります。
回答例:「金額はすべて税込の円で、整数。売上 = qty × unit_price を行ごとに出して合計する。消費税はこの道具では計算しない。unit_price に1円未満の値があれば止まる。」
17. 1つの例を手で計算しましたか?
番号を振ったルールを、サンプルの数行に紙の上で当てはめます。忘れていたルールや決めていなかった場合が、いちばん安く済む時点で見つかります。その結果が、第4部 の期待する出力になります。
回答例:「7行を手で計算 → 出力は3行。SKU-104 は 5個、6,250円。」
その7行(11列のうち5列)を tests/fixtures/orders_sample.csv として保存したものです。
order_id,sku,qty,unit_price,status
5001,SKU-104,2,1250,paid
5002,SKU-221,1,4000,paid
5003,SKU-104,3,1250,paid
5004,SKU-310,2,800,paid
5005,SKU-310,1,800,cancelled
5006,,1,1500,paid
5007,SKU-221,1,4000,refunded3件目の注文は、sku が全角で入っています。ルール4が無ければ、ここで SKU-104 が2行に分かれます。
ポイント ルールを書けないなら、Codex も作れません。作れるのは、それらしく見える推測だけです。
自分の仕事でやってみる
サンプルの最初の 10 行に、番号を振ったルールを手で当てはめます。手が止まったら、そこに足りないルールか例外があります。質問 12 か 13 に書き足します。
第4部 Output を決める
「きれいなファイル」は出力の仕様ではありません。出力は、道具がほかの仕事とつながる所です。受け取る人に必要なだけ、正確に決めます。
18. 出力の形は正確には何ですか?
ファイルの種類、列とその順、並べ方、数の書き方、文字コードを書きます。「いい感じに」で残す所を作りません。Codex はもっともらしいものを選びますが、それが来週の Excel に貼る形と合うとは限りません。
BOM の無い UTF-8 の CSV は、Excel でそのまま開くと文字化けすることがあります。金額に桁区切りのカンマを付けると、列がずれます。
回答例:「CSV。列は sku, units, revenue の順。sku ごとに1行。units の多い順、同じなら sku の昇順。金額はカンマを付けない整数。文字コードは UTF-8(BOM 付き)。」
19. 出力ファイルの名前はどう決めますか?
名前の決まりがあれば、過去の結果を探しやすく、別の週の結果を上書きすることもありません。名前に入れる日付が実行した日か集計した期間か、同じ名前がもうあったらどうするかを決めます。
日付は 2026/10/12 ではなく 2026-10-12 の形にします。スラッシュはファイル名に使えません。
回答例:「sku_summary_2026-10-12.csv。日付は実行した月曜。同じ名前があれば止まって知らせる。」
20. 出力はどこに置きますか?
入力とは別のフォルダを選びます。入力と出力を分けておくのが、元のファイルを上書きしないための、いちばん簡単な守りです。
回答例:「プロジェクトの output/。例外ファイル exceptions_2026-10-12.csv も同じ所に置く。書き出したファイルは input/ に残す。」
21. 誰が、何のために出力を使いますか?
受け取る人が要件を決めます。目で読むファイルなら、読みやすい列が要ります。会計ソフトなどに取り込むファイルなら、見出しの1文字まで、そのソフトの形に合わせます。
ほかの人が使うなら、その人が実際に何をするのかを聞きます。
回答例:「毎週月曜、仕入先への発注書を作るときに自分が見る。月末締めの合計は税理士さんが見る。」
22. 期待する出力のファイルはありますか?
質問17の手計算を、本物のファイルにします。このファイルが「正しい」の定義になり、Codex は変更のたびにそれと比べられます。
回答例:「tests/expected/sku_summary_sample.csv。サンプルの7行から手で書いた。」
sku,units,revenue
SKU-104,5,6250
SKU-310,2,1600
SKU-221,1,4000ポイント 小さなサンプルの期待する出力を手で書けないなら、それを作る道具をまだ頼める段階ではありません。
自分の仕事でやってみる
手計算した行の期待する出力をテキストエディタで書き、サンプルの隣に保存します。数字はすべて2回確かめます。それから、そのファイルを開く人の立場で、質問21に答えます。
第5部 正しさの確かめ方
「エラーなく動いた」は証拠になりません。最後まで動いた道具が、行を落とし、返金を2回数え、端数を逆に処理していることがあります。
この部の5つの質問で、コードができる前に、出力が正しいとどう判断するかを決めます。
23. どんな小さなテスト用ファイルを残しますか?
テストに使う小さな入力ファイルを、fixture(フィクスチャ) と呼びます。1つのファイルで、ふつうの週、キャンセル、値の抜け、空のファイルなど、1つの場面だけを試します。小さいファイルなら、失敗の原因が読みやすくなります。ファイルごとに、期待する結果を用意します。
回答例:「どれも 10 行以下の4つ。7行のサンプル、問題の無い週、1行目だけのファイル、qty の列が無いファイル。」
24. 完成と言う前に、何が通ればよいですか?
受け入れの条件は、正しいか間違いかのどちらかになる文で書きます。「うまく動く」は確かめられません。「サンプルの出力が、期待するファイルと完全に一致する」なら確かめられます。成功だけでなく、失敗したときの動きも入れます。
回答例:「サンプルの出力が期待するファイルと一致する。1行目だけのファイルでは、分かるメッセージを出して止まる。実行の後も、書き出したファイルは変わっていない。」
25. どの合計が合わなければいけませんか?
検算の合計(コントロールトータル)とは、2通りに計算して比べられる数です。入ってきた個数は、集計した個数と除いた個数と例外の個数を足したものに等しいはずです。合わなければ、どの行も正しく見えても、何かが消えたか2回数えられています。
回答例:「サンプルでは、入った 11 個 = 集計 8 個 + 除外 2 個 + 例外 1 個。売上の合計 11,850 円が手計算と合う。」
26. 黙って起きる間違いに、どう気づきますか?
危ないのは、もっともらしいファイルが出てくる失敗です。毎回の実行で画面に出す数を決めておけば、いつもと違う週が目に付きます。先週から急に跳ねていたら、30 秒だけ目を向けます。
回答例:「毎回、読んだ行数・除いた行数・例外の数・売上の合計を表示する。先週より5割以上増えたり減ったりしていたら確かめる。」
27. 変更の後も、前の動きが壊れていないとどう分かりますか?
どんな変更も、昨日まで動いていた所を壊すことがあります。変更のたびに、新しいルールの分だけでなく、すべての fixture をもう一度実行します。
Codex には「これで動くはずです」ではなく、ファイルごとの PASS か FAIL を報告させます。
回答例:「どんな変更の後も、4つの fixture がすべて PASS してから、本番の週に使う。」
注意 テストを通すために、Codex に期待する出力のファイルを書き換えさせてはいけません。テストが落ちたら、コードが間違っているか、自分のルールが変わったかのどちらかです。ルールが変わったなら、仕様書、期待するファイル、コードの順に直します。
自分の仕事でやってみる
今日、いちばん小さな fixture を3つ作ります。ふつうのもの、例外が入ったもの、空か1行目だけのもの。それぞれに期待する結果を書き、検算の式を1行で書きます。
第6部 安全と手入れ
最後の3つの質問で、3つのことを確かめます。道具がデータを壊せないこと。調子の悪い日にも仕事を終えられること。道具に持ち主がいること。
28. 元のファイルに決して触れないと、どう保証しますか?
「道具は元のファイルを読むだけで、書き込まない」とルールで書きます。フォルダを分け、実行の後に元のファイルが変わっていないかを調べれば、確かめられるルールになります。
ファイルを消す・動かす・名前を変える道具なら、まず何が起きるかを見せるだけの実行(ドライラン)を頼みます。
回答例:「読むのは input/ だけ、書くのは output/ だけ。実行の後も書き出したファイルが同じか、テストで確かめる。」
29. 道具が動かないとき、どうやって元に戻りますか?
いつかの月曜、新しい列や書き出しの変化で、道具は止まります。そのときも仕事を終える方法と、最後に動いた版へ戻る方法が要ります。
手作業の手順をいま書いておきます。すべての fixture が通ったら、そのたびに git のコミットなどで戻れる点を残します。
回答例:「MANUAL_FALLBACK.md に、前の Excel での手順を書いておく。確かめた版はすべて git のコミットにする。」
30. 誰が手入れし、何をきっかけに手入れしますか?
書き出しは変わり、ルールも変わり、ソフトは古くなります。担当者(たいていは自分)と、手入れが要るきっかけを書きます。新しい列が増えた、返金の扱いが変わった、消費税率が変わった、などです。
年に 32 時間浮く道具なら、数時間の手入れは払えます。毎月、週末をつぶすほどではありません。
回答例:「自分。書き出しの1行目が変わったら、先に PROJECT_SPEC.md と fixture を直す。1回 30 分まで。」
ヒント 日付とかかった分数だけの、2列の手入れ記録を付けます。手入れの時間が浮いた時間に近づいてきたら、道具を簡単にするか、使うのをやめます。
自分の仕事でやってみる
いま MANUAL_FALLBACK.md を5行以内で書きます。元のファイルがどこにあるか、手作業の手順、出力が最後までできたか途中で止まったかの見分け方です。
1ページ版
このページを印刷するか、CHECKLIST.md として保存します。印を付けるのは、答えが仕様書にそのまま貼れるくらい具体的になったときだけです。
テンプレート:CHECKLIST.md
仕事の名前:____________________ 日付:__________
Part 1 - 作る価値があるか
- [ ] 1 年に何回:____
- [ ] 2 1回の分数(計った値):____ 手作業の分:____
- [ ] 3 1回のミスで失うもの:____
- [ ] 4 ルールと判断を分けて書いた
- [ ] 5 この仕事が続く見込み:____
- [ ] 6 今ある道具を確かめた。足りない所:____
Part 2 - Input を決める
- [ ] 7 種類・文字コード・本物の1行目を写した
- [ ] 8 出どころと、道具に届くまでの道筋
- [ ] 9 本物のサンプルを tests/fixtures/ に保存した
- [ ] 10 変わるもの / 変わってはいけないもの
- [ ] 11 知っている悪い入力を書き出した
Part 3 - Rules を書く
- [ ] 12 すべての手順を番号付きのルールにした
- [ ] 13 例外ごとに:止める / 飛ばして報告 / 既定値
- [ ] 14 ルールが重なったときの順番
- [ ] 15 人に残す判断
- [ ] 16 単位・税込か税抜か・端数を処理する所
- [ ] 17 サンプルの数行を手で計算した
Part 4 - Output を決める
- [ ] 18 形式・列の順・並べ方・文字コード
- [ ] 19 名前の決まりと、同じ名前があるときの扱い
- [ ] 20 出力のフォルダ(入力とは別)
- [ ] 21 誰が、何のために使うか
- [ ] 22 期待する出力を tests/expected/ に保存した
Part 5 - 正しさの確かめ方
- [ ] 23 fixture:ふつう・例外・空(ほかも)
- [ ] 24 受け入れの条件を、正誤で決まる文にした
- [ ] 25 合わなければいけない検算の合計
- [ ] 26 黙った間違いに気づくため、毎回出す数
- [ ] 27 変更のたびに、すべての fixture を実行する
Part 6 - 安全と手入れ
- [ ] 28 元のファイルは読むだけ。出力は別の所
- [ ] 29 手作業の手順を書いた。通るたびに戻れる点
- [ ] 30 手入れする人・きっかけ・かける時間
判断:作る / 穴を埋めてから作る / 既存で済ます / やらない第2部〜6 の、印の付いていない項目を数えます。1つ1つが、書かなければ Codex が代わりに答える質問です。
この先に読むもの
30の質問に答えたら、次は答えを Codex が読む仕様書の形にします。続きは note の記事と、Gumroad の PDF ガイドで書いています。
note の記事一覧: https://note.com/masa_aimaster
Codex は OpenAI の製品です。この記事は OpenAI とは関係のない独立した出版物です。
