folio design-intent / vision なぜ作るかの宣言
なぜ folio を作るのか。 北極星 (目指す状態) と、 そこへ向かう目標・成功基準・機能の方向をまとめる
このビジョンが約束すること (1 文サマリ)
folio の文書規律を一般化し、 専門家でない人も機械も読める 「完璧な文書一式」 をどんなプロジェクトにも生成できるようにする — その北極星と、 3 つの目標・3 つの成功基準・4 本の機能の方向をまとめた、 folio 自身の出発点となる文書です。
ビジョンの中心は次の一文です。 以降の章はすべて、 この一文を 「誰のために・何を・どう確かめて」 実現するかの展開です。
北極星 (このプロジェクトが目指す状態)
どんなプロジェクトの文書も、 専門家でない人が頑張れば読め、 機械が黙って検証できる 「完璧な文書一式」 として生成できる状態にする。
文書には二つの病気があります。 「書いた人と同じ専門知識がないと読めない」 ことと、 「書かれた瞬間から実体とずれて静かに嘘になっていく」 ことです。 folio は、 人間向けのやさしい層と機械向けの厳密な層を同じ 1 枚のページに同居させ、 構造は機械が毎回検査し、 意味は独立のレビュワーが敵対的に確かめる — という規律で、 自分自身の文書からこの病気を取り除いてきました。 目指す状態は、 この規律を folio 固有のものにしておかず一般化し、 どんなプロジェクトでも 「読める・検証できる・古びない」 文書一式が当たり前に手に入ることです。
文書が読まれず、 静かに嘘になっていく — これは書き手の怠慢ではなく、 構造の問題です。 個人の注意力では止まらないから、 仕組みとして解きます。
ソフトウェアの文書は、 多くの場合ふたりの読者のどちらかを諦めています。 専門家向けに書けば発注者や現場の人が読めず、 やさしく書けば厳密さが失われて機械や検証の役に立ちません。 その結果、 「読まれない正式文書」 と 「正しさを誰も保証しないやさしい説明」 が別々に増えていきます。
もう一つの病気は劣化です。 コードや決定は動き続けるのに、 文書は書かれた瞬間から止まっています。 実体との食い違いを見つける仕組みがなければ文書は静かに嘘になり、 嘘になった文書は読まれなくなり、 読まれない文書は直されません。 この悪循環は、 書き手の注意力や善意では止まりません。
同じ規律でも、 立場によって 「うれしさ」 は違います。 このビジョンが誰に何を約束するかを、 4 つの立場ごとに 「得るもの」 の高さで書きます。
専門知識がなくても、 頑張れば文書一式を自分の言葉で理解でき、 「わかったつもり」 のまま承認しなくてよくなる。
読みやすさと厳密さの両立を個人技で背負わされない。 規律の実行と検査はエンジンが肩代わりする。
文書のどこを読めば正確なデータが得られるかが構造で保証され、 推測に頼らず検証や生成に使える。
文書と実体のずれが仕組みで検出されるため、 古い文書に騙されずに合流できる。
北極星は方向であって物差しではありません。 3 つの目標に割り、 それぞれに 「達成できたと言える状態」 (成功基準) を付けます。 数字でなく状態で測るのは、 このビジョンが質を約束するものだからです。
同じ 1 枚の文書が、 非エンジニアの読解と機械の検証の両方に耐える状態にする (人間層と機械層の同居 = dual-audience)。
捏造・脱落・実体との食い違いを、 決定的な機械検査と独立レビュワーの二層で見つかる状態にする (二層を床 = floor・天井 = ceiling と呼ぶ)。
folio 固有でなく、 どんなプロジェクトのどんな文書種にも同じ規律を着せられる状態にする。
予備知識のない読者が、 案内なしで文書一式を読み歩き、 「何を・なぜ・どう確かめるか」 を自分の言葉で言い直せる。
→ G-1 の物差し出荷される文書は例外なく、 機械検査 (floor) と独立レビュー (ceiling) の両方を通過している。
→ G-2 の物差し新しい文書種やプロジェクトの追加が、 エンジン本体の変更なしに部品 (パック) の追加だけで済む。
→ G-3 の物差しビジョンは 「作る機能の一覧表」 ではありません。 目標を実現するための機能の方向を 4 本にまとめます。 folio はまだ照会先となる要件文書を持たないため、 ここでは方向だけを約束します (照会先が生まれたら結びます)。
機械の正本 (契約データ) から、 人間向けの読みやすい層と機械向けの厳密な層を、 同じ 1 枚のページへ決定的に組み上げる。 元データに無いことは書けない。
構造・件数・つながりは決定的な機械検査 (floor) が毎回固め、 意味の忠実さ (捏造・歪み・読み味) は独立した AI レビュワー (ceiling) が敵対的に確かめる。 両方を通らない文書は出荷しない。
要件定義・設計判断の記録・調査記録・不変原則・用語集などの定番文書種を 「パック」 として同梱し、 薄い共通エンジンの上で差し替えられるようにする。
文書同士の 「なぜ」 を照会リンクでつなぎ、 どの記述からたどっても最終的に動かせない原則へ行き着くことを機械が確かめられるようにする。
ビジョンには 「やらないこと」 も書きます。 実現を脅かす 3 つのリスクと、 軸を守るための非目標をはっきりさせます。 リスクの一つ (機械化のやりすぎ) は、 folio 自身が一度踏んで方向転換した実証済みの罠です。
規律の実行コストが書き手の負担として漏れ出すと、 文書を書くこと自体が避けられ、 規律ごと放棄される。 規律はエンジンが背負うのが前提。
意味の正しさまで決定的プログラムで裁こうとすると、 検査は際限なく複雑化し (悪い形を列挙し続ける罠)、 それ自体が保守の重荷になる。 機械は数えられるものだけを持ち、 意味は独立レビュワーに委ねる。
「専門家ならなんとか読める」 水準で満足すると、 北極星 (非エンジニアが読める) から静かに遠ざかる。 読みやすさの検査を専門家の目だけで行うと起きる。
非目標 (このビジョンでは作らない、 と決めていること)
文書の中身を人の代わりに考えるツールは作りません。 何を約束し何を決めるかは人が書き、 folio はそれが 「読める・検証できる・古びない」 形であり続けることだけを引き受けます。 また、 汎用のエディタやプロジェクト管理ツールも作りません。 軸は文書規律の一点です (R-3 と同じく、 軸を守るための線引き)。
ビジョンの最後に、 このプロジェクトの判断の突き当たりになる原則を 1 つだけ置きます。 folio が生成するすべての文書は、 最終的にこのような動かない原則へ行き着きます。
「専門家なら読める」 を合格にしない。 迷ったら、 非エンジニアの読者が読める側・機械が検証できる側に倒し、 その両立のためなら機能の多さと生成の速さを諦める。
これは北極星の言い換えではなく、 判断の規則です。 たとえば 「専門用語のままにすれば早く出せる」 という提案は、 速さより読者を優先するこの原則が退けます。 逆に 「やさしくするために厳密さを削る」 という提案も、 機械が検証できる側を守るこの原則が退けます。 機能・速度・読みやすさ・検証可能性がぶつかったとき、 ここが最後の判定基準です。