---
name: operating-docs
description: 設計ドキュメントの一覧表示、進捗確認、内容参照、インデックス更新、Markdown Lint を実行。ドキュメント管理や整備時に使用。
---

# ドキュメント管理ガイド

設計ドキュメントの一覧表示、進捗確認、内容参照を行います。

## Instructions

### 1. オプション

- なし : ドキュメント一覧と進捗状況を表示
- `--list` : ドキュメント一覧のみを表示
- `--status` : ドキュメントの作成状況を詳細表示
- `--read <ファイル名>` : 指定したドキュメントの内容を表示
- `--summary` : 全ドキュメントの概要を表示
- `--update` : `docs/index.md` と `mkdocs.yml` を現在のドキュメント構成に合わせて更新
- `--update-index` : `docs/index.md` のみを更新
- `--update-mkdocs` : `mkdocs.yml` のみを更新
- `--lint` : Markdown フォーマットをチェックし、違反を自動修正

### 2. 基本例

```bash
# ドキュメント一覧と進捗確認
# 「設計ドキュメントの一覧と作成状況を確認」

# 特定ドキュメントの参照
# --read tech_stack
# 「技術スタック選定ドキュメントの内容を表示」

# docs/index.md と mkdocs.yml を更新
# --update
# 「現在のドキュメント構成に合わせて両ファイルを更新」

# Markdown フォーマットをチェック・修正
# --lint
# 「タスク項目の前に空行がないなどのフォーマット違反を検出し自動修正」
```

### 3. ドキュメント構成

本プロジェクトのドキュメントは以下の構成で管理されています:

**要件定義ドキュメント** (`docs/requirements/`)

- `requirements_definition.md` : 要件定義書（RDRA 2.0）
- `business_usecase.md` : ビジネスユースケース
- `system_usecase.md` : システムユースケース
- `user_story.md` : ユーザーストーリー

**設計ドキュメント** (`docs/design/`)

- `architecture_backend.md` : バックエンドアーキテクチャ
- `architecture_frontend.md` : フロントエンドアーキテクチャ
- `architecture_infrastructure.md` : インフラストラクチャ
- `data-model.md` : データモデル設計
- `domain-model.md` : ドメインモデル設計
- `ui-design.md` : UI 設計
- `test_strategy.md` : テスト戦略
- `non_functional.md` : 非機能要件
- `operation.md` : 運用要件
- `tech_stack.md` : 技術スタック選定

### 4. ドキュメント更新機能

`--update` オプションを使用すると、現在のドキュメント構成に合わせて `docs/index.md` と `mkdocs.yml` と 各ディレクトリの `index.md` を自動更新できます。

**docs/index.md の更新内容**:

- ドキュメント一覧をカテゴリ別に整理
- 各ドキュメントへのリンクと説明を生成
- 「まずこれを読もうリスト」形式で構成

**mkdocs.yml の更新内容**:

- `nav` セクションを現在のドキュメント構成に合わせて更新
- 要件定義、設計、開発、運用などのカテゴリで階層化
- 新しいドキュメントを自動的にナビゲーションに追加

**各ディレクトリの index.md の更新内容**:

- ドキュメント一覧をカテゴリ別に整理
- 各ドキュメントへのリンクと説明を生成

### 5. Lint 機能

`--lint` オプションを使用すると、Markdown ドキュメントのフォーマットをチェックし、違反を自動修正できます。

**チェックルール**:

- タスク項目（リスト）の前には空行が必要
- 番号付きリストのサブリスト前にも空行が必要
- 番号付きリストのサブリストは 5 スペースインデント（3 スペースは NG）
- コロンで終わる行の直後にリストがある場合も空行が必要
- 太字ラベル（半角・全角コロン両方）の直後にリストがある場合も空行が必要

**NG 例** - ラベルの直後にリスト:

```markdown
**受入条件**:
- [ ] ログアウトボタンをクリックするとログアウトできる
```

**OK 例**:

```markdown
**受入条件**:

- [ ] ログアウトボタンをクリックするとログアウトできる
```

**NG 例** - 番号付きリストの直後にサブリスト:

```markdown
1. **対処**: SMB バージョンを確認
   - コントロールパネル > ファイルサービス > SMB で設定
```

**OK 例**:

```markdown
1. **対処**: SMB バージョンを確認

   - コントロールパネル > ファイルサービス > SMB で設定
```

**NG 例** - 番号付きリストのサブリストのインデントが浅い:

```markdown
1. **データとしてのパターン**

   - すべてのパターンがデータ構造として表現される
   - パターン間の境界が明確
```

**OK 例**:

```markdown
1. **データとしてのパターン**

     - すべてのパターンがデータ構造として表現される
     - パターン間の境界が明確
```

**NG 例** - コロンで終わる行の直後にリスト:

```markdown
PMD はカスタム設定で以下をチェック：
- マジックナンバーの使用
```

**OK 例**:

```markdown
PMD はカスタム設定で以下をチェック：

- マジックナンバーの使用
```

**実行手順**:

1. `docs/` 配下の全 Markdown ファイルをスキャン
2. 上記ルールに違反する箇所を検出
3. 違反箇所を自動修正
4. 修正結果を報告

### 6. 出力例

```
設計ドキュメント一覧
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

docs/requirements/
├─ requirements_definition.md (要件定義書)
├─ business_usecase.md (ビジネスユースケース)
├─ system_usecase.md (システムユースケース)
└─ user_story.md (ユーザーストーリー)

docs/design/
├─ architecture_backend.md (バックエンドアーキテクチャ)
├─ architecture_frontend.md (フロントエンドアーキテクチャ)
├─ data-model.md (データモデル設計)
├─ domain-model.md (ドメインモデル設計)
├─ ui-design.md (UI 設計)
├─ test_strategy.md (テスト戦略)
├─ non_functional.md (非機能要件)
├─ operation.md (運用要件)
└─ tech_stack.md (技術スタック選定)

進捗: 14/14 ドキュメント完成 (100%)
```

### 7. 注意事項

- **前提条件**: `docs/` ディレクトリが存在すること
- **制限事項**: Markdown 形式のドキュメントのみ対応
- **推奨事項**: 定期的にドキュメントの進捗を確認し、最新の状態を維持すること
- **更新時の注意**: `--update` 実行前に現在の `docs/index.md` と `mkdocs.yml` をバックアップすることを推奨
- **MkDocs 依存**: `--update-mkdocs` を使用する場合、MkDocs がインストールされている必要がある

### 8. ベストプラクティス

1. **定期確認**: 開発フェーズ移行前にドキュメントの完成度を確認する
2. **整合性維持**: コード変更時は関連ドキュメントも更新する
3. **レビュー活用**: チームレビュー前にドキュメント概要を共有する
4. **バージョン管理**: ドキュメントの変更は Git でコミットする
5. **インデックス同期**: 新しいドキュメント作成後は `--update` でインデックスを同期する
6. **プレビュー確認**: `--update-mkdocs` 後は `mkdocs serve` でナビゲーションを確認する
7. **フォーマット統一**: コミット前に `--lint` でフォーマットの一貫性を確保する

### 関連スキル

- `orchestrating-analysis` : 分析フェーズ全体の作業支援
- `analyzing-requirements` : 要件定義関連の作業支援
- `analyzing-architecture` : アーキテクチャ設計支援
- `tracking-progress` : プロジェクト全体の進捗確認