AI 기반 탐색 - Archyl Docs

Archyl이 AI를 사용하여 코드베이스에서 아키텍처를 자동으로 발견하고 문서화하는 방법을 알아보세요

AI 기반 탐색

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

작동 방식

1. 리포지토리 연결

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

  1. 프로젝트 설정으로 이동합니다
  2. "리포지토리 연결"을 클릭합니다
  3. Git 제공업체를 선택합니다 (GitHub, GitLab, Bitbucket 등)
  4. Archyl이 리포지토리에 접근할 수 있도록 권한을 부여합니다

2. 탐색 시작

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

  1. 프로젝트에서 "탐색 시작"을 클릭합니다
  2. 분석할 브랜치나 경로를 선택합니다
  3. 탐색 설정을 구성합니다 (선택사항)
  4. "탐색 실행"을 클릭합니다

3. AI 분석

AI가 코드베이스를 분석하여 다음을 식별합니다:

  • 프로젝트 구조: 프레임워크, 언어, 빌드 시스템
  • 서비스: 마이크로서비스, API, 백그라운드 워커
  • 데이터 저장소: 데이터베이스, 캐시, 파일 스토리지
  • 외부 통합: 서드파티 API, SaaS 서비스
  • 컴포넌트: 모듈, 패키지, 주요 클래스
  • 관계: 컴포넌트 간 통신 방식

4. 검토 및 승인

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

  1. 각 발견된 요소를 검토합니다
  2. 이름, 설명 또는 관계를 편집합니다
  3. 정확한 발견사항을 승인합니다
  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 모델을 최신 상태로 유지합니다. 더 빠르고, 비용이 적으며, 매 푸시마다 자동으로 실행할 수 있습니다.

작동 방식

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

증분 탐색 활성화

증분 탐색을 활성화하는 두 가지 방법이 있습니다:

  • 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) 자동 (웹훅 또는 GitHub Action)
속도 분 단위 (리포지토리 크기에 따라) 초에서 분
AI 비용 높음 (모든 파일 분석) 낮음 (diff만 분석)
사용 사례 초기 설정, 대규모 리팩토링 일상적인 코드 변경

모범 사례

작게 시작하세요

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

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

정기적인 업데이트

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

  1. 주요 변경 후 탐색을 실행합니다
  2. 대기 중인 새로운 발견사항을 검토합니다
  3. 필요에 따라 기존 요소를 업데이트합니다

수동 작업과 결합

AI 탐색은 시작점입니다:

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

문제 해결

탐색이 너무 오래 걸림

  • 동시성 설정을 줄이세요
  • 대규모 디렉토리 제외 (node_modules, vendor)
  • 특정 경로에 집중하세요

부정확한 결과

  • 진행하면서 검토하고 수정하세요
  • AI는 수정사항으로부터 학습합니다
  • 코드 주석의 더 많은 맥락이 도움됩니다