Agentic OS 技術スタックを下から読む 第27回：仕様は、長く書くほど効くわけではない ―― 注意の予算と、段階に割る設計

Agentic OS 技術スタックを下から読む 第27回：仕様は、長く書くほど効くわけではない ―― 注意の予算と、段階に割る設計

許可の次に来るもの

ここまでは、権限をどう絞るかを見てきました。できる操作を絞り、届く場所を絞り、通ってよい経路を絞ることで、エージェントが越えてはいけない線を下の層から作りました。今回は少し上へ戻ります。やってよい範囲が決まったあとで、そもそも何をやってほしいのかを、どう書けば取り違えにくいのかを見ます。

良い仕様は、すべての要求を一枚に詰め込んだ長大な指示書ではありません。むしろ逆です。読む側には注意の予算があります。ここでいう注意とは、文字を目に入れる力ではなく、複数の条件を同時に保ち、いまの作業に関係するものを選び、矛盾がないように使い分ける力です。この予算は無限ではありません。

たとえば30個の要求を一度に並べるとします。最初の3個は強く残ります。最後の3個も、直前に読んだため残りやすくなります。ところが真ん中の10個から15個は弱くなります。読まれていないわけではありません。重みが薄くなり、似た要求に吸収され、作業中に呼び戻されにくくなります。だから長く書くほど守られる、という直感は成り立ちません。長く詰めるほど、肝心な数個が他の要求に埋もれます。

長い一枚が失敗する理由

一枚の大きな仕様が失敗する理由は、情報量だけではありません。問題は、情報の粒度が混ざることです。目的、禁止事項、作業手順、画面の作法、保存の条件、名前の付け方、失敗時の扱いが同じ重さで並ぶと、どれを優先すべきかが曖昧になります。

人間なら「これは全体方針で、これは今回だけの細部だ」と読み分けます。エージェントにもある程度はできます。しかし、同時に20個以上の制約を守らせ、さらに対象を読み、変更案を作り、結果を整えさせると、注意の使い道が分散します。仕様を読むことに使う注意、対象を理解することに使う注意、実際の出力を組み立てる注意が、同じ枠を取り合うからです。

ここで崩れるのは、たいてい派手な部分ではありません。もっと地味な部分です。名前の付け方が少しずれる。保存するときの条件が一つ抜ける。前提が満たされないときの止まり方が弱くなる。出力の体裁だけは合っているのに、境界の扱いが雑になる。長い仕様は安心感を与えますが、実行の場面では安心感ほど効きません。

まず全体の狙いを置き、細部は起草して直す

最初に置くべきものは、細部を詰め込んだ完全な文書ではありません。短く、高い視点の仕様です。何を作るのか。誰が使うのか。何ができれば成功なのか。何をしてはいけないのか。この4点を、まず300字から600字ほどで置きます。

この段階の仕様は、設計図というより進行方向です。たとえば「利用者が一日に何度も使うため、操作は3手以内に収める」「失敗時には勝手に進まず、理由を示して止まる」「記録は後から追える形で残す」といった条件です。細かい文言を最初から人が一行ずつ書く必要はありません。方向を置いたうえで、細部はエージェントに起草させます。

そのほうが速いだけではありません。抜けも見つけやすくなります。人が白紙から書くと、自分の頭の中にある前提を落としがちです。起草されたものを見ると、「ここは違う」「この場合が足りない」「この制約は強すぎる」と直せます。白紙を埋める作業より、出てきた案を削り、直し、並べ替える作業のほうが、判断に集中できます。

ただし、最初から外せない技術的要求は、この高い視点の段階で入れます。たとえば、保存時に必ず暗号化する、外部へ送らない、入力は決まった形だけ受け付ける、処理は10秒以内に戻る、という要求です。こうした条件を後から足すと、すでに作った構造を引き直すことになります。家を建てたあとで柱の位置を変えるような手戻りです。

書く前に読ませ、計画で止める

込み入った作業では、理解と実行を分けます。いきなり書かせません。まず、対象を読むだけの段階を置きます。この段階では何も変更しません。対象の構造を読み、関係する場所を拾い、作業計画を出し、曖昧な点を質問として挙げさせます。

この一段を入れるだけで、取り違えは大きく減ります。理由は単純です。書き始める前なら、誤解は言葉の修正で済みます。書き始めたあとでは、誤解は構造の修正になります。前者は1分で済むことがあります。後者は30分かかることがあります。

計画には最低でも4つを書かせます。第一に、読んだ対象の要約です。第二に、変更する場所と変更しない場所です。第三に、成功条件です。第四に、不明点です。この4つが出ると、要求のどこが二通りに読めるかが見えます。

たとえば「登録を作る」という要求は大きすぎます。入力欄を作るのか、保存する口を作るのか、本人確認まで含むのか、失敗時の表示まで含むのかが分かりません。計画段階で「今回は、入力された連絡先の形を確認し、重複がなければ登録を受け付ける口を一つ作る」と書かせれば、成功条件が狭まります。狭まるほど、外れ方も狭まります。

最小とは短文ではなく効きどころの保存

仕様を絞るというと、短くすることだと受け取られがちです。しかし、最小とは短いことではありません。最小とは、余計な飾りを落とし、効きどころを残すことです。

落としてはいけない領域があります。まず、組み立て、試験、点検をどう回すかです。作ったら何を動かし、どこを見るのかがないと、終わりが決まりません。次に、正しさの基準です。成功とは、画面が出ることなのか、保存まで終わることなのか、失敗時に止まることまで含むのかを決めます。

対象の構造も必要です。どこに何が並び、どこが入口で、どこが共通部分なのかが分からないと、似た場所に誤って手を入れます。書き方の作法も必要です。名前の付け方、文の調子、並べる順序が揺れると、あとから読む人にも、次に作業するエージェントにも負担が移ります。

さらに、変更履歴の刻み方が要ります。なぜその形にしたのかが残らないと、次の修正で同じ議論をやり直します。最後に、やってよいこと、確認を要すること、やってはいけないことの境界が要ります。ここが曖昧だと、便利そうな変更が勝手に混ざります。

これらを削って短くすると、仕様は軽くなります。しかし、軽くなった分だけ現場で崩れます。必要なのは短文ではなく、焦点です。今回の作業に効く細部だけを残し、関係しない細部を渡さないことです。

段階に割り、関係する分だけ渡す

長い仕様は、一度に渡しません。作業を小さく割り、その単位に関係する部分だけを渡します。全体に効く制約は残しますが、毎回すべての細部を渡す必要はありません。

裏側の処理を作る作業に、表側の色や余白の仕様まで渡すと、注意が散ります。逆に、表側の操作を作る作業に、保存の内部構造をすべて渡す必要もありません。まず土台の構造を作る。次に受け渡しの形を決める。次に操作を作る。最後に表示を整える。このように4段階に分ければ、各段階で見るべきものが減ります。

粒度も重要です。「利用者管理を作る」は大きすぎます。そこには登録、確認、変更、停止、履歴、権限が含まれます。これを「入力された連絡先の形を検査し、重複がなければ仮登録として保存する入口を一つ作る」まで割ると、成功条件がはっきりします。入力が空なら拒む。形が違えば拒む。既存の記録と同じなら拒む。問題がなければ1件だけ作る。ここまで分かれば、作業も点検も狭くなります。

長い仕様そのものは、目次として扱います。全体を8節に分け、今回使う2節だけを渡します。必要なら、関連する節を抜き出して短い作業仕様にします。さらに大きな作業では、別の文脈を持つ下位のエージェントに一部を任せることもあります。その場合も、丸ごとの仕様を渡すのではなく、その担当に必要な目的、境界、受け渡しの形だけを渡します。

ただし、割れば依存が生まれます。表側は裏側との取り決めを必要とします。裏側は保存の制約を必要とします。だから全体を見渡す概要は残します。細かい作業は分けても、束ねる視点を一つ置く必要があります。分割は、ばらばらにすることではありません。関係を明示して、同時に持つ量を減らすことです。

仕様は版を持つ

仕様は一度書いて終わる文書ではありません。作る、試す、直す、また試すという輪の中に置きます。作業の結果から学んだことを、仕様へ戻します。

たとえば、安全な保存の仕方が守られていなかったとします。このとき、実装だけを直して済ませると、次の作業でまた同じ抜けが起きます。仕様側の言葉が足りなかったなら、仕様を直します。「保存する」とだけ書いていたなら、「保存時には読めない形に変換し、復元に必要な鍵は別の場所から受け取る」と書き直します。そのうえで、更新した仕様に合わせて計画や実装を直させます。

版を持たせる利点は、理由が残ることです。第1版では速度だけを条件にしていた。第2版で失敗時の停止を足した。第3版で保存の条件を強めた。こうした履歴があると、あとから来た人も、次に働くエージェントも、現在の形が偶然ではないと分かります。

仕様は会話をまたいで持ち越せる共有の事実です。その場の指示だけに頼ると、次の会話で前提が消えます。版を持つ仕様に残せば、同じ判断を何度も説明しなくて済みます。これは効率の話であると同時に、品質の話でもあります。

仕様は実行の契約である

ここまでをまとめると、仕様は要望の箇条書きではありません。実行できる契約です。文脈の索引です。品質の物差しです。境界の宣言でもあります。

前回見た許可は、できることの範囲を下から狭める設計でした。今回の仕様は、やってほしいことを取り違えさせない設計です。許可だけでは、何を作るべきかは決まりません。仕様だけでは、やってはいけない操作を止められません。両方がそろって、エージェントは安全に、かつ的を外さずに動けます。

良い仕様は長い一枚ではありません。注意の予算を前提にします。まず全体の狙いを置きます。書く前に読ませます。計画で止めます。最小を短さと取り違えません。段階に割り、関係する分だけ渡します。そして、作業から学んだことを版として戻します。

ただし、ここまでは「どう書くか」の話です。書いた仕様が実際に守られたかは、別に確かめなければ分かりません。表向き動くことと、要求を満たすことは違います。次回は、その確かめる側へ進みます。何をもって達成とするのか。どこを人が見て、どこを別の判定に任せるのか。仕様の設計から、検証の設計へ移ります。