选择开始方式

一个 Archyl 项目保存着您软件的 C4 模型：系统、容器、组件和代码，以及它们之间的关系。填充它的方式有四种。这些方式可以组合使用，选择其中任何一种都不会把您绑定住。

无论选择哪种方式，后续步骤都一样：连接您的编程代理，并让模型与代码保持同步。

在应用中绘制

从仪表板创建项目，然后在画布上添加系统、容器和关系。快速入门指南会一步步带您完成。

对于尚不存在的系统，或要在写代码之前勾勒上下文，绘制是合适的起点。您之后可以切换到代码：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 指南。

发现能处理 monorepo：它识别 apps/、packages/、services/ 和 libs/，并把每个服务映射为一个容器。

以代码编写

在仓库根目录的 archyl.yaml 中描述架构并推送。文件格式见架构即代码。

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

元素按名称匹配。推送会创建新内容、更新变更的内容，并且从不删除：仅存在于 Archyl 中的元素会保留，archyl dsl diff 将其列为 "only in Archyl"。

您的编程代理可以写出第一版：运行 archyl setup，然后让它按照 schema 在 archyl.yaml 中描述该仓库。评审这个文件仍然是您的事。

要让文件和模型保持同步，请提交 archyl.yaml，然后用 GitHub Action 从 CI 推送，或使用 项目设置 › 架构即代码 中的 立即同步。两者不一致时，archyl dsl diff --exit-code 会让 CI 作业失败。

从其他工具导入

在项目列表中点击 导入项目 并选择格式：Archyl YAML、Structurizr DSL、LikeC4、IcePanel JSON 或 Backstage JSON。拆分为多个 !include 文件的 Structurizr 工作区可以打包成 zip 上传。详情以及各格式在何处保存项目名称，见导入项目。

Monorepo 演练

下面是在 monorepo 上不使用 AI 发现、从头到尾走一遍代码方式：

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

1. 创建项目并关联仓库。 在 monorepo 的根目录下：

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

这会写入 .archyl.json，把仓库关联到项目。请提交它：它不包含任何密钥。

2. 建模一个系统，每个可部署单元一个容器。 应用和服务成为容器。像 packages/ui 这样的共享包通常不单独作为容器：可以把它描述为使用它的容器的组件，或者省略。

3. 用文件夹名称为每个容器命名。 这样 archyl brief、where、check、impact 和 Guard 钩子才能判断变更的文件属于哪个元素：当路径中的某个文件夹与元素同名时，该文件就属于这个元素。比较时忽略大小写、空格和标点，以及 API、Service 或 Worker 这样的结尾词，因此 Orders Service 匹配 services/orders/…，Payments API 匹配 services/payments/…。

4. 选择单个文件或多个文件。 根目录下的单个 archyl.yaml 最简单。对于大型 monorepo，可以让每个服务在代码旁有自己的文件，并从根目录 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. 推送并检查。

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 报告某个文件未匹配，请用文件夹名称重命名容器，然后再次推送。

6. 保持更新。 提交 archyl.yaml 和被 include 的文件。在发生变更时从 CI 推送，或使用 立即同步，它也会从仓库获取被 include 的文件。

然后投入使用

模型建立之后：

• 连接您的编程代理： 使用 archyl setup（Claude Code、Cursor、VS Code、Codex）或从仪表板连接。之后它们在修改代码之前会调用 plan、brief 和 harness。
• 对照模型检查变更： 在 CI 中使用 archyl check 和 archyl review。参见 CLI 指南。
• 帮助新成员和代理上手： 使用 archyl tour，它会引导走一遍最先要了解的部分，并列出要读的文件。archyl tour --markdown > ONBOARDING.md 可将其写成文档。
• 探索模型： 使用 archyl map、archyl diagram <element> 或应用中的画布。

组合使用

• 先发现，再以代码管理： 运行一次发现并批准，然后运行 archyl dsl pull，此后提交 archyl.yaml。
• 先以代码编写，再发现： 发现只提出模型中尚没有的内容，因此可以补全您写好的容器下的组件。像其他发现一样评审它。
• 在应用中绘制并从代码推送： 两者编辑的是同一个模型。推送会更新文件所描述的内容，其余部分保持不动。