
Codexに「思った通り」を作らせる仕様書の書き方|PROJECT_SPEC.md・ルール表・受け入れ条件・AGENTS.md・作業カード
Codex は、説明されたものを作ります。このキットは、正しいものを説明するためのものです。
Codex のプロジェクトがうまくいかない原因は、たいていコードの前にあります。ルールが頭の中にしかない。完成の定義がない。仕様がチャットの中に流れて消えていく。
『Codex仕様書キット』は、そのまま埋めて使える仕様書一式と、小さな道具3つ分の完成例、どの場面でどれを使うかの説明をまとめたものです。解説は PDF、テンプレートはすぐ写せる Markdown ファイルで付きます。
この記事で読めること
この記事は、Gumroad で販売している PDF ガイド『Codex仕様書キット』(76ページ・全12章)から、中心になる 6 つの章をそのまま抜き出した note 版です。章の番号は元の本のままです。
第1章 Codex の仕事は、コードを書く前に失敗している
第3章 1 ページの仕様書
第4章 ルール表 — 二通りに読めない業務ルール
第6章 5 分で確かめられる合格チェック
第7章 AGENTS.md で、毎回守らせる決まりを 1 か所に書く
第8章 タスクカード — 仕様書を小さな依頼に分ける
最初の章は無料で読めます。続きの 5 章は有料部分です。
第1章 Codex の仕事は、コードを書く前に失敗している
Codex はコードを書くのが得意です。小さな道具づくりがうまくいかない原因が、コードそのものにあることはあまりありません。
失敗はもっと前、頼み方の段階で起きています。Codex は言われたとおりに作ります。ところが、言われたことが実際の仕事と少しずれている。そのずれは、間違った数字がファイル名や報告や請求書に入るまで、誰も気づきません。
この章では、よくある 5 つの失敗の形を見ます。どれも Codex の能力の問題ではなく、渡した情報の問題です。そして、このキットのどの文書がどの失敗を防ぐのかを示します。
よさそうに見える頼み方
たとえば、あなたが小さな雑貨店の事務を担当しているとします。毎週 40 件ほど、仕入先からメールで請求書の PDF が届きます。あとで経理の人や税理士さんが探せるように、1 件ずつ名前を付け直しています。この作業を Codex に頼みます。
指示文:静かに失敗する頼み方
仕入先の請求書 PDF の名前を、日付・仕入先・請求番号・
金額の入ったそろった形に変えて、フォルダにまとめる
スクリプトを書いてください。Codex は、動くものを作ってくれます。では、Codex が推測しなければならなかったことを数えてみます。
どの日付か。請求日か、支払期限か、納品日か。
「令和8年9月9日」と書いてある請求書は、2026-09-09 にするのか、R8 のままにするのか。
どの金額か。小計か、消費税か、税込の合計か、前回からの繰越を含めた今回の請求額か。
仕入先は「株式会社あおば包装」か、「(株)あおば包装」か、「あおば包装」か。
文字の入っていないスキャンの PDF はどうするのか。
元のファイルは移すのか、コピーするのか。同じ名前のファイルがあったら上書きするのか。2 回保存してしまった請求書はどうするのか。
ひとつひとつの推測が、道具が黙って間違える場所になります。エラーで止まるなら、すぐ気づけます。困るのは止まらないほうです。合計が 79,200 円の請求書に ..._72000.pdf という名前が付いていても、何も起きません。小計を拾っただけだからです。
失敗 1 — あいまいな頼み方
あいまいな頼み方は、結果そのものではなく、結果への気持ちを書いています。「そろった形」「きれいに」「見やすく」などです。Codex はその空白を、もっともらしい既定の選択で埋めます。もっともらしいことと、あなたのやり方であることは別です。
直し方は、出力を正確に見せる仕様書を書くことです。「そろった形」ではなく、2026-09-10_あおば包装_INV-88213_45375.pdf と書きます(第3章)。
失敗 2 — 書かれていないルール
あなたは、北星製紙が日付を和暦で書くことを知っています。樫木印刷の請求書では「合計」の上に「小計」が印刷されていることも知っています。納品書が混ざっていたら、考えずによけています。
どれも頼み方には入っていません。あなたにとって、それはルールではなく「いつものやり方」だからです。しかし Codex にとっては、書かれていないルールは存在しないのと同じです。
直し方は、作業をしながら記録すること(第2章)と、条件のあるルールを表にすること(第4章)です。
失敗 3 — 完成の定義がない
Codex は「完成しました。テストもすべて通っています」と報告します。けれども、そのテストは Codex があなたの頼みを理解したとおりに書いたものです。つまり、テストが証明しているのは「コードは Codex が考えたとおりに動く」ことだけです。あなたの考えたとおりかどうかは、まだ誰も確かめていません。
直し方は、正解の出力を自分で書くこと(第5章)と、数分で終わるチェックを自分で実行すること(第6章)です。
失敗 4 — 範囲が広がり続ける
Codex は、役に立ちそうだと考えて、フォルダを見張る機能やメールから添付を取ってくる機能を足します。あなたも作業の途中で「ついでにこれも」と頼みます。足したものの数だけ、確かめることが増え、元の仕事が壊れる道も増えます。
直し方は、「やらないこと」の一覧(第3章)、1 回に 1 つの小さな作業(第8章)、新しいことは書面の変更依頼にすること(第9章)です。
失敗 5 — 仕様がチャットの中にしかない
日付のルールは、長い会話の 14 通目で説明しました。1 週間後、別の会話で不具合の修正を頼むと、その Codex は日付のルールを知りません。もっともらしい選択をして、ルールが静かに変わります。
直し方は、決めたことをプロジェクトのフォルダのファイルに残し、毎回守らせる決まりは AGENTS.md に書くことです(第7章)。
ポイント Codex は、渡された文書以上には正確になれません。道具が「惜しいけれど違う」とき、足りない正確さはたいていコードではなく頼み方の側にあります。
このガイドで作る道具
第2章 から 11 では、1 つの道具を、最初のメモから 2 回目の改訂まで追いかけます。invoice-renamer という、自分のパソコンで動く Python のスクリプトです。inbox/ にある仕入先の請求書 PDF を読み、次のような名前を付けて renamed/ にコピーします。
2026-09-10_あおば包装_INV-88213_45375.pdf
2026-09-09_北星製紙_30417_124300.pdf
2026-09-11_樫木印刷_KP-2026-0193_79200.pdf仕入先の名前も番号も金額も架空です。一方で、出てくる問題はどこにでもあるものです。仕入先ごとに違う日付の書き方(和暦を含む)、合計に見える小計、全角と半角の混ざった文字、スキャンした PDF、2 回保存したファイル、2 ページにまたがる請求書。どれも、あなたの職場でも見たことがあるはずです。
道具が違っても、文書の書き方は同じです。注文 CSV の整形、商品写真の加工、見積書の作成については、第12章 に完成例があります。
この章のチェックリスト
最近 Codex に頼んだことを 1 つ選び、Codex が推測しなければならなかったことを全部書き出す。
その中で、間違っても止まらずに出力されてしまうものに印を付ける。
仕事で守っているのに、一度も書いたことのないルールを 1 つ書く。