なぜ仕様書ではなく「意思決定」を残す？

このAPIのレスポンス、Figmaのデザインと違くないですか？

リリース直前の金曜日。Slackに流れたエンジニアの一言で、チームの血の気が引く。

PMはJiraのチケットを丁寧に更新していた。デザイナーはFigmaを磨き上げていた。エンジニアはGitHubで爆速でPRを出していた。全員が自分の領分でベストを尽くしていたのに、統合の瞬間に「認識のズレ」が発覚する。

金曜の夕方から始まるSlack考古学。「あの仕様ってどこで決まったんだっけ？」「このAPI、元のチケットと違うけど誰が変えた？」——答えは誰の頭の中にもない。なぜなら、決定した瞬間の文脈がどこにも残っていないから。

私たちはこの「誰も悪くないのにプロジェクトが燃える地獄」に何度もハマりました。 Beaket（ビーケット）は、その経験から生まれたツールです。

仕様書は「嘘」をつくようにできている

仕様書が悪いのではありません。構造が悪いのです。

情報の居場所が役割ごとに分かれている——PMはJiraに、デザイナーはFigmaに、開発者はGitHubに住んでいる。これは自然なことで、変えるべきではありません。各ツールがそれぞれの領域で最善だからです。

問題は、この分散した情報を「正」として一箇所にコピーしようとする行為にあります。

NotionやWikiに書き写した瞬間、情報は二つになる。片方が更新されれば、もう片方は嘘になる。更新を止めた仕様書は、過去の判断を失い、実装と乖離した遺物になっていきます。

これは意志の問題ではなく、構造の問題です。コピーが存在する限り、必ず起きる。

だから私たちは、「情報を一箇所に集約する」というアプローチを捨てました。また新しいWikiを作っても、同じ結末を迎えるだけだからです。

Beaketがやるのは、点在する情報の間に関係性を引くことです。

FigmaやGitHubの情報をBeaketにコピーする必要はありません。それぞれのツールが正本であり続ける。Beaketは正本同士を「なぜこの判断をしたのか」という文脈で結ぶだけです。

具体的には、3つのノードでプロジェクトの判断を構造化します。

この3つが相互にエッジで繋がり、意思決定のグラフを形成します。Beaketに詳細な仕様は書きません。書くのは「何を決めたか」「なぜか」「何と繋がっているか」だけ。

正直に言えば、これは私たちが最も議論した部分です。

「もっと詳細に書けるようにすべきでは？」という声は当然ありました。でも、詳細を書けるようにした瞬間、それは新しいWikiになります。そしてWikiは必ず腐る。

だから、Beaketには「書きすぎない」という制約を意図的に入れました。

判断基準はシンプルです——半年後の自分が、理由を探しに来るかどうか。来るなら書く。来ないなら書かない。パラメータ一覧や実装手順はGitHubに任せる。Beaketが持つのは、「なぜそうなったか」の最小単位だけです。

これはトレードオフです。Beaketは包括的な設計書を作るツールにはなれません。意図的にそうしています。

もう一つ、私たちが実装して良かったと思う仕組みがあります。

Specが書かれた後、デザイナーとエンジニアがそれぞれ独立に「Ready」フラグを立てます。デザイナーは「UIの観点で要件を理解した」、エンジニアは「技術的に理解した」という意味です。両方のフラグが立って初めて、そのSpecは「Ready」になる。

これは承認ワークフローではありません。握手です。

「読みました」ではなく「自分の領域から見て、これで進められます」という宣言。曖昧なまま実装が走ることを、仕組みで防いでいます。

そして万が一、Ready後にSpecが変更された場合は、影響範囲——繋がっているBrief、ADR——が自動で可視化されます。Slackの履歴を遡る必要はもうありません。

Beaketは変更履歴を「誰が・いつ・何を変えたか」だけでなく、「なぜ変えたか」まで記録します。

任意のテキストを選択すると、その文言がどの時点で、誰によって、どんな理由で書き変わったかを遡れます。私たちはこれをDecision Trailと呼んでいます。

派手な機能ではありません。でも、半年後に「この仕様、なんでこうなってるの？」と聞かれた時、答えがそこにある。それだけで、チームの判断速度は変わります。

Beaketが全てのチームにフィットするとは思っていません。

小さなチームで、全員が同じ部屋にいて、コンテキストが共有されている環境では、過剰かもしれません。逆に、数百人規模の組織では、まだ検証が足りていません。

私たちが確信しているのは一つだけです。判断の背景が失われることには、必ずコストが発生する。 そのコストは、チームが大きくなるほど、時間が経つほど、加速度的に増える。

Beaketは、そのコストを構造で抑えるための道具です。特効薬ではなく、保険に近い。

「この設計、誰も理由を説明できない」という状態が、あなたのチームでも起きているなら。まずは一つの判断を繋ぐことから始めてみてください。