llm-wiki/raw/official-docs/archunit-user-guide.md

---
title: ArchUnit User Guide — 공식 사용자 가이드 (Index)
source_type: official-doc
url: https://www.archunit.org/userguide/html/000_Index.html
archive_url:
status: raw
confidence: high
tags: [architecture, archunit, architecture-tests, java, junit, ca-skeleton-operational-contract, dependency-rule-enforcement]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-repository-access-permission-contract, feature-architecture-enforcement-rules]
created: 2026-05-27
last_reviewed: 2026-05-27
---

# ArchUnit User Guide — 공식 사용자 가이드 (Index)

> Layer: `raw/official-docs/` — ArchUnit 프로젝트의 공식 User Guide (HTML index) 의 verbatim 발췌. ArchUnit 의 정체성·기본 API·layer 강제·cycle 검사·JUnit 통합의 1차 출처.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-repository-access-permission-contract]] | D8 (Repository 위치/접근 권한을 컴파일 후 테스트 단계에서 강제할 도구로 ArchUnit 채택) 의 1차 근거 |
| [[raw/branch-notes/feature-architecture-enforcement-rules]] | layered architecture rule / package dependency rule / cycle check 를 ArchUnit DSL 로 표현 가능하다는 1차 근거 |

## 컨텍스트

ca-tmpl 의 Clean Architecture / Hexagonal 의존성 규칙 (도메인 → 인프라 금지, application → adapter 금지 등) 을 코드 리뷰가 아닌 자동화 테스트로 강제하려면 도구 선택이 필요. ArchUnit 이 Java 환경에서 사실상 표준이며, 본 raw 는 그 채택 결정의 1차 근거를 보관.

## 출처 / Source

- 원본 URL: https://www.archunit.org/userguide/html/000_Index.html
- 아카이브 URL:
- 저자 / 조직: ArchUnit 프로젝트 (TNG Technology Consulting GmbH 발족, OSS 커뮤니티 유지)
- 발행일: rolling (User Guide 페이지에 ArchUnit 1.4.2 표기 — 2026-05-27 확인 시점)
- 마지막 확인일: 2026-05-27

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

> [§1. Introduction] "ArchUnit is a free, simple and extensible library for checking the architecture of your Java code."

> [§3.1. Importing Classes] "JavaClasses classes = new ClassFileImporter().importPackages(\"com.mycompany.myapp\");"

> [§3.2. Asserting Constraints] "The returned object of type ArchRule can now be evaluated against a set of imported classes: myRule.check(importedClasses);"

> [§4.1. Package Dependency Checks] "noClasses().that().resideInAPackage(\"..source..\").should().dependOnClassesThat().resideInAPackage(\"..foo..\")"

> [§4.6. Layer Checks] "layeredArchitecture().layer(\"Service\").mayOnlyBeAccessedByLayers(\"Controller\")"

> [§3.3. Using JUnit 4 or JUnit 5] "The JUnit test support will automatically import (or reuse) the specified classes and evaluate any rule annotated with @ArchTest."

> [§4.7. Cycle Checks] "slices().matching(\"com.myapp.(*)..\").should().beFreeOfCycles()"

> [§7.2. Composing Member Rules] "Besides methods(), ArchRuleDefinition offers methods, fields, codeUnits, constructors."

## Claims Extracted / 추출된 주장

| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| ARCHUNIT-UG-C1 | ArchUnit 은 Java 코드의 아키텍처를 검사하는 **free, simple, extensible** 라이브러리 | [§1. Introduction] "ArchUnit is a free, simple and extensible library for checking the architecture of your Java code." | `official-vendor-doc` | Java/Kotlin (JVM bytecode) 프로젝트 | Java 외 언어 (Python, Go) 에서 동등 도구가 무엇인지는 본 인용에 없음 |
| ARCHUNIT-UG-C2 | 클래스 import 의 표준 진입점은 `ClassFileImporter().importPackages(<base-package>)` | [§3.1] "JavaClasses classes = new ClassFileImporter().importPackages(\"com.mycompany.myapp\");" | `official-vendor-doc` | ArchUnit 테스트의 초기 부트스트랩 | 단일 root package 만 지원한다는 의미는 아님 — `importPackages(...)` 는 varargs 로 다중 패키지 가능 |
| ARCHUNIT-UG-C3 | 규칙은 `ArchRule` 타입 객체로 표현되며, `myRule.check(importedClasses)` 로 평가 | [§3.2] "The returned object of type ArchRule can now be evaluated against a set of imported classes: myRule.check(importedClasses);" | `official-vendor-doc` | 모든 ArchUnit rule 실행 흐름 | `@ArchTest` 어노테이션과의 자동 호출 메커니즘은 별도 (§3.3) — 본 인용은 수동 check 만 보장 |
| ARCHUNIT-UG-C4 | 패키지 의존 규칙은 fluent DSL 로 표현 가능 — 예: `noClasses().that().resideInAPackage("..source..").should().dependOnClassesThat().resideInAPackage("..foo..")` | [§4.1] "noClasses().that().resideInAPackage(\"..source..\").should().dependOnClassesThat().resideInAPackage(\"..foo..\")" | `official-vendor-doc` | 도메인 → 인프라 금지 같은 패키지 단위 의존 강제 | 정확히 어떤 매칭 패턴 (`..` vs `.*`) 이 어떤 의미인지는 별도 문서 (matcher syntax) 필요 — 본 인용은 한 사례만 |
| ARCHUNIT-UG-C5 | layered architecture 규칙은 layer 이름 + 접근 허용 layer 명시로 표현 — 예: `layeredArchitecture().layer("Service").mayOnlyBeAccessedByLayers("Controller")` | [§4.6] "layeredArchitecture().layer(\"Service\").mayOnlyBeAccessedByLayers(\"Controller\")" | `official-vendor-doc` | Clean/Hexagonal layer 의존 방향 강제 | "layer" 의 식별 기준 (패키지 패턴, annotation 등) 은 본 인용에 없음 — `definedBy()` 등 별도 메서드 결합 필요 |
| ARCHUNIT-UG-C6 | JUnit 4/5 통합은 `@ArchTest` 어노테이션이 붙은 모든 rule 을 자동 import + 평가 | [§3.3] "The JUnit test support will automatically import (or reuse) the specified classes and evaluate any rule annotated with @ArchTest." | `official-vendor-doc` | JUnit 기반 CI 자동화 | "automatically import (or reuse)" 의 캐싱 정책 구체는 본 인용에 없음 — performance tuning 시 별도 확인 |
| ARCHUNIT-UG-C7 | cycle 검사는 slice 패턴 매칭으로 표현 — 예: `slices().matching("com.myapp.(*)..").should().beFreeOfCycles()` | [§4.7] "slices().matching(\"com.myapp.(*)..\").should().beFreeOfCycles()" | `official-vendor-doc` | 모듈 간 순환 의존 방지 | slice 가 반드시 패키지 1단계 단위여야 한다는 의미는 아님 — `(*)` 외 다른 capture 패턴 가능 |
| ARCHUNIT-UG-C8 | 멤버 단위 규칙도 지원 — `methods()`, `fields()`, `codeUnits()`, `constructors()` 등 `ArchRuleDefinition` 의 entry points | [§7.2] "Besides methods(), ArchRuleDefinition offers methods, fields, codeUnits, constructors." | `official-vendor-doc` | 메서드/필드 가시성, annotation 강제 등 fine-grained 규칙 | 어떤 entry point 가 성능상 더 가벼운지는 본 인용에 없음 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `ARCHUNIT-UG-C1`: ArchUnit 의 정체성 (free, simple, extensible, Java)
  - `ARCHUNIT-UG-C2`~`C3`: 기본 API (import + check)
  - `ARCHUNIT-UG-C4`~`C5`: 패키지 의존 규칙 + layered architecture 규칙의 DSL 표현
  - `ARCHUNIT-UG-C6`: JUnit 통합의 자동 호출
  - `ARCHUNIT-UG-C7`: cycle 검사 DSL
  - `ARCHUNIT-UG-C8`: 클래스 외 멤버 단위 규칙 entry points 의 존재
- **이 자료가 증명하지 않는 것**:
  - ArchUnit 이 ca-tmpl 의 실제 패키지 청사진에 맞춰 정확히 어떤 규칙 코드를 가져야 하는지 (구체 매핑은 별도 wiki/projects 에서 결정)
  - ArchUnit 규칙 위반 발생 시 CI 게이트 정책 (fail vs warn) — 본 인용 범위 밖
  - Kotlin / Scala 등 다른 JVM 언어에서의 완전한 동등 동작 (User Guide 의 다른 섹션 확인 필요)
  - ArchUnit 1.x ↔ 0.x API 호환성 (현재 1.4.2 기준 확인됨)
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 layer 정의 (domain / application / adapter / infrastructure) 와 `layeredArchitecture().layer(...).definedBy(...)` 매칭
  - 규칙 작성 후 CI/Gradle 통합 (test task 분리, 위반 시 fail policy)
  - Spring/JPA annotation 강제 규칙 (e.g., `@Service` 가 application 패키지 안에만 있어야 한다 등)

## 메모 / Notes

- ArchUnit User Guide 는 다른 4개 raw (Uncle Bob / Cockburn / Fowler / Richardson — 모두 personal blog) 와 달리 **유일한 official-vendor-doc** strength 자료. 따라서 ca-tmpl 의 "도구 선택" 결정은 본 자료만으로 단독 정당화 가능 (반면 layer/port 의 **개념 정의** 는 personal blog 들의 합성 필요).
- 본 페이지는 index 만 발췌. 실제 규칙 표현의 모든 매처 syntax (`..`, `.*`, `..foo..` 등) 는 별도 챕터 확인 필요 — 본 raw 를 wiki 로 승급할 때 추가 챕터 raw 도 함께 작성 권장.
- ArchUnit 의 "Onion Architecture" 사전 정의 API 도 존재하나 본 인용 범위 밖 — 별도 확인 후 추가 인용 가능.

## Related / 관련

- 같은 주제 다른 raw:
  - [[raw/official-docs/arch-clean-architecture-uncle-bob]] (강제할 의존 방향의 개념적 기반)
  - [[raw/official-docs/arch-hexagonal-cockburn]] (port/adapter 의존 방향의 개념적 기반)
- 이 자료를 인용하는 branch:
  - [[raw/branch-notes/feature-repository-access-permission-contract]]
  - [[raw/branch-notes/feature-architecture-enforcement-rules]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 이 자료를 인용한 wiki 요약: (미작성)