---
title: blog-topic / repository-capability-archunit-fitness-function
source_type: blog-topic
status: raw
related_branches: [feature-repository-access-permission-contract]
related_projects: [ca-tmpl]
tags: [blog-topic, ca-tmpl, persistence, testing, archunit, static-analysis, clean-architecture]
created: 2026-07-02
status_label: ready-for-canonical
target_audience: backend-engineer
inspiration_url:
archive_url:
---

# blog-topic: repository-capability-archunit-fitness-function

> Layer: `raw/blog-topics/` — 작업 중 나온 블로그 글감 원석. 최종 블로그는 canonical 정제 후 `wiki/blog/`에서 작성한다.

## Parent / 부모

- [[raw/branch-notes/feature-repository-access-permission-contract]] — repository 접근 capability를 annotation, registry, ArchUnit rule로 계약화한 branch에서 나온 글감.

## 트리거 / Trigger

- 트리거 유형: `branch-work`
- 트리거 날짜: 2026-07-02
- 트리거 연결 노트: [[raw/branch-notes/feature-repository-access-permission-contract]]

## 글감 / Topic seed

- 한 문장 요지: repository 접근 권한을 사람의 리뷰 기억에 맡기지 않고 annotation + registry + ArchUnit fitness function으로 강제한 이유를 정리한다.
- 예상 제목 후보:
  - Repository 접근 권한을 ArchUnit rule로 고정하기
  - Clean Architecture에서 persistence capability를 계약으로 다루기

## 핵심 주장 후보 / Claim candidates

- 사실 후보:
  - branch가 repository capability registry drift와 3층 검증을 blog topic 후보로 명시한다 — 근거 후보: [[raw/branch-notes/feature-repository-access-permission-contract]] section+line `:311-314`.
- 경험 후보:
  - 기존 boundary enforcement topic은 계층 의존성 중심이고, 이 글감은 repository capability annotation/registry coherence라는 좁은 실패 모드를 다룬다.
- 의견/해석 후보:
  - repository 접근 제한은 "어느 package에서 접근했는가"보다 "어떤 capability로 접근을 허용했는가"까지 내려가야 drift를 줄일 수 있다.

## Outline seed

1. package boundary만으로는 repository intent를 알 수 없다 — 접근 권한의 의미를 capability로 드러낸다.
2. annotation, registry, ArchUnit의 역할 분리 — 선언, 목록, 검증이 서로를 보완한다.
3. fitness function의 한계 — helper/mapper indirection까지 자동 검출한다고 과장하지 않는다.

## Canonical 전환 후보 / Canonical extraction candidates

- `wiki/projects/ca-tmpl/repository-access-capability-contract.md` 후보:
  - ca-tmpl repository access permission contract 구현 사실.
- `wiki/concepts/archunit-fitness-function.md` 후보:
  - ArchUnit rule을 architecture fitness function으로 사용하는 일반 개념.
- 필요한 추가 검증:
  - annotation 이름, registry schema, ArchUnit rule/test anchor.

## Sources / 근거 후보

- [[raw/branch-notes/feature-repository-access-permission-contract]] — blog seed와 capability contract 근거.
- [[raw/blog-topics/clean-architecture-boundary-enforcement-2026-05-28]] — 기존 boundary topic과의 경계.

## 미해결 / Unknown

- 아직 확인해야 할 사실: helper/mapper 우회 경로 검출 가능 범위.
- 과장하면 안 되는 부분: 모든 repository misuse를 자동 검출한다고 쓰면 안 된다. 정적 분석 rule이 볼 수 있는 구조로 제한한다.
- 블로그로 쓰기 전에 필요한 canonical 정제: project 문서의 implemented/local evidence 정리.

## Decision / 처리 결정

- 액션: `promote-to-canonical`
- 이유: `wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound.md` 에 repository capability ArchUnit fitness function 글감으로 반영했다.
- 다음 단계: target canonical이 아직 `draft` 이므로 `blogify` 전 review/verify가 필요하다. 모든 repository misuse를 자동 검출한다고 쓰지 않는다.

## Related / 관련

- 관련 branch: [[raw/branch-notes/feature-repository-access-permission-contract]]
- 관련 error:
- 관련 interview prep:
- derived blog: 생성 전. 생성 시 `wiki/blog/repository-capability-archunit-fitness-function-YYYY-MM-DD.md` 후보