ドキュメントとADR
Archylは、アーキテクチャダイアグラムと共にリッチでリンクされたドキュメントを作成できる強力なドキュメント機能を提供します。アーキテクチャに関する知識を整理し、接続された状態に保ちます。
ドキュメントの作成
手動ドキュメント
ドキュメントを手動で作成するには:
- プロジェクトのドキュメントタブに移動
- 新しいドキュメントをクリック
- タイトルを入力し、Markdownでコンテンツを記述
- タグを追加して整理
- 保存をクリック
ドキュメントはMarkdown構文をフルサポート:
- 見出しとフォーマット
- シンタックスハイライト付きコードブロック
- テーブルとリスト
- 画像とリンク
Gitからのインポート
Gitリポジトリから既存のドキュメントをインポートできます:
- プロジェクト設定 > ドキュメントディスカバリー に移動
- リポジトリ接続を設定
- ドキュメントを発見をクリック
- 発見されたドキュメントをレビューして承認
既存のREADMEファイル、技術仕様、Wikiコンテンツのインポートに最適です。
アーキテクチャ要素へのリンク
ドキュメントはアーキテクチャにリンクすることでより強力に:
リンクの作成
- ドキュメントページを開く
- 要素にリンクをクリック
- アーキテクチャ要素を検索またはブラウズ
- リンクする要素を選択
- 完了をクリック
リンクされたドキュメントの表示
ダイアグラムで要素を表示すると、リンクされたドキュメントが詳細パネルに表示されます。ダイアグラムビューを離れることなく、即座にコンテキストが得られます。
リンクのユースケース
- APIドキュメントをサービスコンテナにリンク
- セットアップガイドをインフラコンポーネントにリンク
- 設計仕様をシステムコンテキストにリンク
- コードコメントをコード要素にリンク
アーキテクチャ決定記録（ADR）
ADRは、重要なアーキテクチャの決定をコンテキストと結果と共に記録します。
ADRとは？
アーキテクチャ決定記録は以下を記録:
| フィールド | 説明 |
|---|---|
| タイトル | 何が決定されたか |
| ステータス | 提案、承認、非推奨、または代替 |
| コンテキスト | なぜこの決定が必要だったか |
| 決定 | 何が決定されたか |
| 影響 | 決定の影響 |
ADRの作成
- プロジェクトの決定タブに移動
- 新しいADRをクリック
- ADRフィールドを入力
- 関連するアーキテクチャ要素にリンク
- 保存をクリック
ADRワークフロー
ADRはライフサイクルに従います:
- 提案: 初期ドラフト、議論中
- 承認: 決定が下され承認された
- 非推奨: もはや関連性がないが履歴として保持
- 代替: より新しい決定に置き換えられた
ADRディスカバリー
ドキュメントと同様に、ADRもリポジトリから発見できます:
- プロジェクト設定 > ADRディスカバリー に移動
- ADRへのパスを設定（例:
docs/adr/） - ADRを発見をクリック
- 発見されたレコードをレビューして承認
ベストプラクティス
ドキュメントを最新に保つ
- アーキテクチャ変更時にドキュメントを更新
- スプリントレトロスペクティブでドキュメントをレビュー
- 重要な決定にはADRを使用
すべてをリンクする
- すべてのシステムに説明ドキュメントを用意
- 影響を受けるコンポーネントにADRをリンク
- 関連するドキュメントを相互参照
タグを効果的に使用
- ドメイン別にタグ付け（認証、決済など）
- タイプ別にタグ付け（API、ガイド、仕様）
- ステータス別にタグ付け（下書き、レビュー、最終）
ADRガイドライン
- 重要な決定にはADRを作成
- 検討した代替案を含める
- トレードオフを記録
- 可能な場合は実装PRにリンク
ドキュメントディスカバリー設定
ドキュメントの発見方法を設定:
パスパターン
スキャンするパスを指定:
docs/
wiki/
README.md
*.md
除外パターン
特定のファイルをスキップ:
node_modules/
vendor/
CHANGELOG.md
次のステップ
- AIによるディスカバリー - アーキテクチャの自動発見
- 共有と埋め込み - 外部へのドキュメント共有
- エクスポート - ダイアグラム付きドキュメントのエクスポート