docs(readme): 루트 README를 구조·문서 지도가 보이는 절 순서로 다시 쓴다
문제: 처음 온 사람이 루트 README만 보고는 저장소 구조와 문서 위치를 알 수 없다. 절이 「아키텍처 한눈에, 퀵스타트, 새 프로젝트로 시작하기, 아키텍처 규칙과 검증, 수동 전용 Gradle 태스크, 더 알아보기」라 `src/platforms/`, 루트 `compose.yaml`, `compose/`, 문서 폴더가 어디에도 없다. 코드와 다른 주장도 있다. - 「수동 전용 Gradle 태스크」는 `grpcPerformanceTest`를 어떤 workflow도 돌리지 않고 `cd src && ./gradlew :grpc:grpc-testkit:grpcPerformanceTest`로 부른다고 한다. 실제로는 `integration-main.yml`이 `-p platforms/optional-build performanceCheck`로 돌리고, gRPC 플랫폼은 다른 빌드라 그 명령은 주 빌드에서 돌지 않는다. - 패키지 이름 바꾸기 명령이 `.java`·`.gradle`·`.yml`만 고친다. `dev.caskeleton`은 `AutoConfiguration.imports` 29개, `spring.factories` 9개, 생성 명령 템플릿, xml·json 파일에도 있다. 고른 방법: design-docs `conventions/docs-system.md` 6.1절 순서로 절을 다시 짠다 (프로젝트 구조 → 시작하기 → 기능 켜고 끄기 → 문서 지도 → 검증 → 새 서비스로 시작하기 → 규칙과 기여). 구조 절은 최상위 폴더 표, `src/` 폴더 표(기본 조립에 들어가나), 의존 방향 도식을 두고 모듈 개수와 버전 숫자는 쓰지 않는다. 틀린 두 주장은 지우거나 `git grep -l 'dev\.caskeleton'`로 찾게 바꾼다. 프로파일 표와 `bootRunH2` 설명은 이미 `src/README.md`가 가지므로 거기를 가리킨다. 문체는 「~한다」로 바꾼다. 버린 대안: 옛 절을 그대로 두고 두 절만 더하기. 6.1절 순서와 다르고, 같은 내용이 `src/README.md`와 두 곳에 남는다. 위험·한계: README 문구를 단언하던 `DeveloperExperienceContractTest .readmeDocumentsOneFirstRunEntrypoint`의 기대 문자열을 「## 시작하기」·「첫 실행 진입점은 하나다.」로 맞췄다. 진입점 하나와 성공 확인을 지키는 계약은 그대로다. 검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py --links README.md` 깨진 링크 0.
This commit is contained in:
@@ -1,161 +1,135 @@
|
||||
# ca-skeleton — Clean Architecture Spring Boot 템플릿
|
||||
# ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿
|
||||
|
||||
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`입니다. 업무 기능의 예시는 생성 명령 `scripts/new-feature.sh`의 출력과 [docs/manual/](docs/manual/README.md)입니다.
|
||||
ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(`AGENTS.md`)과 같은 절차(`docs/work/`)로 일한다. 라이브러리 버전은 `src/gradle/libs.versions.toml`이 정한다.
|
||||
|
||||
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 `CLAUDE.md`가, 빌드·환경 변수 상세는 [src/README.md](src/README.md)가 소유합니다.
|
||||
## 프로젝트 구조
|
||||
|
||||
## 아키텍처 한눈에
|
||||
저장소 루트에는 정해진 것만 둔다. 허용 목록 밖의 최상위 항목은 `scripts/check-repo-layout.py`가 PR에서 막는다.
|
||||
|
||||
의존은 항상 바깥에서 안으로 흐릅니다. adapter가 core의 port에 의존하고, core는 adapter를 알지 못합니다. 이 방향이 유지되는 한 도메인 규칙과 기술 선택(웹 프레임워크, DB, 메시징)을 서로 독립적으로 바꿀 수 있습니다.
|
||||
| 폴더 | 하는 일 | 먼저 읽을 곳 |
|
||||
| --- | --- | --- |
|
||||
| `src/` | Gradle 루트. 모든 코드, 빌드 규칙, registry | [src/README.md](src/README.md) |
|
||||
| `docs/` | 문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | [docs/README.md](docs/README.md) |
|
||||
| `scripts/` | Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 저장소 배치·문서 검사 | `scripts/bootstrap-local.sh`, `scripts/new-feature.sh` |
|
||||
| `compose.yaml` | 개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 |
|
||||
| `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) |
|
||||
| `.github/` | workflow, 공용 action, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) |
|
||||
|
||||
`src/` 아래 폴더는 계층 leaf, 조립, 들여온 제품, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다.
|
||||
|
||||
| 폴더 | 책임 | 기본 조립에 들어가나 |
|
||||
| --- | --- | --- |
|
||||
| `domain-core/` | 도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 |
|
||||
| `application-core/` | command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 |
|
||||
| `application-fileserver/`, `application-notification/`, `application-objectstorage/` | capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 |
|
||||
| `shared-contract/` | 저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 |
|
||||
| `adapter/inbound/` | HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | `web`만 들어간다 |
|
||||
| `adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 |
|
||||
| `composition/` | 조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
|
||||
| `app-bootstrap/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
|
||||
| `platforms/` | 들여온 제품: `messaging`(메시징 플랫폼), `grpc`·`grpc-advanced`(gRPC 라이브러리, 다른 빌드 `optional-build`) | 들어가지 않는다. adapter를 거쳐서만 닿는다 |
|
||||
| `build-logic/`, `config/`, `gradle/` | 빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 |
|
||||
|
||||
의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다.
|
||||
|
||||
```text
|
||||
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
|
||||
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
|
||||
모든 런타임 모듈 -> shared-contract
|
||||
app-bootstrap ─▶ adapter:inbound:* ─▶ application-core ─▶ domain-core
|
||||
app-bootstrap ─▶ adapter:outbound:* ─▶ application-core ─▶ domain-core
|
||||
모든 런타임 모듈 ─▶ shared-contract
|
||||
```
|
||||
|
||||
family 수준의 책임은 다음과 같습니다.
|
||||
불변식: 도메인 규칙은 `domain-core`와 `application-core`에만 있고, 기술 선택(웹, DB, 메시징)은 adapter에만 있다.
|
||||
|
||||
| 모듈 family | 책임 |
|
||||
| --- | --- |
|
||||
| `domain-core` | 순수 도메인 모델·불변식·이벤트·port. 프레임워크·transport·DB·IO 타입 금지 |
|
||||
| `application-core` | command·유스케이스·application 정책·트랜잭션 port. inbound DTO·persistence entity 금지 |
|
||||
| `adapter:inbound:*` | HTTP·gRPC·GraphQL·WebSocket transport 경계, DTO·validation·인증·에러 매핑 |
|
||||
| `adapter:outbound:persistence-*` | JPA/PostgreSQL·MongoDB 영속 구현과 매핑·migration |
|
||||
| `adapter:outbound:*` | support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 고릅니다 |
|
||||
| `shared-contract` | skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
|
||||
| `app-bootstrap` | Spring Boot entrypoint와 composition root |
|
||||
## 시작하기
|
||||
|
||||
등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는
|
||||
[src/config/architecture/modules.json](src/config/architecture/modules.json)이 SSOT입니다. focused
|
||||
test는 해당 Gradle path에서 `./gradlew <gradle-path>:test --console=plain` 형태로 파생하며, root
|
||||
문서나 기억에서 개별 leaf edge를 추론하지 않습니다.
|
||||
|
||||
## 퀵스타트
|
||||
|
||||
전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
|
||||
전제는 Temurin 21(`.tool-versions`에 고정)과 Docker Engine 또는 Docker Desktop이다. Gradle은 저장소의 wrapper를 쓴다. 첫 실행 진입점은 하나다.
|
||||
|
||||
```bash
|
||||
scripts/bootstrap-local.sh
|
||||
```
|
||||
|
||||
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 `compose.yaml` 하나입니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
|
||||
이 스크립트는 네 단계를 차례로 돈다: 컴파일, PostgreSQL 기동, 앱 이미지 빌드와 기동, `GET /api/healthcheck` 확인. 단계마다 `bootstrap N/4` 줄을 찍고, 실패하면 그 단계에서 멈춘다. 쓰는 compose 파일은 루트의 `compose.yaml` 하나다.
|
||||
|
||||
성공하면 이 명령이 HTTP 200을 돌려준다.
|
||||
|
||||
```bash
|
||||
curl -fsS http://localhost:8080/api/healthcheck
|
||||
```
|
||||
|
||||
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
|
||||
내릴 때는 저장소 루트에서 `--profile '*'`를 붙인다. 붙이지 않으면 profile로 띄운 `db` 같은 서비스가 남는다.
|
||||
|
||||
```bash
|
||||
docker compose --profile '*' down
|
||||
```
|
||||
|
||||
`--profile '*'`가 없으면 profile이 달린 `db`가 남습니다. compose는 켜진 profile의 서비스만 내립니다.
|
||||
환경 변수는 `src/.env`(로컬 실행 입력)와 `src/.env.example`(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)이다.
|
||||
|
||||
Redis·Kafka·MongoDB 같은 뒷단 서비스는 `compose.yaml`의 profile로 고릅니다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있습니다.
|
||||
## 기능 켜고 끄기
|
||||
|
||||
`src/.env.example`은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 `src/.env`는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)에 있습니다.
|
||||
기본 조립(`bootJar`)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, `support`·`identifier`뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. `cd src && ./gradlew :app-bootstrap:bootRun`으로 바로 실행할 수 있다.
|
||||
|
||||
### 기본 조립과 부가 기능
|
||||
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src/app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄씩으로 있다.
|
||||
|
||||
기본 조립(`bootJar`)은 web, 관측, `domain-core`·`application-core`·`shared-contract`, support,
|
||||
identifier뿐이라 DB·Redis·Kafka 없이 기동합니다.
|
||||
- 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다.
|
||||
- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다.
|
||||
- 줄마다 필요한 env 키와 끄는 키: [src/README.md](src/README.md) 「기능 추가 = 한 줄 + env」 표.
|
||||
- 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md).
|
||||
- capability 모듈이 지켜야 하는 규칙: [AGENTS.md](AGENTS.md) 「부가 기능(capability) 모듈 규칙」.
|
||||
|
||||
뒷단 서비스는 `compose.yaml`의 profile로 고른다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있다.
|
||||
|
||||
## 문서 지도
|
||||
|
||||
모든 문서 폴더의 지도는 [docs/README.md](docs/README.md)다. 무엇을 하려는지에 따라 여기서 시작한다.
|
||||
|
||||
| 하려는 일 | 시작할 곳 |
|
||||
| --- | --- |
|
||||
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [CLAUDE.md](CLAUDE.md) |
|
||||
| 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` |
|
||||
| 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` |
|
||||
| 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` |
|
||||
| 왜 이렇게 정했는지 보기 | 결정 기록 `docs/adr/`, `docs/notification/adr/` |
|
||||
| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
|
||||
| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` |
|
||||
|
||||
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `CLAUDE.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)).
|
||||
|
||||
## 검증
|
||||
|
||||
명령은 `src/`에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 `gradle_path`에서 읽는다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :app-bootstrap:bootRun
|
||||
./gradlew :app-bootstrap:check --console=plain
|
||||
./gradlew architectureCheck --console=plain
|
||||
```
|
||||
|
||||
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능은 `app-bootstrap/build.gradle`에 주석 처리된
|
||||
`runtimeOnly` 한 줄씩으로 있습니다. 줄의 주석을 풀고 필요한 env를 넣으면 켜지고, 줄을 지우면 사라집니다.
|
||||
줄마다 필요한 env와 끄는 키는 [src/README.md](src/README.md)의 "기능 추가 = 한 줄 + env" 표에 있습니다.
|
||||
`./gradlew test`는 모든 leaf의 `test`를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 [docs/work/reference/gates.md](docs/work/reference/gates.md)가 정한다. 게이트 태스크 하나하나의 설명은 [src/README.md](src/README.md) 「build.gradle — 빌드 / 검증 게이트」다.
|
||||
|
||||
| 프로파일 | 데이터스토어 (persistence-jpa 줄을 넣었을 때) | 스키마 소유자 |
|
||||
| --- | --- | --- |
|
||||
| `local` | Compose PostgreSQL (`./gradlew :app-bootstrap:bootRunH2`는 줄 없이도 모듈을 자기 classpath에 올려 H2 in-memory로 실행) | Flyway (H2는 Hibernate `create-drop`) |
|
||||
| `dev` | PostgreSQL | Flyway |
|
||||
| `prod` | PostgreSQL | Flyway |
|
||||
문서를 고쳤으면 저장소 루트에서 `python3 scripts/check-docs.py`를 돌린다. 규칙은 [docs/README.md](docs/README.md) 「문서 검사」다.
|
||||
|
||||
H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 vendor 동작은 검증하지 않습니다. 프로파일별 설정은 [src/app-bootstrap/src/main/resources/](src/app-bootstrap/src/main/resources/)의 `application-{local,dev,prod}.yml`이, 상세 설명은 [src/README.md](src/README.md)가 소유합니다.
|
||||
## 새 서비스로 시작하기
|
||||
|
||||
## 새 프로젝트로 시작하기
|
||||
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 전체 체크리스트는 [AGENTS.md](AGENTS.md) 「템플릿 재사용 체크리스트」다.
|
||||
|
||||
이 저장소를 새 서비스의 출발점으로 쓸 때 핵심 단계는 다음과 같습니다. 전체 체크리스트는 [AGENTS.md](AGENTS.md)의 "템플릿 재사용 체크리스트"에 있습니다.
|
||||
|
||||
1. [src/settings.gradle](src/settings.gradle)의 `rootProject.name`을 새 서비스 이름으로 바꿉니다.
|
||||
2. 패키지 루트 `dev.caskeleton`을 조직·서비스 패키지로 바꿉니다. 소스뿐 아니라 빌드·설정 파일의 참조도 함께 바꿔야 `mainClass`·`group`이 어긋나 `bootstrap`이 깨지지 않습니다.
|
||||
1. `src/settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
|
||||
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
find . -type f \( -name '*.java' -o -name '*.gradle' -o -name '*.yml' \) -print0 | xargs -0 sed -i 's/dev.caskeleton/com.yourorg.yourservice/g'
|
||||
git grep -l 'dev\.caskeleton' -- src scripts
|
||||
```
|
||||
|
||||
애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다.
|
||||
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다.
|
||||
4. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
|
||||
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
|
||||
|
||||
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만듭니다.
|
||||
4. 모듈 이름과 경계는 그대로 유지합니다.
|
||||
복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`).
|
||||
|
||||
검증은 먼저 composition root의 빠른 테스트와 아키텍처 검사를 확인합니다. 루트에서
|
||||
`./gradlew test`를 호출하면 등록된 모든 하위 프로젝트의 `test`를 실행하므로 일상적인 로컬
|
||||
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 `ci` task가
|
||||
담당합니다.
|
||||
이름을 바꾼 뒤에는 위 「검증」의 두 명령과 `./gradlew :app-bootstrap:test --console=plain`을 돌린다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :app-bootstrap:test
|
||||
./gradlew architectureCheck
|
||||
```
|
||||
## 규칙과 기여
|
||||
|
||||
병합 전 저장소 전체 검증이 필요하면 `./gradlew ci`를 실행합니다.
|
||||
|
||||
## 아키텍처 규칙과 검증
|
||||
|
||||
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬
|
||||
정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 작업을 시작할 때 읽는 지도입니다.
|
||||
일의 종류별 절차는 [docs/work/](docs/work/README.md)에 있습니다.
|
||||
|
||||
- `domain-core`는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다.
|
||||
- controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다.
|
||||
- inbound DTO는 `application-core`나 `domain-core`로 들어가지 않습니다.
|
||||
- 비즈니스 정책은 mapper·filter·config·settings·controller에 두지 않습니다.
|
||||
- 새 외부 시스템 연동은 domain/application port와 adapter 모듈로 표현합니다.
|
||||
|
||||
이 규칙은 두 축으로 자동 강제합니다. `:app-bootstrap:architectureTest`의 분할된 ArchUnit 규칙들이 컴파일된 소스 의존성을,
|
||||
`verifyCleanArchitectureDependencies` 게이트가 JSON registry의 허용 Gradle project edge를
|
||||
검사합니다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew verifyCleanArchitectureDependencies
|
||||
```
|
||||
|
||||
두 검증 축은 [ci-quality-gates.yml](.github/workflows/ci-quality-gates.yml)의 release gate에 연결되어, 규칙 위반이 병합·릴리스를 막습니다.
|
||||
|
||||
## 수동 전용 Gradle 태스크
|
||||
|
||||
아래 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 적어 둔다.
|
||||
|
||||
여기 적힌 태스크 이름이 실재하는지 검사하던 `verifyReadmeCommands`는 삭제했다. 그건 이 문서의
|
||||
```bash 블록을 직접 파싱해 `./gradlew`·`docker compose`·`make` 토큰을 실제 태스크 그래프와 대조하는
|
||||
Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"가 그 파서가 읽을 수 있는 문법의
|
||||
함수가 됐다. 문서와 코드가 어긋나는 것은 결함이지만, 빌드를 실패시켜서 고칠 일은 아니다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
|
||||
```
|
||||
|
||||
- `grpcPerformanceTest` — latency percentile·saturation·drain budget을 **측정**한다. 공유 CI
|
||||
runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf `build.gradle`이 이 태스크의
|
||||
태그를 `test`에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
|
||||
|
||||
|
||||
## 더 알아보기
|
||||
|
||||
- 빌드·검증 게이트·환경 변수 상세: [src/README.md](src/README.md)
|
||||
- 모듈 레지스트리(등록 leaf SSOT): [src/config/architecture/modules.json](src/config/architecture/modules.json)
|
||||
- 에이전트·기여자 작업 규칙: [AGENTS.md](AGENTS.md) · [CLAUDE.md](CLAUDE.md)
|
||||
- release/publish 자동화는 `.github/workflows/release.yml`이 소유하며, release provenance·SBOM·
|
||||
이미지 build/push를 해당 workflow의 명시적 권한과 게이트 아래에서 수행합니다.
|
||||
- 모듈별 설계 결정: [domain-core](src/domain-core/README.md) · [application-core](src/application-core/README.md) · [adapter:inbound:web](src/adapter/inbound/web/README.md) · [adapter:outbound:persistence-jpa](src/adapter/outbound/persistence-jpa/README.md) · [shared-contract](src/shared-contract/README.md) · [app-bootstrap](src/app-bootstrap/README.md)
|
||||
- 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다.
|
||||
- 일을 시작할 때 읽는 지도는 [CLAUDE.md](CLAUDE.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
|
||||
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`다.
|
||||
- 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다.
|
||||
|
||||
+2
-2
@@ -137,8 +137,8 @@ class DeveloperExperienceContractTest {
|
||||
assertThat(readme)
|
||||
.contains("scripts/bootstrap-local.sh")
|
||||
.contains("GET /api/healthcheck")
|
||||
.contains("## 퀵스타트")
|
||||
.contains("첫 실행 진입점은 하나입니다.");
|
||||
.contains("## 시작하기")
|
||||
.contains("첫 실행 진입점은 하나다.");
|
||||
}
|
||||
|
||||
@Test
|
||||
|
||||
Reference in New Issue
Block a user