chore: 문서를 작성할 때 한국어의 표현 작성 스킬 추가 및 1인칭 관점의 글 작성 검증 테스트 추가

2026-07-29 16:48:03 +09:00
parent c39406bbdd
commit 41501b5d06
520 changed files with 95494 additions and 2231 deletions
@@ -0,0 +1,28 @@
+---
+title: branch / feature-application-port-usecase-contract
+source_type: branch-note
+status: verified
+status_label: actually-implemented
+---
+
+# branch: feature-application-port-usecase-contract
+
+## 목표
+
+application layer의 use case가 DTO, JPA entity, HTTP request, external client를 직접 다루지 않도록 port 계약과 command/query 모델을 고정한다.
+
+## 결정 사항
+
+- D3: transaction boundary는 application use case 책임이지만 Spring `@Transactional` 직접 import는 금지하고 `TransactionPort` abstraction을 기본값으로 둔다.
+- D11: `TransactionPort`는 `Supplier<T>`와 `Runnable` 시그니처를 유지한다.
+- D13: `application-core`는 `org.springframework.stereotype.Service`와 `Component` 사용을 DI 등록 목적으로 허용한다. `spring-context`와 `spring-beans` 의존은 유지한다.
+- D13 이유: Spring DI까지 제거하면 use case bean마다 `@Configuration`에서 수동 등록해야 하므로 조립 코드가 급격히 늘어난다.
+- D13 경계: `spring-tx`, Spring Web, JPA annotation은 계속 금지한다. 편의 때문에 application layer의 책임을 transaction, transport, persistence까지 넓히지 않는다.
+
+## 구현 및 검증
+
+`application-core`의 `spring-tx` 의존성을 제거했다. `@Transactional`이 compile classpath에 없도록 했다. `application_does_not_use_spring_transactional_annotation`과 `application_does_not_depend_on_application_context` ArchUnit rule을 두고 negative fixture로 위반 검출을 확인했다.
+
+## 선택의 비용
+
+`application-core`가 Spring core DI 의존을 갖는다는 비용은 수용한다. 대신 허용 목적을 bean 등록으로 좁히고, transaction, transport, persistence 의존은 빌드 규칙과 ArchUnit으로 차단한다.
@@ -0,0 +1,19 @@
+---
+title: branch / feature-log-management-contract
+source_type: branch-note
+status: raw
+status_label: implemented
+---
+
+# branch: feature-log-management-contract
+
+## 결정 사항
+
+- 운영 로그는 structured JSON을 기본 포맷으로 둔다.
+- domain layer logger는 금지하고 domain invariant violation을 application layer에서 client-safe diagnostic log로 변환한다.
+
+## 근거 경계
+
+`domain layer logger 금지`는 외부 공식 문서가 직접 증명한 보편 원칙이 아니라 ca-tmpl 내부 정책이다. 외부 공개 글에서는 프로젝트 지역 결정으로만 표현한다.
+
+이 문서는 `application-core`가 SLF4J를 사용하는 이유를 설명하지 않는다. 단어가 등장하거나 로거가 존재한다는 사실만으로 선택 이유를 만들어내지 않는다.
@@ -0,0 +1,15 @@
+---
+title: Spring component stereotype and scanning notes
+source_type: official-doc
+status: reviewed
+---
+
+# Spring component stereotype and scanning notes
+
+## Supported behavior
+
+Spring stereotype annotations such as `@Component` and `@Service` mark classes as candidates for component scanning and container registration.
+
+## Evidence boundary
+
+This vendor behavior explains what the annotations do. It does not prove why a particular project chose to use them, nor does it prove which other Spring dependencies the project allows. Project rationale must come from the project's own decision record.
@@ -0,0 +1,30 @@
+---
+title: ca-tmpl - Clean Architecture 패키지 레이아웃 결정
+source_type: project
+status: verified
+confidence: high
+---
+
+# ca-tmpl - Clean Architecture 패키지 레이아웃 결정
+
+## 프로젝트 컨텍스트
+
+ca-tmpl은 Java 21, Spring Boot 3.4, Gradle multi-module 기반 Clean Architecture template이다. `domain-core`, `application-core`, `adapter-*`, `shared-contract`, `app-bootstrap`, `sample-portfolio`를 물리적으로 분리한다.
+
+## 실제 구현 내용
+
+`domain-core`는 Spring, JPA, Servlet, Hibernate, Lombok, application, adapter, bootstrap 의존을 금지해 framework-neutral POJO 경계를 유지한다.
+
+`application-core`는 adapter와 bootstrap, Spring Web, persistence, Hibernate에 의존하지 못한다. `@Transactional`과 `ApplicationContext` 직접 의존도 금지한다.
+
+`shared-contract`는 response, request, error, operation, headers, logging, tracing, metrics, registry, annotation 같은 운영 계약 package만 허용한다. business common dumping ground로 사용하지 않는다.
+
+## 경계 검증
+
+Gradle의 `verifyCleanArchitectureDependencies`는 project dependency graph를 검사한다. ArchUnit의 `CleanArchitectureTest`는 source import graph를 검사한다. 두 검사는 서로 다른 그래프를 담당한다.
+
+정적 분석은 모든 우회를 잡지 못한다. `getBean(String)`, `Class.forName(String)`, `BeanFactory#getBeansOfType` 같은 reflection-style bypass는 code review checklist로 보완한다.
+
+## 검증 범위
+
+module dependency matrix와 ArchUnit rule은 로컬에서 검증했다. 운영 배포와 운영 metric으로 검증한 결과는 없다.