# Knowledge YAML 運用ルール（dev-docs-ssot スターターキット）

## 目的

このディレクトリは、`docs/requirements/` 等の **Markdown 正本**を AI・ツールで扱いやすくするための構造化インデックスを管理する。

## 原則

- Markdown が正本（`docs/requirements/REQ-*.md` 等）
- YAML は構造化インデックス（Markdown の代替ではない）
- YAML には必ず `source_refs` で出典 Markdown を指す
- 推測情報は `confidence: low` とする
- 確定していない情報を `confirmed` にしない
- `reference/baseline-open-items.md` の OPEN 項目は `open_questions.yaml` と整合させる

## 更新タイミング

- REQ / ADR / 設計書の Markdown を追加・更新したとき
- ゲートレビューで未決・リスクが見つかったとき
- `reference/baseline-open-items.md` を更新したとき

## 関連ファイル

| 種別 | 正本 | 索引 |
| --- | --- | --- |
| 要件 | `docs/requirements/REQ-*.md` | `requirements.yaml` |
| 未決 | `reference/baseline-open-items.md` | `open_questions.yaml` |
| 意思決定 | `docs/adr/ADR-*.md` | `decisions.yaml` |
| テストトレース | `docs/testing/traceability.csv` | `traceability.yaml` |
| リスク | ゲート出力 `output/gate/` | `risks.yaml` |

## 作業手順

1. Markdown 正本を更新
2. `tools/extract_knowledge_from_markdown.md` に従い YAML を更新
3. `tools/validate_knowledge.md` で検証
4. 必要に応じ `reports/` のレポートを再生成

## 禁止事項

- Markdown 本文に存在しない内容を確定情報として登録する
- 出典なしで `confirmed` にする
- キー名を場当たり的に増やす
- 同じ意味の項目を別 ID で乱立させる