| 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. 基本例
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 ドキュメントのフォーマットをチェックし、違反を自動修正できます。
チェックルール:
- タスク項目(リスト)の前には空行が必要
- 番号付きリストのサブリスト前にも空行が必要
- コロンで終わる行の直後にリストがある場合も空行が必要
- 太字ラベル(半角・全角コロン両方)の直後にリストがある場合も空行が必要
NG 例 - ラベルの直後にリスト:
**受入条件**:
- [ ] ログアウトボタンをクリックするとログアウトできる
OK 例:
**受入条件**:
- [ ] ログアウトボタンをクリックするとログアウトできる
NG 例 - 番号付きリストの直後にサブリスト:
1. **対処**: SMB バージョンを確認
- コントロールパネル > ファイルサービス > SMB で設定
OK 例:
1. **対処**: SMB バージョンを確認
- コントロールパネル > ファイルサービス > SMB で設定
NG 例 - コロンで終わる行の直後にリスト:
PMD はカスタム設定で以下をチェック:
- マジックナンバーの使用
OK 例:
PMD はカスタム設定で以下をチェック:
- マジックナンバーの使用
実行手順:
docs/ 配下の全 Markdown ファイルをスキャン
- 上記ルールに違反する箇所を検出
- 違反箇所を自動修正
- 修正結果を報告
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. ベストプラクティス
- 定期確認: 開発フェーズ移行前にドキュメントの完成度を確認する
- 整合性維持: コード変更時は関連ドキュメントも更新する
- レビュー活用: チームレビュー前にドキュメント概要を共有する
- バージョン管理: ドキュメントの変更は Git でコミットする
- インデックス同期: 新しいドキュメント作成後は
--update でインデックスを同期する
- プレビュー確認:
--update-mkdocs 後は mkdocs serve でナビゲーションを確認する
- フォーマット統一: コミット前に
--lint でフォーマットの一貫性を確保する
関連スキル
orchestrating-analysis : 分析フェーズ全体の作業支援
analyzing-requirements : 要件定義関連の作業支援
analyzing-architecture : アーキテクチャ設計支援
tracking-progress : プロジェクト全体の進捗確認