AI 기반 탐색

Connect a repository from the project settings to enable AI discovery

Archyl의 AI 탐색 기능은 코드베이스를 분석하여 소프트웨어 아키텍처를 자동으로 발견하고 문서화합니다. 수동 문서 작업 시간을 절약하고 아키텍처 문서가 실제 코드와 동기화된 상태를 유지합니다.

작동 방식

1. 리포지토리 연결

먼저 Git 리포지토리를 Archyl에 연결합니다:

  1. 프로젝트 설정으로 이동합니다
  2. "저장소 연결"을 클릭합니다
  3. Git 제공업체를 선택합니다 (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea 또는 자체 호스팅 인스턴스)
  4. Archyl이 리포지토리에 접근할 수 있도록 권한을 부여합니다

2. 탐색 시작

연결 후 AI 탐색을 시작합니다:

  1. 프로젝트에서 "탐색 시작"을 클릭합니다
  2. 분석할 브랜치를 선택합니다
  3. "탐색 실행"을 클릭합니다

3. AI 분석

AI는 여러 단계에 걸쳐 코드베이스를 분석합니다:

  1. 구조 분석 — 시스템 이름, 컨테이너, 외부 의존성을 식별합니다
  2. 상세 탐색 — 소스 파일을 청크 단위로 병렬 분석하여 컴포넌트, 코드 요소, 관계를 찾습니다
  3. 관계 정제 — 컨테이너를 서로 대조하여 서비스 간 의존성을 찾습니다
  4. 병렬 후속 분석 — ADR, 문서, API 계약, 패키지 의존성을 발견합니다

발견되는 요소는 다음과 같습니다:

  • 시스템: 최상위 소프트웨어 시스템과 외부 의존성
  • 컨테이너: 서비스, API, 데이터베이스, 웹 애플리케이션, 워커
  • 컴포넌트: 모듈, 패키지, 핸들러, 리포지토리, 서비스
  • 코드 요소: 파일 경로가 포함된 클래스, 인터페이스, 함수
  • 관계: 요소 간 통신 방식 (사용, 호출, 전송, 읽기)

4. 검토 및 승인

발견사항은 검토를 위해 대기 중 상태로 배치됩니다:

  1. 각 발견된 요소를 검토합니다
  2. 이름, 설명 또는 관계를 편집합니다
  3. 정확한 발견사항을 승인합니다
  4. 부정확한 것은 거부하거나 수정합니다

새 프로젝트(기존 C4 요소가 없는 경우)에서는 빠르게 시작할 수 있도록 발견사항이 자동으로 승인됩니다.

증분 탐색

증분 탐색은 전체 리포지토리가 아닌 변경된 파일만 분석하여 C4 모델을 최신 상태로 유지합니다. 더 빠르고, 비용이 적으며, 매 푸시마다 자동으로 실행할 수 있습니다.

증분 탐색의 작동 방식

  1. 기본 브랜치에 코드가 푸시됩니다
  2. Archyl이 푸시 이벤트를 수신합니다 (웹훅 또는 GitHub Action을 통해)
  3. 푸시된 커밋에서 변경된 파일이 추출됩니다
  4. 소스 파일만 분석됩니다 (삭제된 파일은 건너뜁니다)
  5. 더 작은 파일 세트를 대상으로 AI가 실행됩니다
  6. 새 요소는 검토를 위해 대기 중인 발견사항으로 생성됩니다
  7. 기존 요소는 자동으로 중복 제거되므로 중복이 생기지 않습니다

증분 탐색 활성화

증분 탐색을 활성화하는 방법은 두 가지입니다:

옵션 A: GitHub 웹훅 (별도 구성 불필요)

  1. 프로젝트의 웹훅 구성 설정으로 이동합니다
  2. 푸시 시 탐색을 활성화합니다
  3. 웹훅 URL을 복사하여 GitHub 리포지토리 설정에 추가합니다
  4. push 이벤트를 선택합니다

이제 기본 브랜치에 푸시할 때마다 증분 탐색이 자동으로 트리거됩니다.

옵션 B: 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) 자동 (푸시 웹훅 또는 GitHub Action)
속도 분 단위 (리포지토리 크기에 따라) 초에서 분 단위
AI 비용 높음 (모든 파일 분석) 낮음 (diff만 분석)
사용 사례 초기 설정, 대규모 리팩토링 일상적인 코드 변경
중복 제거 기존 모델 전체를 대상으로 중복 제거 동일한 중복 제거 — 중복 없음

전체 탐색과 증분 탐색 함께 사용하기

권장 워크플로우:

  1. 리포지토리를 처음 연결할 때 전체 탐색을 실행합니다
  2. 모델을 최신 상태로 유지하도록 증분 탐색을 활성화합니다
  3. 대규모 리팩토링이나 마이그레이션 후에는 전체 탐색을 다시 실행합니다

증분 탐색도 전체 탐색과 마찬가지로 대기 중인 요소를 생성하므로, 변경 사항이 C4 모델에 반영되기 전에 항상 검토하게 됩니다.

지원 기술

AI 탐색은 15개 이상의 언어와 프레임워크를 지원합니다:

언어

Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, Scala

빌드 시스템 및 패키지 관리자

npm, Go modules, pip/Poetry, Maven, Gradle, Cargo, Composer, RubyGems, NuGet, CMake (find_package, FetchContent, CPM), Conan, vcpkg

프레임워크

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

인프라

Docker, Kubernetes, Terraform, Helm, Ansible, GitHub Actions, AWS CDK, Pulumi

모노레포 지원

Archyl은 모노레포 구조를 자동으로 감지합니다:

  • apps/, packages/, services/, libs/ 디렉토리
  • 서비스별로 비례하여 파일 샘플링
  • 각 서비스는 C4 모델에서 별도의 컨테이너로 매핑됩니다
  • 서비스 간 관계를 감지합니다

모범 사례

작게 시작하세요

대규모 코드베이스의 경우:

  1. 단일 서비스 또는 모듈부터 시작합니다
  2. 결과를 검토하고 개선합니다
  3. 점진적으로 다른 영역으로 확장합니다

정기적인 업데이트

문서를 최신 상태로 유지하세요:

  1. 자동 업데이트를 위해 증분 탐색을 활성화합니다
  2. 대기 중인 발견사항을 정기적으로 검토합니다
  3. 대규모 리팩토링 후에는 전체 탐색을 실행합니다

수동 작업과 결합

AI 탐색은 시작점입니다:

  1. 무거운 작업에는 AI 활용
  2. 비즈니스 맥락은 수동으로 추가 (설명, ADR)
  3. 관계와 설명 다듬기

REST API

POST   /api/v1/discovery/start                            # Start full discovery
GET    /api/v1/discovery/jobs/:jobId                       # Get job status
POST   /api/v1/projects/:id/discovery/incremental          # Trigger incremental discovery

문제 해결

탐색이 너무 오래 걸림

  • 분석할 파일 수를 줄이세요 (설정에서 최대 파일 수 조정)
  • 정기적인 업데이트에는 증분 탐색을 사용하세요
  • 특정 브랜치에 집중하세요

부정확한 결과

  • 진행하면서 검토하고 수정하세요 — 대기 시스템에서 요소마다 승인하거나 거부할 수 있습니다
  • 코드가 잘 구조화되어 있을수록 결과가 좋아집니다
  • 승인된 요소에 설명을 추가하면 이후 탐색에 활용되는 맥락이 풍부해집니다

분석된 파일 없음

  • 리포지토리가 연결되어 있고 브랜치가 존재하는지 확인하세요
  • 소스 파일이 인식되는 확장자(.go, .ts, .py, .java 등)를 사용하는지 확인하세요
  • 액세스 토큰에 리포지토리 읽기 권한이 있는지 확인하세요