Claude Code, Codex 및 기타 코딩 에이전트에 Archyl의 200개 이상의 MCP 도구에 대한 전체 액세스를 제공하는 플러그인을 오픈소스로 공개했습니다. 시스템 생성, ADR 작성, 드리프트 확인, 준수 규칙 적용까지 터미널에서 자연어 대화만으로 모두 가능합니다.

코딩 에이전트 플러그인: 터미널을 떠나지 않고 아키텍처를 관리하세요

지난달, 우리 팀의 한 개발자가 도저히 가능할 것 같지 않은 일을 하는 걸 지켜봤습니다.

그는 Claude Code에서 모놀리식 서비스를 세 개의 작은 서비스로 분리하는 리팩토링 작업에 한창 빠져있었습니다. 작업 중간에 그는 이렇게 입력했습니다: "Archyl의 ECommerce 시스템 아래에 OrderService, InventoryService, NotificationService 세 개의 새 컨테이너를 만들어줘. OrderService와 나머지 두 서비스 사이에 'calls' 관계를 추가해줘."

10초 후, Archyl의 C4 model에 세 개의 새 컨테이너가 관계가 올바르게 연결된 상태로 아키텍처의 정확한 위치에 생성되었습니다. 그는 탭을 전환하지 않았습니다. 브라우저를 열지도 않았습니다. 그냥 계속 코딩했을 뿐입니다.

그때 저는 이 플러그인을 출시할 준비가 됐다는 걸 깨달았습니다.

컨텍스트 스위칭 문제

아키텍처 문서에는 근본적인 UX 문제가 있습니다: 코드와 다른 곳에 존재한다는 것입니다.

IDE에서 작업 중입니다. 모듈을 재구조화하고, 세 개의 서비스 이름을 바꾸고, 데이터베이스를 읽기/쓰기 복제본으로 분리했습니다. 코드 작업은 끝났습니다. 이제 아키텍처를 업데이트해야 합니다. 이는 브라우저에서 Archyl을 열고, 올바른 프로젝트를 찾고, 올바른 다이어그램으로 이동하고, 컨테이너를 업데이트하고, 관계를 추가하고, 변경 이유를 설명하는 ADR을 작성해야 한다는 뜻입니다.

5분이면 됩니다. 하지만 이 5분에는 숨겨진 비용이 있습니다: 컨텍스트 스위칭입니다. 뇌가 코드를 떠나 시각적 다이어그래밍 모드로 전환하고, 방금 무엇을 했는지 기억하고, 그것을 아키텍처 개념으로 변환한 다음 다시 코딩으로 돌아가야 합니다. 대부분의 개발자는 그냥... 안 합니다. 나중에 문서를 업데이트하겠다고 스스로에게 말하죠. 나중은 결코 오지 않습니다.

이것이 아키텍처 드리프트가 존재하는 이유입니다. 팀이 문서화에 관심이 없어서가 아니라, 도구가 잘못된 장소에 잘못된 시간에 있기 때문입니다.

대화 속의 아키텍처

Archyl Developer Plugin은 여러분의 전체 아키텍처를 코딩 에이전트의 컨텍스트 안에 넣어줍니다. Claude Code용 플러그인이며 (Codex 및 기타 에이전트와도 호환) 에이전트에게 Archyl의 200개 이상의 MCP 도구를 모두 사용하는 방법을 가르쳐줍니다.

실제로 어떤 의미일까요? 다음과 같은 것들이 가능합니다:

리팩토링 중에 에이전트에게 아키텍처 업데이트를 지시할 수 있습니다:

I just split the PaymentService into PaymentProcessor and PaymentGateway.
Update the architecture — remove the old container, create the two new ones,
and move all existing relationships to the appropriate new container.

코드 리뷰 중에 아키텍처 컨텍스트를 물어볼 수 있습니다:

Get the full C4 model and tell me which components depend on the UserRepository.
Are there any conformance rules I should know about before changing the data layer?

작업 계획 중에 문서가 여전히 정확한지 확인할 수 있습니다:

What's the current drift score? Show me which elements have drifted
and what the AI thinks is out of date.

설계 회의 후에 터미널을 떠나지 않고 결정사항을 기록할 수 있습니다:

Create an ADR: we decided to migrate from REST to gRPC for all internal
service communication. Context: latency requirements from the mobile team.
Link it to the ApiGateway and all backend service containers.

에이전트가 MCP 호출을 처리하고, 프로젝트 ID를 관리하며, 작업을 연쇄적으로 실행합니다. 여러분은 원하는 것을 자연어로 설명하기만 하면 됩니다.

플러그인이 다루는 범위

이 플러그인은 에이전트에게 7개 도메인에 걸친 구조화된 지식을 제공합니다:

C4 모델링 — 시스템, 컨테이너, 컴포넌트, 코드 요소 및 관계를 생성하고 관리합니다. 에이전트는 C4 계층 구조를 이해하고 적절한 명명 규칙(시스템과 컨테이너는 PascalCase, 코드 요소는 정확한 심볼 이름)을 적용합니다.

문서화 — ADR을 작성하고, 프로젝트 문서를 생성하고, 사용자 플로우를 정의하고, AI가 생성한 인사이트를 검토합니다. ADR은 영향을 받는 C4 요소에 연결되므로 아키텍처 결정이 아키텍처와 연결된 상태를 유지합니다.

거버넌스 — 준수 규칙을 생성하고, 컴플라이언스 검사를 실행하고, 아키텍처 드리프트를 모니터링합니다. 에이전트는 AI 코딩 세션이 시작되기도 전에 가드레일을 설정할 수 있습니다.

운영 — 여러 환경에 걸친 릴리스를 추적하고, API 계약(OpenAPI, gRPC, GraphQL)을 문서화하고, 이벤트 채널(Kafka, NATS, SQS)을 매핑하고, 기술 레이더를 관리합니다.

협업 — 코멘트를 추가하고, 변경 요청(아키텍처를 위한 PR과 같은)을 생성하고, 화이트보드를 관리합니다. 아키텍처 논의가 코드 논의가 이루어지는 곳에서 함께 이루어집니다.

히스토리 — 스냅샷을 찍고, 아키텍처 버전을 시간 여행하며, 변경 사항을 비교합니다. 누군가 "마이그레이션 전에 아키텍처가 어떤 모습이었나요?"라고 물으면, 에이전트가 답할 수 있습니다.

통합 — 아키텍처 변경 알림을 위한 웹훅을 구성하고, 마켓플레이스 위젯을 관리하고, 조직 내 모든 프로젝트의 글로벌 아키텍처를 조회합니다.

세 단계로 설정하기

설정은 간단합니다:

1. 마켓플레이스를 추가하고 플러그인을 설치합니다:

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

2. 프로젝트의 .mcp.json에 MCP 서버를 추가합니다:

{
    "mcpServers": {
        "archyl": {
            "type": "http",
            "url": "https://api.archyl.com/mcp",
            "headers": {
                "X-API-Key": "arch_your_api_key_here"
            }
        }
    }
}

3. 에이전트를 재시작하고 아키텍처와 대화를 시작하세요.

그게 전부입니다. 플러그인이 자동으로 로드되며 에이전트는 모든 도구의 사용법을 알고 있습니다. 설정 파일도, 커스텀 프롬프트도, 수동 연결도 필요 없습니다.

오픈소스인 이유

이 플러그인은 github.com/archyl-com/agent-skills에서 완전한 오픈소스로 제공됩니다. 여기에는 몇 가지 이유가 있습니다.

첫째, 투명성입니다. 플러그인이 AI 에이전트에게 아키텍처와 상호작용하는 방법을 가르칠 때, 그것이 주는 모든 지시를 읽을 수 있어야 합니다. 스킬 정의, 레퍼런스 파일, 워크플로우 예시 모두 마크다운으로 공개되어 있습니다.

둘째, 기여입니다. Archyl에는 200개 이상의 MCP 도구가 있으며, 최고의 워크플로우는 실제 사용에서 나옵니다. 팀이 효과적인 패턴을 발견하면, 예를 들어 메이저 릴리스 전에 아키텍처를 감사하는 워크플로우 같은 것을, 다시 기여할 수 있습니다. 커뮤니티가 사용함으로써 플러그인이 더 좋아집니다.

셋째, 이식성입니다. 스킬 콘텐츠는 Claude Code에 종속되지 않습니다. 플러그인 포맷을 지원하는 모든 에이전트와 함께 작동합니다. .claude-plugin과 .codex-plugin 매니페스트가 모두 포함되어 있습니다. 다음 달에 플러그인을 지원하는 새로운 코딩 에이전트가 등장하면, 스킬 콘텐츠가 바로 이전됩니다.

무엇이 바뀌는가

변화는 미묘하지만 의미가 큽니다.

플러그인 이전에는 아키텍처 문서화가 별도의 활동이었습니다. 코드를 작성한 다음 문서화했습니다. 두 개의 워크플로우, 두 개의 도구, 두 가지 사고 방식. 문서화는 항상 한 발짝 떨어져 있었기 때문에 항상 한 발짝 뒤처져 있었습니다.

플러그인을 사용하면 아키텍처 문서화가 코딩 대화의 일부가 됩니다. "문서를 업데이트하는" 것이 아니라, 무엇이 바뀌었는지 언급하면 에이전트가 처리합니다. 아키텍처가 동기화 상태를 유지하는 것은 누군가가 업데이트를 기억했기 때문이 아니라, 업데이트 자체가 아무런 수고 없이 이루어지기 때문입니다.

이것은 에이전트 워크플로우에서 특히 강력합니다. AI 에이전트가 코드베이스를 변경할 때, 동시에 아키텍처도 업데이트할 수 있습니다. 코드를 리팩토링하는 동일한 세션에서 C4 model도 업데이트하고, ADR도 기록하고, 준수 검사도 실행합니다. 아키텍처 거버넌스가 개발 흐름의 자연스러운 일부가 되며, 더 이상 사후 작업이 아닙니다.

시작하기

플러그인을 설치하고, MCP 서버를 연결한 다음, 에이전트에게 아키텍처를 설명해달라고 요청해보세요. 그런 다음 변경을 요청해보세요. 터미널 대화에서 C4 model을 처음 업데이트하는 순간, 왜 지금까지 다른 방식으로 했는지 의아해질 것입니다.

플러그인은 지금 바로 사용할 수 있습니다. 전체 문서는 가이드에 있으며, 소스 코드는 GitHub에 있습니다.

여러분의 아키텍처가 다른 탭에 살 필요가 없습니다. 이제 그럴 필요가 없어졌습니다.

코딩 에이전트 플러그인: 터미널을 떠나지 않고 아키텍처를 관리하세요 - Archyl Blog