Agent Hub: 자율 AI 에이전트를 위한 아키텍처 가드레일

소프트웨어가 작성되는 방식에 근본적인 변화가 일어나고 있습니다.

6개월 전, 엔지니어는 새로운 서비스를 구축하는 데 이틀을 보냈습니다. ADR을 확인하고, 동료에게 어떤 데이터베이스를 사용할지 물어보고, 몇 달에 걸쳐 체득한 네이밍 컨벤션을 따르고, 아키텍처를 이해하기 때문에 아키텍처에 맞는 코드를 푸시했습니다.

오늘날, AI 에이전트는 20분이면 그 일을 해냅니다. 코드는 컴파일되고, 테스트도 통과합니다. 하지만 에이전트는 팀이 PostgreSQL로 표준화했는데 MongoDB를 사용했습니다. 구조화된 로깅 대신 fmt.Println 호출을 곳곳에 뿌렸습니다. 3번의 스프린트를 들여 구축한 service 레이어를 우회하고 HTTP handler에서 직접 데이터베이스 쿼리를 실행했습니다.

에이전트는 더 빠릅니다. 하지만 자신이 무엇을 모르는지 모릅니다.

거버넌스 없는 속도의 진짜 비용

코드 생산 속도가 사실상 무한한 시대에 접어들고 있습니다. Claude Code, Cursor, Copilot Workspace, Devin — 이러한 도구들은 몇 분 안에 전체 서비스를 만들어낼 수 있습니다. 주 단위로 배포하던 팀이 이제는 일 단위로 배포합니다. 병목은 "얼마나 빠르게 코드를 작성할 수 있는가"에서 "아키텍처 엔트로피가 얼마나 빠르게 시스템을 파괴할 수 있는가"로 이동했습니다.

다섯 개의 AI 에이전트가 동시에 같은 코드베이스에서 작업하면 어떤 일이 벌어지는지 생각해 보세요:

• 에이전트 A가 Express 패턴으로 새 REST 엔드포인트를 추가합니다. 에이전트 B가 Fiber 패턴으로 또 다른 엔드포인트를 추가합니다. 이제 같은 서비스에 두 개의 API 프레임워크가 존재합니다.
• 에이전트 C가 데이터베이스를 직접 쿼리하는 결제 모듈을 만듭니다. 에이전트 D가 repository 레이어를 거치는 주문 모듈을 만듭니다. 이제 두 가지 데이터 접근 패턴이 생겼습니다.
• 에이전트 E가 6개월 전에 기술 레이더에서 폐기된 라이브러리를 채택합니다. 완벽하게 동작합니다. 하지만 시한폭탄이기도 합니다.

이것들 중 어느 것도 버그가 아닙니다. 모두 CI를 통과합니다. 개별적으로는 모두 잘 동작합니다. 하지만 합쳐지면, 서로 충돌하는 패턴의 누더기로 코드베이스를 조용히 변모시키고, 이를 풀어내는 데 몇 달이 걸리게 됩니다.

이것이 Agent Hub를 만들어 해결하고자 하는 문제입니다.

아키텍처 가드레일: 아키텍처를 위한 Linter

적합성 규칙은 결정론적인 검사입니다 — AI가 관여하지 않습니다 — 아키텍처 결정에 대해 코드 변경을 검증합니다. 아키텍처를 위한 ESLint라고 생각하면 됩니다: 구문이 아니라 구조를 검사합니다.

7가지 규칙 유형이 수백 개의 팀에서 관찰한 거버넌스 요구사항을 포괄합니다:

Required Pattern — 가장 단순하면서도 가장 강력한 규칙입니다. 코드에 반드시 존재해야 하거나 존재해서는 안 되는 패턴을 정의합니다. Go에서 fmt.Println, TypeScript에서 console.log, 어디서든 eval()을 금지합니다. 모든 셸 스크립트에 set -euo pipefail을 요구합니다. SQL 쿼리에서 SELECT *를 금지합니다.

Naming Convention — 파일, 타입, 함수 전반에 걸쳐 네이밍 규칙을 강제합니다. Go 파일은 snake_case여야 합니다. React 컴포넌트는 PascalCase여야 합니다. Python 모듈은 PEP 8을 따라야 합니다. 에이전트가 코드를 생성할 때 자체 기본값이 아닌 팀의 컨벤션을 따릅니다.

Technology Constraint — 컨테이너별로 기술 스택을 고정합니다. 백엔드는 Go만 허용합니다. 프론트엔드는 JavaScript가 아닌 TypeScript여야 합니다. lodash 금지(네이티브 JS 사용). moment.js 금지(date-fns 사용). 에이전트가 팀이 이미 거부한 의존성을 실수로 도입하는 것을 방지합니다.

Layer Boundary — 여기서 진정한 위력을 발휘합니다. 아키텍처 레이어와 어떤 레이어가 어떤 레이어에서 import할 수 있는지 정의합니다. Domain은 adapter에서 import할 수 없습니다. Service는 domain에서만 가능합니다. Handler는 service를 거쳐야 하며, repository에 직접 접근해서는 안 됩니다. Clean Architecture, Hexagonal Architecture, DDD — 코드를 누가(또는 무엇이) 작성했는지에 관계없이 모든 변경에서 자동으로 시행됩니다.

Contract Compliance — 코드 엔드포인트가 API 계약과 일치하는지 검증합니다. Archyl에 OpenAPI 사양이 있다면, 적합성 엔진이 핸들러가 실제로 그것을 구현하는지 확인합니다. 유령 엔드포인트도, 누락된 라우트도 없습니다.

Dependency Rule — 코드의 모든 import는 C4 model에서 대응하는 관계를 가져야 합니다. Service A가 갑자기 Service B를 호출하기 시작하는데 아키텍처에 "uses" 관계가 없다면 규칙이 이를 포착합니다. 아키텍처 드리프트가 즉시 가시화됩니다.

Event Channel Compliance — 시스템이 Kafka, NATS 또는 다른 메시지 브로커를 사용하는 경우, 이 규칙은 코드의 프로듀서와 컨슈머가 아키텍처에서 선언된 이벤트 채널과 일치하는지 검증합니다. 무단 topic도, 미선언 컨슈머도 없습니다.

96개 규칙, 설정 불필요

정규식 패턴을 작성하는 것은 지루한 일입니다. 그래서 21개 기술을 포괄하는 96개의 사전 구축 규칙 카탈로그를 만들었으며, 한 번의 클릭으로 바로 사용할 수 있습니다.

카탈로그는 카테고리별로 구성되어 있습니다:

Security (11개 규칙) — 하드코딩된 비밀번호, API 키, 시크릿 금지. eval() 금지. SQL 문자열 연결 금지. TLS 검증 비활성화 금지. CORS 와일드카드 오리진 금지. 해싱에 MD5 또는 SHA1 사용 금지. 이것들은 제안이 아닙니다 — 에이전트 시대에서 이것들은 타협의 여지가 없습니다. 아무도 하지 말라고 말하지 않으면 AI 에이전트는 기꺼이 설정 파일에 데이터베이스 비밀번호를 하드코딩합니다.

Infrastructure (22개 규칙) — Dockerfile에서 :latest 태그 금지. Kubernetes 매니페스트에서 리소스 제한 필수. 특권 컨테이너 금지. hostNetwork 금지. 헬스 체크 필수. GitHub Actions 버전을 commit SHA로 고정. Terraform에서 하드코딩된 자격 증명 금지. 와일드카드 IAM 정책 금지. 에이전트가 Infrastructure-as-Code를 생성할 때, 이 규칙들은 출력이 데모 수준이 아닌 프로덕션 수준이 되도록 보장합니다.

Code Quality (10개 언어에 걸친 18개 규칙) — Go: panic() 금지, init() 금지, 전역 가변 상태 금지. TypeScript: any 타입 금지, var 선언 금지. Python: 빈 except: 금지, 가변 기본 인수 금지, import * 금지. Java: System.out.println 금지, 빈 catch 블록 금지. Rust: unwrap() 금지, unsafe 금지. 각 규칙은 AI 에이전트가 컨텍스트 없이 지속적으로 이러한 실수를 저지르기 때문에 존재합니다.

Architecture (5개 규칙) — Clean Architecture, Hexagonal Architecture, DDD 레이어드, MVC 분리, handler-service-repository 적용. 이것들은 가장 비용이 많이 드는 종류의 드리프트 — 아키텍처가 아무도 설계하지 않은 것으로 서서히 변이하는 드리프트 — 를 방지하는 구조적 가드레일입니다.

Testing (3개 규칙) — 건너뛴 테스트 커밋 금지. 테스트 스위트에 .only() 남기기 금지. 프로덕션 코드에서 TODO/FIXME 금지. AI 에이전트가 "준비됨" 대신 "동작함"에 최적화할 때 생성하는 부주의한 커밋을 방지하는 작은 규칙들입니다.

에이전트 컨텍스트: 한 번의 호출로 완전한 지식

규칙은 에이전트에게 무엇을 하면 안 되는지 알려줍니다. 컨텍스트는 무엇을 해야 하는지 알려줍니다.

get_agent_context MCP 도구는 연결된 모든 에이전트에게 단 한 번의 호출로 완전한 아키텍처 브리핑을 제공합니다:

• C4 Model — 프로젝트의 모든 시스템, 컨테이너, 컴포넌트 및 관계
• Architecture Decision Records — 근거와 결정을 포함한 활성 ADR
• Technology Stack — 조직 전체에서 사용 중인 기술
• Active Guardrails — 모든 적합성 규칙으로, 에이전트가 코드 작성 전에 경계를 파악
• API Contracts — API 표면을 정의하는 OpenAPI, gRPC, GraphQL 사양
• Event Channels — Kafka topic, NATS subject, 메시지 스키마

이 도구는 마크다운 버전도 생성합니다 — 리포지토리에 커밋할 수 있는 CLAUDE.md 파일입니다. 이를 읽는 모든 에이전트는 Archyl의 MCP 서버에 연결할 필요 없이 완벽한 아키텍처 지식을 갖추고 작업을 시작합니다.

이것이 추측하는 에이전트와 아는 에이전트의 차이입니다. 동작하는 코드와 제자리에 있는 코드의 차이입니다.

왜 지금 이것이 중요한가

AI 코딩 환경은 빠르게 움직이고 있습니다. 6개월 안에 대부분의 전문 개발에는 어떤 형태로든 AI 에이전트가 관여하게 될 것입니다. 1년 안에 멀티 에이전트 워크플로가 보편화될 것입니다 — 서로 다른 에이전트가 같은 시스템의 서로 다른 부분에서 동시에 작업합니다.

거버넌스 없이는 이것이 혼돈으로 이어집니다. 극적인 종류의 혼돈이 아닙니다 — 느리고 교활한 종류의 혼돈입니다. 모든 커밋이 개별적으로는 합리적이지만 누적 효과는 아키텍처 부패인 혼돈. 6개월 후 코드베이스를 보며 왜 세 가지 다른 로깅 라이브러리와 두 가지 ORM 패턴이 있고, 어떻게 된 건지 모든 것에 의존하는 서비스가 존재하는지 설명할 수 없는 그런 혼돈입니다.

아키텍처 가드레일은 이 역학을 근본적으로 바꿉니다:

AI 에이전트를 도입하는 팀에게: 아키텍처 결정은 더 이상 에이전트가 코드를 작성할 때 사라지는 부족 지식이 아닙니다. 자동으로 시행되는 규칙으로 인코딩됩니다. 에이전트는 시니어 엔지니어가 코드 리뷰에서 제공하는 것과 동일한 거버넌스를 받습니다 — 다만 즉시, 모든 변경에 대해, 리뷰 피로 없이.

플랫폼 팀에게: 수십 개의 서비스와 수백 개의 AI 생성 변경에 걸쳐 패턴을 표준화할 수 있으며, 각각을 수동으로 리뷰할 필요가 없습니다. 규칙을 한 번 정의하고 모든 곳에 적용합니다. 팀이 AI 에이전트로 새 서비스를 만들 때, 자동으로 플랫폼의 컨벤션을 따릅니다.

규제 산업에게: 컴플라이언스 요구사항을 적합성 규칙으로 인코딩할 수 있습니다. "모든 서비스에 헬스 체크가 있어야 합니다." "로그에 PII가 없어야 합니다." "저장 시 암호화가 필수입니다." 이것들은 문서화만 되는 것이 아니라 검증 가능해집니다. 감사 추적은 모든 AI 생성 변경이 병합되기 전에 규칙에 대해 검증되었음을 보여줍니다.

오픈 소스 메인테이너에게: PR을 제출하는 기여자(사람이든 AI든)는 아키텍처 적합성에 대한 즉각적인 피드백을 받습니다. 기여자가 몰랐던 컨벤션을 위반하는 PR을 더 이상 리뷰할 필요가 없습니다. 규칙은 아키텍처의 기대사항을 실행 가능한 제약 조건으로 문서화합니다.

에이전트 시대에 번성할 팀은 최고의 AI 에이전트를 가진 팀이 아닙니다. 가장 명확한 아키텍처 경계를 가진 팀입니다. 에이전트는 교체 가능합니다. 아키텍처는 그렇지 않습니다.

시작하기

Agent Hub는 지금 모든 Archyl 사용자에게 제공됩니다. 사이드바의 Agent 아이콘을 클릭하세요. 카탈로그를 탐색하고, 가드레일을 추가하고, AI 에이전트가 여러분이 정의한 경계 안에서 작업하도록 하세요.

여러분의 아키텍처 결정은 AI에게 선택 사항이어서는 안 됩니다. 이제 더 이상 선택 사항이 아닙니다.