mcpField
D
docs

docs

github.com/dedalus-erp-pas開発132 回インストール
リポジトリ

docs について

docsは、プロダクトオーナー向けのフランス語READMEの作成・更新と、プロジェクトのdocs/内にある技術文書の改善を行うスキルです。未作成の場合はCLAUDE.mdとAGENT.mdも生成します。

主な機能

  1. 01フランス語のREADME.mdを作成・更新
  2. 02docs/内のMarkdown文書を確認・改善
  3. 03未作成時にCLAUDE.mdとAGENT.mdを生成
  4. 04プロジェクト文書の不足箇所を特定

活用シーン

  1. 01コードベースを調査してプロジェクトREADMEを作成
  2. 02大きな変更後に文書を更新
  3. 03関係者のオンボーディング時にdocs/を確認

インストール

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

$npx skills add https://github.com/dedalus-erp-pas/foundation-skills --skill docs

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

詳細

README ジェネレーター

プロダクトオーナー向けの、フランス語で書かれた簡潔な README.md を生成（または更新）し、Mermaid 図で説明します。docs/ ディレクトリ内の技術ドキュメントをすべてレビューして改善します。CLAUDE.md と AGENT.md が存在しない場合は、それらも生成します。

使用するタイミング

  • プロジェクトのルートに README.md が存在しない場合
  • 大規模な変更後、既存の README.md が古くなっている場合
  • 重要な機能の追加やアーキテクチャの変更後
  • プロダクトオーナーや新しい関係者をプロジェクトに迎える場合

作業内容

ステップ 1：コードベースを調査する

プロジェクトの目的、アーキテクチャ、技術スタックを理解するため、コードベースを徹底的に調査します。

  • パッケージマニフェスト： ルートおよびサブパッケージ（モノレポ）にある package.json、composer.json、pyproject.toml、Cargo.toml、または同等のファイルを読みます
  • プロジェクト構成： 最上位のディレクトリと主要なファイルを一覧表示し、アーキテクチャを理解します
  • ドキュメント： docs/ ディレクトリがあるか確認します。docs/ 内の各 .md ファイルの最初の 20〜30 行を読み、それぞれの短いフランス語の説明（1 行）を推測します。これは目次で使用します
  • CI/CD： .github/workflows/、.gitlab-ci.yml、Jenkinsfile、Dockerfile、docker-compose.yml を探します
  • データベース： マイグレーション、スキーマ、Prisma/TypeORM/Sequelize の設定を探します
  • ルート／コントローラー： ルート定義、API エンドポイント、コントローラーを調べます
  • Git 情報： git log --oneline -10 と git remote -v を実行し、最近の活動とホスティング先を把握します
  • 環境： .env.example や環境設定ファイルを探します
ステップ 2：作成または更新する
  • プロジェクトのルートに README.md が存在するか確認します
  • 存在しない場合： 以下のテンプレートを使用して新規作成します
  • 存在する場合： 既存の内容を読み、事実に関するセクション（スタック、アーキテクチャ、機能）を更新し、チームが追加したカスタムセクションは保持します
ステップ 3：内容を生成する

以下の「README テンプレート」セクションで定義されているテンプレートに従います。執筆ガイドラインに沿って、すべての内容をフランス語で記述します。

ステップ 4：ファイルを書き込む

プロジェクトのルートに README.md を保存します。

ステップ 5：CLAUDE.md と AGENT.md を生成する

これらのファイルがプロジェクトのルートに存在しない場合に限ります。 すでに存在する場合は変更しないでください。

  • CLAUDE.md — コードベースの調査に基づいて Claude Code 向けの指示を生成します（下記の専用セクションを参照）
  • AGENT.md — コードベースの調査に基づいて自律型 AI エージェント向けの指示を生成します（下記の専用セクションを参照）
ステップ 6：技術ドキュメントをレビューする

docs/ ディレクトリ内のすべての .md ファイルをレビューし、以下に定義されているドキュメント品質ルールに従って改善を提案します。

各ファイルについて：

  1. ファイル全体を読む
  2. ドキュメント品質ルールの各ルールに照らして評価する
  3. 具体的な改善を提案する — ルールに違反するセクションを書き直します
  4. ファイルに変更を直接適用する
  5. ファイルごとの変更概要をユーザーに報告する

既存のドキュメントファイルを削除しないでください。 内容の改善のみを行います。

ステップ 7：ドキュメントの不足を特定する

コードベースの調査結果（ステップ 1）と既存の docs/ ファイルを照合し、重要または必須の機能がドキュメント化されていない箇所を特定します。

  1. ドキュメント化済みのトピックを一覧化する — 各 docs/*.md ファイルの内容をまとめます
  2. コードベースの機能を一覧化する — ステップ 1 の調査結果から、コード内で確認できた主要な機能、モジュール、API、統合、ワークフロー、アーキテクチャ上の判断をまとめます
  3. ギャップを分析する — 2 つの一覧を比較し、次のいずれかに該当する機能を指摘します。
    • 本番コードで使用されているが、対応するドキュメントがない
    • 中核となるビジネスワークフロー（認証、データパイプライン、外部サービスとの統合など）
    • 背景を知らない新しいチームメンバーが理解に困るアーキテクチャ上の判断
    • 動作がわかりにくい複雑なモジュール
  4. 新しいドキュメントファイルを提案する — 各ギャップについて、以下をユーザーに提示します。
    • 提案するファイル名（例：docs/authentication-flow.md）
    • 記載内容の説明（1 行）
    • 優先度：Critical（システムの理解を妨げる）または Important（オンボーディングに大きく役立つ）
  5. どのファイルを作成するかユーザーに確認する
  6. 承認されたファイルをドキュメント品質ルールに従って作成する — フランス語で、簡潔に、PO 向けに記述し、役立つ場合は Mermaid 図を含めます
ステップ 8：確認する

実施した内容をユーザーにまとめて報告します。

  • 作成したファイルと更新したファイル
  • 含めた主なセクション
  • 特定できず、プレースホルダーとして残した情報
  • ドキュメントレビュー： レビューした docs/ ファイルの一覧と、各ファイルに適用した改善内容の概要（1 行）
  • ドキュメントの不足： 提案した新しいドキュメントファイル、承認されたファイル、作成したファイルの一覧

README テンプレート

生成する README.md は、次の構成に従う必要があります。

# [プロジェクト名]

短い説明（1〜2 文、専門用語を使わない）。製品が何をするものか、誰を対象としているかを説明します。

## 目次

README のすべてのセクションをアンカーリンク付きで列挙した、自動生成の目次です。技術ドキュメントのサブセクションも含めます。

## Table des matières

- [À quoi sert ce produit ?](#à-quoi-sert-ce-produit-)
- [Fonctionnalités principales](#fonctionnalités-principales)
- [Comment ça fonctionne](#comment-ça-fonctionne)
- [Environnements](#environnements)
- [Déploiement](#déploiement)
- [Stack technique](#stack-technique)
- [Documentation complémentaire](#documentation-complémentaire)

### Documentation technique

| Document | Description |
|----------|-------------|
| [Architecture REST & WebSocket](docs/REST-WebSocket-Architecture.md) | Description de l'architecture API |
| [Schéma de base de données](docs/database-schema.md) | Structure des tables et relations |

重要： 各ドキュメントファイルの説明は、内容を実際に読んで（ステップ 1）導き出してください。創作してはいけません。

## この製品の目的

ビジネス上の価値を説明します。ユーザーの視点から、製品で実現できることを 3〜5 個の箇条書きで示します。

## 主な機能

ユーザーにとってのメリットを中心に機能を列挙します。箇条書きを使用してください。実装方法ではなく、ユーザーができることに焦点を当てます。

## 仕組み

Mermaid の graph LR または graph TD を使った概要レベルのアーキテクチャ図を示し、その後に短い文章で説明します。

```mermaid
graph LR
    A[Utilisateur] --> B[Application Web]
    B --> C[API Backend]
    C --> D[Base de données]
    C --> E[Services externes]
`` `

L'utilisateur interagit avec l'application web, qui communique avec l'API backend. Le backend gère la logique métier et stocke les données en base.
## 環境

環境情報を含む表です。

| Environnement | URL | Description |
|---------------|-----|-------------|
| Développement | `http://localhost:3000` | Environnement local |
| Staging | `https://staging.example.com` | Pré-production |
| Production | `https://app.example.com` | Environnement de production |

設定ファイルに実際の URL がある場合はそれを使用し、ない場合は現実的なプレースホルダーを使用します。

## デプロイ

Mermaid の graph LR 図で CI/CD パイプラインを示し、その後に短く説明します。

## 技術スタック

技術スタックをカテゴリ別に 3〜5 行でまとめます。

- **Frontend :** React, TypeScript, TailwindCSS
- **Backend :** Node.js, NestJS, TypeORM
- **Base de données :** PostgreSQL
- **Hébergement :** Docker, GitLab CI/CD
## 関連ドキュメント

docs/ ファイルがあれば、そのリンクを記載します。docs/ フォルダーがない場合、このセクションは省略します。

Mermaid 図のルール

  1. ラベルはフランス語にする — すべてのノードラベルとエッジラベルをフランス語にします
  2. 図 1 つあたりのノードは最大 8〜10 個 — 読みやすく、概要レベルに保ちます
  3. 使用可能な種類： graph、flowchart、sequenceDiagram
  4. 使用禁止の種類： classDiagram、erDiagram、stateDiagram（PO 向けとしては専門的すぎます）
  5. 各図の下に文章で説明を付ける — 図だけでは不十分です
  6. シンプルで明快にする — 入れ子のサブグラフ、複雑な条件、技術的な詳細は避けます
Mermaid 図の例
graph LR
    A[Développeur] -->|Push du code| B[GitLab CI]
    B -->|Tests auto| C{Tests OK ?}
    C -->|Oui| D[Déploiement Staging]
    C -->|Non| E[Notification erreur]
    D -->|Validation manuelle| F[Déploiement Production]

この図は、継続的デプロイのパイプラインを示しています。開発者がコードをプッシュすると、自動テストが開始されます。テストに合格すると、コードはステージング環境にデプロイされ、手動での承認後に本番環境へデプロイされます。

フランス語の執筆ガイドライン

  • 自然でプロフェッショナルなフランス語を使用し、「vous」（敬称）で呼びかけます
  • フランス語に相当する表現がない技術用語（WebSocket、Docker、CI/CD、API など）を除き、英語由来の表現は避けます
  • 文は短くします。 1文あたり最大20語です
  • 長い段落より箇条書きを優先します
  • 技術用語は使いません。 開発者ではなく、プロダクトオーナー向けに書きます
  • READMEではコードブロックを使用しません（Mermaid図を除く）
  • 頭字語は初出時に説明します（例：「CI/CD（継続的インテグレーションと継続的デリバリー）」）
  • 文書全体で用語を統一します

ドキュメント品質ルール

これらのルールは、docs/ 内のファイルをレビューおよび改善する際に適用されます。各ドキュメントファイルはこれらのルールに従う必要があります。

言語
  • フランス語で記述します — すべての内容をフランス語にします
  • 例外： フランス語に相当する表現がない技術用語（API、WebSocket、Docker、CI/CD、JSON など）は英語のままにします
  • 敬称を使用します — 一貫して「vous」を使用します
  • 頭字語は初出時に説明します
簡潔さ
  • 文は短くします — 1文あたり最大20語です
  • 段落より箇条書きを優先します — 長いテキストブロックより、構造化されたリストを使用します
  • 不要な前置きは省きます — 「このセクションでは、これから……を見ていきます」のような導入は削除し、要点から始めます
  • 1つの段落につき1つのアイデアにします — 2つのトピックを扱う段落は分割します
読みやすさ
  • 必要な情報をすぐ見つけられる構成にします — 読者が必要な情報に移動しやすいよう、見出し（H2、H3）を適切に使います
  • セクション内で初めて言及する重要な用語を太字にします
  • 比較には表を使用します — 選択肢、機能、設定を比較する場合は、文章ではなく表を使います
  • コード例は短く、要点を絞ります — コードブロックは最大10～15行とし、目的を説明するコメントを1行添えます
対象読者
  • 原則としてプロダクトオーナー向けにします — 「どのように」より先に「何を」「なぜ」を説明します
  • テーマに応じて技術的な詳細を含めます — パーサー、プロトコル、データベーススキーマ、APIコントラクトには技術的な詳細を含めるべきです
  • 技術的なセクションには明確なラベルを付けます — 見出しやコールアウト（例：「> 技術的な詳細」）を使い、技術に詳しくない読者が読み飛ばせるようにします
Mermaid図
  • 長い説明より図を優先します — 概念にフロー、シーケンス、アーキテクチャが含まれる場合は、文章の代わりに、または文章と併せてMermaidを使用します
  • 上記のMermaid図ルールに従います（フランス語のラベル、ノード数は最大8～10個、使用可能な種類、図の下に説明文を記載）
  • 冗長な説明を置き換えます — フローやアーキテクチャを5行以上で説明するセクションは、図への置き換えや図の追加を検討します
構成
  • すべてのドキュメントファイルは、ファイル名またはトピックに合ったH1タイトルから始めます
  • タイトルの直後に短い導入段落を置きます（1～2文）。文書の対象読者と内容を説明します
  • 論理的な順序にします： 背景／目的 → 仕組み → 詳細／リファレンス → 例

新規作成モードと更新モード

新規作成モード（既存のREADME.mdがない場合）

コードベースを調査し、すべてのセクションを新規作成します。

更新モード（README.mdがすでにある場合）
  1. 既存のREADME.mdを読みます
  2. テンプレートに該当するセクションを特定します
  3. 事実に関するセクション（技術スタック、アーキテクチャ、機能、環境）を、最新のコードベースの状態に合わせて更新します
  4. テンプレートに該当しない独自のセクションは保持します — チームが手動で追加した可能性があります
  5. すべてのセクションが反映されるように目次を更新します

CLAUDE.md の生成

プロジェクトのルートに CLAUDE.md が存在しない場合にのみ生成してください。

コードベースを調査して、以下の内容を推定し、含めてください。

  • プロジェクトの概要： プロジェクトの内容を1段落でまとめます
  • 技術スタックと主要な依存関係： バージョンを含めます
  • プロジェクト構成： 主要なディレクトリとその用途
  • 便利なコマンド： 開発、ビルド、テスト、lint、マイグレーション、シード — package.json のスクリプトまたは Makefile で確認した実際のコマンド
  • コード規約： 命名パターン、ファイル構成のパターン、確認できたアーキテクチャパターン（例：React フック、サービスパターン、コントローラーとルートの分離）
  • Git ワークフロー： ブランチの命名規則（確認できる場合）、コミットメッセージのパターン（git log から）
  • 主要なファイルとディレクトリ： Claude が把握しておくべきもの
  • 注意点と重要事項： プロジェクト固有のもの（例：モノレポ構成、共有パッケージ、必要な環境変数）
  • 従うべきパターン： 既存のコードスタイルから推定した、新しいコードを書く際のパターン

AGENT.md の生成

プロジェクトのルートに AGENT.md が存在しない場合にのみ生成してください。

コードベースを調査して、以下の内容を推定し、含めてください。

  • プロジェクトの概要と目的： 2〜3文
  • モノレポの構成： パッケージ間の依存関係（該当する場合）
  • 必須コマンド： インストール、開発、ビルド、テスト、マイグレーション、シード — 実際のコマンド
  • コード規約： 自動変更を行う際に守るべきもの
  • 開発ワークフロー： ブランチ、コミット、CI/CD パイプライン
  • 自動変更に関する重要事項： 避けること、必ず行うこと、変更してはならない重要なファイル

出力例

README に期待される形式を簡潔に示した例を以下に示します。

# Overwatch

Plateforme de supervision applicative permettant de surveiller la santé et les performances de vos applications en temps réel.

## Table des matières

- [À quoi sert ce produit ?](#à-quoi-sert-ce-produit-)
- [Fonctionnalités principales](#fonctionnalités-principales)
- [Comment ça fonctionne](#comment-ça-fonctionne)
- [Environnements](#environnements)
- [Déploiement](#déploiement)
- [Stack technique](#stack-technique)
- [Documentation complémentaire](#documentation-complémentaire)

### Documentation technique

| Document | Description |
|----------|-------------|
| [Architecture API](docs/api-architecture.md) | Vue d'ensemble de l'architecture REST |

## À quoi sert ce produit ?

- Surveiller la disponibilité de vos applications en continu
- Recevoir des alertes en cas de dysfonctionnement
- Visualiser l'historique de santé via des tableaux de bord
- Gérer les environnements de déploiement (dev, staging, production)
- Centraliser la supervision de toutes vos applications

## Fonctionnalités principales

- **Tableau de bord temps réel** — Vue d'ensemble de la santé de toutes vos applications
- **Historique de santé** — Graphiques et métriques sur les performances passées
- **Gestion multi-environnements** — Suivi par environnement de déploiement
- **Alertes automatiques** — Notification en cas de dégradation du service

## Comment ça fonctionne

` ``mermaid
graph LR
    A[Utilisateur] --> B[Interface Web]
    B --> C[API NestJS]
    C --> D[Base PostgreSQL]
    C --> E[Vérification de santé]
    E --> F[Applications surveillées]
` ``

L'utilisateur accède à l'interface web pour consulter l'état de ses applications. L'API backend effectue des vérifications de santé régulières et stocke les résultats en base de données.

## Stack technique

- **Frontend :** React 18, TypeScript, TailwindCSS
- **Backend :** NestJS, TypeORM, PostgreSQL
- **Infrastructure :** Docker, GitLab CI/CD

チェックリスト

README.md を保存する前に、以下を確認してください。

  • すべての内容がフランス語である（技術用語を除く）
  • 目次にすべてのセクションが含まれ、アンカーリンクが正しい
  • Documentation technique サブセクションに、すべての docs/*.md ファイルと、内容から推定した説明が記載されている
  • Mermaid 図が有効で、ノード数が最大8〜10個である
  • Mermaid 図では、許可されたタイプ（graph、flowchart、sequenceDiagram）のみを使用している
  • すべての図の下に文章による説明がある
  • Mermaid 図のラベルがフランス語である
  • コードブロックがない（Mermaid を除く）
  • 1文が20語未満である
  • 敬称を一貫して使用している
  • 略語が初出時に説明されている
  • CLAUDE.md は、存在しなかった場合にのみ生成されている
  • AGENT.md は、存在しなかった場合にのみ生成されている
  • すべての docs/*.md ファイルを Documentation Quality Rules に照らして確認した
  • ドキュメントがフランス語で、簡潔で、読みやすく、PO 向けである
  • 冗長な説明に代わる箇所に Mermaid 図を追加した
  • ギャップ分析を実施した：コードベースの機能と既存ドキュメントを比較した
  • 不足している重要または必須のドキュメントについて、作成前にユーザーへ提案した
  • 新しいドキュメントファイルが Documentation Quality Rules に準拠している
  • 作成・更新した内容、改善したドキュメント、新たに提案・作成したドキュメントについてユーザーに伝えた

コメント

Markdown 対応