적합성 규칙 팩

Rules grouped by type, with packs and a browsable catalog

규칙 팩은 일반적인 아키텍처 패턴의 모범 사례를 담아 큐레이션한 적합성 규칙 모음입니다. 규칙을 처음부터 작성하는 대신 팩을 설치하면, 명확한 원칙에 따라 실전에서 검증된 규칙 세트를 몇 초 만에 갖출 수 있습니다.

왜 규칙 팩인가?

대부분의 팀은 마이크로서비스, 클린 아키텍처, 이벤트 기반 시스템 같은 잘 알려진 패턴을 따릅니다. 각 패턴에는 자동으로 강제해야 할 제약이 따릅니다:

  • 마이크로서비스는 데이터베이스를 공유해서는 안 됩니다
  • 도메인 레이어는 인프라 코드를 import해서는 안 됩니다
  • 이벤트는 스키마 계약을 따라야 합니다

규칙 팩은 이러한 원칙을 실행 가능한 가드레일로 바꿉니다.

사용 가능한 팩

팩 규칙 수 초점
Microservices 10 서비스 경계, 독립적인 배포 가능성, 제한된 통신
Clean Architecture 9 레이어 경계, 도메인 격리, 포트/어댑터 강제
Event-Driven 8 채널 준수, 스키마 요구 사항, 데드 레터 큐
API-First 8 계약 요구 사항, 버전 관리, 인증 문서화
Security Baseline 8 게이트웨이 강제, 시크릿 관리, 외부 접근 제어

팩 설치

archyl-developer 스킬 사용

AI 코딩 에이전트에게 요청하세요:

Install the microservices conformance rules pack

에이전트가 Archyl MCP 서버를 호출하여 모든 규칙을 한 번에 생성합니다.

SDK 사용

import { ArchylClient } from "@archyl/sdk";

const client = new ArchylClient({
  apiKey: process.env.ARCHYL_API_KEY,
  organizationId: "your-org-id",
});

// Install a pack by name
await client.governance.installPack("microservices");

UI 사용

에이전트 허브 > Packs로 이동하여 원하는 팩에서 Install을 클릭합니다.

각 팩의 구성

Microservices (규칙 10개)

  • 공유 데이터베이스 금지 — 각 서비스는 자체 데이터를 소유해야 합니다. 서비스 간 조회는 API를 통해서만 이루어집니다.
  • 독립적인 배포 가능성 — 서비스 간에 컴파일 타임 의존성이 없어야 합니다. 공유 라이브러리는 버전이 관리되어야 합니다.
  • 제한된 통신 — 서비스는 직접적인 데이터베이스 접근이나 파일 공유가 아니라, 정의된 API 계약이나 이벤트 채널을 통해 통신합니다.
  • 서비스 격리 — 서비스 간 import가 없어야 합니다. 각 서비스는 자체 의존성 트리를 가집니다.

Clean Architecture (규칙 9개)

  • 도메인 레이어 순수성 — 도메인 코드에는 외부 import가 전혀 없습니다. 프레임워크, ORM, HTTP 모두 사용하지 않습니다.
  • 의존성 방향 — 의존성은 안쪽을 향합니다. 핸들러는 서비스에, 서비스는 도메인에 의존하며, 그 반대는 허용되지 않습니다.
  • 포트/어댑터 강제 — 인프라 관련 코드(DB, HTTP, 메시징)는 도메인이나 서비스 레이어가 아니라 어댑터 패키지에 위치합니다.
  • 인터페이스 경계 — 서비스는 구체적인 구현이 아니라 인터페이스(포트)를 사용합니다.

Event-Driven (규칙 8개)

  • 채널 준수 — 이벤트 생산자와 소비자는 선언된 이벤트 채널을 사용해야 합니다. 임의로 토픽을 생성해서는 안 됩니다.
  • 스키마 요구 사항 — 모든 이벤트에는 정의된 스키마가 있어야 합니다. 타입이 없는 페이로드는 허용되지 않습니다.
  • 데드 레터 큐 — 소비자는 메시지 처리 실패에 대비해 DLQ를 구성해야 합니다.
  • 토픽 명명 규칙 — 토픽은 일관된 명명 패턴(예: domain.entity.event)을 따릅니다.

API-First (규칙 8개)

  • 계약 필수 — 모든 공개 엔드포인트에는 OpenAPI, gRPC 또는 AsyncAPI 계약이 등록되어 있어야 합니다.
  • 버전 관리 — API 엔드포인트에는 버전 접두사(/v1/, /v2/)가 포함되어야 합니다.
  • 인증 문서화 — 보안 스킴이 계약에 문서화되어 있어야 합니다.
  • 문서화되지 않은 엔드포인트 금지 — 대응하는 계약 문서가 없는 핸들러 파일은 위반을 트리거합니다.

Security Baseline (규칙 8개)

  • 게이트웨이 강제 — 외부 트래픽은 API 게이트웨이나 로드 밸런서를 거쳐야 합니다. 서비스를 직접 노출해서는 안 됩니다.
  • 시크릿 관리 — 소스 코드에 시크릿, API 키, 비밀번호를 하드코딩해서는 안 됩니다. 환경 변수나 시크릿 매니저를 사용하세요.
  • 외부 접근 제어 — 외부 요청을 받는 서비스는 인증과 속도 제한을 강제해야 합니다.
  • TLS 필수 — 모든 서비스 간 통신에는 TLS를 사용해야 합니다. 서비스 간 평문 HTTP는 허용되지 않습니다.

규칙 사용자 지정

팩을 설치한 후에도 모든 규칙을 자유롭게 편집할 수 있습니다:

  • 심각도 변경 — 위험 허용 수준에 맞지 않으면 규칙을 critical에서 medium으로 낮춥니다
  • 특정 규칙 비활성화 — 팩 전체를 제거하지 않고 필요 없는 규칙만 개별적으로 끕니다
  • 설정 수정 — 프로젝트 구조에 맞게 파일 glob, 패턴, 허용 import 또는 레이어 정의를 조정합니다

에이전트 허브로 이동해 규칙의 편집 아이콘을 클릭하면 규칙을 수정할 수 있습니다.

팩 조합

팩은 누적해서 적용됩니다. 여러 팩을 설치해 서로 다른 아키텍처 관심사를 다룰 수 있습니다:

조합 사용 사례
Microservices + API-First + Security Baseline 보안 가드레일을 갖춘 API 중심 마이크로서비스 플랫폼
Clean Architecture + Security Baseline 엄격한 레이어 경계와 보안 위생을 갖춘 모놀리스
Event-Driven + Microservices 이벤트 소싱 기반 마이크로서비스 시스템
API-First + Clean Architecture 계약 중심 모놀리스 또는 모듈형 모놀리스

두 팩에 겹치는 규칙이 있으면 Archyl이 중복을 제거하므로 충돌이 발생하지 않습니다.

기여하기

규칙 팩은 오픈 소스입니다. 새 팩을 제안하거나, 기존 팩에 규칙을 추가하거나, 이슈를 보고할 수 있습니다:

다음 단계