적합성 규칙 (가드레일)

적합성 규칙은 아키텍처 결정을 기준으로 코드 변경을 검증하는 결정론적 검사입니다. 명명 규칙, 기술 제약, 레이어 경계, 보안 패턴을 강제합니다 — AI는 전혀 관여하지 않습니다.

사이드바에서 에이전트 허브로 이동해 적합성 규칙을 관리하세요.

왜 적합성 규칙인가?

AI 코딩 에이전트(Claude Code, Cursor, Copilot)는 코드를 생성할 때 여러분의 아키텍처 결정을 알지 못합니다. 적합성 규칙은 이러한 결정을 실행 가능한 제약으로 인코딩합니다:

• 기술 레이더가 PostgreSQL을 지정하고 있다면 에이전트는 MongoDB를 사용할 수 없습니다
• 아키텍처가 서비스 레이어를 요구한다면 에이전트는 HTTP 핸들러에 데이터베이스 호출을 넣을 수 없습니다
• 팀이 구조화된 로깅을 사용한다면 에이전트는 fmt.Println을 추가할 수 없습니다

규칙은 결정론적으로 평가됩니다 — LLM도, 확률적 출력도 없습니다. 같은 코드는 항상 같은 결과를 냅니다.

규칙 유형

Archyl은 7가지 유형의 적합성 규칙을 지원합니다:

필수 패턴

코드에 반드시 있어야 하거나 있어서는 안 되는 패턴을 검사합니다.

설정:

• File glob — 패턴과 일치하는 파일만 검사합니다 (예: *.go, *.{ts,tsx})
• Forbidden patterns — 발견되면 위반을 트리거하는 정규식 패턴
• Required patterns — 누락되면 위반을 트리거하는 정규식 패턴

파일 glob은 중괄호 확장을 지원합니다. *.{js,jsx,ts,tsx}는 모든 JavaScript 및 TypeScript 파일과 일치합니다.

명명 규칙

파일, 타입, 함수의 명명 패턴을 검증합니다.

설정:

• Patterns — 범위(파일/타입/함수) + 정규식 + 설명으로 이루어진 목록

기술 제약

컨테이너에서 허용되는 언어와 라이브러리를 제한합니다.

설정:

• Allowed languages — 쉼표로 구분된 목록 (예: go, typescript)
• Forbidden imports — 한 줄에 import 하나씩

레이어 경계

클린 아키텍처, 헥사고날 아키텍처 또는 DDD의 레이어 import 규칙을 강제합니다.

설정:

• Layers — 이름, 경로 패턴(glob), 허용된 import 소스로 각 레이어를 정의합니다
• 레이어 이름을 클릭해 import 권한을 켜거나 끕니다

계약 준수

엔드포인트 핸들러 파일에 올바른 API 계약 문서가 포함되어 있는지 검증합니다.

설정:

• Contract type — HTTP (OpenAPI), gRPC, GraphQL 또는 AsyncAPI
• Endpoint file patterns — 엔드포인트 정의가 담긴 파일을 지정하는 glob
• Strict mode — 활성화하면 계약 문서가 없는 일치 파일이 모두 위반을 트리거합니다

의존성 규칙

아키텍처 경계 간에 금지된 import 경로를 강제합니다.

설정:

• Scope — 컨테이너 또는 컴포넌트 수준
• Forbidden pairs — 서로 절대 의존해서는 안 되는 소스 경로 패턴과 대상 경로 패턴 (예: **/service/** -> **/handler/**)

이벤트 채널 준수

이벤트 생산자/소비자 패턴이 명명 규칙을 따르는지 검증합니다.

설정:

• Producer patterns — 이벤트 생산 코드를 식별하는 정규식 패턴 (예: kafka\.Send)
• Consumer patterns — 이벤트 소비 코드를 식별하는 정규식 패턴
• Topic regex — 유효한 토픽 이름이 일치해야 하는 패턴 (예: ^[a-z]+\.[a-z]+\.[a-z]+$)

규칙 팩

팩은 한 번의 클릭으로 설치할 수 있는 큐레이션된 규칙 모음입니다. 규칙을 하나씩 추가하는 대신 팩을 설치하면 스택에 맞는 완전한 규칙 세트를 갖출 수 있습니다.

도구 모음에서 Packs를 클릭해 사용 가능한 팩을 둘러보세요.

아키텍처 팩

언어 팩

도메인 팩

규칙 카탈로그

Archyl은 23개 기술에 걸친 169개의 사전 구축 규칙 카탈로그를 제공합니다. 에이전트 허브에서 카탈로그 찾아보기를 클릭해 카탈로그를 둘러보세요.

지원 기술

Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, React, Vue, Angular, Next.js, Docker, Kubernetes, Terraform, SQL, Shell, YAML, GitHub Actions

카테고리

카탈로그에서 원하는 규칙을 클릭하면 추가됩니다 — 설정 양식이 자동으로 미리 채워집니다.

심각도 수준

각 규칙에는 영향도를 결정하는 심각도가 있습니다:

심각 또는 높음 수준의 위반이 하나라도 발견되면 적합성 검사는 실패합니다. 보통 및 낮음 수준의 위반은 보고되지만 검사를 실패시키지는 않습니다.

적합성 대시보드

에이전트 허브의 대시보드 탭은 모든 프로젝트의 적합성 검사 현황을 실시간으로 보여 줍니다.

표시 내용

• 통계 카드 — 전체 검사 수, 합격률(색상으로 구분), 합격 수, 실패 수
• 합격 / 실패 비율 — 비율을 한눈에 보여 주는 시각적 막대
• 최근 검사 배너 — 가장 최근 검사의 상태와 전체 보고서 링크
• 최근 검사 목록 — 상태, 트리거 유형, 프로젝트 이름, 파일 수, 위반 수, 경과 시간이 표시된 전체 검사 목록

필터링

상단의 프로젝트 드롭다운으로 검사를 프로젝트별로 필터링하거나, "모든 프로젝트"를 선택해 전체를 확인하세요.

검사 보고서

검사를 클릭하면 전체 보고서를 자세히 볼 수 있습니다:

• 심각도 분포 막대 — 심각/높음/보통/낮음 위반의 비율을 시각화
• 파일별로 묶인 위반 — 각 위반의 심각도, 제목, 설명, 제안이 담긴 접을 수 있는 섹션
• 검사 상세 — 트리거 유형, 커밋 SHA, 시작 시각, 소요 시간

각 검사 보고서에는 고유한 공유 가능한 URL이 있습니다 (예: /agent/dashboard/:checkId).

검사 삭제

다중 선택으로 여러 검사를 한 번에 삭제할 수 있습니다:

1. 개별 검사 옆의 체크박스를 클릭하거나 "모두 선택"을 사용합니다
2. 나타나는 빨간색 Delete 버튼을 클릭합니다
3. 검사와 해당 위반 기록이 영구적으로 삭제됩니다

CI/CD 통합

적합성 규칙은 모든 풀 리퀘스트에서 자동으로 실행할 수 있습니다. 설정 방법은 GitHub Actions 통합을 참고하세요.

작동 방식

1. GitHub에서 PR이 열리거나 업데이트됩니다
2. Archyl GitHub Action이 변경된 파일을 가져옵니다
3. 파일이 평가를 위해 Archyl API로 전송됩니다
4. 결과가 PR 댓글과 커밋 상태 검사로 표시됩니다
5. 심각 또는 높음 위반이 발견되면 워크플로가 실패합니다

PR 댓글

위반이 발견되면 Archyl이 PR에 상세한 댓글을 게시합니다:

• 심각도별 위반 수를 보여 주는 요약 표
• 설명과 제안이 포함된 파일별 위반 사항
• 이후 푸시할 때는 댓글을 새로 달지 않고 기존 댓글을 업데이트합니다

규칙 관리

규칙 생성

1. Packs를 클릭해 스택에 맞는 큐레이션된 규칙 세트를 설치하거나,
2. 카탈로그 찾아보기를 클릭해 169개의 사전 구축 규칙 중에서 골라 추가하거나,
3. 사용자 정의 규칙을 클릭해 새 규칙을 직접 만듭니다

규칙 활성화/비활성화

규칙 옆의 스위치를 전환해 규칙을 활성화하거나 비활성화합니다. 비활성화된 규칙은 평가되지 않습니다.

규칙 편집

규칙의 편집 아이콘(연필)을 클릭해 이름, 설명, 심각도 또는 설정을 수정합니다.

규칙 삭제

삭제 아이콘(휴지통)을 클릭한 뒤 확인합니다. 이 작업은 되돌릴 수 없습니다.

규칙 필터링

• 검색 — 규칙 이름이나 설명으로 필터링합니다
• 유형 필터 — 유형 칩을 클릭해 특정 유형의 규칙만 표시합니다

MCP 통합

AI 에이전트는 MCP 서버를 통해 적합성 규칙을 사용할 수 있습니다:

사용 가능한 MCP 도구

에이전트에서 검사 실행

run_conformance_check 도구를 사용하면 AI 에이전트가 커밋하기 전에 코드를 검증할 수 있습니다. 에이전트는 작업 중인 파일을 전송합니다:

{
  "projectId": "your-project-uuid",
  "changedFiles": [
    { "path": "internal/handler/user.go", "status": "modified" }
  ],
  "fileContents": {
    "internal/handler/user.go": "package handler\nimport..."
  }
}

응답에는 다음이 포함됩니다:

• passed — 검사 통과 여부 (심각/높음 위반이 없으면 통과)
• violations — 심각도, 파일 경로, 제목, 제안이 포함된 위반 목록
• rulesEvaluated — 평가된 규칙
• filesAnalyzed — 분석된 파일 수
• checkId — 검사 ID (대시보드에서 확인 가능)

에이전트는 이 피드백을 활용해 코드를 커밋하기 전에 위반 사항을 수정할 수 있습니다.

에이전트 컨텍스트

MCP 도구 get_agent_context는 아키텍처 브리핑의 일부로 활성화된 모든 적합성 규칙을 반환합니다. 작업을 시작하기 전에 이 도구를 호출하는 AI 에이전트는 어떤 가드레일을 지켜야 하는지 알 수 있습니다.

REST API

# Rules
GET    /api/v1/conformance/rules              # List rules
POST   /api/v1/conformance/rules              # Create rule
POST   /api/v1/conformance/rules/bulk         # Create multiple rules (used by packs)
GET    /api/v1/conformance/rules/:id          # Get rule
PUT    /api/v1/conformance/rules/:id          # Update rule
DELETE /api/v1/conformance/rules/:id          # Delete rule
POST   /api/v1/conformance/rules/:id/toggle   # Enable/disable

# Checks
POST   /api/v1/projects/:id/conformance/check # Trigger check with changed files
GET    /api/v1/conformance/checks             # List all checks (org-wide, ?projectId= filter)
GET    /api/v1/conformance/checks/:id/report  # Get check report with violations
POST   /api/v1/conformance/checks/delete      # Bulk delete checks { ids: [...] }

# Stats
GET    /api/v1/conformance/stats              # Org-wide statistics
GET    /api/v1/projects/:id/conformance/stats  # Project statistics

모든 엔드포인트는 인증이 필요합니다 (JWT, 또는 변경 작업의 경우 쓰기 범위가 있는 API 키).