grill 討論 (2026-06-10) で確定した決定 6 件。 根因は 「機械 gate があるものだけが磨かれる」 という価値の非対称で、 16-gate 全 green のサイトが初見の人間に読めなかった (独立 5-lens 監査 wf_8b14e53a が実測で裏取り)。
| # | 論点 | 決定 |
|---|---|---|
| 1 | 読者定義 | 層別: 入口 = 初見の外部開発者 / spec 本文 = 既習者の参照 / decisions = 経緯を追う維持者 |
| 2 | 入口 | folio build に landing template (hero + 読者別導線)。 型は本調査に基づき設計し、 rendered の見た目を反復確認 |
| 3 | 統一 chrome | build が全ページに注入 (パンくず・戻り導線・目次)。 constitution への注入は 枠のみ・本文不変の範囲で grill 中に user 承認済 — ただし本文に触れる注入 (見出しへの id 付与等) はこの承認範囲外であり、 §6 の open question として ADR 起草時に再確認する |
| 4 | 既定値 | バランス型規範 + audience toggle: essence・表・図は可視 / EARS 全文・経緯は折る / 作業ログ撤去・jargon xref 必須・blob 解体 |
| 5 | 意味層 | co-author 堅持 (ADR-0033 不触)・機械導出 view の拡大のみ |
| 6 | 恒久機構 | floor gate 群 + readability ceiling + constitution P-14 新設 (人間可読性の原則化) |
multi-agent workflow (6 軸並列 sweep → critic による coverage 検証 → gap-fill 3 件 → synthesis)。 critic は 「決定 1-6 の設計を根拠付きで起案できるか」 を問い、 3 つの gap (landing 現状実装の有無確認 (照合結果 = hero/読者別導線は未実装)・chrome 注入の bash 実装パターン・readability 閾値の floor/ceiling 分配) を特定、 gap-fill agent が folio の実コード (bin/folio / common.css / 既存 gate) と照合して verified とした。 critic 総括:
決定 1から6 の大枠は根拠付き起案が可能。ただしコード実検証で landing 未実装と chrome 未注入と floor 閾値の未照合の 3 ギャップ判明。詳細は gaps 参照。
docs サイトの landing page 設計には、確立された複数のパターンが存在する。共通する骨格は「一文ヒーロー（価値提案）→ 読者類型別エントリポイント → getting-started 導線 → 全体一覧」の 4 層構造であり、Nielsen Norman Group の progressive disclosure 研究が裏付けるように、landing page は「目的地」でなく「列車の発着駅」として機能させることが重要である。ヒーロー文の書き方には JTBD（Jobs to be Done）型と機能列挙型があり、developer docs では JTBD 型（user outcome を先行させる）が実証的に離脱率を下げる。読者類型別エントリポイントは Stripe（ユースケース先行）・Rust（習熟度段階）・Terraform（フェーズ別カード）・MDN（役割別学習パス）でそれぞれ異なる軸で実装されており、folio のような spec framework では「初見外部開発者 / spec 参照者 / ADR 維持者」の 3 軸が最も自然な切り口となる。getting-started 導線は単一 CTA（Starlight）から段階的ウィザード（Docusaurus）まで幅があるが、静的 HTML 制約下では単一リンク＋短い説明文が最適解である。landing の情報量は「above the fold に 3-5 項目」が認知負荷研究の推奨値であり、それを超える情報は折り畳みまたは下スクロールに委ねるべきである。
既習者が要件・仕様書を「読む」のではなく「参照・検索」する行動に最適化された文書構造には、確立された複数の設計原則が存在する。NN/G のアイトラッキング研究(2017)は「layer-cake パターン」を実証した: 読者は見出しと小見出しの水平ストライプだけを走査し、目的の見出しで止まって初めて本文を読む。この行動を前提とすると、(1)見出しを拾い読みするだけで文書全体の構造が掴める階層密度、(2)散文より表による要件列挙、(3) Progressive Disclosure による二次情報の折りたたみ、(4) ID ベースのアンカー参照という 4 軸が効果を持つことが、RFC 7322/7992・IEEE 29148 SRS・DITA reference topic・WCAG/Diátaxis・Stripe/Redoc の実採用例からそれぞれ独立して確認できる。folio の静的 HTML + bash build 環境では SSG・JS フレームワークを使わないため、これら全パターンは CSS + `<details>` + data 属性 + `<section>` セマンティクスで再現可能であり、JS を使うとしても read-only な表示補助(TOC scroll-sync 等)の範囲に留まる。
Diátaxis（Daniele Procida, PyCon AU 2017「What nobody tells you about documentation」で初公表、diataxis.fr で体系化）は、ドキュメントを「action-cognition 軸」×「acquisition-application 軸」の 2 軸で 4 象限に分類する：tutorial（学習×実践）/ how-to（実務×実践）/ reference（実務×理論）/ explanation（学習×理論）。「型を混ぜることが混乱の最大原因」であり、それぞれ読者の状態（studying vs working）と内容性質（practical vs theoretical）が異なる。folio の読者層別決定（入口=初見 / spec=既習 / decisions=維持者）は Diátaxis に部分的に整合するが、folio 固有の「dual-audience（人間+AI agent が同一 DOM を読む）」「spec = reference かつ constitution（原則）」「ADR = explanation」という 3 点で標準 Diátaxis を越える拡張が必要である。Canonical・Sequin・Wagtail 等の採用事例からは、landing page（4 型の外に置く navigation hub）+ progressive disclosure（初見→既習の段階的誘導）の組み合わせが実証済みの共存パターンとして浮かぶ。
サイト chrome (パンくず・サイドバー・ページ内目次・prev/next・a11y 基盤) は、規格・実装ともに構成要素ごとに確立した慣行が存在する。パンくずは W3C WCAG G65 (SC 2.4.8 Location) が基準、WAI-ARIA APG が `nav[aria-label="Breadcrumb"] > ol > li` + `aria-current="page"` + CSS セパレータを規定する。schema.org BreadcrumbList の JSON-LD は SEO (Google・Bing) へのセマンティクス伝達として MDN・Google Search Central ともに推奨する。「On this page」目次はビルド時に h2/h3 から anchor リンクを生成して右カラムに配置する手法が Sphinx / MkDocs Material / mdBook で共通して採用されている (静的 HTML 注入で JS 不要)。複数 nav ランドマークは各々を aria-label または aria-labelledby で識別する (WAI-ARIA APG Landmark)。skip link は `position:absolute; clip` → `:focus` で表示するパターンが WCAG 2.1 達成基準 2.4.1 の技術的実装として標準化されている。folio build が静的 HTML を全ページへ機械注入する構成は、これらすべてを build 時テンプレート展開で実現可能であり、JS なしで完結する。
「型を framework が所有し強制する」文書システムは、ADR (Nygard/MADR)、RFC/man page、OpenAPI レンダラー、SSG テーマ (Sphinx/Docusaurus/Starlight/Hugo) という 4 系統で実践されている。共通する利点は「読者の認知負荷削減」「著者の記入漏れ防止」「ツール連携のための機械可読性」の三点。強制の深度には幅があり、XML スキーマ (DITA) による剛強制から Hugo archetype のような柔強制 (生成時のみ) まで連続的に分布する。失敗モードとして、テンプレートが内容の思考を代替してしまう「over-templating」と、テンプレート改訂後に既存コンテンツが旧構造のまま放置される「構造ドリフト」が文献で繰り返し指摘される。folio の制約 (bash CLI による静的 HTML 生成、JS read-only) では、生成時の gate 検査 (floor) と LLM review (ceiling) の組み合わせが既存の ADR/MADR 方式と最も整合する。
段階的開示 (progressive disclosure) は「よく使う情報を前面に、まれにしか必要としない情報を要求時に開示する」原則として Nielsen (1995) が定式化した。reference ドキュメントに適用する際の本質的緊張は「隠しすぎが参照性を破壊する」点にある。Diataxis フレームワークが明確に言語化するとおり、reference は「読む」ものでなく「引く」ものであり、ユーザーは既知の場所に既知の形式で情報があることを期待する。したがって reference では「折り畳み量を最小化し、よく参照される情報は常時可視」が原則となる一方、背景説明・運用注記・エラー一覧など二次情報は折り畳み候補となる。HTML `<details>` 要素は Chromium 系ブラウザで find-in-page が自動展開するがFirefox/Safariは非対応という非互換があり、印刷時は `@media print { details { display: block } }` の CSS ワークアラウンドが必要。GOV.UK / Canada.ca などの公的ガイドラインは「まず折り畳みなしで書ける構造を目指せ、accordion は最終手段」と位置づけており、これは folio の「floor gate で巨大段落 lint」設計と整合する。audience toggle (人間向け essence / 機械向け EARS) の先行例としては Stripe の言語切替タブ・Redoc の nested schema 折り畳みがあり、「コンテキストを保ったまま冗長なレイヤーのみ開示」というパターンが確立されている。
critic が特定した 3 gap を、 folio の実装現状 (bin/folio / common.css / render-gate) と突き合わせて解消した追加調査。 「業界パターンが folio 制約 (静的 HTML / 単一 common.css / classic JS read-only / file:// 直開き / bash flat marker 置換) の下で実装可能か」 を verified にしている。
静的 HTML + 単一 CSS（JS は read-only 補助のみ）で左 sticky サイドナビ・中央本文・右 on-this-page TOC・上部パンくずの chrome を狭幅 viewport で破綻させない CSS パターンを 5 つ特定した。folio の技術制約（body max-width:940px / モバイル BP 未存在 / JS は classic script 補助のみ / file:// 直開き必須）に照らすと、(1) 3 カラム Grid を狭幅で単一カラムへ折りたたむ grid-template-areas コラプス、(2) sticky サイドナビを min-width ブレークポイント外では normal-flow に戻す Conditional Sticky、(3) 右 TOC を狭幅で非表示にする Media-Query TOC Hide、(4) ハンバーガーなし JS-free ナビ折りたたみとして details/summary 要素を使う手法、(5) Playwright multi-viewport 視覚回帰の CI 戦略、の 5 パターンが実在の採用事例・仕様で裏付けられた。checkbox hack はアクセシビリティ上 Wikimedia が details 要素への移行を決定（T333394）しており新規採用に適さない。MkDocs Material は 220–479px / 480–719px / 720–959px / 960–1219px / 1220px+ の 5 段階 em ブレークポイントを採用し、Sphinx RTD は 480px・768px の 2 段、mdBook は 980px 単一境界を採用している。folio の common.css には現在 @media ルールがダークモード 1 本のみ（verified）で、3 カラム chrome 追加時は 980–1024px 以上で Grid 活性化・それ未満でシングルカラム化する BP を新設することが最小追加となる。Playwright file:// は page.goto('file://…') で動作するが、同一環境（Docker/CI）でのベースライン生成が必須で、ローカル HTTP サーバー起動（python -m http.server など）の方が font 描画ブレを抑えられる（verified パターン）。
bash CLI（sed/awk によるフラット marker 置換）で静的 HTML ページ群に breadcrumb・TOC・skip-link・prev/next を一括注入する際の核心課題は 4 点に集約される。(1) ディレクトリ深さに応じた相対パスプレフィックスの算出：find で取得したパスの "/" 個数を tr -cd '/' | wc -c でカウントし "../" を繰り返す手法が最小依存で実装可能。(2) JSON-LD BreadcrumbList の URL 戦略：Google は絶対 URL を要求するが、相対 URL もバリデータが URL 検査時に補完するため構造データとしては機能する。file:// 直開き時は JSON-LD を SEO 無効（コンテンツ確認目的）と割り切り BASE_URL 変数が空のときは script ブロック自体を省略するか "@id" を省略する二段構え戦略が現実的。(3) h2/h3 から on-this-page TOC を生成する awk パイプライン：Python-Markdown 互換の slugify（lowercase・非英数→ハイフン・重複に _N サフィックス）は純 awk+sed で再現でき、id 無し見出しへの attr 注入は sed の in-place 置換で実施できる。(4) 複数 nav landmark の aria-label：W3C APG は「複数 nav が同一ページに存在する場合は各々に一意な aria-label を付与せよ」と規定しており、breadcrumb/site-nav/toc/prev-next の 4 種には "breadcrumbs"・"Primary"（または "Site"）・"Table of contents"・"Page" といった固定ラベルをテンプレートに埋め込むだけで機械生成が成立する。SSG（Hugo/Sphinx/Jekyll）がテンプレートエンジン・ページオブジェクト・パスヘルパーで暗黙に吸収している「深さ計算・前後ページ追跡・重複 slug カウンタ」を bash では明示的に実装する必要があり、それがコストと落とし穴の主要源となる。
技術文書の可読性を機械的 lint（floor gate）と LLM review（ceiling）に分配する設計は、業界の確立した実践と符合する。定量閾値は英語では「文 25-30 語、段落 3-6 文」が GOV.UK・Hemingway App・Vale 実用例のコンセンサスだが、EARS 形式の要件文は構造上 1 文に複数節を持つため同一閾値を適用すると false positive が頻発し、floor gate の対象から除外する設計が妥当。日本語（CJK）では形態素解析なしに「語」を計数できないため、textlint-ja 実績（`sentence-length` max:100字、`max-ten` max:3読点）が示すように文字数＋句読点カウントを代理指標とし、句点（。）・感嘆符（！）・疑問符（？）のみで文境界を認識する句点ベース近似が bash/awk で実現可能。floor と ceiling の分割基準は「決定論的・偽陽性ゼロ保証可能か否か」であり、非空性・最小文字数・リンク到達性はフローア向き、文体的適切さ・文脈依存判断は ceiling 向きという Mozilla/LintMe の知見が裏付けている。
synthesis agent が 6 軸 + gap-fill を統合した設計推奨。 全推奨に根拠パターンが紐づく (調査に無い思いつきは混ぜない)。 ADR 起草はこの節を出発点に grill で確定する。
6 軸 + gap-fill 調査を実コードで照合した結果、critic 評価の 3 ギャップ前提を全て verified とした。(1) landing: repo-root index.html は手書き 33 行・build 生成の architecture/index.html は status グルーピングリストのみで、hero/読者別導線/getting-started/カードはゼロ — 決定 2 は新規実装として読み直す。(2) chrome: 現状は init scaffold が hand-code する cluster-nav リンク 3 本のみ (bin/folio L1811-1928)、breadcrumb/skip-link/on-this-page TOC/prev-next は未注入 — 決定 3 はゼロベース。(3) floor: validate は現在 16 gate (a〜p) で構造検査 (REQ-DA-STRUCT) + render-safety pattern-lint のみ、段落長/文長/essence-非空/hero-非空 等の readability 閾値 gate は不在 — 決定 6 の floor 閾値は新規追加領域。設計骨格は Diátaxis (landing=4型外の navigation hub)・NN/g progressive disclosure (2段上限)・W3C APG (4 nav landmark の一意 aria-label)・GOV.UK (accordion は最終手段)・MADR/RFC (型の必須節強制) という確立パターンで全面的に裏付けられる。folio 固有制約 (静的 HTML / 単一 common.css / classic JS read-only / file:// 直開き / bash flat marker 置換) では、Grid-template-areas コラプス + Conditional Sticky + details/summary ナビ折りたたみ + ROOT_REL 深さカウント + BASE_URL 二段構え + playwright multi-viewport が実装パターンとして適合する。common.css は @media が dark-mode 1 本のみで狭幅 breakpoint 未存在 (verified)、render-gate ceiling は viewport 1280 単一 (blind spot) ゆえ、3 カラム chrome 追加時は 980px breakpoint 新設と mobile-375/tablet-768 視覚回帰拡張が最小追加となる。
build が全 spec/ADR/glossary ページ (constitution は P-10 frozen ゆえ chrome 注入を慎重に・cross-ref のみ) に 4 種 chrome を marker 置換で注入する。配置・形式・生成規則: (1) skip-link = body 直後・最初の focusable、<a href="#main-content" class="skip-link">。CSS で画面外 (position:absolute) → :focus で出現。main に id=main-content tabindex=-1。(2) breadcrumb = main 先頭・h1 直上、<nav aria-label="Breadcrumbs"><ol><li><a>...<li><span aria-current="page">。セパレータは CSS li:not(:last-child)::after { content:'→' }。schema.org BreadcrumbList JSON-LD を BASE_URL 非空時のみ <script type=application/ld+json> で併注入 (position 1始まり整数)。(3) on-this-page TOC = 右カラム (デスクトップ sticky) + 狭幅は本文先頭インライン、<nav aria-labelledby="toc-heading"><h2 id=toc-heading>。awk 2-pass で h2/h3 抽出・既存 id 優先・無ければ出現順連番 id=h2-N を sed in-place 注入 (CJK 見出しは slug 化せず連番)。h4 以下は除外。(4) prev-next = 本文末尾、<nav aria-label="Page"><a rel=prev><a rel=next>、cluster order 配列から導出 (spec cluster 内のみ・reference 型は線形でないため限定)。head に <link rel=prev/next> 併出力。生成規則: 相対パスは ROOT_REL=$(printf '../%.0s' $(seq 1 $depth)) で深さ算出 (depth=rel_path の '/' 数 tr -cd '/' | wc -c)。4 nav の aria-label は固定リテラル (Breadcrumbs/Primary/toc-heading 参照/Page) で APG 一意性を満たす。全 chrome は ADR-0035 nav-regen-drift gate (m) の検査対象に含める。sed injection 回避は perl -p または r コマンド file 参照。
ページ種別 × 既定表示 (可視 / fold / 撤去) の規範表:
| ページ種別 (folio-doc-type) | 可視 (既定 open) | fold (既定 closed details) | 撤去/非該当 |
|---|---|---|---|
| landing (nav-index/hub) | hero 一文・読者別カード・getting-started CTA・cluster 一覧 (全可視) | なし (folding 量ゼロ) | 本文・EARS (landing は本文を持たない=列車駅) |
| cluster README (索引) | §Purpose・§Contents・cluster-nav・配下リンク | 大規模 status group (>8 entry は既定折り) | EARS 全文 |
| spec (reference) | essence・spec-row summary・表・図・見出し | EARS 全文 (req__machine)・経緯・運用注記 | なし |
| ADR (explanation) | Title・Status・Context・Decision | Consequences・代替案詳細・検討経緯 | なし (frozen ゆえ build は本文非改変・chrome のみ) |
| glossary (reference) | 用語 canonical・1行 essence | 長い定義本文 (任意) | EARS |
| constitution (prescriptive explanation) | 原則文 (P-1..P-13)・背景説明 | なし (原則は全可視が望ましい・P-10 frozen) | EARS・audience toggle (不変資産ゆえ最小介入) |
横断規則: (a) details ネストは 2 段上限 (NN/g)・3 段以上禁止。(b) summary には essence 冒頭 1 文を入れ折り畳み状態でも find-in-page (Firefox/Safari) と AI scan を部分補完。(c) @media print で全 details 強制展開 (印刷欠落防止)。(d) data-audience=machine 要素は CSS display:none でフィルタするが DOM に残す (REQ-DA-STRUCT-4 aria-hidden 禁止)。(e) audience toggle (人間/機械/両方) は全種別共通 chrome として右上に配置 (landing 除く)。
classic script (ES module/fetch 不使用・vendoring・read-only 表示補助) での audience toggle 実装パターン: (1) DOM 構造 = build が data-audience="human"|"machine" 属性を各要素に付与済 (REQ-DA-STRUCT-3 で値域 floor 検査済)。machine 部は既定 CSS display:none、human 部は表示 (現行 folio の CSS-only 出し分けを踏襲)。(2) toggle UI = chrome 右上に 3 状態ボタン <div class="audience-toggle" role="group" aria-label="audience 切替"> に「人間向け / 機械向け / 両方」3 ボタン。(3) 動作 = inline classic script で document.querySelectorAll('[data-audience]') を走査し body の class (.show-human / .show-machine / .show-both) を切替えるだけ (DOM 構造は変更しない=read-only enhancement)。CSS 側で body.show-machine [data-audience=human]{display:none} 等を定義。(4) 永続化 = localStorage 任意 (file:// でも動作するがセキュリティ文脈で制限ありゆえ必須にしない)。永続不要なら単純 class 切替で十分。(5) file:// 互換 = inline script・no fetch・no module ゆえ file:// 直開きで動作。(6) progressive enhancement = JS 無効時は CSS 既定 (human 表示・machine は DOM に存在し AI 読取可) で degrade。toggle は表示制御のみで意味データ (essence/EARS) は手書き SSoT のまま (決定 5 と整合)。根拠: Stripe 言語切替タブ + axis5 audience-aware disclosure + MEMORY.md (JS は read-only enhancement・aria-hidden 不使用)。
調査では決め切れず、 user 判断ないし実機確認を要する論点。 ADR 起草 (folio-nmy / folio-2ii) の grill agenda になる。
追記 (転記外、 本文書の編集判断): 本文書自身が header 直後に手書きの cluster-nav を置いている (既存 research leaf doc に前例なし)。 決定 3 の chrome 注入が leaf research にも及ぶ実装段階で、 この手書き nav は build 導出版へ置換 (または curated region 化) しないと二重化・ドリフトの種になる — ADR 起草時の確認事項とする。