AI 네이티브 팀을 위한 Architecture Intelligence

지난 6개월 동안 무언가가 변했습니다. AI 에이전트는 함수를 작성하는 수준에서 전체 서비스를 작성하는 수준으로 진화했습니다. Claude Code, Cursor, Codex — 이들은 더 이상 어시스턴트가 아닙니다. 팀원입니다. PR을 열고, 코드를 리뷰하고, 기능을 배포합니다.

하지만 밤잠을 설치게 하는 것이 있습니다: 이 에이전트들은 아키텍처가 어떻게 생겼는지 전혀 모릅니다.

에이전트는 10분 만에 완벽하게 깔끔한 Go 서비스를 작성할 수 있습니다. 하지만 3개월 전에 팀이 모든 서비스 간 통신을 Kafka를 통해 라우팅하기로 결정했다는 것은 모릅니다. 결제 서비스에 대한 직접적인 데이터베이스 접근이 금지되어 있다는 것도 모릅니다. 지난 분기에 Python이 기술 레이더에서 "보류"로 이동되었다는 것도 모릅니다.

그 결과는? 머신 스피드로 진행되는 아키텍처 드리프트입니다.

우리는 이 문제를 해결하기 위해 Archyl을 만들었습니다. 그리고 오늘, 출시 이후 가장 큰 업데이트를 배포합니다: Architecture Intelligence — Archyl을 AI 네이티브 개발의 신경 체계로 만드는 완전한 에코시스템입니다.

문제: 에이전트는 빠르게 코딩하지만, 눈을 감고 코딩합니다

인간 개발자가 팀에 합류하면, 문서를 읽고, 질문을 하고, 시스템의 멘탈 모델을 구축하는 데 며칠을 보냅니다. 규칙을 배웁니다 — 문서화된 것과 그렇지 않은 것 모두. 경계를 이해합니다.

AI 에이전트는 이 모든 것을 건너뜁니다. 태스크를 받고, 코드를 작성하고, PR을 엽니다. 리뷰에서 아키텍처 위반을 아무도 잡지 못하면, 그대로 배포됩니다. 이것이 세 팀에 걸쳐 열 개의 서비스에서 작업하는 열 개의 에이전트로 곱해지면, 신중하게 설계된 아키텍처가 몇 주 만에 무너집니다.

우리는 이런 일이 일어나는 것을 직접 목격했습니다. 1월에 완벽한 C4 모델을 가지고 있던 팀이 3월에는 드리프트 점수가 40%에 달했습니다. 신경을 쓰지 않아서가 아닙니다 — 에이전트들이 아키텍처가 존재한다는 것을 몰랐기 때문입니다.

해결책: 인프라로서의 아키텍처

아키텍처 문서는 유지보수하는 대상이 아니어야 합니다. 스스로 유지보수되어야 하고 — 모든 에이전트가 한 줄의 코드를 작성하기 전에 참조하는 대상이어야 합니다.

그것이 우리가 만든 것입니다. 오늘 배포되는 내용은 다음과 같습니다.

10개의 에이전트 스킬

기존의 archyl-developer 스킬은 에이전트에게 200개 이상의 MCP 도구에 대한 접근을 제공했습니다. 하지만 워크플로우가 없는 도구 상자였습니다. 오늘, 전체 개발 라이프사이클을 커버하는 9개의 전문 스킬을 추가합니다:

코딩하기 전에

archyl-preflight — 기능 구현 전에 실행하세요. 계획된 접근 방식을 C4 모델, 컨포먼스 룰, 기술 레이더, API 컨트랙트와 대조하여 검사합니다. 한 줄의 코드를 작성하기 전에 명확한 PASS / WARN / FAIL 판정을 받습니다.

> user service에 Redis 캐시를 추가하려고 합니다. 괜찮을까요?

Preflight 검사: WARNING
- Redis는 기술 레이더에서 승인됨 ✓
- User service가 C4 모델에 존재함 ✓
- ⚠ 문서화된 기존 캐시 컨테이너 없음 — 생성을 권장
- ⚠ "핸들러에서 직접 DB 접근 금지" 규칙이 적용됨 — 서비스 레이어를 통해 캐시에 접근하도록 보장

배포한 후에

archyl-postship — 배포 후에 실행하세요. 방금 구축한 것을 분석하고, C4 모델을 업데이트하고, 아키텍처 결정에 대한 ADR을 생성하고, 아키텍트 리뷰를 위한 Change Request를 제출합니다. 작업의 부산물로 문서가 스스로 업데이트됩니다.

리뷰 중에

archyl-review — 아키텍처 리뷰 봇입니다. PR diff를 문서화된 아키텍처와 대조하여 검사하고 구조화된 피드백을 제공합니다: 컨포먼스 위반, 경계 침범, 미승인 기술, 누락된 API 컨트랙트. ESLint와 비슷하지만, 아키텍처를 위한 것입니다.

가시성을 위해

archyl-changelog — 모든 아키텍처 변경 사항의 읽기 쉬운 타임라인을 생성합니다: 새로운 서비스, 수정된 관계, ADR 결정, 드리프트 변화. 아키텍처 리뷰 미팅에 완벽합니다.

archyl-dora — DORA 메트릭을 아키텍처 변경과 연관시킵니다. 마이크로서비스 분해가 리드 타임을 개선했나요? 드리프트 급증이 변경 실패율 증가에 선행했나요? 이제 데이터가 있습니다.

archyl-roi — 아키텍처 결정의 재정적 영향을 정량화합니다. "컨포먼스 룰에 대한 투자가 지난 분기에 재작업을 줄여 약 $23,000을 절약한 것으로 추정됩니다." 이것이 아키텍처 예산 승인을 받게 하는 종류의 데이터입니다.

예방을 위해

archyl-predict — 아키텍처 리스크가 현실화되기 전에 예측합니다. "현재 추세대로라면, 드리프트 점수가 5월까지 50%를 넘을 것입니다. PaymentService에 12개의 인바운드 의존성이 있습니다 — 분해를 고려하세요."

archyl-autofix — 드리프트가 감지되면, 구체적인 수정 사항을 제안합니다. 코드에 맞게 문서를 업데이트하거나, 아키텍처에 재정렬하기 위한 코드 변경을 제안합니다. 인간의 리뷰를 위한 Change Request를 생성합니다.

조율을 위해

archyl-orchestrate — 여러 에이전트가 동시에 다른 서비스에서 작업할 때, 이 스킬은 API 컨트랙트를 협상하고, 의존성 충돌을 해결하고, 크로스 팀 변경이 아키텍처를 손상시키지 않도록 보장합니다.

6개의 GitHub Actions

아키텍처 거버넌스는 CI에 속합니다. 모든 PR과 머지에서 자동으로 실행되는 6개의 GitHub Actions을 배포합니다:

권장 설정은 파일 하나입니다:

name: Architecture
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-checks:
    if: github.event_name == 'pull_request'
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

  main-update:
    if: github.event_name == 'push'
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

GitHub를 사용하지 않으신다면? GitLab CI와 Bitbucket Pipelines용 템플릿도 제공합니다.

컨포먼스 룰 팩

아키텍처 거버넌스를 처음부터 설정하는 것은 번거롭습니다. 그래서 몇 초 만에 설치할 수 있는 5개의 사전 빌드된 룰 팩을 만들었습니다:

에이전트 스킬로 설치하세요: "마이크로서비스 컨포먼스 룰 팩을 설치해 줘." 끝.

SDK

커스텀 통합을 구축하는 팀을 위해, 공식 SDK를 공개합니다:

npm install @archyl/sdk    # Node.js 18+, 의존성 없음
pip install archyl-sdk     # Python 3.10+

const archyl = new ArchylClient({ apiKey: 'arch_...', organizationId: 'uuid' });
const drift = await archyl.governance.computeDrift(projectId);
const predictions = await archyl.projects.getPredictions(projectId);

3개의 새로운 AI 기반 API

내부적으로, 3개의 새로운 백엔드 기능을 배포합니다:

예측 분석 (GET /projects/:id/predict) — 실제 통계 분석입니다. 드리프트 점수의 선형 회귀, DORA 메트릭 궤적, 컨포먼스 감쇠율, 그리고 fan-in/fan-out 결합 분석을 통한 복잡도 핫스팟 탐지. 감이 아니라 — 수학입니다.

아키텍처 Diff 분석 (POST /projects/:id/architecture-diff) — git diff를 보내면, 구조화된 C4 모델 델타를 돌려받습니다. 새로운 서비스, 변경된 의존성, 아키텍처 결정을 감지하는 AI 기반 분석입니다. 중요한 결정이 감지되면 ADR을 제안합니다.

ROI 계산 (GET /projects/:id/roi) — 아키텍처 투자 수익을 정량화합니다. DORA 메트릭을 전후로 분할하고, 생산성 향상(절약된 시간 × 시간당 비용), 신뢰성 향상(방지된 인시던트 × 인시던트 비용)을 계산하고, ADR을 재정적 영향 순으로 순위를 매깁니다.

세 가지 모두 MCP 도구로 제공되므로, 모든 에이전트 스킬이 직접 호출할 수 있습니다.

전체 루프

모든 것이 어떻게 맞물리는지 보여드립니다:

에이전트가 태스크를 받음
       │
       ▼
  archyl-preflight ──── 아키텍처에 대해 접근 방식을 검증
       │
       ▼
  에이전트가 코드를 작성
       │
       ▼
  archyl-review ──────── C4 모델에 대해 PR을 리뷰
       │
       ▼
  CI: conformance-check ─ 위반 사항을 차단
  CI: drift-score ──────── 정렬을 강제
       │
       ▼
  main에 머지
       │
       ▼
  CI: auto-cr ──────────── Change Request를 제출
  CI: generate-context ─── archyl.txt를 업데이트
       │
       ▼
  archyl-postship ──────── C4 모델 + ADR을 업데이트
       │
       ▼
  다음 에이전트가 archyl.txt를 읽음 ← 사이클 반복

아키텍처가 유지보수되는 것이 아닙니다. 아키텍처가 스스로 유지보수합니다.

시작하기

1. 스킬을 설치하세요:

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-preflight@archyl-com-agent-skills

2. GitHub Actions를 추가하세요: 위의 워크플로우를 .github/workflows/architecture.yml에 복사하세요.

3. 첫 번째 archyl.txt를 생성하세요: generate-context action을 실행하거나 에이전트에게 물어보세요: "이 프로젝트의 아키텍처 컨텍스트 파일을 생성해 줘."

4. 코딩을 시작하세요. 이제 에이전트가 아키텍처를 알고 있습니다.

앞으로의 계획

이것은 기반입니다. 우리는 예측과 ROI를 위한 프론트엔드 대시보드, 더 많은 코딩 에이전트와의 깊은 통합, 그리고 컨포먼스 룰 팩을 위한 커뮤니티 마켓플레이스를 작업하고 있습니다.

아키텍처 문서는 항상 팀이 하려고 했지만 끝내 하지 못한 것이었습니다. 에이전트가 코드를 작성할 때, 아키텍처는 인간이 소유해야 하는 유일한 것이 됩니다. Archyl은 그것을 혼자서 하지 않아도 되도록 보장합니다.

오늘 배포한 모든 것은 오픈 소스입니다. 피드백을 기다리겠습니다.