Frontmatter Schema 短縮版の導入
背景
普段 AI に対して「log としてレポートせよ」「reference として仕様書を書け」「decision として ADR を書け」といった指示を頻繁に出している。その際に meta/SCHEMA.md を添付しているが、フルスキーマは長すぎて毎回のプロンプトに含めるには重い。
加えて実運用で以下の問題が観測されている:
- LLM がコードブロックにファイル名を付け忘れる
- 出力パスの type ディレクトリを単数形(
log/)で書きがち(正しくは複数形logs/)
そこで、frontmatter を正しく書ける最小限の情報+出力ルールだけを抜き出した短縮版を作成し、日常的な執筆依頼にはこちらを使う運用に切り替える。
type 振り分けの整理
短縮版に含める type の使い分けを、現状の運用感を元に確定させた。
| type | 用途 | 性質 |
|---|---|---|
reference | 仕様書、マニュアル、ゲームマニュアル | 参照される、長寿命、更新される |
log | メモ、引き継ぎ書、作業記録 | 時点の記録、時系列で意味を持つ |
decision | ADR | 選択の理由、supersede 関係を持ちうる |
page | About、規約等 | サイト運営メタ、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-27title: Hello---```
## 標準例(log)出力時のコードブロック冒頭:`<!-- File: src/content/ja/logs/2026-09-27-memo.md -->`
```yaml---date: 2026-09-27title: 検討メモtype: logtags: [meta]time: "10:00"---```使い分け
| 用途 | 使うもの |
|---|---|
| 日常の執筆依頼(log/reference/decision の作成) | 短縮版 |
| schema 自体の議論・改訂・実装との整合確認 | フル版(meta/SCHEMA.md) |
| 可視性チャネルの詳細挙動を詰める場面 | フル版 |
期待効果
- プロンプト長の削減により応答速度・コスト面で有利
- 「必須は
dateとtitleのみ」「id は書かない」「可視性フラグの OR 挙動」といった間違えやすい要点は短縮版でもカバー - ファイル名コメントの強制により、保存先を毎回明示せずとも正しいパスで出力される
- 複数形パスの明記で
log/vslogs/の揺れを抑止 - 詳細な実装マッピングや派生値計算はフル版側に残しており、SSOT は
meta/SCHEMA.mdのまま維持
メモ
短縮版は本記事のコードブロックに埋め込んだ形が現時点の版。今後 schema が変わった際は、フル版更新に追随して本記事の短縮版も更新するか、meta/SCHEMA-short.md として別ファイル化するかを検討する。
type を将来増やす候補(tutorial / review / announce 等)は現時点では tags で代替可能なため保留。必要になってから追加する方針。