Archylがコードベースからアーキテクチャを自動的に発見・ドキュメント化するAI機能について

AIによるディスカバリー

ArchylのAIディスカバリー機能は、コードベースを分析してソフトウェアアーキテクチャを自動的に発見・ドキュメント化します。手動でのドキュメント作成にかかる時間を大幅に節約し、アーキテクチャドキュメントが実際のコードと同期した状態を維持できます。

仕組み

1. リポジトリの接続

まず、GitリポジトリをArchylに接続します:

プロジェクト設定に移動
「リポジトリを接続」をクリック
Gitプロバイダーを選択（GitHub、GitLab、Bitbucketなど）
Archylにリポジトリへのアクセスを許可

2. ディスカバリーの開始

接続後、AIディスカバリーを開始:

プロジェクトで「ディスカバリーを開始」をクリック
分析するブランチまたはパスを選択
ディスカバリー設定を構成（オプション）
「ディスカバリーを実行」をクリック

3. AI分析

AIがコードベースを分析して以下を特定:

プロジェクト構造: フレームワーク、言語、ビルドシステム
サービス: マイクロサービス、API、バックグラウンドワーカー
データストア: データベース、キャッシュ、ファイルストレージ
外部連携: サードパーティAPI、SaaSサービス
コンポーネント: モジュール、パッケージ、主要クラス
リレーションシップ: コンポーネント間の通信方法

4. レビューと承認

ディスカバリーは「保留中」状態でレビューに配置されます:

発見された各要素をレビュー
名前、説明、リレーションシップを編集
正確なディスカバリーを承認
不正確なものを拒否または修正

対応技術

AIディスカバリーは以下で最適に動作します:

言語

JavaScript/TypeScript
Python
Go
Java
C#
Ruby
PHP
Rust

フレームワーク

React、Next.js、Vue、Angular
Express、Fastify、NestJS
Django、Flask、FastAPI
Spring Boot
ASP.NET Core
Ruby on Rails

インフラストラクチャ

Docker/Kubernetes
Terraform
AWS CDK
クラウド設定ファイル

インクリメンタルディスカバリー

インクリメンタルディスカバリーは、リポジトリ全体ではなく変更されたファイルのみを分析して C4 モデルを最新に保ちます。より高速で、コストが低く、プッシュごとに自動的に実行できます。

動作の仕組み

デフォルトブランチにコードがプッシュされる
Archyl がプッシュイベントを受信（Webhook または GitHub Action 経由）
コミットから変更ファイルが抽出される
ソースファイルのみが分析される（削除ファイルはスキップ）
AI がより小さなファイルセットで実行される
新しい要素が保留中のディスカバリーとして作成される
既存の要素は自動的に重複排除される

インクリメンタルディスカバリーの有効化

インクリメンタルディスカバリーを有効にする方法は2つあります：

GitHub Webhook — プロジェクトの Webhook 設定で Discovery on Push を有効化
GitHub Action (CI/CD) — ワークフローに Archyl Incremental Discovery Action を追加。詳細は GitHub Actions 統合を参照。

name: Architecture Sync
on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

フルディスカバリー vs インクリメンタルディスカバリー

	フルディスカバリー	インクリメンタルディスカバリー
スコープ	リポジトリ全体	変更ファイルのみ
トリガー	手動（UI/API）	自動（Webhook または GitHub Action）
速度	分単位（リポジトリサイズによる）	秒〜分
AI コスト	高い（全ファイルを分析）	低い（diff のみを分析）
ユースケース	初期セットアップ、大規模リファクタリング	日常のコード変更

ベストプラクティス

小さく始める

大規模なコードベースの場合:

単一のサービスまたはモジュールから開始
結果をレビューし改善
他の領域に段階的に拡張

定期的な更新

ドキュメントを最新に保つ:

大きな変更後にディスカバリーを実行
保留中の新しいディスカバリーをレビュー
必要に応じて既存の要素を更新

手動との組み合わせ

AIディスカバリーは出発点:

重い作業にはAIを使用
ビジネスコンテキストは手動で追加
リレーションシップと説明を改善

トラブルシューティング

ディスカバリーに時間がかかる

並行処理の設定を下げる
大きなディレクトリ（node_modules、vendorなど）を除外
特定のパスに集中

不正確な結果

随時レビューして修正
AIは修正から学習
コードコメントにより多くのコンテキストがあると改善

AIによるディスカバリー - Archyl Docs