기술 레이더
기술 레이더는 아키텍처 전반에서 사용되는 모든 기술의 시각적 개요를 제공합니다. 기술은 자동으로 사분면으로 분류되며, C4 요소 및 관계에서의 실제 사용량에 따라 도입 수준이 결정됩니다.
핵심 개념
기술
기술은 아키텍처에서 사용되는 모든 도구, 언어, 프레임워크 또는 서비스를 나타냅니다. 각 기술에는 다음 정보가 있습니다:
| 필드 | 설명 |
|---|---|
| 이름 | 표시 이름 (예: PostgreSQL, React, Kubernetes) |
| 카테고리 | 레이더 사분면을 결정하는 분류 |
| 설명 | 사용법이나 목적에 대한 선택적 메모 |
| 아이콘 | 시각적 식별을 위한 선택적 로고 |
사분면
기술은 카테고리에 따라 네 개의 사분면으로 그룹화됩니다:
| 사분면 | 카테고리 |
|---|---|
| 언어 | 프로그래밍 언어, 런타임 |
| 프레임워크 | 프레임워크, 라이브러리 |
| 데이터 | 데이터베이스, 메시지 브로커, 오브젝트 스토리지 |
| 인프라 | 클라우드 서비스, DevOps 도구, 전송 프로토콜, 기타 |
도입 링
각 기술은 아키텍처 전반에서의 사용 범위에 따라 링에 배치됩니다:
| 링 | 기준 | 의미 |
|---|---|---|
| 핵심 | 4개 이상의 요소/관계에서 사용 | 기반 기술, 깊이 내재됨 |
| 활성 | 2-3개의 요소/관계에서 사용 | 적극 도입 중, 사용 확대 |
| 신규 | 1개의 요소/관계에서 사용 | 최근 도입, 평가 중 |
| 등록됨 | 아직 어떤 요소에도 연결되지 않음 | 카탈로그화되었지만 적극 사용되지 않음 |
거버넌스 링
도입 링은 기술이 얼마나 사용되는지를 나타냅니다. 거버넌스 링은 아키텍트가 그 기술에 대해 무엇을 결정했는지를 기록합니다. 두 기준은 서로 독립적입니다. 사용량으로는 Core이지만 결정으로는 보류일 수 있으며, 지금 걷어내고 있는 라이브러리가 바로 그런 경우입니다.
| 링 | 의미 |
|---|---|
| 채택 | 새 작업의 기본 선택 |
| 시험 | 위험을 감수할 수 있는 프로젝트에서 시도할 가치가 있음 |
| 평가 | 살펴볼 가치가 있지만 아직 프로덕션용은 아님 |
| 보류 | 새 작업에는 사용하지 않음 |
관리 뷰에서 기술을 만들거나 편집할 때 링과 짧은 근거(예: "대신 slog 사용")를 설정합니다. 링은 레이더, 테이블, 상세 패널에 배지로 표시되며 마우스를 올리면 근거가 보입니다. 보류만 필터로 걷어내는 중인 기술을 모두 볼 수 있습니다. 링이 없는 기술은 미분류로 남습니다.
레이더로 의존성 검사하기
POST /api/v1/projects/{projectId}/technologies/check는 최대 50개의 의존성 매니페스트(각 1MB)를 받아 파싱하고, 각 의존성을 이름으로 조직의 기술과 매칭합니다. 매칭은 대소문자, 구두점, 앞쪽의 npm 스코프, .js나 -go 같은 접미사를 무시하고 Go 모듈 경로의 마지막 세그먼트를 사용합니다. 따라서 github.com/sirupsen/logrus는 Logrus라는 기술과 매칭됩니다. 프로젝트 보기 권한이 필요하며 읽기 전용 API 키로 충분합니다.
{"manifests": [{"path": "go.mod", "content": "module example.com/app\n\nrequire github.com/sirupsen/logrus v1.9.3\n"}]}
응답에는 각 의존성과 매칭된 기술(없으면 null), 그리고 요약이 포함됩니다. 매칭되지 않았거나 링이 없는 의존성은 unclassified로 집계됩니다.
{
"dependencies": [
{
"name": "github.com/sirupsen/logrus",
"version": "1.9.3",
"ecosystem": "Go",
"filePath": "go.mod",
"isDev": false,
"technology": {"id": "…", "name": "Logrus", "radarRing": "hold", "radarNote": "Use slog"}
}
],
"summary": {"total": 1, "adopt": 0, "trial": 0, "assess": 0, "hold": 1, "unclassified": 0}
}
풀 리퀘스트를 막으려면 summary.hold가 0보다 클 때 CI 작업을 실패시키세요. 코딩 에이전트는 MCP 도구 check_dependencies로 같은 검사를 사용할 수 있습니다. 이 도구는 coding 프로필에 포함되며, 보류 상태인 각 의존성과 그 근거를 담은 짧은 요약을 덧붙입니다.
지원 매니페스트: go.mod, package.json, requirements.txt, pyproject.toml, Cargo.toml, pom.xml, build.gradle(.kts), Gemfile, composer.json, .csproj, packages.config, CMakeLists.txt, conanfile.txt, conanfile.py, vcpkg.json.
뷰
레이더 뷰
기본 뷰입니다. 기술은 레이더 차트에 점으로 표시되며, 사분면과 링에 따라 배치됩니다. 기술 환경의 전체 그림을 한눈에 파악할 수 있습니다.
상호작용:
- 점 위에 호버하여 기술 이름 표시 및 관련 기술 하이라이트
- 점을 클릭하여 상세 패널 열기
- 사분면 라벨 클릭으로 해당 사분면 필터링
테이블 뷰
사분면과 링별로 그룹화된 모든 기술의 구조화된 목록입니다. 각 항목에는 기술 이름, 아이콘, 상대적 도입 정도를 나타내는 사용 바가 표시됩니다.
헤더의 뷰 선택기에서 테이블 뷰로 전환합니다. 기술을 체계적으로 검토하거나 아키텍처 리뷰 미팅 시 유용합니다.
관리 뷰
기술의 생성, 편집, 삭제를 위한 관리 뷰입니다.
뷰 선택기에서 접근하거나 /technologies/management로 이동합니다.
요소에 기술 추가
기술은 C4 요소 및 관계에 연결되며, 이것이 레이더 배치를 결정합니다.
요소 패널에서
- 다이어그램에서 시스템, 컨테이너 또는 컴포넌트 선택
- 요소 상세 패널 열기
- 기술 섹션에서 기술 검색 및 선택
- 변경 사항은 즉시 저장됨
관계에서
- 두 요소 사이의 관계(엣지)를 클릭
- 관계 패널에서 기술 찾기
- 관련 기술 추가 (예: 통신에 사용되는 프로토콜이나 프레임워크)
AI 디스커버리 중
저장소에서 AI 기반 디스커버리를 실행하면, Archyl이 코드베이스에서 기술을 자동으로 감지하고 발견된 요소에 연결합니다.
기술 관리
기술 만들기
- 기술 → 관리 뷰로 이동
- 기술 추가 클릭
- 이름, 카테고리, 선택적 설명 입력
- 원하는 경우 로고 이미지 업로드
- 만들기 클릭
기술 편집
- 관리 뷰에서 목록의 기술 찾기
- 편집 버튼 (연필 아이콘) 클릭
- 이름, 카테고리, 설명 또는 로고 수정
- 변경 사항 저장 클릭
기술 삭제
- 관리 뷰에서 기술 행의 삭제 버튼 (휴지통 아이콘) 클릭
- 삭제 확인
기술을 삭제하면 연결된 모든 요소와 관계에서 제거됩니다.
상세 패널
레이더 또는 테이블 뷰에서 기술을 클릭하면 상세 패널이 열립니다. 표시 내용:
사용 통계
- 요소: 이 기술을 사용하는 C4 요소 수
- 관계: 참조하는 관계 수
- 도입 수준: 가장 많이 사용되는 기술 대비 상대적 퍼센트 바
연관 기술
선택한 기술과 함께 자주 나타나는 기술입니다. 스택 내 자연스러운 조합을 보여줍니다 — 예를 들어 React와 TypeScript가 함께 자주 나타나는 경우 등입니다.
관련 요소
이 기술을 사용하는 모든 시스템, 컨테이너 또는 컴포넌트의 목록입니다. 요소를 클릭하면 다이어그램에서 직접 해당 위치로 이동합니다.
기술 검색
레이더 페이지에서
헤더 바의 검색 필드를 사용하여 이름 또는 카테고리로 기술을 필터링합니다. 사분면 및 링 필터와 결합하여 결과를 더 좁힐 수 있습니다.
명령 팔레트에서
Cmd+K (또는 Ctrl+K)를 눌러 명령 팔레트를 엽니다. 기술 이름을 입력하면 기술 배지와 함께 일치하는 기술이 나타납니다. 선택하면 검색이 미리 입력된 기술 페이지로 이동합니다.
필터링
사분면 필터
사분면 드롭다운을 클릭하여 특정 사분면(언어, 프레임워크, 데이터 또는 인프라)의 기술만 표시합니다.
링 필터
링 필(핵심, 활성, 신규, 등록됨)을 클릭하여 도입 수준으로 필터링합니다. 헤더의 링 분포 바도 클릭 가능한 필터로 작동합니다.
복합 필터
모든 필터가 함께 작동합니다. 예를 들어, "프레임워크" 사분면 + "핵심" 링으로 필터링하여 가장 중요한 프레임워크 종속성을 확인할 수 있습니다.
활성 필터는 필터 바 아래에 제거 가능한 칩으로 나타납니다. 모두 지우기를 클릭하여 초기화합니다.
모범 사례
카탈로그를 최신 상태로 유지
- 도입 시 기술 추가
- 폐기된 기술 제거
- 도구의 역할이 변경되면 카테고리 업데이트
일관되게 기술 연결
- 적절한 C4 수준에서 기술 적용 — 언어와 프레임워크는 컨테이너/컴포넌트에, 인프라는 시스템에
- 관계에 사용되는 프로토콜이나 전송 방식 태그 (예: gRPC, REST, AMQP)
- 구체적으로 — "SQL Database"보다 "PostgreSQL" 사용
거버넌스에 레이더 활용
- 아키텍처 리뷰 미팅에서 레이더 검토
- 신규 링의 기술은 팀 평가 후보
- 사용되지 않는 등록됨 링의 기술은 제거 후보
- 건전한 레이더는 대부분의 기술이 핵심 또는 활성에 위치
연관 기술 활용
- "연관" 데이터를 사용하여 기술 클러스터링 이해
- 불일치를 나타낼 수 있는 예상치 못한 조합 식별
- 같은 목적의 유사 기술이 있을 때 표준화 기회 발견
다음 단계
- AI 기반 디스커버리 — 코드에서 자동으로 기술 감지
- 아키텍처 인사이트 — 아키텍처에 대한 추천 받기
- 요소 및 스타일링 — C4 요소에 대해 알아보기