Shared Knowledge MCP Server

--- description: プロジェクトのドキュメント作成に関する規約と原則 ruleId: document-01jpfcn4mphghcm0jaj3wy7b7j tags: - documentation - development - best-practices globs: - '**/*.java' - '**/*.scala' - '**/*.ts' - '**/*.js' - '**/*.py' - '**/*.go' - '**/*.rs' --- # ドキュメント規約 ## 基本原則 このドキュメントでは、プロジェクト全体で一貫したドキュメントを作成するための規約を定義します。質の高いドキュメントは、プロジェクトの理解を助け、メンテナンス性を向上させるために不可欠です。 ### 1. 明確性と簡潔性 - 簡潔かつ明確な文章を心がける - 一文は短く保ち、複数の概念を一文に詰め込まない - 必要な情報を過不足なく提供する ### 2. 構造化された内容 - 階層的な見出しを適切に使用する（`#`、`##`、`###`など） - 関連するトピックをセクションにまとめる - 目次（TOC）を提供して長文ドキュメントのナビゲーションを容易にする ### 3. 一貫性のある形式 - 用語の使用を統一する（用語集を作成し、参照する） - フォーマットとスタイルを一貫させる - テンプレートを活用する ## ドキュメントの種類 ### 1. 技術仕様書 技術的な詳細を記述するドキュメント。 - システムアーキテクチャ - データモデル - API仕様 - インタフェース定義 ```markdown # [コンポーネント名] 技術仕様書 ## 概要 [コンポーネントの簡潔な説明] ## アーキテクチャ [アーキテクチャ図と説明] ## 主要コンポーネント [各コンポーネントの説明] ## データフロー [データの流れの説明] ## API仕様 [APIメソッド、パラメータ、戻り値の詳細] ## 制約事項 [既知の制限や制約] ``` ### 2. ユーザーガイド システムの使用方法を説明するドキュメント。 - インストール手順 - 基本操作 - 設定方法 - トラブルシューティング ```markdown # [プロダクト名] ユーザーガイド ## 概要 [プロダクトの簡潔な説明と主な機能] ## インストール [インストール手順] ## 基本操作 [基本的な使い方] ## 高度な機能 [高度な機能の説明] ## よくある問題 [一般的な問題と解決策] ``` ### 3. 開発ガイド 開発者向けのガイドライン。 - 開発環境のセットアップ - コーディング規約 - レビュープロセス - デプロイメントフロー ```markdown # 開発ガイド ## 開発環境 [開発環境のセットアップ手順] ## コーディング規約 [コーディング規約の概要と参照先] ## ビルドプロセス [ビルド手順] ## テスト [テスト戦略とテスト実行方法] ## デプロイメント [デプロイメントプロセス] ``` ## マークダウン標準 ### 見出し - `#` - メインタイトル（ドキュメントごとに1つ） - `##` - 主要セクション - `###` - サブセクション - `####` - 詳細セクション - 見出しレベルはスキップしない（`#` の次は必ず `##`） ### リスト - 箇条書きリストには `-` を使用 - 番号付きリストには `1.` を使用 - リストの階層は空白4つでインデント ```markdown - 項目1 - サブ項目1.1 - サブ項目1.2 - 項目2 1. 番号付きサブ項目2.1 2. 番号付きサブ項目2.2 ``` ### コードブロック - バッククォート3つでコードブロックを囲む - 言語識別子を指定して構文ハイライトを有効にする ````markdown ```typescript function example(): string { return "Hello World"; } ``` ```` ### テーブル - シンプルなテーブルにはマークダウンテーブル構文を使用 - 複雑なテーブルにはHTMLを使用することも可 ```markdown | 列1 | 列2 | 列3 | |-----|-----|-----| | 値1 | 値2 | 値3 | | 値4 | 値5 | 値6 | ``` ### 画像 - 画像の説明テキストを必ず含める - 適切なサイズと形式を選択 ```markdown  ``` ### リンク - 相対パスを優先 - リンクテキストは内容を適切に説明 ```markdown [ドキュメント規約](document-01jpfcn4mphghcm0jaj3wy7b7j.md) ``` ## 文書更新のガイドライン ### 1. 定期的なレビューと更新 - ドキュメントは少なくとも3か月に1回レビュー - 機能変更時は関連ドキュメントを必ず更新 - ドキュメントの「最終更新日」を記録 ### 2. バージョン管理 - ドキュメントはコードと同じリポジトリで管理 - 重要な変更にはバージョン番号を割り当て - 変更履歴を記録 ### 3. フィードバックの収集 - ドキュメントにフィードバックメカニズムを提供 - 受け取ったフィードバックに基づいて改善 ## 参考資料 - [Google技術文書作成ガイド](https://developers.google.com/tech-writing) - [Microsoft Writing Style Guide](https://docs.microsoft.com/style-guide) - [AsciiDoc](https://asciidoc.org/)ドキュメント形式 - [Markdown Guide](https://www.markdownguide.org/)