k2works/operating-docs

ドキュメント管理ガイド

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

Instructions

1. オプション

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

2. 基本例

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

# 特定ドキュメントの参照
# --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 例 - ラベルの直後にリスト:

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

OK 例:

**受入条件**:

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

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

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

OK 例:

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

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

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

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

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

OK 例:

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

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

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

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

OK 例:

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 : プロジェクト全体の進捗確認