Archyl で最初のアーキテクチャプロジェクトを作成し、ドキュメント化するためのステップバイステップガイド

最初のプロジェクトの作成

この包括的なガイドでは、Archyl で最初のアーキテクチャドキュメントプロジェクトを作成する方法を、初期設定からチームとの共有まで説明します。

前提条件

始める前に：

Archyl アカウント（こちらでサインアップ）
ドキュメント化したいソフトウェアシステム
オプション：コードベースリポジトリへのアクセス

ステップ 1：新しいプロジェクトの作成

ダッシュボードから

Archyl にログインします
「+ 新規プロジェクト」 ボタンをクリックします
プロジェクトの詳細を入力します：
- 名前：明確で説明的な名前（例：「EC プラットフォーム」）
- 説明：システムの概要
- タグ：整理のためのキーワード（例：「バックエンド」、「マイクロサービス」）
「プロジェクトを作成」 をクリックします

プロジェクト設定

作成後、プロジェクトを設定します：

公開設定：パブリックまたはプライベート
チームアクセス：どのチームが閲覧/編集できるか
リポジトリ：AI ディスカバリーのために接続（オプション）

ステップ 2：システムコンテキストの理解

ダイアグラムを描く前に、システムのコンテキストを理解しましょう：

ユーザーの特定

誰がシステムを使用しますか？

エンドユーザー（顧客、従業員）
管理者
外部開発者
他のシステム

外部システムの特定

システムは何と連携しますか？

決済プロセッサー
認証プロバイダー
メール/通知サービス
アナリティクスプラットフォーム
パートナー API

ステップ 3：システムコンテキストダイアグラムの作成

メインシステムの追加

空のキャンバスで、「+」 をクリックまたは右クリックします
「システムを追加」 を選択します
入力します：
- 名前：システムの名前
- 説明：システムの機能
- タイプ：内部（自社所有）

ユーザーの追加

「+」 をクリックし、「人物を追加」 を選択します
各ユーザータイプを作成します：
- 名前：「顧客」、「管理者ユーザー」など
- 説明：役割と行動

外部システムの追加

「+」 をクリックし、「外部システムを追加」 を選択します
各外部依存について：
- 名前：「Stripe」、「SendGrid」など
- 説明：提供するもの

関係の作成

ソース要素にカーソルを合わせます
接続ポイントからターゲットにドラッグします
ラベルを追加：「〜経由で注文」、「〜経由でメール送信」など
オプションで技術を追加：「REST/HTTPS」、「SMTP」

ステップ 4：コンテナへの深入り

コンテナビューを開く

メインシステムをダブルクリックして、コンテナレベルにズームインします。

コンテナの特定

技術的な構成要素は何ですか？

アプリケーション：Web アプリ、モバイルアプリ、デスクトップクライアント
サービス：API サーバー、バックグラウンドワーカー
データストア：データベース、キャッシュ、ファイルストレージ
メッセージキュー：イベントバス、キュー

コンテナの追加

各コンテナについて：

「+」 をクリックし、「コンテナを追加」 を選択します
入力します：
- 名前：「Web アプリケーション」、「API サーバー」、「PostgreSQL」
- 説明：その責任
- 技術：「React」、「Node.js」、「PostgreSQL 15」

コンテナの接続

コンテナ間の通信方法を示します：

Web アプリ → API サーバー：「API コールを実行 [REST/HTTPS]」
API サーバー → データベース：「データの読み書き [SQL]」
API サーバー → キャッシュ：「セッションデータをキャッシュ [Redis プロトコル]」

ステップ 5：コンポーネントの追加（オプション）

重要なコンテナについて、コンポーネントにズームインします：

コンテナをダブルクリックします
主要モジュールを表すコンポーネントを追加します：
- コントローラー
- サービス
- リポジトリ
- ユーティリティ

ステップ 6：AI ディスカバリーの使用（オプション）

AI にアーキテクチャのドキュメント化を支援させましょう：

リポジトリの接続

プロジェクト設定 → リポジトリに移動します
Git プロバイダーを接続します
リポジトリを選択します

ディスカバリーの実行

「ディスカバリーを開始」 をクリックします
分析が完了するまで待ちます
保留中のディスカバリーを確認します

レビューと承認

発見された各要素を確認します
必要に応じて名前/説明を編集します
正確な項目を承認します
不正確なものは拒否または修正します

ステップ 7：ドキュメントの追加

要素の説明

任意の要素をクリックして詳細な説明を追加します：

目的と責任
行われた重要な決定
重要な注意事項

アーキテクチャ決定記録

重要な決定をドキュメント化します：

ADR セクションに移動します
「新規 ADR」をクリックします
記入します：
- タイトル：「永続化に PostgreSQL を使用」
- コンテキスト：なぜこの決定が必要だったか
- 決定：何が決定されたか
- 結果：決定の影響

ドキュメントのリンク

コンテキストのために ADR とドキュメントを特定の要素にリンクします。

ステップ 8：チームとの共有

チームメンバーの招待

プロジェクト設定 → チームに移動します
「招待」をクリックします
メールアドレスを入力します
ロールを割り当てます（閲覧者、編集者、管理者）

共有リンクの作成

アカウントを持たないステークホルダーのために：

ツールバーの「共有」をクリックします
アクセスオプションを設定します
リンクをコピーして共有します

ダイアグラムのエクスポート

プレゼンテーションやドキュメント用：

「エクスポート」をクリックします
形式を選択（PNG、SVG、PDF）
ダイアグラムをダウンロードします

ベストプラクティス

シンプルに始める

システムコンテキストから始める
段階的に詳細を追加する
一度にすべてをドキュメント化しようとしない

コミュニケーションに注力する

明確で説明的な名前を使用する
説明にコンテキストを追加する
最も重要な関係を示す

次のステップ

おめでとうございます！最初のアーキテクチャドキュメントを作成しました。学習を続けましょう：

最初のプロジェクトの作成 - Archyl Docs