mcpField
P
project-documentation

project-documentation

github.com/jiffies開発0139 回インストール39 週間前に更新
リポジトリ

project-documentation について

プロジェクトの README やシステム文書を作成する Skill です。セットアップ、設定、アーキテクチャを明確に説明したいメンテナー向けに、Mermaid 図、手順ガイド、設定チェックリストを提供します。

主な機能

  1. 01Mermaid によるシステムフロー図
  2. 02段階的なセットアップガイド
  3. 03設定ドキュメントの構成指針
  4. 04README テンプレートと品質チェックリスト

活用シーン

  1. 01新しいソフトウェアプロジェクトの文書作成
  2. 02既存 README の改善
  3. 03環境変数と設定ファイルの説明

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/jiffies/project-documentation-skill --skill project-documentation

インストール後、Claude Code で/project-documentationを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

examples/
complete-example.md
references/
mermaid-patterns.md
step-by-step-guide.md
config-organization.md

詳細

プロジェクトドキュメント

ソフトウェアプロジェクト向けに、明確で網羅的かつ使いやすい README とシステムドキュメントを作成します。

主な機能

このスキルを使うと、次のような高品質なプロジェクトドキュメントを作成できます。

  1. Mermaid フローチャート - システムの動作原理を可視化します
  2. 手順ごとの説明 - 初心者にもわかりやすい詳細なガイドです
  3. 設定ドキュメント - 環境変数と設定ファイルをわかりやすく整理します

ワークフロー

1. プロジェクトを理解する

ドキュメントを作成する前に、必要な情報を集めます。

  • プロジェクトの主な機能と目的
  • 技術スタック（フロントエンド、バックエンド、データベース、外部サービス）
  • ユーザーのワークフロー（起動手順、主な操作）
  • 外部依存関係（API キー、アカウント、ツール）
  • 設定項目（必須と任意）

情報源：README、package.json、.env.example、主要なコードファイル（main.ts、app.ts、routes/）

2. Mermaid フローチャートを作成する

プロジェクトのニーズに応じて、適切な図を選びます。

  • コアフロー図（必須）- 起動からタスク完了までのユーザー操作の流れ
  • データフロー図（推奨）- システムコンポーネント間のやり取りと API 呼び出し
  • 技術アーキテクチャ図（推奨）- 技術スタックと階層構造

テンプレートとパターンの詳細：references/mermaid-patterns.md を参照してください。

3. 手順ごとの説明を作成する

次の順序で使用手順を整理します。

  1. 前提条件（ソフトウェア、アカウント、ツール）
  2. プロジェクトのクローンと依存関係のインストール
  3. 外部サービスの認証情報の取得（必要な場合）
  4. 環境変数の設定
  5. システムの初期化（必要な場合）
  6. サービスの起動
  7. 機能の使用
  8. システムの動作確認

各手順に含める内容：目的、コマンド、想定される出力、ヒント、注意事項。

手順作成ガイドの詳細：references/step-by-step-guide.md を参照してください。

4. 設定ドキュメントを整理する

.env.example を明確な区切りで構成します。

# ========================================
# Main Category Title
# ========================================
CONFIG_ITEM=example_value

# ----------------------------------------
# Subcategory Title
# ----------------------------------------
CONFIG_ITEM=example_value

各設定項目について、次の内容を記載します。

  • 必須か任意か
  • 目的と用途
  • 取得方法（外部サービスの場合）
  • デフォルト値
  • 完全な設定例

整理ガイドの詳細：references/config-organization.md を参照してください。

5. README の推奨構成
# Project Name - Brief Description
## Features
## System Operation Principles (Mermaid diagrams)
## Quick Start (Step by Step)
## Common Commands
## API Examples
## Tech Stack
## Project Structure
## Documentation
## Important Notes
## License

品質チェックリスト

ドキュメントを完成させる前に、次の項目を確認します。

フローチャート：

  • コアフローでユーザーの操作が明確に示されている
  • データフローがシステムのやり取りを正確に反映している
  • アーキテクチャ図に技術スタック全体が示されている
  • 適切な色が使われ、複雑さが抑えられている（ノード数は20未満）

使用手順：

  • 前提条件がすべて記載されている
  • 各手順に明確なタイトルと目的がある
  • コピーしてすぐに使えるコマンドが記載されている
  • 想定される出力が説明されている
  • よくある問題への対処法が含まれている

設定：

  • 必須か任意かが明確に示されている
  • 各項目の目的が説明されている
  • 取得方法が記載されている
  • 区切りとグループ分けが明確である
  • 複数の選択肢を比較している（該当する場合）

使いやすさ：

  • わかりやすいアイコンが使われている（✅ ⚠️ 💡）
  • 複数の選択肢が提示されている（該当する場合）
  • トラブルシューティングのヒントが含まれている
  • 簡潔でわかりやすい表現になっている
  • すべてのリンクにアクセスできる

参考資料

ベストプラクティス

  1. ユーザーの視点を最優先 - 予備知識がまったくないことを前提にします
  2. 実行しやすさ - すべてのコマンドをコピーして貼り付けられるようにします
  3. 完全性 - 必要な情報をすべて含めます
  4. 明瞭さ - 図、表、コードブロックを使用します
  5. 検証可能性 - 検証手順を示します

よくあるシナリオ

新規プロジェクト：構成を把握 → 図を作成 → 手順を記述 → 設定を整理 → 品質を検証

既存プロジェクトの更新：現在の README を読む → 不足箇所を特定 → 内容を追加・最適化 → 品質を検証

設定の最適化：機能ごとに分類 → 区切りを追加 → 必須・任意を明記 → 入手方法へのリンクを追加

コメント

Markdown 対応