decisiondecided

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 として持っていた。

この設計は次の問題を生んでいた:

  1. type追加のたびに schema 変更が必要 — フラットなフォルダ運用(別ADR 2026-09-21-flat-folder-model)の思想と矛盾
  2. 認知負荷が高い — 記事作成時に「このtypeで使えるフィールドは何か」を毎回確認する必要
  3. scope enum が閉じている — 新スコープ追加は schema 変更を伴い、tags で代替可能
  4. raw_log / curated_log / supersedes の意味付き関係が独自記法 — related で吸収可能
  5. date / last_updated の git 自動取得が壊れやすい — コピペで更新扱い、shallow clone で日付欠落、rebaseで履歴消失

Decision

frontmatter を 完全にフラットな1層構造 に統一する。type別追加フィールドを廃止し、全フィールドを全typeで共通利用可能とする。

共通必須フィールド

フィールド型説明
idstringYYYY-MM-DD-slug 形式
dateYYYY-MM-DD初版作成日、並び順の基準、手入力

共通任意フィールド

フィールド型効果
titlestring未指定時「タイトル未設定」表示
typestring未指定時「未分類」、色は出現順自動割当
tagsstring[]フィルタ・分類、scope を吸収
relatedid[]関連リンク、supersedes 等の意味付き関係も本文で表現
statusstringバッジ表示、値は自由(decisionならdecided等、referenceならevergreen等)
updatesdate[]更新履歴、追記型。revision = updates.length + 1
noindexbooleanクローラ除外
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自動取得00000
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

src/content.config.ts
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 };

派生値のヘルパー

src/lib/entry-helpers.ts
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-21
updates:
- 2026-09-25
- 2026-10-15

初版のみの記事は updates を書かないか空配列でよい。