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章）。

このガイドで作る道具

第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 つ書く。