시작 방법 선택

Archyl 프로젝트는 소프트웨어의 C4 모델을 담습니다. 시스템, 컨테이너, 컴포넌트, 코드와 그 사이의 관계입니다. 이를 채우는 방법은 네 가지입니다. 서로 조합할 수 있고, 어느 쪽을 택해도 묶이지 않습니다.

방법 적합한 경우 필요한 것 첫 모델까지
앱에서 그리기 탐색 중이거나 시스템이 아직 만들어지지 않았을 때 브라우저 컨텍스트 다이어그램은 몇 분
AI로 디스커버리 코드가 있고 첫 초안을 빨리 원할 때 연결된 저장소와 요금제의 AI 디스커버리 몇 분, 그다음 리뷰
코드로 작성 모델을 풀 리퀘스트에서 리뷰하고 코드와 함께 버전 관리하고 싶을 때, 또는 코드를 AI에 보내고 싶지 않을 때 archyl CLI와 텍스트 편집기 파일을 작성하는 시간만큼
가져오기 이미 Structurizr, LikeC4, IcePanel, Backstage로 모델링하고 있을 때 해당 도구의 내보내기 파일 1분 이내

무엇을 고르든 다음 단계는 같습니다. 코딩 에이전트를 연결하고, 모델을 코드와 일치시켜 유지하는 것입니다.

앱에서 그리기

대시보드에서 프로젝트를 만든 다음 캔버스에 시스템, 컨테이너, 관계를 추가합니다. 빠른 시작 가이드가 단계별로 안내합니다.

아직 존재하지 않는 시스템이나, 코드가 나오기 전에 컨텍스트를 스케치할 때는 그리기가 알맞은 시작입니다. 나중에 코드로 전환할 수 있습니다. 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. 시스템 하나에 배포 단위마다 컨테이너 하나로 모델링합니다. 앱과 서비스는 컨테이너가 됩니다. packages/ui 같은 공유 패키지는 보통 그 자체로 컨테이너가 되지 않습니다. 이를 사용하는 컨테이너의 컴포넌트로 기술하거나 생략하세요.

3. 각 컨테이너의 이름을 폴더 이름으로 짓습니다. 그래야 archyl brief, where, check, impact, Guard 훅이 변경된 파일이 어느 요소에 속하는지 알 수 있습니다. 파일 경로의 폴더 중 하나가 요소의 이름과 같으면 파일은 그 요소에 속합니다. 비교할 때는 대소문자, 공백, 문장 부호, 그리고 API, Service, Worker 같은 끝 단어를 무시하므로 Orders Service는 services/orders/…와, Payments API는 services/payments/…와 일치합니다.

4. 파일을 하나로 할지 여럿으로 할지 고릅니다. 루트의 archyl.yaml 하나가 가장 간단합니다. 큰 모노레포라면 각 서비스의 코드 옆에 파일을 두고 루트에서 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는 파일이 기술하는 것을 업데이트하고 나머지는 그대로 둡니다.