reference

Frontmatter Schema 短縮版の導入

背景

普段 AI に対して「log としてレポートせよ」「reference として仕様書を書け」「decision として ADR を書け」といった指示を頻繁に出している。その際に meta/SCHEMA.md を添付しているが、フルスキーマは長すぎて毎回のプロンプトに含めるには重い。

加えて実運用で以下の問題が観測されている:

  • LLM がコードブロックにファイル名を付け忘れる
  • 出力パスの type ディレクトリを単数形(log/)で書きがち(正しくは複数形 logs/)

そこで、frontmatter を正しく書ける最小限の情報+出力ルールだけを抜き出した短縮版を作成し、日常的な執筆依頼にはこちらを使う運用に切り替える。

type 振り分けの整理

短縮版に含める type の使い分けを、現状の運用感を元に確定させた。

type用途性質
reference仕様書、マニュアル、ゲームマニュアル参照される、長寿命、更新される
logメモ、引き継ぎ書、作業記録時点の記録、時系列で意味を持つ
decisionADR選択の理由、supersede 関係を持ちうる
pageAbout、規約等サイト運営メタ、unlisted: true 明示

判断の要点:

  • ゲームマニュアルは reference のまま(page はサイト運営メタに限定)
  • 「何について」は type ではなく tags で表現する(例: tags: [game-a, manual])
  • type は当面増やさない。現状の4分類は「参照する / 記録する / 決める / サイト運営」で MECE に近い

短縮版

以下を執筆依頼時のプロンプトに添付する。

# Frontmatter Schema (Short)
## 出力ルール(重要)
コードブロックの1行目に必ずファイルパスをHTMLコメントで記述する:
```
<!-- File: src/content/ja/{type複数形}/YYYY-MM-DD-slug.md -->
```
- パスは複数形: `decisions` / `references` / `logs` / `pages`
- 言語: `ja` または `en`
- 例: `<!-- File: src/content/ja/logs/2026-09-27-handover-note.md -->`
## 必須
- `date`: YYYY-MM-DD(初版作成日)
- `title`: string
## 任意
- `type`: `decision` / `reference` / `log` / `page` など自由文字列
- `tags`: string[](小文字ハイフン繋ぎ)
- `related`: string[](他記事の id 配列)
- `status`: 自由文字列(バッジ表示)
- decision: `proposed` / `decided` / `superseded` / `deprecated`
- reference: `seed` / `growing` / `evergreen`
- page: `draft` / `published`
- `description`: string(SEO/OGP、結論が分かる要約)
- `time`: "HH:MM"(同日ソート補助)
- `updates`: date[](更新履歴、末尾追記)
- 可視性フラグ(無効を優先で OR):
- `nobuild: true` — ビルド対象外(404)
- `nolist: true` — 完全ステルス(URL直打ちのみ、RSS/sitemap/検索/wikiリンク全除外、noindex)
- `unlisted: true` — 一覧から除外(トグルONで表示)。RSS/sitemap/検索は通常、SEO通常
- `noindex: true` — noindex + sitemap除外 + Pagefind除外(一覧・RSSには出す)
## type 使い分け
- `reference` — 仕様書、マニュアル、参照ドキュメント(長寿命・更新される)
- `log` — メモ、引き継ぎ書、作業記録(時点の記録・時系列)
- `decision` — ADR(選択の理由・supersede 関係あり)
- `page` — About・規約等のサイト運営メタ(`unlisted: true` 明示)
「何について」は type ではなく `tags` で表現する。
## ID とファイル名
- ファイル名 basename が id(`id` は frontmatter に書かない)
- 命名推奨: `YYYY-MM-DD-slug.md`(`about.md` 等の日付なしも可)
- basename は `^[a-z0-9][a-z0-9-]*$`
- URL: `/{lang}/{id}/`
## 他記事参照
- 本文中は `[[id]]` プレースホルダーを使用
- 未存在・`TBD:` 明示は無効表示になる
## 最小例
```yaml
---
date: 2026-09-27
title: Hello
---
```
## 標準例(log)
出力時のコードブロック冒頭:
`<!-- File: src/content/ja/logs/2026-09-27-memo.md -->`
```yaml
---
date: 2026-09-27
title: 検討メモ
type: log
tags: [meta]
time: "10:00"
---
```

使い分け

用途使うもの
日常の執筆依頼(log/reference/decision の作成)短縮版
schema 自体の議論・改訂・実装との整合確認フル版(meta/SCHEMA.md)
可視性チャネルの詳細挙動を詰める場面フル版

期待効果

  • プロンプト長の削減により応答速度・コスト面で有利
  • 「必須は date と title のみ」「id は書かない」「可視性フラグの OR 挙動」といった間違えやすい要点は短縮版でもカバー
  • ファイル名コメントの強制により、保存先を毎回明示せずとも正しいパスで出力される
  • 複数形パスの明記で log/ vs logs/ の揺れを抑止
  • 詳細な実装マッピングや派生値計算はフル版側に残しており、SSOT は meta/SCHEMA.md のまま維持

メモ

短縮版は本記事のコードブロックに埋め込んだ形が現時点の版。今後 schema が変わった際は、フル版更新に追随して本記事の短縮版も更新するか、meta/SCHEMA-short.md として別ファイル化するかを検討する。

type を将来増やす候補(tutorial / review / announce 等)は現時点では tags で代替可能なため保留。必要になってから追加する方針。