doc-tracer-add-frontmatter

name	doc-tracer-add-frontmatter
description	Markdownドキュメントにトレーサビリティ用のYAMLフロントマターを追加する。新規ドキュメント作成時や、既存ドキュメントにトレース情報を追加する際に使用。
allowed-tools	Read, Edit, Glob, Grep

YAMLフロントマター追加

Markdownドキュメントにトレーサビリティ用のYAMLフロントマターを追加します。

フロントマター構造

---
trace:
  id: doc:docs/XX_レイヤー名/ドキュメント名.md
  parent:
    - doc:docs/上位レイヤー/親ドキュメント.md
  children:
    - doc:docs/下位レイヤー/子ドキュメント1.md
    - doc:docs/下位レイヤー/子ドキュメント2.md
  implements:
    - doc:docs/01_要件定義/機能要件定義書.md
  uses:
    - component:コンポーネント名
    - api:/api/v1/endpoint
---

5層構造とレイヤー間の関係

レイヤー	役割	親レイヤー
01_要件定義	WHY（なぜ作るか）	なし（最上位）
02_仕様書	WHAT（何を作るか）	01_要件定義
03_基本設計	HOW概要（どう作るか）	02_仕様書 または 01_要件定義
04_詳細設計	HOW詳細	03_基本設計
05_プログラム設計	実装設計	04_詳細設計

手順

1. 対象ドキュメントの確認

$ARGUMENTS

ファイルパスからレイヤーを判定:

• 01_要件定義/ → 最上位層、parentなし
• 02_仕様書/ → parent: 01_要件定義
• 03_基本設計/ → parent: 02_仕様書 または 01_要件定義
• 04_詳細設計/ → parent: 03_基本設計
• 05_プログラム設計/ → parent: 04_詳細設計

2. 親ドキュメントの特定

同じ機能領域の上位層ドキュメントを探す:

# 例: 認証関連なら
ls docs/02_仕様書/ | grep -i 認証
ls docs/01_要件定義/ | grep -i 要件

3. フロントマター生成

IDは doc: プレフィックス + ファイルパス（docs/から）:

---
trace:
  id: doc:docs/03_基本設計/認証基本設計書.md
  parent:
    - doc:docs/02_仕様書/認証仕様書.md
---

4. ドキュメントに追加

ファイルの先頭にフロントマターを追加。既存のフロントマターがある場合は trace: セクションをマージ。

ベストプラクティス

1. parent vs children: 子ドキュメント側に parent を書く方が運用しやすい
2. uses: プログラム設計書のみコード要素への参照を記載
3. implements: 要件を直接実装する場合のみ使用（通常は階層構造で十分）

注意事項

• IDはファイルパスから自動生成されるため、id: フィールドは省略可能
• parent と children は同じエッジを生成するため、どちらか一方だけ使用
• 孤立ドキュメント（parentなし）は doc-tracer check で検出される

---

⚠️ 重要: uses: フィールドでハマらないために

絶対にやってはいけないこと

❌ 存在しないノードIDを uses: に書く

# これはリンク切れになる
uses:
  - module:scan  # ← まだスキャンしてないのに書いた

正しい手順

1. 先にスキャンを実行してノードIDを確認

   ./doc-tracer scan .
   curl -s http://localhost:8888/api/graph | jq '.nodes[] | .id'
   

2. 確認したIDのみを uses: に書く

   uses:
     - module:scan  # ← スキャン結果で存在を確認済み
   

3. 再スキャンしてチェック

   ./doc-tracer scan . && ./doc-tracer check
   

よくあるノードID形式

コードタイプ	ノードID形式	例
Goファイル (cmd/)	module:ファイル名	module:scan
Goファイル (internal/db/)	module:db/ファイル名	module:db/schema
Vueコンポーネント	component:コンポーネント名	component:Header
TypeScript	module:ファイル名	module:utils
Composable	composable:関数名	composable:useAuth

完了確認

./doc-tracer scan . && ./doc-tracer check
# 「問題なし」が出るまで uses: を修正する