Masayan tech blog.

  1. ブログ記事一覧>
  2. AI時代のドキュメント作成：Claude Codeでビジネス、開発で必要なドキュメント作成を劇的に効率化

AI時代のドキュメント作成：Claude Codeでビジネス、開発で必要なドキュメント作成を劇的に効率化

公開日
最終更新日

目次

環境

  • MacOS Apple M4 Max Sequoia 15.1
  • Claude Code 2.0.22

この記事を読むことで得られるメリット

  • Claude Codeを活用した効率的なドキュメント作成手法を習得できる
  • Mermaid記法を使った視覚的な図表作成のノウハウが身につく
  • カスタムコマンドの作成方法と運用のベストプラクティスを理解できる
  • ドキュメント作成における典型的なエラーと対処法を事前に把握できる
  • 全36種類の実践的なドキュメント例を知ることができる

この記事を読むのにかかる時間

約10分

要約

Claude Codeとカスタムコマンドを活用することで、ER図、シーケンス図、フローチャートなど技術ドキュメントや、ロードマップ、SWOT分析などのビジネスシーンでよく作成するドキュメントを効率的に作成できる。

Markdown + Mermaid記法を使用し、「コマンド作成→プロンプト改善→エラー修正」のサイクルを回すことで、実務で使える高品質なドキュメントを短時間で生成可能になる。日本語の文字化けやMermaid構文エラーなど、典型的な問題への対処法も含めて解説する。

はじめに

ビジネスや開発の現場において、ドキュメント作成は避けて通れない重要な業務である。しかし、図表の作成やフォーマットの統一には多くの時間が必要で、本来注力すべきコア業務の時間を圧迫してしまう。

本記事では、Claude Codeを活用してドキュメント作成を劇的に効率化する具体的な手法を紹介する。カスタムコマンドを構築し、AIとの対話を通じて高品質なドキュメントを短時間で生成する実践的なアプローチをお伝えする。

例.OAuth2.0認証シーケンス図

どのような精度のドキュメントが作成できるのかについて先に知りたいと思うので、先に画像を載せておく。これくらいなら精度はかなり高く整った出力が可能

Claude Codeによるドキュメント作成の全体像

基本的なアプローチ

Claude Codeでドキュメント作成を効率化するには、Markdown + Mermaid記法の組み合わせが最適である。Markdownの可読性とMermaidの視覚表現力を組み合わせることで、技術文書からビジネス資料まで幅広いドキュメントに対応できる。

以下に、全36種類のドキュメント例を整理している

💻 開発系 (19種類)

📐 Architecture - システム設計 (10種類)

コマンド

用途

使用例

architecture-diagram.md

システム全体のアーキテクチャ図

マイクロサービス構成、レイヤー構造

class-diagram.md

クラス図 (UML)

OOP設計、クラス関係性

data-flow-diagram.md

データフロー図

データの流れ、処理の流れ

dependency-diagram.md

依存関係図

モジュール依存、パッケージ依存

er-diagram.md

ER図 (データベース設計)

テーブル設計、リレーション

sequence-diagram.md

シーケンス図

API呼び出しフロー、処理順序

state-diagram.md

状態遷移図

ステータス管理、ワークフロー

swimlane-diagram.md

スイムレーン図

部門横断プロセス、責任明確化

tech-stack-diagram.md

技術スタック図

使用技術の全体像

use-case-diagram.md

ユースケース図

機能要件、アクター定義

📝 Documentation - 仕様書・ドキュメント (3種類)

コマンド

用途

使用例

api-document.md

API仕様書

RESTful API、エンドポイント定義

mcp-tool-document.md

MCPツールドキュメント

MCP開発用ドキュメント

rfc.md

RFC (技術提案書)

技術変更提案、アーキテクチャ変更

🔄 Workflow - 開発プロセス (3種類)

コマンド

用途

使用例

event-storming.md

イベントストーミング

DDD、ドメイン設計ワークショップ

flowchart.md

フローチャート

処理フロー、ロジック図

git-graph.md

Gitグラフ

ブランチ戦略、リリースフロー

🧪 Testing - テスト (1種類)

コマンド

用途

使用例

test-case-spec.md

テストケース仕様書

テストシナリオ、期待結果定義

👥 Team - チーム運営 (2種類)

コマンド

用途

使用例

onboarding-guide.md

🆕 オンボーディングガイド

新メンバー導入資料

postmortem.md

ポストモーテム

障害振り返り、インシデント分析

📊 ビジネス系 (17種類)

📊 Strategy - 戦略・分析 (4種類)

コマンド

用途

使用例

business-model-canvas.md

ビジネスモデルキャンバス

事業モデル設計

competitive-analysis.md

競合分析

競合他社調査、市場分析

lean-canvas.md

リーンキャンバス

スタートアップ向けビジネスモデル

swot-analysis.md

SWOT分析

強み・弱み・機会・脅威分析

👥 User Research - ユーザーリサーチ (4種類)

コマンド

用途

使用例

customer-journey-map.md

カスタマージャーニーマップ

顧客体験の可視化

funnel-analysis.md

ファネル分析

コンバージョン分析、離脱率

persona.md

ペルソナ

ターゲットユーザー定義

user-journey.md

ユーザージャーニー

ユーザー行動フロー

📅 Planning - プロジェクト管理 (5種類)

コマンド

用途

使用例

gantt-chart.md

ガントチャート

スケジュール管理、工程表

raci-matrix.md

RACI責任分担表

役割分担、責任明確化

roadmap.md

ロードマップ

機能開発計画、製品ビジョン

timeline.md

タイムライン

時系列イベント、マイルストーン

wbs.md

WBS (作業分解図)

タスク分解、階層構造

📈 Visualization - 可視化ツール (4種類)

コマンド

用途

使用例

decision-tree.md

決定木

意思決定フロー、条件分岐

mindmap.md

マインドマップ

アイデア整理、ブレインストーミング

pie-chart.md

円グラフ

割合表示、構成比

quadrant-chart.md

4象限チャート

優先度マトリクス、ポジショニング

効率的なドキュメント作成サイクル

ドキュメント作成は、以下の4つのステップを繰り返すサイクルで進める:

1. カスタムコマンドの作成

まず、Claude Codeに「ER図を作成するカスタムコマンドを作成して」と指示すると、.claude/commands/create-docs/sequence-diagram.mdが生成される（ファイル名は都度異なる）

2. コマンドを実行する

生成されたコマンドをClaude Codeに実行させると一旦ドキュメントの作成を試みてくれる。うまくいけばそのまま成功するが、いくつかの原因により失敗するケースがある。

/create-docs:sequence-diagram OAuth2.0認証シーケンス図

3. エラーの発生と学習

実際にコマンドを実行すると、典型的なエラーに遭遇することが多い:

  • Mermaid構文エラー: 日本語ラベルのクォーテーション不足
  • 文字化け: UTF-8エンコーディングの問題

4. フィードバックと修正

エラー内容や失敗をClaude Codeに詳細にフィードバックする。「先ほどのコマンドで文字化けが発生しました。UTF-8で保存するように修正してください」といった具体的な指示を出すことで、AIは改善版を迅速に生成してくれる。

このサイクルを2〜3回繰り返すことで、実務で使える高品質なカスタムコマンドが完成する。

実践例:シーケンス図作成コマンド

具体例として、OAuth 2.0認証フローのシーケンス図作成コマンドを見てみよう。

コマンドの構造

コマンドを実行

/create-docs:sequence-diagram OAuth 2.0認証フローのシーケンス図

create-docs:sequence-diagram

# シーケンス図作成コマンド

$ARGUMENTSで指定された内容について、マーメイド記法を使用したシーケンス図を作成してください。

## 作成フロー

1. **シーケンス図の作成**: 指定された内容に基づいてマーメイド記法のシーケンス図を作成
2. **ユーザーへの提示**: 作成したシーケンス図をユーザーに提示
3. **保存先の確認**: ユーザーに保存先を確認
4. **ファイル保存**: 確認した保存先にマークダウンファイルとして保存
・・・

作成要件の定義

コマンドには以下の要件を明記している:

図の構成

  • 主要な登場人物(アクター)を明確に定義
  • 時系列に沿った処理フローを表現
  • 各ステップに番号と説明を付与
  • 必要に応じてループや条件分岐を含める

出力形式

  • Mermaid記法のsequenceDiagramを使用
  • 日本語で記述(必要に応じて英語の技術用語を併記)
  • participantで登場人物を定義
  • 矢印と説明文で処理の流れを表現

補足情報

  • シーケンス図の下に「フローの説明」セクションを追加
  • 各ステップの詳細な解説を箇条書きで記載
  • 主要な要素や用語の定義を提供
  • セキュリティやベストプラクティスのポイントを追加

実際の出力例

  • Mermaid記法によるシーケンス図
  • フローの詳細説明(12ステップ)
  • 主要なパラメータの解説
  • セキュリティ上のポイント

これらの情報が数分で生成されることで、ドキュメント作成時間を大幅に短縮できる。

よくあるエラーと対処法

Mermaid構文エラー

問題: 日本語やスペースを含むラベルで構文エラーが発生する

対処法: 日本語を含むすべてのラベルをダブルクォーテーションで囲む

# ❌ エラーになる例
participant User as ユーザー

# ✅ 正しい例
participant User as "ユーザー"

文字化けの問題

問題: 生成されたファイルを開くと日本語が文字化けしている

対処法: Write toolを使用してファイルを作成する

Claude CodeのWrite toolはUTF-8エンコーディングを保証する。カスタムコマンドには以下の指示を含めること:

  • 必ずWrite toolを使用してファイルを作成すること
  • ファイル作成後、必ず内容を確認すること
  • 文字化けが発生した場合は、ファイルを削除して再作成すること

トークン消費量の問題

問題: 複雑な図表の作成時に以下のエラーが発生する

API Error: Claude's response exceeded the 32000 output token maximum.

対処法: 図を分割する

また、利用量制限に達した場合は、リセット時間まで待つ必要がある。ビジュアライズ機能は特にトークン消費量が多いため、使用頻度に注意が必要である。

まとめ

Claude Codeとカスタムコマンドを活用することで、ドキュメント作成の効率は劇的に向上する。

重要なのは、完璧を目指すのではなく、「作成→改善→フィードバック」のサイクルを回し続けることである。エラーを恐れず、失敗から学び、徐々にコマンドを洗練させていくプロセスこそが、AI時代のドキュメント作成における本質的なスキルとなる。

まずは小さく始めて、実務で使いながら改善を重ねていこう。AI時代のドキュメント作成は、もはや時間のかかる作業ではなく、創造的な思考を支援するツールとなっている。