用語集 (Glossary) folio — canonical vocabulary
folio glossary
folio-framework 語の canonical 定義集 — 非エンジニアにも届く平易定義 + 機械可読 term レコードの dual-audience 用語集
この用語集が約束すること (要旨)
この用語集は、 folio という仕組みを動かすために使う言葉を 1 か所に集めて、 だれが読んでも意味がぶれないようにするための辞書です。 各語には、 専門知識がなくても読める平易な説明と、 機械が参照するための正式な記録 (正式名・場所・関連する決め事) の両方が載っています。 folio 自身の言葉を folio のやり方で記述した、 自己適用 (dogfood) の一例でもあります。
用語 (36 語)
folio-framework の言葉 (36 語)
spec
「何を作りたいか・どうあるべきか」という設計の意図そのものを書き残した文書です。 どう実装するか (手順) や、 なぜそう決めたか (理由) とは紙を分けて、 目的だけをはっきり書きます。
使われる文書: 原則 P-3、原則 P-7
機械層 — 構造化 term レコード
- canonical (en)
- spec
- slug / anchor
- #term-spec
- domain
- folio-closed
- 正式定義
- WHAT (設計意図) を declarative に記述する design-intent 文書。 実装 HOW・決定 WHY と content domain を分離する (P-3 / P-7)。
- 使われる文書: P-3
- 使われる文書: P-7
ADR
ある設計上の判断について「何を決めたか・なぜそう決めたか・他の案と比べてどうか」を 1 件ずつ記録した文書です。 一度書いたら後から書き換えず、 当時の判断の記録として残します。
使われる文書: ルール §10.3
機械層 — 構造化 term レコード
- canonical (en)
- ADR
- slug / anchor
- #term-ADR
- domain
- folio-closed
- 正式定義
- Architecture Decision Record。 設計の WHY (決定・根拠・trade-off) を 1 決定 = 1 文書で記録する frozen な歴史資産 (ADR-worthiness は rules §10.3)。
- 使われる文書: rules §10.3
constitution
folio が絶対に守ると約束した、 いちばん上位の決めごと集です。 ここを変えるには必ず人の承認が要り、 ほかの決めごととは別格に扱われます。
使われる文書: 原則 P-10
機械層 — 構造化 term レコード
- canonical (en)
- constitution
- slug / anchor
- #term-constitution
- domain
- folio-closed
- 正式定義
- folio の不変原則 (P-1〜P-14) を定める最上位 spec。 Amendment は user 承認必須・spec graph scan 対象外の特別枠 (P-10)。
- 使われる文書: P-10
invariant
文書がいつでも必ず満たしていなければならない条件のことです。 この条件は機械による自動チェックで守られ続けます。
機械層 — 構造化 term レコード
- canonical (en)
- invariant
- slug / anchor
- #term-invariant
- domain
- folio-closed
- 正式定義
- spec が常に満たすべき構造的・意味的な不変条件。 EARS 要件と folio validate gate が機械的に保証する。
inventory
folio が持つすべての設計文書を機械が自動で読み取って作る一覧表です。 どこに何があるかを機械が把握するための目録になります。
使われる文書: 検証要件 REQ-VER-010
機械層 — 構造化 term レコード
- canonical (en)
- inventory
- slug / anchor
- #term-inventory
- domain
- folio-closed
- 正式定義
- design-intent 空間の全 spec を <head> JSON-LD から走査して生成する機械可読 index (inventory.json)。 prime digest と object-graph の projection 元 (REQ-VER-010)。
- 使われる文書: REQ-VER-010
prime
目録から要点だけを抜き出した短い要約を作る機能です。 AI に「今これだけ知っておいて」と最小限の情報を渡すために使います。
使われる文書: 検証要件 REQ-VER-012
機械層 — 構造化 term レコード
- canonical (en)
- prime
- slug / anchor
- #term-prime
- domain
- folio-closed
- 正式定義
- inventory から progressive disclosure 用の Tier 1 digest を生成する subcommand。 AI への context 注入に使う (REQ-VER-012)。
- 使われる文書: REQ-VER-012
cluster
設計文書を中身の種類ごと (設計意図・決定の記録・調査) に分けて入れておく、 引き出しのようなフォルダのことです。
使われる文書: 原則 P-7、自己仕様 §2
機械層 — 構造化 term レコード
- canonical (en)
- cluster
- slug / anchor
- #term-cluster
- domain
- folio-closed
- 正式定義
- design-intent/ 内の content domain 別ディレクトリ (spec / decisions / research)。 各 cluster は README.html を index に持つ (P-7 3-domain、 具体 dir 名は folio-self-spec §2)。
- 使われる文書: P-7
- 使われる文書: folio-self-spec §2
vocabulary
folio で使う言葉の正式な意味を保持しているファイルです。 文書中の用語にかぶせる説明ふきだしは、 ここから作られます。 folio 自身では、 書き換えるときに人が触る大もとは別の設計データ側にあり、 このファイルはそこから毎回作り直される生成物です (直接書き換えても次の作り直しで消えます。 作り直し忘れは検査が見つけて止めます)。
使われる文書: 原則 P-5
機械層 — 構造化 term レコード
- canonical (en)
- vocabulary
- slug / anchor
- #term-vocabulary
- domain
- folio-closed
- 正式定義
- folio-framework 語の canonical 定義を保持する YAML (vocabulary.yaml)。 folio fix の tooltip populate と Layer 1 consumer の glossary.html derive が読む runtime SSoT (P-5)。 SSoT-first に flip した folio 自身では編集の正本 (edit-SSoT) は glossary contract YAML 側にあり、 本 file はそこからの生成 projection (projection stale gate が byte 一致を保証・ADR-0052)。 flip しない Layer 1 consumer では本 file が edit-SSoT を兼ねる (ADR-0051 §2.3)。
- 使われる文書: P-5
SSoT
ある事柄について「正しい定義はここ 1 か所だけ」と決めた基準点のことです。 他の場所はそこを参照するだけにして、 食い違いを防ぎます。 folio ではこの基準点が 2 つの役割に分かれるので、 どちらを指すのかを必ず言い分けます。 1 つは、 書き換えるときに人が触る大もとのファイル (編集の源)。 もう 1 つは、 できあがった文書の中にある機械向けの正確な記録 (公式の表明) です。
使われる文書: 決定 ADR-0051 §2.3
機械層 — 構造化 term レコード
- canonical (en)
- SSoT
- slug / anchor
- #term-SSoT
- domain
- folio-closed
- 正式定義
- Single Source of Truth。 ある object / term の唯一の正準定義 site で、 他所はそこへ参照する。 SSoT-first 転換後は層を明示する修飾付き full 形で用いる: canonical SSoT = 提示層 (生成 HTML) 内の機械層 (精密 normative) / edit-SSoT = 正本 = 提示層を produce する編集起点 (contract YAML、 ADR-0051 §2.3)。
- 使われる文書: ADR-0051 §2.3
dual-audience
1 つの文書を、 人が読んで分かる説明と、 機械が正確に読み取れる記録の両方を兼ねるように作るやり方です。 同じ 1 枚の中に両方が入っていて、 その文書そのものが公式の表明になります。 書き換えの大もとは、 文書とは別の設計データ (生成のもとになるファイル) に置かれることがあり、 そのときは文書の方が生成物になります。
使われる文書: 決定 ADR-0033、決定 ADR-0050、決定 ADR-0051 §2.3
機械層 — 構造化 term レコード
- canonical (en)
- dual-audience
- slug / anchor
- #term-dual-audience
- domain
- folio-closed
- 正式定義
- 1 HTML artifact が machine (精密 normative = canonical SSoT) と human (essence + 視覚 view) の双方を同一 DOM に併せ持つ pattern (ADR-0033)。 artifact 自身が canonical WHAT (提示層) で機械層はその内部にある。 SSoT-first に flip した doc は編集の源が正本 (edit-SSoT) = contract YAML に分かれ、 flip しない doc は提示層が edit-SSoT を兼ねる (ADR-0050 / ADR-0051 §2.3)。
- 使われる文書: ADR-0033
- 使われる文書: ADR-0050
- 使われる文書: ADR-0051 §2.3
data-audience
文書の各部分が「人向け」か「機械向け」かを示す目印です。 この目印で、 人が読む説明と機械が読む記録をきれいに分けます。
機械層 — 構造化 term レコード
- canonical (en)
- data-audience
- slug / anchor
- #term-data-audience
- domain
- folio-closed
- 正式定義
- 要素が machine 向けか human 向けかを示す属性 taxonomy (machine | human の 2 値)。 dual-audience の構造分離に使う。
EARS
要件 (守るべきこと) を書くときの、 決まった 5 つの型のことです。 「いつ守るのか」を型でそろえることで、 あいまいさをなくします。
機械層 — 構造化 term レコード
- canonical (en)
- EARS
- slug / anchor
- #term-EARS
- domain
- folio-closed
- 正式定義
- Easy Approach to Requirements Syntax。 要件を ubiquitous / event / state / optional / unwanted の 5 pattern で記述する記法。
essence
ある項目の定義場所にすでに書いてある内容を使い回して作る、 短い要約のことです。 説明を新しく書き起こさず、 元の言葉を再利用します。
使われる文書: ルール §9.2、原則 P-7
機械層 — 構造化 term レコード
- canonical (en)
- essence
- slug / anchor
- #term-essence
- domain
- folio-closed
- 正式定義
- defined-object の定義 site の既存内容を再利用した plain-text 要約。 xref tooltip の生成元 (rules §9.2、 新規に書き起こさない = P-7)。
- 使われる文書: rules §9.2
- 使われる文書: P-7
dogfood
folio 自身を、 folio が定めたやり方や道具で作って確かめることです。 自分のルールが実際に役立つかを、 自分で使って検証します。
機械層 — 構造化 term レコード
- canonical (en)
- dogfood
- slug / anchor
- #term-dogfood
- domain
- folio-closed
- 正式定義
- folio 自身を folio の規約・機構で構築し検証する self-application。 規約が実用に耐えるかの検証手段。
floor
機械が自動でできる品質チェックの層です。 ここは「最低限ここは必ず守る」という下限を、 機械的に強制します。
使われる文書: 決定 ADR-0028
機械層 — 構造化 term レコード
- canonical (en)
- floor
- slug / anchor
- #term-floor
- domain
- folio-closed
- 正式定義
- deterministic な機械検査層 (folio validate gate)。 二層 enforcement の下限で、 機械化可能な品質を CI で強制する (ADR-0028)。
- 使われる文書: ADR-0028
ceiling
機械では判断しきれない、 意味や読みやすさといった品質を、 AI のレビューで補う層です。 機械チェックの上限を超えた部分を見ます。
使われる文書: 決定 ADR-0028
機械層 — 構造化 term レコード
- canonical (en)
- ceiling
- slug / anchor
- #term-ceiling
- domain
- folio-closed
- 正式定義
- LLM review 層 (Phase F spec-review agent)。 floor が機械検査できない意味的品質を補完する上限 (ADR-0028)。
- 使われる文書: ADR-0028
xref
文書の中から、 別の決めごとや項目へ張るリンクのことです。 リンクの抜けがないかを機械が自動でチェックして保証します。
使われる文書: 決定 ADR-0034
機械層 — 構造化 term レコード
- canonical (en)
- xref
- slug / anchor
- #term-xref
- domain
- folio-closed
- 正式定義
- defined-object への in-band な untyped cross-reference (a class=xref + data-tooltip)。 folio fix が穴を materialize し validate が completeness を機械保証する (ADR-0034)。
- 使われる文書: ADR-0034
defined-object
固有の名前 (ID) を持っていて、 他から参照できる項目のことです。 原則・要件・決定・ルールの各番号などが当てはまります。
機械層 — 構造化 term レコード
- canonical (en)
- defined-object
- slug / anchor
- #term-defined-object
- domain
- folio-closed
- 正式定義
- 一意 canonical ID を持つ参照可能 object (principle P-N / requirement REQ-* / decision ADR-NNNN / rule §)。 Class A xref の対象。
canonical name
1 つの物事に対して「正式にはこう呼ぶ」と決めた、 ただ 1 つの呼び名です。 表記のゆれや言い換えを禁じて、 言葉を一貫させます。
使われる文書: 原則 P-5
機械層 — 構造化 term レコード
- canonical (en)
- canonical name
- slug / anchor
- #term-canonical-name
- domain
- folio-closed
- 正式定義
- 1 entity に対する唯一の正準名 (P-5)。 表記ゆれ・同義語を禁じ、 用語の一貫性を保つ。
- 使われる文書: P-5
progressive disclosure
情報を一度に全部見せず、 要約からだんだん詳しくたどれるように段階的に開く見せ方です。 まず要点、 次に概要、 最後に全文の順です。
機械層 — 構造化 term レコード
- canonical (en)
- progressive disclosure
- slug / anchor
- #term-progressive-disclosure
- domain
- folio-closed
- 正式定義
- 情報を Tier 1 (digest) から Tier 2 (lead) Tier 3 (full body) へ段階開示する pattern。 folio prime の inventory digest が体現する。
caller-marker
設計文書を勝手に編集できないよう見張る仕組みです。 決められた正しい入口を通ったときだけ編集を許可します。
使われる文書: 決定 ADR-0006
機械層 — 構造化 term レコード
- canonical (en)
- caller-marker
- slug / anchor
- #term-caller-marker
- domain
- folio-closed
- 正式定義
- spec 編集を gate する hook 機構 (.folio/architect-active marker file or env var)。 folio-architect 経由の編集のみ許可する (ADR-0006)。
- 使われる文書: ADR-0006
gate
folio の自動チェックが文書一式にかける、 検査の 1 単位です。 違反でストップさせるものと、 注意だけ出すものの 2 種類があります。
使われる文書: ルール §10.2、検証要件 REQ-VER-023
機械層 — 構造化 term レコード
- canonical (en)
- gate
- slug / anchor
- #term-gate
- domain
- folio-closed
- 正式定義
- folio validate / CI が spec 集合へ課す機械検査の単位。 block (violation = exit 1) と warn (exit code 非影響) の 2 channel を持つ (rules §10.2 / REQ-VER-023)。
- 使われる文書: rules §10.2
- 使われる文書: REQ-VER-023
marker
「ここからここまではこういう扱い」という境界を、 文書の中に書いておく目印です。 中身を機械が管理するのか人が書くのかを区別します。
機械層 — 構造化 term レコード
- canonical (en)
- marker
- slug / anchor
- #term-marker
- domain
- folio-closed
- 正式定義
- HTML comment による所有境界の宣言 (folio:chrome-* / folio:nav-curated / folio:landing-hero 等)。 内側が build 所有か人間所有かは機構ごとに定まる。
golden
正解とする出力をファイルとして保存しておき、 後の出力と 1 文字ずつ比べて、 変わっていないかを確かめる基準のことです。
使われる文書: 検証要件 REQ-VER-004
機械層 — 構造化 term レコード
- canonical (en)
- golden
- slug / anchor
- #term-golden
- domain
- folio-closed
- 正式定義
- 期待出力を file として commit し byte 比較で回帰を検出する基準 (tests/baselines)。 更新は --accept + diff review の明示手続きを経る (REQ-VER-004)。
- 使われる文書: REQ-VER-004
keystone
目印などの前提がない対象は、 あえて検査せず素通りさせて全体をきれいに保つ、 という考え方です。 誤った警告を出すより、 検査しない方を選びます。
機械層 — 構造化 term レコード
- canonical (en)
- keystone
- slug / anchor
- #term-keystone
- domain
- folio-closed
- 正式定義
- 機構の前提 (marker / opt-in signal) を持たない対象を検査せず skip し clean を保つ設計原則。 誤発火より無検査を選び、 採用は対象側の明示 opt-in に委ねる。
frozen
正式に決まった後はもう本文を書き換えない、 歴史の記録としての文書のことです。 実際とのずれは別の文書に記録します。
使われる文書: 原則 P-10
機械層 — 構造化 term レコード
- canonical (en)
- frozen
- slug / anchor
- #term-frozen
- domain
- folio-closed
- 正式定義
- accepted 後に本文を改訂しない歴史資産 (ADR / constitution)。 実装との乖離は living spec が divergence trace として記録する (P-10)。
- 使われる文書: P-10
chrome
すべてのページに自動で付く、 ナビゲーションの枠 (リンクや目次など) のことです。 手で書き換えても、 作り直すと上書きされます。
使われる文書: 決定 ADR-0039 §2.3
機械層 — 構造化 term レコード
- canonical (en)
- chrome
- slug / anchor
- #term-chrome
- domain
- folio-closed
- 正式定義
- folio build が全 page の marker 領域へ注入・維持するナビ枠 (skip-link / breadcrumb / ページ内目次 / prev-next、 ADR-0039 §2.3)。 手編集は再 build が上書きする。
- 使われる文書: ADR-0039 §2.3
curated region
目印の内側を人が自由に書き、 その内容を folio が壊さずそのまま保つ領域のことです。 自動で付く枠とは、 中身を持つ向きが逆です。
機械層 — 構造化 term レコード
- canonical (en)
- curated region
- slug / anchor
- #term-curated-region
- domain
- folio-closed
- 正式定義
- marker の内側を人間が author し、 folio build が verbatim に往復保全する領域 (nav-curated / landing-hero)。 chrome と所有の向きが逆。
remediate
チェックで見つかった問題を直す操作や道具のことをまとめてこう呼びます。 見た目の作り直しとリンクの埋め込みで、 担当する道具が分かれます。
使われる文書: ルール §11.2
機械層 — 構造化 term レコード
- canonical (en)
- remediate
- slug / anchor
- #term-remediate
- domain
- folio-closed
- 正式定義
- validate が検出した違反を解消する操作・tool の総称。 表示層 regen は folio build、 graph materialize は folio fix が分担する (rules §11.2)。
- 使われる文書: rules §11.2
fold
クリックで開閉して折りたためる表示のことです。 機械向けの細かい記録や長い一覧をふだんは畳んでおき、 人向けの要点をいつも見えるようにします。
機械層 — 構造化 term レコード
- canonical (en)
- fold
- slug / anchor
- #term-fold
- domain
- folio-closed
- 正式定義
- details/summary による折り畳み表示。 machine 精密部や長大列を既定で畳み、 人間向け要旨を常時可視に保つ (dual-audience の human view 側)。
sandbox
決まった手順で動作を試す検証の仕組みです。 部品を本番と切り離した安全な場所で、 想定の入力を使って単体で確かめます。
使われる文書: 決定 ADR-0013、決定 ADR-0017
機械層 — 構造化 term レコード
- canonical (en)
- sandbox
- slug / anchor
- #term-sandbox
- domain
- folio-closed
- 正式定義
- tests/ の決定的 verification framework (scenario YAML + runner + fixtures + golden)。 hook / CLI を mock payload・隔離 root で単体検証する (ADR-0013 / 0017)。
- 使われる文書: ADR-0013
- 使われる文書: ADR-0017
harness
検証の手順を実際に走らせて、 結果が正しいかを判定する実行役のプログラムです。 検査の種類ごとに走らせ方を使い分けます。
使われる文書: 検証要件 REQ-VER-011
機械層 — 構造化 term レコード
- canonical (en)
- harness
- slug / anchor
- #term-harness
- domain
- folio-closed
- 正式定義
- scenario を実行し assertion する runner 実装 (tests/runner.sh)。 kind (hook / cli-golden / cli-scaffold 等) ごとの実行経路を持つ (REQ-VER-011)。
- 使われる文書: REQ-VER-011
landing
folio の入口となるトップページの型です。 ひとことの見出しから、 進む先のボタン、 読者別の案内カード、 一覧へと並ぶ構成になっています。
使われる文書: 決定 ADR-0039 §2.2
機械層 — 構造化 term レコード
- canonical (en)
- landing
- slug / anchor
- #term-landing
- domain
- folio-closed
- 正式定義
- design-intent/index.html の入口 template (hero 一文 → 単一 CTA → 読者別カード → cluster 一覧、 ADR-0039 §2.2)。 型は build 所有・文言は curated。
- 使われる文書: ADR-0039 §2.2
architecture-description
システムが『どんな部品でできていて、 それらがどうつながり、 どんな原則で成り立っているか』という構造の姿を、 1 つの文書にまとめて記述する文書の種類のことです。 folio 自身の作りを説明した folio-self-spec が、 その一例にあたります。
機械層 — 構造化 term レコード
- canonical (en)
- architecture-description
- slug / anchor
- #term-architecture-description
- domain
- folio-closed
- 正式定義
- 構造の WHAT を 1 文書で捉える doc-type (ISO/IEC/IEEE 42010)。 system の構成要素・関係・原則を記述する。 folio-self-spec はその instance。 design-intent space (空間全体) でも Layer Architecture (2 層構造) でもない。
design-intent space
folio の設計の意図をまとめて置いてある場所 (design-intent/ フォルダ全体) のことです。 設計の狙いを書いた文書・決定の記録・調査・素材が、 ここにひとまとまりで収められています。
使われる文書: 原則 P-7
機械層 — 構造化 term レコード
- canonical (en)
- design-intent space
- slug / anchor
- #term-design-intent-space
- domain
- folio-closed
- 正式定義
- folio repo の design-intent/ ディレクトリ全体 = spec / decisions / research / assets を含む設計意図の空間 (P-7 3-domain、 constitution §1 の architecture specification framework が書く対象)。 architecture-description (空間内の 1 doc-type) でも Layer Architecture でもない。
- 使われる文書: P-7
Layer Architecture
folio の仕組みを 2 つの階層に分けた全体構造のことです。 folio そのもの (土台の層) と、 folio を使って文書を作る側のプロジェクト (使う層) の 2 段に分かれています。
機械層 — 構造化 term レコード
- canonical (en)
- Layer Architecture
- slug / anchor
- #term-layer-architecture
- domain
- folio-closed
- 正式定義
- constitution §3 が定める folio の 2 層構造 = Layer 0 META FRAMEWORK (folio 自身) と Layer 1 consumer (folio を使う project)。 design-intent space (design-intent/ 空間) でも architecture-description (doc-type) でもない。