arc42-documentation

arc42 アーキテクチャドキュメント

目的

実績ある arc42 テンプレート（https://arc42.org/）に沿って、構造化された完全なアーキテクチャドキュメントを生成します。このテンプレートには、ステークホルダーの要件から技術的な実装の詳細まで、ソフトウェアアーキテクチャのあらゆる側面を網羅する、標準化された 12 のセクションがあります。

このスキルを使用する場面

• 包括的なアーキテクチャドキュメントが必要な新規プロジェクトを開始するとき
• 構造化されたアーキテクチャの説明が不足している既存システムをドキュメント化するとき
• 技術レベルの異なるステークホルダー向けにアーキテクチャの概要を作成するとき
• 認定（例：iSAQB）に向けてアーキテクチャドキュメントを準備するとき
• 複数のプロジェクトに一貫したドキュメント標準を確立するとき

arc42 テンプレートの概要

arc42 テンプレートは、次の 12 のセクションで構成されています。

1. 導入と目標 - 要件の概要、品質目標、ステークホルダー
2. 制約 - 技術上および組織上の制限
3. コンテキストとスコープ - システムの境界、外部インターフェース
4. ソリューション戦略 - 基本的なアーキテクチャ上の決定
5. ビルディングブロックビュー - 静的な分解（コンポーネント、モジュール）
6. ランタイムビュー - 動的な動作（シナリオ、ワークフロー）
7. デプロイメントビュー - インフラストラクチャと技術環境
8. 横断的な概念 - 繰り返し使われるパターンと原則
9. アーキテクチャ上の決定 - 根拠を含む重要な ADR
10. 品質要件 - 品質ツリーとシナリオ
11. リスクと技術的負債 - 既知の問題と制限
12. 用語集 - ドメイン用語と技術用語

厳守事項

必須事項

• arc42 ドキュメントのワークフローの進捗管理に todo ツールを使用する
• ファイル操作ではターミナルコマンドよりも search/*、read/*、edit/* ツールを優先する
• docs/architecture/arc42/ ディレクトリにドキュメントを作成する
• templates/arc42-template.md に記載されたテンプレート構造を使用する
• 12 のセクションすべてを記入する（情報がまだ得られないセクションには「TBD」と記載する）
• セクション 9（アーキテクチャ上の決定）に既存の ADR への参照を含める
• 新しい arc42 ドキュメントを参照するように docs/architecture.md を更新する
• プロジェクト固有のコンテキストに合わせて内容を調整する（定型的な説明は削除する）
• 視覚的な表現（コンテキスト、ビルディングブロック、デプロイメント）には Mermaid 図を使用する
• ステークホルダー向けのセクション（1、3、10）は、技術者以外にも理解しやすい内容にする
• シェルコマンドではなくエディターツールを使用して、ターミナルでの承認を最小限に抑える
• arc42 ドキュメントを既存の ADR および機能仕様と同期した状態に保つ
• 情報が不足している、または不明確な場合は、ユーザーに確認する（一度に質問は 1 つ）
• ドキュメントに記載するすべての要件、制約、品質目標は、実際の仕様またはユーザーからの入力に基づくものとする

禁止事項

• edit/* ツールが利用できる場合に、ファイル編集にターミナルコマンドを使用する
• 複数ステップのワークフローで todo ツールの使用を省略する
• arc42 のヘルプテキストをそのまま最終ドキュメントにコピーする
• 既存の ADR に価値を加えることなく、その内容を重複させるドキュメントを作成する
• 「TBD」または「該当なし」と記載せずにセクションを省略する
• コードレベルのドキュメントの代わりに arc42 を使用する
• 些細な機能の arc42 ドキュメントを作成する（代わりに標準的な ADR を使用する）
• 要件、制約、品質目標、技術的な詳細を創作または捏造する
• ユーザーに確認できるにもかかわらず、情報が不完全なまま作業を進める

アクション

1. Todo による進捗管理を開始する

todo ツールを使用して、arc42 ワークフローの進捗を管理する todo リストを作成します。

• ドキュメントのスコープを評価する
• ディレクトリ構造を作成する
• テンプレートから arc42 ドキュメントを生成する
• 主要なセクション（1、3、4、5）を記入する
• 視覚的な図を追加する
• 既存の ADR へのリンクを追加する
• 完全性を検証する
• ドキュメントのインデックスを更新する
• ドキュメントをコミットする

2. ドキュメントの対象範囲を確認する

メンテナーに、一度に1つずつ質問します。

• システム全体を対象にしますか、それとも特定のサブシステム／機能を対象にしますか？
• セクション 9 で参照すべき既存の ADR はありますか？
• どの程度の詳細が必要ですか（概要レベルか、詳細な技術仕様か）？
• 主なステークホルダーは誰ですか（開発者、アーキテクト、経営陣）？

3. ディレクトリ構造を作成する

edit/createFile ツールを使用して（ターミナルコマンドではなく）、ディレクトリと初期ファイルを作成します。

4. arc42 ドキュメントを生成する

• read/* ツールを使用して templates/arc42-template.md を読み込みます
• edit/createFile を使用して、カスタマイズしたバージョンを docs/architecture/arc42/architecture.md に作成します
• cp や cat などのターミナルコマンドは使用せず、エディターツールを優先します

5. 主要なセクションを埋める（反復的に進める）

各セクションを完了したら、todo リストを更新します。

推奨される順序でセクションを進めます。

1. docs/spec.md と機能仕様書から関連する内容を見つけるために、search/* ツールを使用します
2. セクション 1（概要と目標）から始めます。spec.md の内容を使って最も簡単に埋められます
3. セクション 3（コンテキストとスコープ）を追加し、システムの境界を定義します
4. セクション 4（ソリューション戦略）に主要なアーキテクチャ上の決定を記述します
5. セクション 5（ビルディングブロックビュー）を完成させ、コンポーネント構造を記述します
6. 入手できる情報に基づいて、残りのセクションを埋めます

段階的な進め方： セクションに「TBD」と記して、後から埋めてもかまいません。このドキュメントは継続的に更新される成果物です。

変更には edit/editFiles を使用し、ターミナルのテキストエディターや sed/awk コマンドは使用しないでください。

6. 視覚的な図を追加する

図を追加したら、todo を更新します。

主要なセクションでは、edit/editFiles を使用して Mermaid 図を作成します。

• セクション 3： コンテキスト図（C4 レベル 1）
• セクション 5： コンポーネント図（C4 レベル 2/3）
• セクション 6： 重要なシナリオのシーケンス図
• セクション 7： デプロイ図

コミットする前に、mcp-mermaid ツールを使用して図をプレビューします。

7. 既存の ADR をリンクする

完了したら、todo を更新します。

search/codebase を使用して adr-*.md に一致するすべての ADR ファイルを探し、**セクション 9（アーキテクチャ上の決定）**で次のことを行います。

• 既存の ADR をすべて一覧にします
• 各決定の概要を簡潔に記載します
• ADR ファイルへのリンクを記載します

edit/editFiles を使用してセクションを更新します。

8. 完成度を検証する

確認して、todo リストをチェックします。

• 12 のセクションがすべてある（「TBD」と記されている場合も含む）
• 少なくともセクション 1、3、4、5 に内容が記載されている
• コンテキストとビルディングブロックの図が含まれている
• 用語集にドメイン固有の用語が含まれている
• ドキュメントに arc42 のヘルプテキストが残っていない

9. ドキュメントのインデックスを更新する

edit/editFiles を使用して、docs/architecture.md に arc42 ドキュメントへの参照を追加します。

## Comprehensive Architecture Documentation

For a complete architecture overview following the arc42 standard, see:
- [arc42 Architecture Documentation](architecture/arc42/architecture.md)

10. ドキュメントをコミットする

todo を完了済みにしてから、ターミナルは git 操作にのみ使用します。

git add docs/architecture/arc42/ docs/architecture.md
git commit -m "docs: add arc42 architecture documentation"

メンテナンスのガイドライン

arc42 ドキュメントは次のように扱います。

• 更新のタイミング： 大規模なアーキテクチャ変更があったとき、新しい品質要件が生じたとき、重大なリスクが特定されたとき
• レビュー： スプリント計画やアーキテクチャレビューのミーティングで行います
• バージョン管理： 機能／ADR に関連付けた明確なメッセージを付けて変更をコミットします
• 段階的な改善： ドキュメント全体を省略するより、不完全なセクションに「TBD」と記すほうが望ましいです

参考資料

リソース	説明
arc42.org	ダウンロードや例を掲載した arc42 の公式ウェブサイト
arc42 Docs	各セクションの詳しい説明と実践的なヒント
arc42 by Example	実際のアーキテクチャドキュメントの例
arc42 on GitHub	テンプレートのソースリポジトリ
iSAQB Curriculum	arc42 を使用する認定プログラム

成功のためのヒント

1. 小さく始める：まずはセクション1、3、4を埋めてから、内容を広げます
2. 図を使う：優れたコンテキスト図は、1000語に値します
3. 複製せず、リンクする：既存のADRを参照し、コピーしないでください
4. 対象読者に合わせる：ステークホルダーに応じて、各セクションの詳細度を調整します
5. 最新の状態に保つ：定期的なスケジュールではなく、アーキテクチャの変更時に更新します
6. バージョン管理：関連するコード変更と一緒にドキュメントをコミットします