적합성 규칙 (Guardrails)
적합성 규칙은 아키텍처 결정에 대해 코드 변경을 검증하는 결정론적 검사입니다. 명명 규칙, 기술 제약, 레이어 경계 및 보안 패턴을 강제합니다 — AI는 전혀 관여하지 않습니다.
사이드바에서 Agent Hub로 이동하여 적합성 규칙을 관리하세요.
왜 적합성 규칙인가?
AI 코딩 에이전트(Claude Code, Cursor, Copilot)가 코드를 생성할 때, 아키텍처 결정을 알지 못합니다. 적합성 규칙은 이러한 결정을 실행 가능한 제약으로 인코딩합니다:
- 기술 레이더가 PostgreSQL을 지정하면 에이전트는 MongoDB를 사용할 수 없습니다
- 아키텍처가 서비스 레이어를 요구하면 에이전트는 HTTP handler에 데이터베이스 호출을 넣을 수 없습니다
- 팀이 구조화된 로깅을 사용하면 에이전트는
fmt.Println을 추가할 수 없습니다
규칙은 결정론적으로 평가됩니다 — LLM 없음, 확률적 출력 없음. 동일한 코드는 항상 동일한 결과를 생성합니다.
규칙 유형
Archyl은 7가지 적합성 규칙 유형을 지원합니다:
필수 패턴
코드에 반드시 존재해야 하거나 존재하면 안 되는 패턴을 검사합니다.
| 사용 사례 | 예시 |
|---|---|
| 디버그 로깅 금지 | fmt.Println, console.log, print() 금지 |
| 보안 위험 금지 | eval(), innerHTML, 하드코딩된 비밀번호 금지 |
| 오류 처리 요구 | 셸 스크립트에서 set -euo pipefail 요구 |
| 표준 강제 | SQL 쿼리에서 SELECT * 금지 |
설정:
- File glob — 패턴과 일치하는 파일만 검사 (예:
*.go,*.ts) - 금지 패턴 — 발견 시 위반을 트리거하는 정규식 패턴
- 필수 패턴 — 누락 시 위반을 트리거하는 정규식 패턴
명명 규칙
파일, 타입, 함수의 명명 패턴을 검증합니다.
| 범위 | 예시 |
|---|---|
| 파일 | Go 파일은 snake_case.go여야 함 |
| 타입 | 내보낸 타입은 PascalCase여야 함 |
| 함수 | 함수는 동사로 시작해야 함 (Get, Create, Delete) |
설정:
- 패턴 — 범위(파일/타입/함수) + 정규식 + 설명의 목록
기술 제약
컨테이너에서 허용되는 언어와 라이브러리를 제한합니다.
| 사용 사례 | 예시 |
|---|---|
| 언어 잠금 | 백엔드는 Go만 사용 |
| 의존성 금지 | lodash 금지 (네이티브 JS 사용) |
| 마이그레이션 강제 | moment.js 금지 (date-fns 사용) |
설정:
- 허용 언어 — 쉼표로 구분된 목록 (예:
go, typescript) - 금지 import — 줄당 하나의 import
레이어 경계
Clean Architecture, 헥사고날 아키텍처 또는 DDD 레이어 import 규칙을 강제합니다.
| 레이어 | import 가능 대상 |
|---|---|
| Domain | 없음 (순수 비즈니스 로직) |
| Service | Domain만 |
| Adapter | Domain, Service |
| Infrastructure | Domain만 |
설정:
- 레이어 — 각 레이어에 이름, 경로 패턴(glob), 허용된 import 소스를 정의
- 레이어 이름을 클릭하여 import 권한을 전환
계약 준수
코드 엔드포인트가 Archyl에 저장된 API 계약과 일치하는지 검증합니다.
설정:
- 계약 유형 — HTTP (OpenAPI), gRPC, GraphQL 또는 AsyncAPI
- 엔드포인트 파일 패턴 — 엔드포인트 정의를 포함하는 파일의 glob
- 엄격 모드 — 활성화 시, 계약에 없는 모든 엔드포인트가 위반을 트리거
의존성 규칙
컴포넌트 간 의존성이 C4 관계 모델과 일치하는지 확인합니다.
설정:
- 범위 — 컨테이너 또는 컴포넌트 수준
- 관계 존재 요구 — 모든 코드 import에 해당하는 C4 관계가 있어야 함
- 금지 쌍 — 서로 의존해서는 안 되는 특정 요소 쌍
이벤트 채널 준수
코드의 이벤트 생산자/소비자가 선언된 EventChannel과 일치하는지 검증합니다.
설정:
- 생산자 패턴 — 이벤트 생산 코드를 식별하는 정규식 패턴
- 소비자 패턴 — 이벤트 소비 코드를 식별하는 정규식 패턴
- Topic 정규식 — 코드에서 topic 이름을 추출하는 패턴
규칙 팩
팩은 한 번의 클릭으로 설치할 수 있는 큐레이션된 규칙 모음입니다. 규칙을 하나씩 추가하는 대신 팩을 설치하면 스택에 맞는 완전한 규칙 세트를 얻을 수 있습니다.
도구 모음에서 Packs를 클릭하여 사용 가능한 팩을 탐색하세요.
아키텍처 팩
| 팩 | 규칙 수 | 강제 내용 |
|---|---|---|
| Clean Architecture | 5 | domain/service/adapter/infra 레이어 경계, 모듈 격리 |
| Hexagonal Architecture | 4 | Ports & Adapters 패턴, 코어 격리 |
| Domain-Driven Design | 3 | DDD 레이어, CQRS 커맨드/쿼리 분리 |
언어 팩
| 팩 | 규칙 수 | 커버 내용 |
|---|---|---|
| Go Backend | 26 | 에러 래핑, goroutine 안전성, 컨텍스트 전파, 명명, panic 금지, init() 금지 |
| React Frontend | 23 | TypeScript 엄격성, 컴포넌트 패턴, 데이터 페칭, DOM 조작 금지 |
| Next.js Full-Stack | 20 | React 규칙 + SSR 안전성, window 가드, localStorage 훅 |
| Python Backend | 16 | 예외 처리, async 패턴, 타입 힌트, 전역 상태 금지 |
| Java Backend | 11 | Spring DI 패턴, 예외 처리, System.exit 금지 |
| Rust Backend | 8 | unwrap/unsafe 금지, 올바른 에러 타입, todo!() 금지 |
| Kotlin / Android | 5 | null 안전성, 불변성, println 금지 |
| Vue Frontend | 10 | v-html 금지, TypeScript 엄격성, innerHTML 금지 |
| .NET / C# Backend | 5 | async 패턴, 예외 처리, ILogger |
| Swift / iOS | 3 | Optional 안전성, 강제 언래핑 금지 |
도메인 팩
| 팩 | 규칙 수 | 커버 내용 |
|---|---|---|
| Security Essentials | 17 | 하드코딩된 시크릿, 인젝션, 취약한 암호화, TLS, CORS |
| DevOps & Infrastructure | 24 | Docker, Kubernetes, Terraform, GitHub Actions, 셸 스크립트 |
| API Best Practices | 9 | 상태 코드, SQL 안전성, 계약 문서, 하드코딩된 URL 금지 |
| Testing & Reliability | 5 | 건너뛴 테스트 금지, .only() 금지, sleep 금지, TODO 금지 |
| Event-Driven Architecture | 3 | Kafka/RabbitMQ 토픽 명명, 하드코딩된 토픽 금지 |
규칙 카탈로그
Archyl은 24개 기술에 걸쳐 170+개의 사전 구축 규칙 카탈로그를 제공합니다. Agent Hub에서 Catalog를 클릭하여 카탈로그를 탐색하세요.
지원 기술
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
카테고리
| 카테고리 | 예시 |
|---|---|
| Architecture & Design | Clean Architecture, Hexagonal, DDD, MVC, handler-service-repository |
| 보안 | 하드코딩된 시크릿 금지, eval() 금지, SQL 인젝션 금지, TLS 비활성화 금지, CORS 와일드카드 금지 |
| 코드 품질 | 디버그 로깅 금지, 빈 catch 블록 금지, bare except 금지, any 타입 금지, unwrap() 금지 |
| Infrastructure & DevOps | Docker 버전 고정, K8s 리소스 제한, 특권 컨테이너 금지, Terraform 태그 |
| 명명 규칙 | 언어별 snake_case, PascalCase, camelCase |
| 테스트 및 신뢰성 | 건너뛴 테스트 금지, .only() 금지, TODO/FIXME 금지 |
| 성능 | 동기 sleep 금지, N+1 쿼리 금지, 루프 내 await 금지 |
| API 및 데이터 | 원시 SQL 금지, 올바른 HTTP 상태 코드, 요청 본문 검증 |
카탈로그에서 규칙을 클릭하면 추가됩니다 — 설정 양식이 자동으로 미리 채워집니다.
심각도 수준
각 규칙에는 영향을 결정하는 심각도가 있습니다:
| 심각도 | 의미 | 예시 |
|---|---|---|
| Critical | 머지 전 반드시 수정 | 하드코딩된 시크릿 금지, eval() 금지, 레이어 경계 위반 |
| High | 머지 전 수정 권장 | 디버그 로깅 금지, Docker 버전 고정, Go에서 panic 금지 |
| Medium | 편한 시점에 수정 | 명명 규칙, any 타입 금지, JS에서 var 금지 |
| Low | 정보성 | TODO/FIXME 금지, React에서 인라인 스타일 금지 |
규칙 관리
규칙 생성
- Packs를 클릭하여 스택에 맞는 큐레이션된 규칙 세트를 설치하거나,
- Catalog를 클릭하여 170+개의 사전 구축 규칙에서 선택하여 추가하거나,
- Custom을 클릭하여 새 규칙을 수동으로 생성
규칙 활성화/비활성화
규칙 옆의 스위치를 전환하여 활성화 또는 비활성화합니다. 비활성화된 규칙은 평가되지 않습니다.
규칙 편집
규칙의 편집 아이콘(연필)을 클릭하여 이름, 설명, 심각도 또는 설정을 수정합니다.
규칙 삭제
삭제 아이콘(휴지통)을 클릭한 후 확인합니다. 이 작업은 되돌릴 수 없습니다.
규칙 필터링
- 검색 — 규칙 이름 또는 설명으로 필터링
- 유형 필터 — 유형 필을 클릭하여 특정 유형의 규칙만 표시
CI/CD 통합
적합성 규칙은 모든 풀 리퀘스트에서 자동으로 실행할 수 있습니다. 설정 방법은 GitHub Actions 통합을 참조하세요.
작동 방식
- GitHub에서 PR이 열리거나 업데이트됨
- Archyl GitHub Action이 변경된 파일을 가져옴
- 파일이 평가를 위해 Archyl API로 전송됨
- 결과가 PR 댓글 및 커밋 상태로 표시됨
- Critical 또는 High 위반이 발견되면 워크플로우가 실패함
PR 댓글
위반이 발견되면 Archyl이 PR에 상세한 댓글을 게시합니다:
- 심각도별 위반 수를 포함하는 요약 테이블
- 파일별 위반 사항(설명 및 제안 포함)
- 댓글은 후속 푸시 시 업데이트됩니다(중복 생성되지 않음)
MCP 통합
적합성 규칙은 MCP 서버를 통해 AI 에이전트가 접근할 수 있습니다:
사용 가능한 MCP 도구
| 도구 | 설명 |
|---|---|
list_conformance_rules |
선택적 프로젝트 필터로 모든 규칙 나열 |
create_conformance_rule |
새 규칙 생성 |
update_conformance_rule |
규칙 설정, 심각도 또는 활성 상태 업데이트 |
delete_conformance_rule |
규칙 삭제 |
get_agent_context |
활성 guardrails를 포함한 전체 아키텍처 컨텍스트 가져오기 |
에이전트 컨텍스트
MCP 도구 get_agent_context는 아키텍처 브리핑의 일부로 모든 활성 적합성 규칙을 반환합니다. 작업 시작 전에 이 도구를 호출하는 AI 에이전트는 어떤 guardrails를 준수해야 하는지 알게 됩니다.
컨텍스트에는 다음도 포함됩니다:
- C4 model (시스템, 컨테이너, 컴포넌트, 관계)
- 근거가 포함된 활성 ADR
- 기술 스택
- API 계약
- 이벤트 채널
REST API
적합성 규칙은 REST API를 통해서도 사용할 수 있습니다:
GET /api/v1/conformance/rules # 규칙 나열
POST /api/v1/conformance/rules # 규칙 생성
POST /api/v1/conformance/rules/bulk # 여러 규칙 생성 (팩에서 사용)
GET /api/v1/conformance/rules/:id # 규칙 조회
PUT /api/v1/conformance/rules/:id # 규칙 업데이트
DELETE /api/v1/conformance/rules/:id # 규칙 삭제
POST /api/v1/conformance/rules/:id/toggle # 활성화/비활성화
POST /api/v1/projects/:id/conformance/check # 변경된 파일로 검사 트리거
GET /api/v1/projects/:id/conformance/checks # 검사 이력 나열
GET /api/v1/conformance/checks/:id/report # 검사 보고서 조회
GET /api/v1/projects/:id/conformance/stats # 프로젝트 통계 조회
모든 엔드포인트는 인증이 필요합니다 (JWT 또는 변경 작업을 위한 쓰기 범위의 API 키).