執筆は思考にコードよりも近い

執筆は思考にコードよりも近い

［画像: Technical diagram: a human head with a glowing idea in its brain, tagged source (1, idea, human thought); a dashed line marks where human thought ends; beyond it, a handwritten page tagged 1st derivative (2, articulation, closest to thought) and a code window tagged 2nd derivative (3, code, an implementation of #2)］

私はしばらくの間、マット・ポコック氏と、仕様駆動開発の最良の方法について、ほとんど議論のようなものを交わしてきました。

マットは素晴らしい昔ながらの開発者であり、真のソフトウェアエンジニアです。そして彼はAIを活用して自身の能力を驚異的なレベルまで高めています。彼の開発スキルは驚異的で、GitHubでほぼ他のどのスキルリポジトリよりも多くのスターを獲得しています。2

では、私の意見の相違点は何でしょうか？

基本的に、私は彼が古いやり方で物事を行うことの頂点にいると考えています。 彼は膨大なスキルと、人々が手動で実行することを推奨するコマンドを多数持っています。人間をプロセスに組み込むことは、彼にとって主要なテーマですが、私はそれをアンチパターンだと考えています。

しかし、彼の最近の中心的な考えは、開発プロジェクトにおいて最も重要なものはコードそのものであるということです。仕様は有用であり、すべてがそうですが、コードそのものが主要な成果物です。あらゆるものの真実の源です。1

私は強く反対します。私が構築しているもの、そしてなぜ構築しているのかを表現することが、はるかに重要だと考えています。基本的に、そのアイデアです。あなたの意図です。

ウェブアプリの構築、ビジネスの開始、惑星連邦の管理など、AI（あるいはAIなしでも）で構築するあらゆるプロジェクトにおいて、最も重要なことは、自分が本当に望むことをどれだけ完全に、そして正確に表現できるかだと考えています。

明確にしておきますが、開始前に完璧で結晶化した表現が必要だと言っているわけではありません。誰もそんなことはできません。私たちは人間であり、構築を進めるにつれて、私たちが望むものはより明確になります。私の主張は、そのイテレーションがどこで行われるかということです。理想的な状態の表現の中で、コードの周りを回るのではなく。そして、ループは2つあり、1つではありません。あなたの意図と執筆は、実際に何を望むのかを理解するにつれて行ったり来たりし、執筆と実装は、構築するにつれて行ったり来たりします。

本当の問題は表現力です ​

2026年現在、AIで見られる問題のほとんどは誤って帰属されていると考えています。AIは実行において驚異的です。私たちがそれを実行するように依頼したことを正確に行うことにおいて、信じられないほど優れています。この時点での問題の多くは、AIが仕事を完璧に実行しているにもかかわらず、その結果が私たちの心にあったものとは異なっているということです。

しかし、これはコミュニケーションの問題です。表現力の問題です。

著者は同じ問題を抱えています。これは一般的にライターズ・ブライデネス（書き手の盲点）と呼ばれています。それは、自分の脳内にあるものを完璧に捉えていると思っているが、実際にはそうではないという状態です。そのため、受信者、つまり読者は、著者が意図した情報を見落としたり、全く異なる解釈を得たりします。

コードは表現であり、ソースではない ​

マットの立場の問題は、彼がコードを権威あるものと考えていることです。それは実際には抽象化であり、絵画が画家が伝えようとしていたことの抽象化であるのと同じです。それは実行であり、模倣であり、表現です。

しかし、これよりも高次の形態があります。それが執筆です。そして画像です。

執筆は、人間と思考の最も近いものです。私が人々によく言うように、私にとって執筆は思考そのものです。それは、圧倒的な差で、私たちが持っている最も近いものです。

［画像: Fidelity drops at every step: thought and intent, the source in your head, is articulated into writing, the closest capture of thought, which is implemented as code, an implementation of the writing; an axis underneath runs from high fidelity to low fidelity］

正確性は精度よりも重要 ​

しかし、マットがコードに魅了されている理由は理解できます。それは執筆よりもさらに多くのもの、つまり精度を持っています。しかし、執筆の方がより正確です。したがって、それは正確性と精度のトレードオフです。

明らかに両方を望みますが、AIで構築する際には、正確性がはるかに重要だと考えています。その古典的な例は、射手が的の中心を狙うことです。

したがって、精度のない正確性とは、すべてブルズアイの周りに着弾するが、それぞれ異なる場所にある一連のショットです。正確性のない精度とは、その逆です。すべてのショットがタイトなグループに集まりますが、狙っていた場所から遠く離れた、端の方に集まります。

［画像: Two archery targets: writing's arrows all land close around the bullseye, each in a different spot; code's arrows land in one tight group out in the outermost ring］

AIで構築する際、結果は私たちの脳内にあったものと一致することを望みます。それが正確性です。そして、私たちの人間の脳内のブルズアイを捉えるのに、執筆ほど近い方法はありません。

［画像: Charcoal sketch of a stone archery target: a tight purple arrow cluster cracks the outer ring while quill pens surround the bullseye］

理想状態の成果物 ​

では、それは何を意味するのでしょうか？

それは、あなたが望むものを書面で表現することが、AIプロジェクトにとって最も重要なことであるということです。そして、それは単に厳格な仕様形式やPRD形式だけでなく、より包括的で創造的な方法で表現することを意味します。

私は2025年末にこれを理解し、私がやることすべてをIdeal State Artifact (ISA)と呼ばれるものに切り替えました。これは、AIと対話するための新しいドキュメントとアプローチです。それは、私たちが構築しようとしているものの、より深いキャプチャであり、表現のさまざまなタイプのために複数のセクションを使用します。

表現された理想状態があり、これは散文です。潜在的に多くの量になります。私のハーネス（LifeOS）は、必要に応じてこれを埋めるのに役立つディスカッションスキル（マットの/grill-me skillに似ています）を使用します。これは数段落になることもあれば、あるトピックに関する4,000語の自由連想や深い内省になることもあります。

次に制約があり、構築したくないものなどがあります。次に、プロジェクトの理想状態を更新する際に下された決定があります。私たちは最初から完璧な理想状態を持っていることはめったにありません。時には構築を開始するにつれて明らかになることもあり、それは問題ありません。それがまさに決定セクションの目的です。構築が何かを教えてくれたり、ISAを再読して望むものが変わったりした場合、日付と理由とともにISAに書き戻します。これにより、イテレーションはコードに埋もれるのではなく、表現の中で行われます。

そして、最も重要なセクション（上部の理想状態定義の後ろ）は、私たちが理想状態基準（ISC）と呼ぶものです。これらは、アプリケーションで実際に構築し、テストしているものです。それらは非常に原子化されており、テスト可能な機能の断片です。それらのそれぞれに独自の評価（eval）が関連付けられており、その複雑さは基本的なassertから、マルチフェーズのcode → assert → System 1 question set → Rubric / Tournament / LLM as a Judgeまで様々です。

理想状態基準がこのように定義され、その評価がISA内に直接定義されていることの本当に強力な点は、ISCが同時に構築の基盤であり、テストハーネスでもあるということです！

［画像: Diagram of an Ideal State Artifact: Ideal State, Constraints, Decisions, and Ideal State Criteria with an eval ladder from assert to LLM as a judge, feeding both what we build from and the test harness］

以下は、家族の食事プランナーのためのISAの小さな例です。これはその一部のみを示しています。実際のISAは、完全な理想状態の表現、テスト戦略、評価自体、および実行ステータスも持ちます。

［画像: The family meal planner ISA rendered as a page: the ideal state as one sentence and three summary bullets, two constraints (no peanuts, weeknights 40 minutes or less), five criteria with four done and the variety criterion still open, and one decision dropping calorie tracking］

食事プランナーISAの一部：理想状態、制約、基準、および決定

［画像: Checking the meal planner ISA: the peanut, grocery-list and 40-minute criteria go to a plain code assert; the kid-appeal criterion goes to a fast model question set; the variety criterion goes to a stronger model as judge, with cost rising from $ to $$$］

描くフクロウ ​

私が何を意味するのかを示す3つの例を挙げます。それぞれにアイデア、そのアイデアの表現、そしてその表現の実装があります。そして、それぞれにおいて間違いは同じです。中間ステップをスキップして、実装を真実として扱うことです。

これらの例のどれも、初日から完璧な表現を必要とするわけではありません。書けるものを書き、構築し、ドラフトが言えなかったことを教えてくれます。書いたものを読むことも、あなたが望むものを変えます。違いは、両方の種類の教訓がISAに戻されるということです。以下の各ISAも単なるスライスであり、理想状態と基準のみです。実際のISAはさらに多くの情報を含んでいます。

フクロウ ​

完璧なフクロウの絵を描きたいとしましょう。あなたの心にはそれが美しいイメージとしてあります。しかし、あなたは絵を描くのがあまり得意ではなく、このアナロジーでは描画がコードに相当します。その結果、ほとんどフクロウだと認識できない棒人間のフクロウができあがります。

コードが真実の源であるバージョンでは、その棒人間が権威ある成果物となります。私たちはそれを分析し、文書化し、その比率についてメモを取り、多くの時間をかけてそれを改良します。私たちは悪い描画の周りをぐるぐる回っています。

［画像: Two bands. Without an ISA: the intent of a perfect owl skips the writing and becomes a stick-figure owl, which loops through analyze it, document it and iterate on it. With an ISA there are two loops: the intent is written down as an ISA holding the ideal state, four criteria and decisions, and rereading it revises what you want; then the drawing is made from the ISA and every criterion is checked back against it］

私たちがスキップしたのは、脳からキャプチャされた状態へのクリーンな翻訳であり、それを行うために最も正確なツールである執筆を使用することでした。その書面による説明は、描画が実装しようとしているものです。

［画像: The owl ISA rendered as a page: a great horned owl on a dead branch at dusk, looking straight at you, and four open criteria (ear tufts and yellow forward eyes, talons gripping the branch, a stranger says owl within two seconds, it feels watchful), each with evidence that the stick figure fails it］

フクロウISAの一部、最初の棒人間と比較して：4つの基準すべてが未解決のままです。

今、すべての描画は、最後の描画ではなく、ISAに対してチェックされます。棒人間は4つの基準すべてに失敗し、次の試みは正確に何を目指すべきかを知ります。そして、ドラフトが実際に望むものが変わったことに気づかせた場合、それはISAに決定として記録されます。それは7番目の描画に埋もれることはありません。

ウェブアプリ ​

友人が小さなヨガスタジオを経営しており、常連客がテキストメッセージを送ることなくクラスを予約できるようにしたいと考えています。誰かがAIに1行のプロンプトを与え、AIはログインウォール、電話では読みにくいカレンダーグリッド、誰も求めていない確認メール、そして12人収容の部屋に20人の定員を持つ予約アプリを構築します。

コードが真実の源である場合、そのアプリが仕様となります。カレンダーグリッドのためにテストが書かれます。ログインフローが文書化されます。誰かがメールシステムをリファクタリングします。バージョン1のすべての事故は、コード内にあるため要件となり、やがて誰も実際にどの部分を望んでいたのかを言うことができなくなります。

［画像: Two bands. Without an ISA: the intent to book a class in ten seconds skips the writing and becomes version one, with a login wall and a capacity of 20, which loops through write tests, document it and refactor it. With an ISA there are two loops: the intent is written down as an ISA holding the ideal state, four criteria and decisions, and rereading it revises what you want; then the booking app is made from the ISA and every criterion is checked back against it］

［画像: The studio booking ISA rendered as a page: a regular books Thursday's class from her phone in ten seconds, one constraint (the room holds 12), and four criteria where version one fails the three-tap booking and the overbooking check, and only the one-screen roster passes］

スタジオ予約ISAの一部、バージョン1のアプリと比較して

ISAを使用すると、ログインウォールはISC-1に失敗し、間違った定員はISC-2に失敗するため、両方とも削除されます。テスト基準がカレンダーグリッドのテストを要求していないため、誰もカレンダーグリッドのテストを書きません。そして、コードは使い捨てになります。バージョン1が悪すぎる場合、それを破棄して同じISAに対して再構築し、同じ評価が新しいビルドをチェックします。コードが望んでいたことの唯一の記録である場合、これはできません。

キッチン ​

これはソフトウェア以外でも機能します。例えば、キッチンのリフォームを考えてみましょう。アイデアは日曜日の朝です。あなたたち2人が料理をし、友人がカウンターのスツールに座り、全員が会話に参加します。あなたは請負業者に簡単なスケッチを渡しますが、彼らはコンロを壁に向かって設置し、料理する人は全員に背を向けるようにします。

実装優先バージョンは、構築されたものを調整するために次の3ヶ月を費やすことです。キャビネットを移動し、フードを交換し、すべてを測定し、部屋が現状のまま文書化します。今や日曜日の朝ではなく、キャビネットについて議論しています。

［画像: Two bands. Without an ISA: the intent of Sunday mornings together skips the writing and becomes the kitchen as built, with the stove facing the wall, which loops through move a cabinet, swap the hood and measure it. With an ISA there are two loops: the intent is written down as an ISA holding the ideal state, three criteria and decisions, and rereading it revises what you want; then the plan, which fails ISC-1 on paper, is made from the ISA and every criterion is checked back against it］

［画像: The kitchen remodel ISA rendered as a page: Sunday morning, two people cooking, friends at the counter, nobody's back to anybody; one constraint (the window over the sink stays); three criteria where the contractor's first plan fails the cook-faces-the-room check, the 120 cm aisles pass, and the conversation walkthrough waits on a mock-up］

キッチンのISAの一部、請負業者の最初の計画と比較して

これを書き留めることで、コンロを壁に設置する計画は、誰かが木材を1枚切る前に、紙の上でISC-1に失敗します。請負業者が問題だったわけではありません。彼らはAIのように、優れた実行者です。彼らが欠いていたのは、実行するための書面による目標でした。

3つのケースすべてにおいて、2つの有用なループがあり、ISAが両方の中心に位置します。最初のループでは、あなたの意図とISAがお互いを形作ります。あなたが望むことを書き留め、それを読み返すことで、実際に何を意味したのかがわかり、ISAが変更されます。2番目のループでは、実装はあなたが書いたものに対してチェックされ、ドラフトがまだ言えなかったことを示すたびに、あなたが書いたものはよりシャープになります。両方において、イテレーションは正常であり、良いことです。ISAは、イテレーションが記録される場所、つまり理想状態、基準、および決定ログです。

全体のアイデアを1つのドキュメントに ​

したがって、私たちが最終的に得るものは、私たちが構築しているすべてのプロジェクトのための単一のドキュメントであり、私たちの心の中にあるものを可能な限り最も正確に表現したものです。理想状態の表現が最も重要であるため、Ideal State Artifactと呼んでいますが、実際にはドキュメント全体が、私たちが構築したいものについての私たちの心の中のアイデアを可能な限り最も正確に表現したものです。

AIが賢くなるにつれて、これがより重要になる理由 ​

さて、マットに戻ると、このプロジェクトの実装のためのソースコード、TypescriptやPythonのようなコンピュータフレンドリーな言語で書かれたものが、Ideal State Artifactよりも元のアイデアの表現としてどれほど忠実度が低いか、はるかに明確になったはずです。

だからこそ、私はマットとこの件について議論し、ISAシステムを代替案として提供しようとしてきました。彼の素晴らしい開発者の頭脳を、プログラミングに関する古い考え方を最適化することに浪費していると考えています。4

リチャード・サットンの「ビターレッスン」から私たちがすべて学ぶべきことは、AIが賢くなるほど、私たちが望むことを正確に、そして私たちを喜ばせる方法で実行できるようになるということです。

レガシーな仕様駆動開発に過度に傾倒し、その日の、あるいはその瞬間のコードの正確な形式に固執することは、努力する場所を完全に間違っています。3

AIが賢くなるほど、私たちが望むことを正確に理解させることに、より多くの努力を注ぐべきです。そして、それを実現するためのステップを細かく管理することには、より少なくすべきです。