decisiondecided

ID命名規則を `YYYY-MM-DD-slug` に全type統一する

ID命名規則を YYYY-MM-DD-slug に全type統一する

Context

Parlourite Notes 開始3日目時点で、type別に異なるID命名規則を採用していた:

type旧フォーマット例
ADRR-XXXX2026-09-20-page-type-addition
ReferenceREF-XXXXREF-0001
PagePAGE-slug2026-09-19-about
LogLOG-YYYY-MM-DD-slugLOG-2026-09-21-xxx

この不統一により以下の問題が発生していた:

  1. エクスプローラ上のソート性が type によって異なる。連番型(R-XXXX)は作成順ソートが効くが、時系列的な直感と一致しない。
  2. 「なぜtypeによって命名規則が違うのか」の合理的説明が困難。
  3. 新規記事作成時の採番判断コスト。連番型は「次の空き番号」を知る必要があり、LLMに任せるとハルシネーション懸念。
  4. プレースホルダー記法 [[R-XXXX]] を維持したまま複数type参照する場合の記法統一性欠如。

業界慣習の調査結果:

慣習フォーマット採用例
Jekyll/Hexo系ブログYYYY-MM-DD-slug.mdJekyll 公式、多数の静的サイトジェネレータ
ADR公式 (Michael Nygard)NNNN-title.md の連番adr-tools
Zettelkasten / ObsidianYYYYMMDDHHMM-title.mdObsidian community
user個人習慣YYMMDD-*本人の長年の慣習

Decision

全typeのIDを YYYY-MM-DD-slug フォーマットに統一する。IDはファイル名 basename を正典とし、frontmatter には書かない。

  • 例: 2026-09-21-astro-adoption.md, 2026-09-21-parlourite-notes-direction.md
  • typeの区別は frontmatter の type フィールドで行う(IDには含めない)
  • 日付は初回作成日を手入力(date フィールド)。git履歴からの自動取得はしない
  • slug は小文字ハイフン繋ぎ(例: astro-adoption, id-naming-convention)
  • 同日複数記事の衝突時は slug 側で区別(2026-09-21-astro-adoption, 2026-09-21-astro-integrations)。数字サフィックスは使わない

frontmatter に id を書かない理由

Astro v5 Content Layer API の glob() loader は id を予約フィールドとして扱い、collection ルートからの相対パス(拡張子なし)から自動生成する。frontmatter 側に id: を書くと衝突エラーになる。

本プロジェクトでは Astro が自動生成する entry.id(例: decision/2026-09-21-sample-decision)の末尾セグメントを src/lib/entries.ts の extractId() で抽出し、NormalizedEntry.id として利用する。したがって user が意識する ID = ファイル名 basename = YYYY-MM-DD-slug。

採番はスクリプト化する:

Terminal window
npm run new -- --lang ja --type decision --slug astro-adoption
# → src/content/ja/decision/2026-09-21-astro-adoption.md を生成、frontmatter雛形入り

Rationale

  1. 業界標準への準拠: Jekyll/Hexo慣習と完全一致。第三者が見て違和感がない。
  2. 時系列ソートの一貫性: エクスプローラのファイル名順ソートで作成順が保たれる。
  3. user個人習慣との整合: YYMMDD 慣習の拡張版(4桁年)として自然に受け入れ可能。
  4. type非依存: 記事が type 間で変換される場合(例: log → reference 昇華)にID変更不要。
  5. ハルシネーション耐性: 「今日の日付+slug」というルールは明確で、LLM生成時のミスが起きにくい。連番方式では「既存最大値の把握」が必要でエラー源。
  6. Astro glob loader との整合: frontmatter id を持たないことで予約フィールドとの衝突を回避。

Alternatives Considered

案α: 全type共通で YYMMDD-slug(user慣習に完全一致)

  • 却下理由: 4桁年のほうが100年スパンで曖昧性がない。ISO 8601風で業界慣習にも合致。差分は6文字vs10文字で運用負荷ほぼ変わらず。

案β: TYPE-YYYY-MM-DD-slug(type明示)

  • 例: ADR-2026-09-21-astro-adoption
  • 却下理由: 冗長。type情報は frontmatter で持てば十分。フォルダ運用のフラット化と合わせても、type区別のためにIDにprefix不要。

案γ: 現行維持(type別命名)

  • 却下理由: Context に記載した問題が解消されない。

案δ: Zettelkasten風 YYYYMMDDHHMM-slug

  • 却下理由: 秒/分粒度のIDは会話・記録で読み上げにくい。userの「時間はソート用と割り切る」方針とも過剰。log の time は frontmatter に別途持つ。

Pugh Matrix

評価軸:

  • C1: 業界慣習との整合
  • C2: エクスプローラソート性
  • C3: LLM生成のハルシネーション耐性
  • C4: user慣習との親和性
  • C5: 冗長性の低さ
案C1C2C3C4C5合計
Baseline (現行 type別)000000
α: YYMMDD-slug+++++++6
β: YYYY-MM-DD-slug (採用)+++++0+5
γ: TYPE-YYYY-MM-DD-slug+++0—+1
δ: YYYYMMDDHHMM-slug0+++0-+2

採用は案β。案αが総合点で上だが、100年スパンの曖昧性回避と業界標準(ISO 8601, Jekyll/Hexo)への完全整合を重視。

Consequences

Positive

  • 全typeで同じ命名ルールを覚えるだけで良い
  • エクスプローラで常に時系列ソートが効く
  • 採番スクリプトが type 非依存で単純化
  • ADR/Reference/Log 間の変換・昇華が容易(IDが不変)
  • Astro glob loader の予約フィールドと衝突しない

Negative

  • 旧記事の [[R-XXXX]] 等の参照は新ID形式への置換が必要(移行時対応)
  • ADR公式(adr-tools)方式から離れるため、ツールチェーン利用時は独自対応

Neutral

  • URL構造は /{lang}/{id}/ に決定済み(別途)

Migration

対象: 旧 ID 規則の全記事

手順:

  1. 各ファイルの初版作成日を確認し frontmatter date に手入力
  2. 新ID形式(YYYY-MM-DD-slug.md)にリネーム
  3. frontmatter から id / last_updated / revision / supersedes / superseded_by を削除
  4. 全ファイル内の [[R-XXXX]] 参照を [[YYYY-MM-DD-slug]] に一括置換
  5. npx astro sync && npm run build で動作確認後コミット