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層構造とレイヤー間の関係

手順

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を確認

   bash

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

2. •

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

   yaml

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

3. •

   再スキャンしてチェック

   bash

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

よくあるノードID形式

完了確認

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