llm-wiki/raw/official-docs/governance-archunit-official.md

---
title: ArchUnit — 공식 소개 페이지
source_type: official-doc
url: https://www.archunit.org/
archive_url:
status: raw
confidence: high
related_branches: [feature-contract-registry-governance, feature-test-taxonomy-fixture-contract]
related_projects: [ca-tmpl]
tags: [architecture-test, governance, fitness-function, archunit, ca-skeleton]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# ArchUnit — 공식 소개 페이지

> Layer: `raw/official-docs/` — ArchUnit 공식 홈페이지 발췌. registry governance와 architecture test가 **annotation/scan 기반 fitness function**으로 작동할 때의 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-contract-registry-governance]] | Group G-G 대안 평가 — "ArchUnit annotations as registry" 대안의 능력/한계 평가 근거 (markdown SSOT 채택의 비교 기준) |
| [[raw/branch-notes/feature-test-taxonomy-fixture-contract]] | ArchUnit 을 verifier (fitness function) 로 사용하는 결정 — contract test 분류 |

## 컨텍스트 / 왜 저장했는지

`feature-contract-registry-governance`의 ca-tmpl 대안 후보 중 **"ArchUnit annotations as registry"**가 있었다. 즉 registry를 markdown/YAML로 두는 대신 **@Capability("...")** 같은 annotation을 코드에 박고 ArchUnit으로 scan하는 모델이다. 그 대안의 가능성과 한계를 평가하려면 ArchUnit이 무엇을 검증할 수 있는지 원문이 필요.

## 출처 / Source

- 원본 URL: https://www.archunit.org/
- 아카이브 URL: (미수집)
- 저자 / 조직: ArchUnit 프로젝트 (TNG Technology Consulting)
- 발행 상태: 지속적으로 갱신 (최신 v1.4.2 / 2026-04 기준)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Homepage tagline] "A free, simple and extensible library for checking the architecture of your Java code using any plain Java unit test framework."

> [§Capabilities] ArchUnit can "check dependencies between packages and classes, layers and slices, check for cyclic dependencies and more."

> [§How it works] ArchUnit operates by "analyzing given Java bytecode, importing all classes into a Java code structure," enabling architectural validation within existing test infrastructures.

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| AU-OFF-C1 | ArchUnit 은 plain Java unit test framework 안에서 작동하는 free·simple·extensible library 로, **Java 코드의 architecture 를 검사**하는 목적 | [§Homepage tagline] "A free, simple and extensible library for checking the architecture of your Java code using any plain Java unit test framework." | `official-vendor-doc` | JVM 기반 코드베이스 | non-JVM 언어 (Python, Go, Node.js) 에서 동일 검사가 가능하다는 뜻은 아님 (.NET 포트는 별도) |
| AU-OFF-C2 | ArchUnit 의 검사 범위는 **package/class 간 dependency, layer/slice 정의, cyclic dependency 검출 등** | [§Capabilities] "check dependencies between packages and classes, layers and slices, check for cyclic dependencies and more." | `official-vendor-doc` | 정적 (bytecode 기반) 아키텍처 검사 | runtime 상태 (예: 실제 호출 그래프, profile별 활성 bean) 를 검증한다는 뜻은 아님 |
| AU-OFF-C3 | ArchUnit 의 작동 메커니즘은 **Java bytecode 를 분석**하여 모든 class 를 Java code structure 로 import 하는 방식 | [§How it works] "analyzing given Java bytecode, importing all classes into a Java code structure" | `official-vendor-doc` | 컴파일된 .class 파일이 존재하는 환경 | source code 만으로 (compile 없이) 검사 가능하다는 뜻은 아님 — bytecode 가 입력 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `AU-OFF-C1`: ArchUnit 의 정체성·라이선스·통합 방식 (plain Java unit test framework)
  - `AU-OFF-C2`: ArchUnit 이 검사하는 항목의 카테고리 (package/class dependency, layer/slice, cyclic)
  - `AU-OFF-C3`: bytecode 분석이 작동 메커니즘이라는 사실
- **이 자료가 증명하지 않는 것**:
  - ArchUnit annotation 을 **도메인 contract registry SSOT** 로 사용하는 것이 공식 권장 패턴이라는 명제 (Homepage 에서 그러한 use case 미언급)
  - registry 의 필수 column (default, allowed_values, compatibility_impact) 을 annotation 으로 표현 가능하다는 명제
  - operations/non-code 영역에서 ArchUnit 으로 registry 를 다룰 수 있다는 명제
  - "annotation = SSOT" 모델이 "markdown SSOT" 보다 우월하다는 명제
- **내 프로젝트(ca-tmpl) 에 적용하려면 추가 확인이 필요한 것**:
  - ArchUnit 의 `LayeredArchitecture`, `noClasses().that().resideIn(...)` 같은 구체적 DSL 시맨틱 (별도 User Guide 인용 필요 — [[raw/official-docs/archunit-annotation-as-registry-evaluation]] 참고)
  - ArchUnit annotation 접근 API (`getAnnotationOfType`, `JavaAnnotation.get(...)`) 의 정확한 시그니처 (별도 User Guide 인용 필요 — [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] 참고)

## 메모 / Notes (내 프로젝트 해석 — 미검증)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- ArchUnit annotation을 registry로 쓰는 대안의 약점:
  - registry **공통 필수 column**(default, allowed_values, compatibility_impact 등)을 annotation 하나로 다 표현 못 함.
  - external platform mapping row를 코드 없이 표현 못 함.
  - operations(non-code)에서 registry를 다루기 어렵다.
- 강점: 코드와 registry가 항상 동기화. drift 불가능.
- ca-tmpl 결정 = markdown SSOT + YAML registry + ArchUnit은 **scan/enforcement layer**로 사용. 즉 ArchUnit은 registry의 owner가 아니라 verifier.
- 본 skeleton의 contract test 결정에 ArchUnit이 다수 등장하는 이유 (예: `noClasses().that().resideIn("..contract..").should().dependOnClassesThat().resideInAPackage("..features.(?!sample).+..")`)

> **주의 (이전 버전에 있던 한국어 인용 제거됨)**: 이전 버전에 있던 "Java 바이트코드를 분석하여 정의된 규칙 위반을 자동으로 감지하므로, 아키텍처 의도를 코드 수준에서 강제하는 fitness function으로 작동한다" 문장은 **homepage 원문에서 verbatim 으로 확인되지 않음** (해석 가능한 paraphrase 였음). 본 마이그레이션에서 verbatim 원문 인용만 보존하기 위해 메모 영역으로 이동·표기. fitness function 명시 인용은 [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] 의 *Building Evolutionary Architectures* 인용을 참조.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/archunit-annotation-as-registry-evaluation]] (annotation-as-registry 대안 평가)
  - [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] (Layer 2 fitness function 정적 검사 가능 범위 평가)
- 인용하는 branch:
  - [[raw/branch-notes/feature-contract-registry-governance]]
  - [[raw/branch-notes/feature-test-taxonomy-fixture-contract]]
- canonical contract 섹션:
  - [[raw/project-notes/ca-skeleton-operational-contract#21. Contract Registry]]
  - [[raw/project-notes/ca-skeleton-operational-contract#12. Test Contract]]
- 대안 그룹: **Group G-G — Skeleton Governance** (registry/test-taxonomy 양쪽)
- 본 source의 위치: 대안 2 — ArchUnit annotations as registry (rejected; verifier로만 사용)
- 인용하는 wiki: (미작성)