# doc-tracer-add-frontmatter

> Markdownドキュメントにトレーサビリティ用のYAMLフロントマターを追加する。新規ドキュメント作成時や、既存ドキュメントにトレース情報を追加する際に使用。

- Author: 大和田知洋
- Repository: tomohiro-owada/doc-tracer
- Version: 20260203162209
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/tomohiro-owada/doc-tracer
- Web: https://mule.run/skillshub/@@tomohiro-owada/doc-tracer~doc-tracer-add-frontmatter:20260203162209

---

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

# YAMLフロントマター追加

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

## フロントマター構造

```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. 親ドキュメントの特定

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

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

### 3. フロントマター生成

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

```yaml
---
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:` に書く**

```yaml
# これはリンク切れになる
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形式

| コードタイプ | ノード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` |

### 完了確認

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