---
title: thombergs/buckpal — Clean/Hexagonal Architecture 예제 (책 동반 코드)
source_type: official-doc
url: https://github.com/thombergs/buckpal
archive_url:
status: raw
confidence: high
tags: [ca-architecture-layout, hexagonal, buckpal, github-reference, get-your-hands-dirty, official-doc]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-architecture-enforcement-rules, feature-skeleton-package-blueprint-contract, feature-domain-feature-onboarding-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# thombergs/buckpal — Clean/Hexagonal Architecture 예제 (책 동반 코드)

> Layer: `raw/official-docs/` — Tom Hombergs 의 GitHub repo README 발췌. *Get Your Hands Dirty on Clean Architecture* (Packt) 동반 코드.
> Spring Boot + Java 로 Hexagonal 을 적용할 때 가장 많이 인용되는 reference 구현체. ca-tmpl `Topic 1 — Architecture Layout` 대안 비교 (대안 2: hexagonal).

## Parent / 활용 branch (필수)

> 이 자료는 혼자 존재하지 않는다. ca-tmpl architecture 결정 비교군의 한 축.

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-architecture-enforcement-rules]] | ArchUnit 으로 의존성 방향을 컴파일 시점에 강제하는 reference 사례 — ca-tmpl enforcement 도구 선택의 비교 근거 |
| [[raw/branch-notes/feature-skeleton-package-blueprint-contract]] | feature(account) 내부에 hexagonal 구조를 두는 하이브리드 패키지 패턴의 reference — ca-tmpl 의 4-layer 와 매핑 비교 |
| [[raw/branch-notes/feature-domain-feature-onboarding-contract]] | 새 feature 추가 시 port/adapter 정의 워크플로우의 reference 예시 |

특정 branch 없이 foundational 조사로 수집한 경우:

- [[raw/project-notes/ca-skeleton-operational-contract]] — §20 Skeleton Blueprint Contract / §19 Domain Application Readiness Contract 의 대안 비교 (대안 2: hexagonal)

## 컨텍스트

ca-tmpl 의 feature-first 결정에 대한 대안 3: Hexagonal Architecture 의 사실상 표준 reference 구현체. 책의 권위 (Packt 출간) 와 함께 GitHub Star 2,500+ 로 reference 자료로 분류 가능. **5개 architecture 대안 중 ca-tmpl 결정에 구조적으로 가장 가까운 reference** (account/ feature 최상위 + 그 안에 layer).

## 출처 / Source

- 원본 URL: https://github.com/thombergs/buckpal
- 아카이브 URL: (미수집)
- 저자 / 조직: Tom Hombergs
- 동반 서적: *Get Your Hands Dirty on Clean Architecture* (2nd edition, Packt)
- Star 수: 약 2,500 (요구 기준 1000+ 충족)
- 발행일: GitHub repo rolling (책 1판 2019, 2판 이후 지속 업데이트)
- 마지막 확인일: 2026-05-27
- **재검증 상태 (2026-05-27)**: WebFetch 로 GitHub README 재확인 완료 — 5/5 핵심 인용 verbatim 일치. Star 수 2.5k 확인.

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

> [§README — purpose] "This repository implements a small web app in the Hexagonal Architecture style, as discussed in the book 'Get Your Hands Dirty on Clean Architecture'."

> [§README — learning bullet 1] "Learn the concepts behind 'Clean Architecture' and 'Hexagonal Architecture'."

> [§README — learning bullet 2] "Develop your domain code independent of database or web concerns."

> [§README — learning bullet 3] "Free your domain layer of oppressive dependencies using dependency inversion."

> [§README — learning bullet 4] "Structure your code in an architecturally expressive way."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| BUCKPAL-C1 | buckpal repo 는 Hexagonal Architecture 스타일의 small web app 구현체이며, *Get Your Hands Dirty on Clean Architecture* 책에서 논의된 내용을 코드로 보임 | [§README — purpose] "This repository implements a small web app in the Hexagonal Architecture style, as discussed in the book \"Get Your Hands Dirty on Clean Architecture\"." [2026-05-27 verified] | `official-reference` | Spring Boot + Java 백엔드의 Hexagonal 학습 reference | "small web app" 이므로 multi-feature / multi-bounded-context 시나리오의 reference 는 아님 — account 1개 도메인만 다룸. 책 저자의 self-published reference 이며 Cockburn endorsement 아님 |
| BUCKPAL-C2 | 학습 목표 중 하나는 Clean Architecture 와 Hexagonal Architecture 의 개념 학습 | [§README — learning bullet 1] "Learn the concepts behind \"Clean Architecture\" and \"Hexagonal Architecture\"." [2026-05-27 verified] | `official-reference` | 학습 의도 진술 | Clean Architecture 와 Hexagonal 의 차이점에 대한 buckpal 의 입장은 본 인용에 없음 — 책 본문 별도 |
| BUCKPAL-C3 | 학습 목표 중 하나는 도메인 코드를 database / web 관심사로부터 독립적으로 개발하는 것 | [§README — learning bullet 2] "Develop your domain code independent of database or web concerns." [2026-05-27 verified] | `official-reference` | 도메인-인프라 분리 학습 | "독립적" 의 정도 — 도메인이 framework annotation 을 일체 안 써야 하는지 등 — 는 본 인용에 없음 |
| BUCKPAL-C4 | 학습 목표 중 하나는 dependency inversion 으로 도메인 layer 를 oppressive dependency 로부터 해방 | [§README — learning bullet 3] "Free your domain layer of oppressive dependencies using dependency inversion." [2026-05-27 verified] | `official-reference` | DIP 적용 학습 | "oppressive dependency" 의 구체 목록 (JPA / Spring annotation / Lombok 등) 은 본 인용에 없음 — 책 본문 참조 필요 |
| BUCKPAL-C5 | 학습 목표 중 하나는 코드를 architecturally expressive 한 방식으로 구조화 | [§README — learning bullet 4] "Structure your code in an architecturally expressive way." [2026-05-27 verified] | `official-reference` | 패키지 구조의 명시성 | "architecturally expressive" 가 feature-first vs layer-first vs hexagonal 중 어느 것을 의미하는지 본 인용에 없음 — buckpal 의 실제 패키지 구조 (account/adapter/in/web 등) 별도 관찰 필요 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `BUCKPAL-C1` ~ `C5`: buckpal 이 Hexagonal 스타일을 표방하며 small web app 단위로 Clean/Hexagonal 학습을 의도한다는 README 진술
- **이 자료가 증명하지 않는 것**:
  - buckpal 의 실제 패키지 구조 (`account/domain`, `account/application/port/in`, `account/adapter/out/persistence` 등) 의 정확한 트리 — README 단편이 아닌 repo 트리 직접 관찰 필요
  - ArchUnit rule 의 구체 정의 (어떤 패키지가 어떤 패키지로의 의존을 막는지) — `BuckPalArchitectureTest.java` 별도 확인 필요
  - "feature(account) 내부에 hexagonal 구조를 두는 하이브리드" 라는 ca-tmpl 측 해석 — 이는 user 메모의 추론이며 README 가 직접 진술 안 함
  - buckpal 이 Cockburn 원형의 "공식 reference" 라는 보장 — Cockburn 본인이 endorse 하지 않음, Hombergs 의 책 동반 코드일 뿐
  - multi-feature / multi-bounded-context 환경에서의 적용 패턴
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - buckpal 의 ArchUnit test 가 ca-tmpl 의 enforcement 요구 (feature 간 import 금지 등) 를 그대로 적용 가능한지
  - ca-tmpl 의 4-layer 명명 (presentation/application/domain/infrastructure) 이 buckpal 의 (adapter/in, application, domain, adapter/out) 과 정확히 매핑되는지 (특히 presentation vs adapter/in/web)
  - account 1개 도메인 reference 를 multi-feature 로 확장 시 cross-feature 통신 패턴 (event vs direct port call)

## 메모 / Notes (내 프로젝트 해석)

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

- 적용 시나리오: 도메인 중심 Spring Boot 백엔드의 표준 학습 reference.
- 패키지 구조 특징 (user 관찰, 본 README 인용 범위 밖): `account/domain`, `account/application/port/in`, `account/application/port/out`, `account/adapter/in/web`, `account/adapter/out/persistence`. **feature(account) 내부에 hexagonal 구조를 두는 하이브리드**.
- 장점: ArchUnit 으로 의존성 방향 컴파일 시점 검증. 책+코드의 일관성으로 학습 곡선 완만.
- 단점: 도메인이 단순(account 1개) 해서 multi-feature 시나리오 가이드는 약함.
- ca-tmpl(feature-first) 와의 차이: **사실상 매우 유사 (user 해석)**. buckpal 도 최상위가 `account/` feature 이며 그 아래 layer 를 둠. ca-tmpl 의 4-layer 이름 (presentation/application/domain/infrastructure) 이 buckpal 의 (adapter/in, application, domain, adapter/out) 과 매핑됨. **5개 대안 중 ca-tmpl 결정에 가장 가까운 reference**.
- 신뢰도: 서적 동반 + 별 2500 → 사실상 reference template 로 인용 가능. 단 출처 표기는 "Hombergs 의 책 *Get Your Hands Dirty on Clean Architecture*" 이며 **Cockburn official 이 아님**.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/hexagonal-cockburn-wikipedia-summary]] (Hexagonal 원형 — Wikipedia)
  - [[raw/official-docs/onion-palermo-original-2008]] (자주 혼동되는 Onion 원형)
  - [[raw/official-docs/modulith-spring-official-doc]] (modular monolith 공식 대안)
- 같은 주제 company-tech-blog:
  - [[raw/company-tech-blogs/hexagonal-woowahan-techblog-2023]] (한국 대기업 실 적용 사례 — vendor-specific)
- 인용하는 branch / project:
  - [[raw/branch-notes/feature-architecture-enforcement-rules]]
  - [[raw/branch-notes/feature-skeleton-package-blueprint-contract]]
  - [[raw/branch-notes/feature-domain-feature-onboarding-contract]]
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용한 wiki 요약: (미작성)