Arc42 アーキテクチャドキュメンテーション スキル

実績のある arc42 テンプレート に従ってアーキテクチャドキュメンテーションを作成・管理するための arc42-mcp-server MCPサーバーの使用ガイドです。このサーバーは 6 つのツールを提供し、11 言語と 2 つの出力形式 (AsciiDoc、Markdown) をサポートしています。

前提条件

arc42-mcp-server MCPサーバーが設定され、実行中である必要があります。インストールと設定については セットアップ手順 を参照してください。

---

ワークフロー: 最初から始める場合

1. ガイドをロード → arc42-workflow-guide — arc42 の全体構造と各セクションの内容を理解します
2. ワークスペースを初期化 → arc42-init — 12 個のセクションファイル、config.yaml、README を含むディレクトリ構造を作成します
3. ステータスを確認 → arc42-status — 現在の進捗、完成度、取り組む必要があるセクションを確認します
4. テンプレートを生成 → generate-template — 特定のセクションを作成する前に詳細な構造とガイダンスを取得します
5. コンテンツを作成 → update-section — セクションにコンテンツを書き込みまたは追記します
6. コンテンツをレビュー → get-section — メタデータ (文字数、最終変更日時) 付きの既存コンテンツを読み込みます

ワークフロー: 既存のドキュメンテーション

1. ステータスを確認 → arc42-status — 現在の状態を評価し、不足している部分を特定します
2. セクションを読む → get-section — 既にドキュメント化されている内容を確認します
3. テンプレートを生成 → generate-template — 不完全なセクションの想定される構造を理解します
4. セクションを更新 → update-section — 不足している部分を埋めたり、既存のコンテンツを改善したりします

---

ツールリファレンス

1. arc42-workflow-guide

包括的な arc42 ドキュメンテーション ワークフロー ガイドをロードします。新しいドキュメンテーション作業を開始する際は必ずこれを最初に呼び出してください — 各セクションにどの情報が属するかについて説明します。

パラメータ	型	必須	デフォルト	説明
language	enum	いいえ	"EN"	言語コード: EN、DE、ES、FR、IT、NL、PT、RU、CZ、UKR、ZH
format	enum	いいえ	"asciidoc"	出力形式: asciidoc (または adoc)、markdown (または md)

戻り値: セクション説明、利用可能な言語、サポートされている形式、ワークスペース ルート パスを含む完全なワークフロー ガイド テキスト。

2. arc42-init

arc42 ドキュメンテーション ワークスペースを初期化します。すべての 12 個のセクション ファイル、config.yaml、README、およびメイン ドキュメンテーション ファイルを含む arc42-docs/ ディレクトリを作成します。

パラメータ	型	必須	デフォルト	説明
projectName	string	はい	—	ドキュメント化されているプロジェクトの名前
language	enum	いいえ	"EN"	言語コード (上記参照)
format	enum	いいえ	"asciidoc"	出力形式: asciidoc/adoc または markdown/md
force	boolean	いいえ	false	ワークスペースが既に存在する場合でも再初期化を強制する
targetFolder	string	いいえ	サーバーデフォルト	arc42-docs/ が作成される対象フォルダーの絶対パス

戻り値: ワークスペース ルート パス、作成されたセクション数、設定 (arc42 テンプレート参照バージョン、日時、コミット SHA を含む)。

作成される構造:

<targetFolder>/arc42-docs/
├── README.md
├── arc42-documentation.adoc (or .md)
├── config.yaml
├── sections/
│   ├── 01_introduction_and_goals.adoc (or .md)
│   ├── 02_architecture_constraints.adoc (or .md)
│   └── ... (すべての 12 セクション)
└── images/

3. arc42-status

ドキュメンテーション完成度のステータスを確認します。文字数、完成度パーセンテージ、全体的な進捗を含むセクション別の進捗を表示します。

パラメータ	型	必須	デフォルト	説明
targetFolder	string	いいえ	サーバーデフォルト	arc42-docs/ を含むフォルダーの絶対パス

戻り値: プロジェクト名、初期化状態、言語とフォーマット情報、arc42 テンプレート参照バージョン、セクション別ステータス (存在、文字数、完成度 0-100%、最終変更日時)、全体的な完成度パーセンテージ。

4. generate-template

特定のセクションの詳細なテンプレートを生成します。コンテンツを作成する前に必ずこれを使用してください — 想定される構造、サブセクション、含めるべき情報のガイダンスを提供します。

パラメータ	型	必須	デフォルト	説明
section	enum	はい	—	セクション ID (下記のセクション参照を参照)
language	enum	いいえ	"EN"	言語コード
format	enum	いいえ	"asciidoc"	出力形式: asciidoc/adoc または markdown/md

戻り値: ガイダンス付きの完全なテンプレート コンテンツ、セクション メタデータ (タイトル、説明、順序)、フォーマット詳細。

5. update-section

特定のセクションにコンテンツを書き込みます。フォーマットは既存ファイルまたは config.yaml から自動検出されます。

パラメータ	型	必須	デフォルト	説明
section	enum	はい	—	セクション ID (下記のセクション参照を参照)
content	string	はい	—	セクションに書き込むコンテンツ
mode	enum	いいえ	"replace"	"replace" は上書き、"append" は既存に追加
targetFolder	string	いいえ	サーバーデフォルト	arc42-docs/ を含むフォルダーの絶対パス

戻り値: セクション タイトル、ファイル パス、検出されたフォーマット、文字数、使用された書き込みモード。

重要: ADR (セクション 9) を追加する場合またはインクリメンタルなコンテンツを追加する場合は、既存のエントリを上書きしないように mode: "append" を使用してください。

6. get-section

メタデータを含む特定のセクションのコンテンツを読み込みます。

パラメータ	型	必須	デフォルト	説明
section	enum	はい	—	セクション ID (下記のセクション参照を参照)
targetFolder	string	いいえ	サーバーデフォルト	arc42-docs/ を含むフォルダーの絶対パス

戻り値: セクション コンテンツ、言語、フォーマット、タイトル、説明、ファイル メタデータ (パス、最終変更タイムスタンプ、文字数、バイト単位のファイル サイズ)。

---

12 個の Arc42 セクション

#	セクション ID	名前	主なコンテンツ
1	01_introduction_and_goals	イントロダクションとゴール	要件概要、品質ゴール、ステークホルダー
2	02_architecture_constraints	アーキテクチャ制約	技術的、組織的、政治的制約
3	03_context_and_scope	コンテキストとスコープ	ビジネス コンテキスト、技術コンテキスト、外部インターフェース
4	04_solution_strategy	ソリューション戦略	テクノロジー決定、トップレベルの分解、品質アプローチ
5	05_building_block_view	ビルディング ブロック ビュー	システムの静的分解 (レベル 1、2、3)
6	06_runtime_view	ランタイム ビュー	主要シナリオ、シーケンス図、プロセス フロー
7	07_deployment_view	デプロイメント ビュー	インフラストラクチャ、デプロイメント図、ノード マッピング
8	08_concepts	横断的概念	セキュリティ、永続化、ロギング、エラー処理パターン
9	09_architecture_decisions	アーキテクチャ決定	コンテキスト、決定、ステータス、結果を含む ADR
10	10_quality_requirements	品質要件	品質ツリー、品質シナリオ
11	11_technical_risks	リスクと技術的負債	既知のリスク、技術的負債アイテム
12	12_glossary	用語集	ドメイン用語と定義

---

推奨ドキュメンテーション順序

最も影響力のあるセクションから始めてください。12 個すべてのセクションを順序どおりにドキュメント化する必要はありません。

優先度	セクション	理由
1 番目	セクション 1 — イントロダクションとゴール	ここから始めてください: スコープ、品質ゴール、ステークホルダーを確立します
2 番目	セクション 3 — コンテキストとスコープ	システムの境界と外部インターフェースを早期に定義します
3 番目	セクション 4 — ソリューション戦略	主要なテクノロジーと設計決定をキャプチャします
4 番目	セクション 5 — ビルディング ブロック ビュー	システムの静的構造をドキュメント化します
5 番目	セクション 9 — アーキテクチャ決定	決定が新鮮なうちに重要な ADR を記録します
その後	セクション 2 — 制約	技術的/組織的制約をドキュメント化します
その後	セクション 6～8 — ランタイム、デプロイメント、概念	動的動作、インフラストラクチャ、横断的関心事を埋めます
最後	セクション 10～12 — 品質、リスク、用語集	ドキュメンテーションを完成させます

---

行動ガイドライン

セクションを作成する前に

1. テンプレートを最初に生成する — セクションの generate-template を呼び出して、想定される構造とサブセクションを理解します
2. 明確化の質問をする — プロジェクトの詳細を仮定しないでください。ユーザーの特定のコンテキスト、テクノロジー、決定について質問してください
3. 既存のコンテンツを確認する — get-section を呼び出して、構築する既存コンテンツがあるかどうかを確認します
4. 設定されたフォーマットを尊重する — arc42-status を呼び出してプロジェクトが AsciiDoc または Markdown のどちらを使用しているかを確認してから、そのフォーマットでコンテンツを作成します

コンテンツの品質

• WHY を、WHAT だけではなくドキュメント化する — 決定の背景にある根拠とトレードオフに焦点を当てます
• ダイアグラムを含める — コンテキスト図、ビルディング ブロック ビュー、デプロイメント ビュー、シーケンス図に Mermaid または PlantUML 構文を使用します
• 具体的である — 具体的なテクノロジー名、バージョン番号、測定可能な品質属性を使用します
• セクションを焦点を絞った状態に保つ — 各セクションは異なる目的を持っています。セクション全体で情報を重複させないようにしてください
• 適切なフォーマットを使用する — 出力形式に合わせます (AsciiDoc は = 見出し、NOTE:、TIP: などの訓告を使用します。Markdown は # 見出しを使用します)

ADR ベスト プラクティス (セクション 9)

• 新しい ADR を追加する際は常に mode: "append" を使用してください — 既存の ADR を上書きしないようにするためです
• 最初に常に get-section を呼び出してください — 既存の ADR を読み込んで次の ADR 番号を決定します
• 一貫した ADR 構造に従ってください: 番号付きタイトル、ステータス、コンテキスト、決定、結果 (ポジティブとネガティブ)

ツール レスポンスの使用

すべてのツール レスポンスには以下が含まれます:

• success — 操作が成功したかどうかを示すブール値
• message — 何が起こったかの人間が読める要約
• data — 構造化されたレスポンス データ (ツールによって異なります)
• nextSteps — 推奨される後続アクションの配列。これらを使用してユーザーに次に何をすべきかをガイドします

---

多言語サポート

11 言語がサポートされています。arc42-init 中に言語を設定します。これは config.yaml に保持され、後続のすべての操作に適用されます。

コード	言語	コード	言語
EN	英語	PT	ポルトガル語
DE	ドイツ語	RU	ロシア語
ES	スペイン語	CZ	チェコ語
FR	フランス語	UKR	ウクライナ語
IT	イタリア語	ZH	中国語
NL	オランダ語

複数フォーマット サポート

フォーマット	エイリアス	拡張子	最適な用途
AsciiDoc (デフォルト)	asciidoc、adoc	.adoc	プロフェッショナル ドキュメント — インクルード、訓告、相互参照、目次生成をサポートします
Markdown	markdown、md	.md	シンプルさ — 広くサポートされています。GitHub/GitLab レンダリング

arc42-init 中にフォーマットを設定します。update-section ツールは既存ファイルまたは config.yaml からフォーマットを自動検出します。フォーマット エイリアス (md/adoc) は、フォーマット パラメータが使用される場所であればどこでも受け入れられます。

---

例

詳細な使用例については references/examples.md を参照してください。次の内容を対象としています:

• 最初からの新規プロジェクトの開始
• 特定のセクション (例: デプロイメント ビュー) のドキュメント化
• 適切な追記モードでの Architecture Decision Records (ADR) の追加
• 横断的概念のドキュメント化
• 多言語ドキュメンテーション
• 既存のドキュメンテーションの確認と改善
• 既存のワークスペースの再初期化