始め方を選ぶ

Archyl のプロジェクトは、ソフトウェアの C4 モデルを保持します。システム、コンテナ、コンポーネント、コード、そしてそれらの間のリレーションシップです。モデルを埋める方法は 4 つあります。組み合わせることができ、どの方法を選んでも縛られることはありません。

どれを選んでも、次のステップは同じです。コーディングエージェントを接続し、モデルをコードと同期させ続けます。

アプリで描く

ダッシュボードからプロジェクトを作成し、キャンバスにシステム、コンテナ、リレーションシップを追加します。手順はクイックスタートで順を追って説明しています。

まだ存在しないシステムや、コードを書く前にコンテキストをスケッチしたい場合は、描くことから始めるのが適切です。後からコードに切り替えることもできます。archyl dsl pull は描いた内容を archyl.yaml に書き出します。

AI でディスカバリーする

AI ディスカバリーは接続されたリポジトリを読み取り、システム、コンテナ、コンポーネント、リレーションシップ、テクノロジーを提案します。承認するまで、何もモデルには入りません。

アプリから: プロジェクト設定 › Git 統合 でリポジトリを接続し（Git 統合を参照）、ディスカバリーを開始して、見つかったものをレビューします。

ターミナルから、リポジトリのルートで:

archyl login
archyl init --new

init --new はプロジェクトを作成し、git の remote からリポジトリを接続し、進捗を表示しながらディスカバリーを実行し、レビューを開き、結果を描画し、コーディングエージェントの接続を提案します。便利なフラグ: --name、--team、--branch、セルフホストの remote 用の --provider（github_enterprise、gitlab_private、gitea）、すべてのデフォルトを受け入れる --yes。CLI ガイドを参照してください。

ディスカバリーはモノレポに対応しています。apps/、packages/、services/、libs/ を認識し、各サービスをコンテナにマッピングします。

コードとして書く

リポジトリのルートにある archyl.yaml にアーキテクチャを記述し、push します。ファイル形式はコードとしてのアーキテクチャにあります。

archyl login
archyl init --new --no-discover   # create the project and link this repository, no AI
$EDITOR archyl.yaml               # describe the architecture
archyl dsl diff                   # what a push would create or change
archyl dsl push                   # import it
archyl diagram                    # look at the result

最小限のファイル:

version: "1.0"
systems:
  - name: Shop
    containers:
      - name: Storefront
        type: web_app
        technologies: [React]
      - name: Orders API
        type: api
        technologies: [Go]
      - name: Orders DB
        type: database
        technologies: [PostgreSQL]
  - name: Stripe
    external: true
relationships:
  - from: Storefront
    to: Orders API
    label: Places orders
    type: calls
  - from: Orders API
    to: Orders DB
    type: reads_from
  - from: Orders API
    to: Stripe
    label: Charges cards
    type: calls

要素は名前で照合されます。push は新しいものを作成し、変更されたものを更新し、削除は行いません。Archyl にしかない要素はそのまま残り、archyl dsl diff では「only in Archyl」と表示されます。

最初のバージョンはコーディングエージェントに書かせることもできます。archyl setup を実行し、スキーマに沿って archyl.yaml にリポジトリを記述するよう依頼してください。レビューするのは引き続きあなたです。

ファイルとモデルを同期させ続けるには、archyl.yaml をコミットし、GitHub Action を使って CI から push するか、プロジェクト設定 › コードとしてのアーキテクチャ の 今すぐ同期 を使います。両者に差分があると、archyl dsl diff --exit-code は CI ジョブを失敗させます。

別のツールからインポートする

プロジェクト一覧で プロジェクトをインポート をクリックし、形式を選びます: Archyl YAML、Structurizr DSL、LikeC4、IcePanel JSON、Backstage JSON。!include ファイルに分割された Structurizr のワークスペースは zip でアップロードできます。詳細と、各形式がプロジェクト名をどこに保持するかは、プロジェクトのインポートにあります。

モノレポのウォークスルー

モノレポについて、AI ディスカバリーを使わずにコードの方法を最初から最後までたどります:

shop/
├── apps/
│   ├── storefront/
│   └── admin/
├── services/
│   ├── orders/
│   └── payments/
└── packages/
    └── ui/

1. プロジェクトを作成し、リポジトリを紐づけます。 モノレポのルートで:

archyl init --new --no-discover --name "Shop" --team platform

これにより .archyl.json が書き込まれ、リポジトリがプロジェクトに紐づきます。このファイルはコミットしてください。秘密情報は含まれません。

2. デプロイ単位ごとに 1 つのコンテナを持つ 1 つのシステムとしてモデリングします。 アプリとサービスはコンテナになります。packages/ui のような共有パッケージは、通常それ自体をコンテナにはしません。それを使うコンテナのコンポーネントとして記述するか、省きます。

3. 各コンテナにフォルダーと同じ名前を付けます。 こうすることで、archyl brief、where、check、impact、Guard フックは、変更されたファイルがどの要素に属するかを判別できます。ファイルは、そのパス内のフォルダーのいずれかが要素の名前を持つとき、その要素に属します。比較では大文字と小文字、スペース、句読点、および API、Service、Worker のような末尾の語を無視するため、Orders Service は services/orders/… に、Payments API は services/payments/… に一致します。

4. ファイルを 1 つにするか複数にするかを選びます。 ルートに archyl.yaml を 1 つ置くのが最も簡単です。大きなモノレポでは、各サービスのコードの隣にそれぞれのファイルを置き、ルートから include します。こうすると各チームが自分の部分を編集できます:

# archyl.yaml
version: "1.0"
include:
  - apps/storefront/archyl.yaml
  - services/orders/archyl.yaml
  - services/payments/archyl.yaml
systems:
  - name: Shop
    description: The online shop
  - name: Stripe
    external: true

# services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Shop
    type: api
    technologies: [Go]
relationships:
  - from: Payments API
    to: Stripe
    label: Charges cards
    type: calls

include のパスは宣言したファイルからの相対パスで、リレーションシップはどのファイルの要素でも指定できます。ルールは Include にあります。

5. push して確認します。

archyl dsl diff
archyl dsl push
archyl where services/payments/internal/charge.go   # should name Payments API
archyl diagram "Payments API"                       # the container and its neighbours

where がファイルを未一致と報告した場合は、コンテナの名前をフォルダーに合わせて変更し、もう一度 push します。

6. 最新の状態に保ちます。 archyl.yaml と include されたファイルをコミットします。変更時に CI から push するか、今すぐ同期 を使います。今すぐ同期 は include されたファイルもリポジトリから取得します。

モデルを活用する

モデルができたら:

• コーディングエージェントを接続する: archyl setup（Claude Code、Cursor、VS Code、Codex）またはダッシュボードから接続します。エージェントはコードを変更する前に plan、brief、ハーネスを呼び出すようになります。
• 変更をモデルと照合する: CI で archyl check と archyl review を実行します。CLI ガイドを参照してください。
• 人とエージェントをオンボーディングする: archyl tour は、最初に知っておくべき部分を、読むべきファイルとともに案内します。archyl tour --markdown > ONBOARDING.md で書き出せます。
• モデルを探索する: archyl map、archyl diagram <element>、またはアプリのキャンバスを使います。

方法を組み合わせる

• ディスカバリーしてからコードで管理する: ディスカバリーを実行して承認し、archyl dsl pull を実行して、以降は archyl.yaml をコミットします。
• コードで書いてからディスカバリーする: ディスカバリーはモデルにまだないものだけを提案するため、書いたコンテナの下のコンポーネントを埋めることができます。他のディスカバリーと同様にレビューしてください。
• アプリで描き、コードから push する: どちらも同じモデルを編集します。push はファイルが記述する内容を更新し、それ以外には手を触れません。