코딩 에이전트 스킬

Archyl은 전체 아키텍처를 코딩 에이전트(Claude Code, Codex, Cursor 또는 호환 가능한 도구)로 가져오는 코딩 에이전트 스킬 11종을 제공합니다. 에디터와 Archyl 대시보드를 번갈아 오갈 필요 없이, 에이전트가 코딩 전에 변경 사항을 검증하고, 배포된 내용을 문서화하고, C4 모델을 기준으로 풀 리퀘스트를 리뷰하고, 아키텍처 드리프트를 예측합니다. 이 모든 작업이 터미널에서 이루어집니다.

스킬은 오픈 소스이며 github.com/archyl-com/agent-skills에서 확인할 수 있습니다.

AI 네이티브 아키텍처 워크플로우

11종의 스킬은 함께 동작하며 끊김 없는 아키텍처 루프를 이룹니다:

preflight → code → review → CI (GitHub Actions) → postship → generate context
    ↑                                                              |
    └──────────────────────────────────────────────────────────────┘

사전 요구 사항

• API 접근 권한이 있는 Archyl 계정
• API 키 (Archyl 대시보드의 프로필 > API 키에서 발급)
• Claude Code, Codex, Cursor 또는 호환 가능한 코딩 에이전트

설치

1단계: 마켓플레이스 추가

Claude Code에서 다음 명령어를 실행하세요:

/plugin marketplace add archyl-com/agent-skills

그런 다음 자동 업데이트를 설정하세요:

1. /plugin 실행
2. Marketplaces 선택
3. archyl-marketplace 선택
4. Enable auto-update 선택

2단계: 플러그인 설치

/plugin install archyl-developer@archyl-marketplace

archyl-developer 플러그인 하나로 스킬 11종과 Guard 훅이 모두 설치됩니다. 설치 후 코딩 에이전트를 재시작하세요.

3단계: MCP 서버 구성

프로젝트의 .mcp.json에 Archyl MCP 서버를 추가하세요:

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

arch_your_api_key_here를 Archyl 대시보드에서 발급받은 실제 API 키로 교체하세요.

기타 코딩 에이전트

스킬 파일은 플러그인 형식을 지원하는 모든 에이전트와 호환됩니다. Cursor, Codex 또는 기타 도구에서는 agent-skills 리포지토리의 파일을 직접 사용할 수도 있습니다.

빠른 설정

가장 빠르게 시작하는 방법은 설정 스크립트입니다. 에이전트에 필요한 모든 구성 파일을 생성해 줍니다.

설정 스크립트

프로젝트 루트에서 실행하세요:

npx archyl-setup

다음 세 파일이 생성됩니다:

템플릿: CLAUDE.md

생성된 CLAUDE.md에는 다음과 같은 지시 사항이 들어 있습니다:

# Architecture

This project is documented in Archyl (project ID: `proj_xxx`).

## Before coding
Run `/archyl-preflight` to validate your approach against the architecture.

## After shipping
Run `/archyl-postship` to update the C4 model and create ADRs.

## Architecture rules
Always run `/archyl-review` before requesting a code review.

팀의 워크플로우에 맞게 이 템플릿을 수정할 수 있습니다.

핵심 스킬

archyl-developer

기반이 되는 스킬입니다. 다음 영역에 걸친 Archyl의 200개 이상의 MCP 도구에 대한 구조화된 지식을 에이전트에 제공합니다:

프롬프트 예시:

Create a new system called PaymentPlatform with containers for
the API server, a PostgreSQL database, and a React frontend.

Create an ADR titled "Migrate from REST to gRPC for internal services".
Set it as proposed, explain the context around latency requirements,
and link it to the ApiGateway and PaymentService containers.

Show me the technology radar. Add Temporal as an adopted workflow
orchestration technology and tag it on the OrderProcessing container.

archyl-preflight

코딩을 시작하기 전에 실행하여 계획한 접근 방식을 기존 아키텍처에 비추어 검증합니다. Preflight는 C4 모델, 적합성 규칙, 최근 ADR을 기준으로 계획을 확인해 위반 사항을 조기에 잡아냅니다.

프롬프트 예시:

/archyl-preflight I'm planning to add a new Redis cache between the
API server and the database to reduce read latency.

/archyl-preflight We want to split the UserService into separate
authentication and profile services.

코드를 한 줄도 작성하기 전에 의존성 위반, 이름 충돌, 기존 ADR과 모순되는 접근 방식 같은 문제를 알려 줍니다.

archyl-postship

배포 후에 실행하여 아키텍처 문서를 자동으로 갱신합니다. 코드베이스에서 무엇이 바뀌었는지 분석한 뒤 다음을 수행합니다:

• C4 모델 갱신 (새 컨테이너, 컴포넌트, 관계)
• 중요한 결정에 대한 ADR 생성
• 필요한 경우 팀 검토를 위한 변경 요청 생성

프롬프트 예시:

/archyl-postship We just shipped the Redis caching layer.
Update the architecture to reflect the new cache container
and its relationships.

/archyl-postship Document the authentication service split
we shipped this sprint.

archyl-harness

거버넌스 아래에서 코딩하기 위한 작업 세션 프로토콜로, Archyl Harness를 뒷받침하는 스킬입니다. 에이전트에게 전체 루프를 가르칩니다: 시작 전 plan_work, 집중된 컨텍스트와 어드바이저리 리스를 얻는 start_work_session, 프로젝트 지식 그래프를 위한 remember/recall, 그리고 아키텍처 변경 요청을 열 수 있는 결과와 함께 호출하는 finish_work_session입니다.

Work under the harness: plan, declare a session, respect the
guardrails, and finish with an honest summary.

리뷰 및 거버넌스 스킬

archyl-review

구조화된 아키텍처 리뷰 봇입니다. C4 모델, 적합성 규칙, ADR을 기준으로 diff를 분석하여 아키텍처를 고려한 코드 리뷰 코멘트를 제공합니다.

프롬프트 예시:

/archyl-review Review the current branch against the architecture.
Flag any conformance violations or undocumented dependencies.

/archyl-review Check if PR #42 introduces any new cross-system
dependencies that aren't in the C4 model.

archyl-changelog

ADR, 릴리스, 적합성 검사, 드리프트 이벤트, 모델 갱신을 포함한 변경 사항의 타임라인, 즉 아키텍처 변경 로그를 생성합니다.

프롬프트 예시:

/archyl-changelog Show the architecture timeline for the last month.

/archyl-changelog What changed in the PaymentPlatform system
since the v2.0 release?

archyl-autofix

코드와 아키텍처 문서 사이에 드리프트가 감지되면, autofix가 둘을 다시 일치시키기 위한 구체적인 수정안을 코드 또는 모델 쪽에 제안합니다.

프롬프트 예시:

/archyl-autofix We have drift on the PaymentService container.
Propose fixes to resolve it.

/archyl-autofix Show all current drift issues and suggest
the fastest path to zero drift.

인텔리전스 스킬

archyl-dora

아키텍처 변경을 DORA 딜리버리 성과 메트릭과 연관 지어 분석합니다. 아키텍처 결정이 배포 빈도, 리드 타임, 변경 실패율, 평균 복구 시간에 어떤 영향을 주는지 확인할 수 있습니다.

프롬프트 예시:

/archyl-dora Show DORA metrics for the last quarter.
Did the microservice split improve deployment frequency?

/archyl-dora Correlate recent architecture changes
with our change failure rate trend.

archyl-roi

아키텍처 결정이 가져오는 재무적 영향을 계산합니다. 아키텍처 개선으로 절약된 시간, 예방된 장애, 개발자 생산성 변화를 추정합니다.

프롬프트 예시:

/archyl-roi What's the estimated ROI of our migration
from monolith to microservices?

/archyl-roi Calculate the cost of our current architectural
drift vs the cost of fixing it.

archyl-predict

앞으로 발생할 아키텍처 문제를 미리 예측합니다. 과거 추세를 바탕으로 드리프트, DORA 지표 악화, 복잡도 핫스팟을 예측합니다.

프롬프트 예시:

/archyl-predict Which components are most likely to drift
in the next 30 days?

/archyl-predict Based on current trends, will our deployment
frequency regress this quarter? Which services are at risk?

오케스트레이션

archyl-orchestrate

같은 코드베이스에서 작업하는 여러 에이전트를 조율합니다. 서비스 간 API 계약 협의와 의존성 충돌 해결을 처리하고, 에이전트들이 서로 충돌하는 아키텍처 변경을 하지 않도록 합니다.

프롬프트 예시:

/archyl-orchestrate Two agents are modifying services that share
an API contract. Coordinate the changes to avoid conflicts.

/archyl-orchestrate Agent A is adding a new field to the
UserService API. Check if Agent B's PaymentService integration
will break.

이 스킬은 에이전트마다 서로 다른 서비스를 맡고 있어, 서로의 작업을 방해하지 않고 공유 계약을 협의해야 하는 멀티 에이전트 환경에서 특히 유용합니다.

적합성 규칙 팩

Archyl은 마이크로서비스, 이벤트 기반, 레이어드 등 일반적인 아키텍처 패턴을 위한 적합성 규칙 팩을 미리 만들어 제공합니다. 이 규칙 팩은 위의 모든 스킬과 함께 동작하여 아키텍처를 자동으로 강제합니다.

사용 가능한 규칙 팩과 사용자 정의 규칙을 만드는 방법은 적합성 규칙 가이드를 참조하세요.

SDK

코딩 에이전트 외의 사용자 정의 도구에 Archyl을 통합하려면 TypeScript, Python, Go용 SDK를 사용할 수 있습니다.

SDK 세부 정보와 API 레퍼런스는 MCP 서버 문서를 참조하세요.

작동 방식

각 스킬은 특정 Archyl MCP 도구에 대한 구조화된 지식(매개변수, 예상 값, 모범 사례 포함)을 코딩 에이전트에 제공합니다. 에이전트에 아키텍처 작업을 요청하면 다음과 같이 동작합니다:

1. 스킬의 지식을 바탕으로 호출할 MCP 도구를 식별합니다
2. 올바른 매개변수(프로젝트 ID, 요소 유형, 관계 유형)를 구성합니다
3. 복잡한 워크플로우를 위해 여러 호출을 연결합니다
4. 생성, 수정 또는 지적된 내용의 요약을 반환합니다

에이전트는 항상 list_projects를 먼저 호출하여 사용 가능한 프로젝트를 탐색하고 후속 작업에 필요한 projectId를 가져옵니다.

C4 모델 참조

스킬은 C4 모델의 4가지 레벨을 모두 이해합니다:

관계 유형

요소를 연결할 때 에이전트는 적절한 관계 유형을 사용합니다:

기여하기

스킬은 오픈 소스입니다. 다음과 같은 방법으로 기여할 수 있습니다:

• 도구 이름, 매개변수 또는 설명 수정
• 새로운 Archyl 기능에 대한 커버리지 추가
• 워크플로우 예제 개선
• 추가 사용 사례를 위한 새 스킬 파일 작성

자세한 내용은 기여 가이드를 참조하세요.