Frontmatter Schema をフラット構造に統一する
Context
これまで Parlourite Notes の frontmatter は 共通フィールド + type別追加フィールド の2層構造で設計されていた。
- Decision には
status / supersedes / superseded_by / raw_log - Reference には
status(値は別enum) - Page には
page_type / effective_date / revision / supersedes - Log には
noindex / time / raw_log / curated_log
さらに scope: parlourite-note | parlourite-game | universal | meta を必須 enum として持っていた。
この設計は次の問題を生んでいた:
- type追加のたびに schema 変更が必要 — フラットなフォルダ運用(別ADR
2026-09-21-flat-folder-model)の思想と矛盾 - 認知負荷が高い — 記事作成時に「このtypeで使えるフィールドは何か」を毎回確認する必要
scopeenum が閉じている — 新スコープ追加は schema 変更を伴い、tags で代替可能raw_log/curated_log/supersedesの意味付き関係が独自記法 —relatedで吸収可能date/last_updatedの git 自動取得が壊れやすい — コピペで更新扱い、shallow clone で日付欠落、rebaseで履歴消失
Decision
frontmatter を 完全にフラットな1層構造 に統一する。type別追加フィールドを廃止し、全フィールドを全typeで共通利用可能とする。
共通必須フィールド
| フィールド | 型 | 説明 |
|---|---|---|
id | string | YYYY-MM-DD-slug 形式 |
date | YYYY-MM-DD | 初版作成日、並び順の基準、手入力 |
共通任意フィールド
| フィールド | 型 | 効果 |
|---|---|---|
title | string | 未指定時「タイトル未設定」表示 |
type | string | 未指定時「未分類」、色は出現順自動割当 |
tags | string[] | フィルタ・分類、scope を吸収 |
related | id[] | 関連リンク、supersedes 等の意味付き関係も本文で表現 |
status | string | バッジ表示、値は自由(decisionならdecided等、referenceならevergreen等) |
updates | date[] | 更新履歴、追記型。revision = updates.length + 1 |
noindex | boolean | クローラ除外 |
time | “HH:MM” | 同日ソート補助 |
廃止フィールド
scope— tags に吸収revision—updates配列から導出last_updated—updates.at(-1) ?? dateから導出supersedes/superseded_by—related+ 本文自然文raw_log/curated_log—relatedで代替page_type/effective_date— tags +date/updatesで代替llm_summary— title 命名で代替- git 履歴からの日付自動取得 — 手入力に一本化
type の扱い
typeは任意フィールド。未指定は「未分類」として扱う- schema は
z.string().optional()、enum で縛らない - 新 type 追加時、schema 変更不要
- gem.css の type別色は出現順でパレット配列から自動割当
Rationale
1. type別スキーマは type別フォルダと同じ矛盾を持つ
別ADR 2026-09-21-flat-folder-model でフォルダを自由運用にした思想と、schema がtype別に閉じているのは一貫性を欠く。両方をフラット化して初めて「type非依存の管理機構」が完成する。
2. 認知負荷の激減
記事作成時に必要な最低情報は id と date の2つのみ。追加情報は「書きたければ書く、書かなければ何も起きない」でよい。SCHEMA.md を都度参照する必要が消える。
3. updates 配列による履歴の可視化
last_updated を単一値で持つのは最終更新日しか残らない。配列にすることで:
- 更新履歴が全て残る
revisionはupdates.length + 1で導出可能(フィールド重複解消)- 「Rev.3 (2026-10-15)」表示は
updates.at(-1)で組める
学術論文のリビジョン履歴、RFC の Change Log 等、履歴を配列で持つのは一般的な慣習である。
4. git 自動取得の廃止理由
git 履歴から date / last_updated を取る方式は次の問題がある:
- ローカルコピペで実質未変更でも「更新扱い」される
- CI の shallow clone(
fetch-depth: 1)では履歴が取れず日付が壊れる - rebase / squash merge で履歴が書き換わると日付が飛ぶ
- 別リポジトリからのファイル移動で初回コミット日が実態と乖離
- 「並び順を手動制御したい」要件と衝突
手入力は単純で壊れない。順序制御が意図的に効く。将来必要になれば git 取得を後付けできる(YAGNI)。
5. Zod optional の挙動を活用
Astro Content Collections は Zod schema で検証し、必須フィールド欠落は ビルドエラー。任意フィールドは undefined として型に現れ、UI側で entry.data.status && <Badge/> のような分岐で「あれば表示、なければ何も出ない」を自然に実現できる。
「フィールドが存在すれば効果を与える」設計はこれで完全に達成される。
Pugh Matrix
Baseline: 現行の2層構造(type別追加フィールドあり)
| 案 | 認知負荷 | type追加コスト | 情報表現力 | 日付信頼性 | 合計 |
|---|---|---|---|---|---|
| Baseline: 2層構造 + git自動取得 | 0 | 0 | 0 | 0 | 0 |
| A: フラット + git自動取得 | ++ | ++ | - | 0 | +3 |
| B: フラット + 手入力 + updates配列 | ++ | ++ | + | ++ | +7 |
| C: 2層維持 + updates配列のみ改善 | - | - | + | ++ | +1 |
案Bを採用。
Consequences
Positive
- 記事作成の最低ハードルが
id+dateの2つのみに低下 - 新 type 追加時のコード変更ゼロ
- 更新履歴が frontmatter に残り、記事の変遷が追える
- 日付制御が意図通りに効く(並び順が壊れない)
- schema 定義が短くなり、保守負荷が下がる
Negative / Trade-off
supersedesの有向性が失われる — 本文自然文とstatus: supersededで表現、機械的追跡が必要になれば後付けrevision手動管理が必要 — ただしupdates.length + 1で自動導出可能なので実質不要statusに不整合な値も書けてしまう — 運用ルール(meta/RULES.md)で慣習値を示すが強制はしない- 記事更新のたびに
updatesへ手動追記が必要 — 認知的に軽く、忘れても実害は限定的
Neutral
- 既存記事のマイグレーションは不要(システム構築段階のため)
- 本文中の型付き関係表現(「supersedes」等)は自然文 +
[[id]]プレースホルダーで運用
Implementation Notes
Zod schema
import { z, defineCollection } from 'astro:content';import { glob } from 'astro/loaders';
const notes = defineCollection({ loader: glob({ pattern: '**/*.md', base: './content' }), schema: z.object({ id: z.string().regex(/^\d{4}-\d{2}-\d{2}-[a-z0-9-]+$/), date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), title: z.string().default('タイトル未設定'), type: z.string().optional(), tags: z.array(z.string()).default([]), related: z.array(z.string()).default([]), status: z.string().optional(), updates: z.array(z.string().regex(/^\d{4}-\d{2}-\d{2}$/)).default([]), noindex: z.boolean().optional(), time: z.string().regex(/^\d{2}:\d{2}$/).optional(), }),});
export const collections = { notes };派生値のヘルパー
import type { CollectionEntry } from 'astro:content';
export const getLastUpdated = (entry: CollectionEntry<'notes'>): string => entry.data.updates.at(-1) ?? entry.data.date;
export const getRevision = (entry: CollectionEntry<'notes'>): number => entry.data.updates.length + 1;
export const getDisplayType = (entry: CollectionEntry<'notes'>): string => entry.data.type ?? 'uncategorized';更新運用
記事を更新したら updates 配列に日付を追記する:
date: 2026-09-21updates: - 2026-09-25 - 2026-10-15初版のみの記事は updates を書かないか空配列でよい。