docs(agents)!: 루트 AGENTS.md를 40줄 정본으로 줄이고 CLAUDE.md가 가져온다
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은 AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만 닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은 규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은 AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs harness/01-harness-design.md 13절 Q1·Q2·Q3). - AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증, 일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄. - 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새), 테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스), 계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새 src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 → src/composition/AGENTS.md(새), capability 규칙·완료 기준 → docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 → .claude/rules/settings-and-runtime.md, 문서 편집 규칙 → .claude/rules/docs.md, 템플릿 재사용 체크리스트 → README 「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길· 작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다. - 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛 행에 취소선을 긋고 「지침 배치」 행을 더했다. - check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10), 진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지, .claude/rules·skills·agents 문서의 이력 ID와 링크를 본다. - DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서 읽는다. 단언은 그대로다. 버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함), CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크. 위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로 읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다. 검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10), check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트 변경은 마지막 트리에서 desktop documentContractTest로 확인한다. BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로 옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행.
This commit is contained in:
@@ -0,0 +1,12 @@
|
||||
---
|
||||
paths:
|
||||
- "**/*.md"
|
||||
---
|
||||
|
||||
# 문서를 고칠 때
|
||||
|
||||
- 문서 위치·언어·머리 블록 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다.
|
||||
- 기록 문서(`docs/design/`, `docs/history/`, `docs/reviews/`, `docs/adr/`)는 맨 위 머리 블록만 고친다.
|
||||
- 진입 문서(`AGENTS.md`, 모든 `src/**/AGENTS.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다.
|
||||
- 문서를 읽는 테스트가 있다. 태그 `document-contract`(main 단계)·`repository-contract`(PR)다. 고친 문서의 경로로 `git grep -n '<경로>' -- 'src/*.java'`를 해서 그 테스트를 찾고 desktop에서 돌린다.
|
||||
- 고친 뒤 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`를 돌린다.
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
paths:
|
||||
- "src/**/src/test/**/*.java"
|
||||
- "src/**/src/testFixtures/**/*.java"
|
||||
- "src/**/src/*Test/**/*.java"
|
||||
- "src/**/src/*Testkit/**/*.java"
|
||||
---
|
||||
|
||||
# Java 테스트 작성 규칙
|
||||
|
||||
새로 쓰거나 고치는 테스트에 적용한다. 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`, 계층별로 무엇을 검증하는지는 그 계층의 `AGENTS.md` 「테스트」 절이다.
|
||||
|
||||
## 작성 규칙
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로 쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트 메서드를 고칠 때 한국어로 바꾼다. 같은 클래스의 고치지 않은 메서드는 바꾸지 않아도 되고, 바꾸면 같은 커밋에 넣고 보고에 적는다.
|
||||
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할 것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다. 예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때 `// when & then`까지 허용). 한 줄 테스트와 ArchUnit `.check()`는 주석 없이 쓴다.
|
||||
4. `@Nested`는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다.
|
||||
5. then은 when의 결과 하나만 단언한다. 여러 필드는 `usingRecursiveComparison()` 또는 `extracting(..).containsExactly(..)`로 한 번에 비교한다. `isNotNull`·`isPresent`·`doesNotThrowAnyException`만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외). 예외는 타입과 reason·message를 함께 단언한다. 표 형태 입력은 `@ParameterizedTest`로 쓴다.
|
||||
6. 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는 포트는 fake와 adapter가 같은 추상 계약 테스트(`XxxContract`)를 통과한다. Mockito는 프레임워크 경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다.
|
||||
|
||||
GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고, 실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다.
|
||||
|
||||
## 코드만 보고는 헷갈리는 것
|
||||
|
||||
- 저장소 파일을 읽는 테스트는 태그가 있어야 한다. 문서와 대조하면 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow·Compose를 읽으면 `repository-contract`(PR)다. 태그 없이 저장소를 읽으면 `test`에서 실패한다. 이유는 `src/build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」다.
|
||||
- 성능 lane에는 단언을 끄는 스위치가 없다. `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 하나라도 있으면 테스트 전에 실패한다.
|
||||
- 테스트는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절).
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
paths:
|
||||
- "src/**/*Settings.java"
|
||||
- "src/**/settings/**"
|
||||
- "src/**/autoconfigure/**"
|
||||
- "src/**/application*.yml"
|
||||
- "src/**/application*.yaml"
|
||||
- "src/**/config/module-defaults/**"
|
||||
- "src/.env.example"
|
||||
- "src/.env.local.example"
|
||||
- "src/Dockerfile"
|
||||
- "compose.yaml"
|
||||
- "compose/**"
|
||||
- "src/**/compose/**"
|
||||
- "src/app-bootstrap/compose-lanes/**"
|
||||
---
|
||||
|
||||
# 설정과 런타임 규칙
|
||||
|
||||
## 설정
|
||||
|
||||
- 비밀 값(토큰, 비밀번호, 개인 키)을 코드, 테스트 fixture, 문서 예시에 하드코딩하지 않는다. 예시 값이면 `example`·`dummy`·`changeme`처럼 예시임이 보이게 쓴다.
|
||||
- 새 설정 그룹은 typed settings class로 만든다. 흩어진 `@Value`보다 configuration properties와 settings class를 쓴다.
|
||||
- 새 settings class를 만들면 바인딩·값 검증 테스트를 더한다.
|
||||
- capability 모듈의 설정 prefix는 하나다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor다(`docs/manual/10-capabilities.md` 기준 4, Redis 예외 포함).
|
||||
- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다. 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다.
|
||||
- `application.yml`은 환경마다 안전한 기본값과 분명한 자리표시자만 담는다.
|
||||
|
||||
## Docker·Compose
|
||||
|
||||
- `src/Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다.
|
||||
- container 안에서 필요한 profile, port, env 키를 문서나 예시 설정에 반영한다.
|
||||
- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다. 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`).
|
||||
- Docker는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절).
|
||||
+2
-1
@@ -1,9 +1,10 @@
|
||||
.vscode/
|
||||
src/**/bin/
|
||||
# Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project
|
||||
# settings file is committed: it denies the Agent tool for everyone (AGENTS.md 「Superpowers Workflow」).
|
||||
# settings and the path rules are committed: everyone who opens the repository gets them (CLAUDE.md).
|
||||
.claude/*
|
||||
!.claude/settings.json
|
||||
!.claude/rules/
|
||||
|
||||
# Operator input, not a build input. The examples beside it are the tracked contract;
|
||||
# verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one.
|
||||
|
||||
@@ -1,344 +1,37 @@
|
||||
# AGENTS.md
|
||||
# AGENTS.md — 백엔드 템플릿의 정본
|
||||
|
||||
## 프로젝트 정체성
|
||||
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다.
|
||||
|
||||
이 저장소는 단순한 예제 블로그 애플리케이션이 아니라, Java 21 + 버전 카탈로그에 고정된 Spring Boot 4.x + Gradle 멀티모듈 기반의 Clean Architecture 템플릿이다.
|
||||
## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다
|
||||
|
||||
기본 패키지는 `dev.caskeleton`이다. 업무 기능의 예시는 `scripts/new-feature.sh`의 출력과 `docs/manual/`이다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
|
||||
1. `domain-core`가 framework·transport·database·cloud 의존성을 가진다.
|
||||
2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
|
||||
3. inbound DTO가 `application-core`나 `domain-core`로 들어간다.
|
||||
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
|
||||
5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
|
||||
6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
|
||||
7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
|
||||
|
||||
## Prime Directive
|
||||
## 지도
|
||||
|
||||
에이전트는 속도보다 아키텍처 보존을 우선한다.
|
||||
- Gradle 루트는 `src/`다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registry `src/config/architecture/modules.json`이다. 문서는 leaf 개수를 적지 않는다.
|
||||
- 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다.
|
||||
- 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `src/build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다.
|
||||
- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). `src/platforms/*`는 계층이 아닌 들여온 제품, `src/composition/*`는 조립만 한다.
|
||||
- capability는 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`.
|
||||
|
||||
동작하는 코드라도 HARD-STOP 조건을 하나라도 위반하면 완료된 작업이 아니다.
|
||||
## 맡은 일
|
||||
|
||||
다음 HARD-STOP 7개 항목이 이 저장소의 정본(canonical) 로컬 정책 권위이자 SSOT다.
|
||||
먼저 `docs/work/README.md`, 그다음 맡은 일의 playbook 하나를 끝까지 읽는다(모두 `docs/work/`): 새 기능 `new-feature.md` · 리뷰·수정·리팩터링 `improve.md` · 대안 비교와 소유자 결정 `research-design.md` · 문서 `docs-writing.md` · 게이트·릴리스·파생 서비스 `operate.md` · 일 나누기 `delegate.md`. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.
|
||||
|
||||
1. `domain-core`가 framework, transport, database, cloud 의존성을 가진다.
|
||||
2. controller가 repository, Spring Data interface, persistence entity를 직접 사용한다.
|
||||
3. inbound DTO가 `application-core` 또는 `domain-core`로 유출된다.
|
||||
4. 비즈니스 규칙이 mapper, filter, configuration, settings, controller로 이동한다.
|
||||
5. 프로젝트 의존성이 `src/config/architecture/modules.json` 또는 Gradle 의존성 검증을 위반한다.
|
||||
6. 관련 검증 없이, 또는 실행하지 못한 이유를 밝히지 않고 완료를 주장한다.
|
||||
7. 결론의 범위와 위험에 맞는 증거 없이 repository/corpus 전체 결론을 내린다.
|
||||
## 검증
|
||||
|
||||
root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 한 줄씩 가리킨다. 두 문서가 어긋나면
|
||||
이 `AGENTS.md` 목록이 우선한다. 일의 종류별 절차는 `docs/work/`에 있다. 자동 강제 범위는 아래 Gradle
|
||||
정책 권위와 ArchUnit/Test가 담당한다.
|
||||
- leaf 하나: registry의 `gradle_path`로 `./gradlew <gradle-path>:check --console=plain`(`src/`에서). 기억이나 폴더 이름으로 짐작하지 않는다.
|
||||
- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때). 게이트 고르기는 `docs/work/reference/gates.md`.
|
||||
- 문서·지침을 고쳤으면 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`.
|
||||
|
||||
## Superpowers Workflow
|
||||
## 일하는 방식
|
||||
|
||||
이 프로젝트에서 에이전트는 관련 Superpowers 스킬을 먼저 확인하고, 작업 성격에 맞는 스킬을 사용한다. 사용자 지시와 이 `AGENTS.md`가 로컬 프로젝트의 최상위 규칙이며, Superpowers는 그 규칙을 실행하기 위한 작업 방식이다.
|
||||
|
||||
사용 가능한 주요 스킬과 트리거:
|
||||
|
||||
- `superpowers:using-superpowers`: 대화나 작업을 시작할 때 관련 스킬을 확인한다.
|
||||
- `superpowers:brainstorming`: 기능 설계, 구조 변경, 동작 변경, 새 문서 정책 수립 전에 사용한다.
|
||||
- `superpowers:writing-plans`: 승인된 설계가 있고 작업이 여러 단계로 나뉠 때 사용한다.
|
||||
- `superpowers:executing-plans`: 작성된 계획을 현재 세션에서 순차 실행할 때 사용한다.
|
||||
- `superpowers:subagent-driven-development`, `superpowers:dispatching-parallel-agents`: 이 저장소에서는
|
||||
쓰지 않는다. 세션 안의 하위 에이전트(Agent 도구)는 `.claude/settings.json`이 막는다. 일을 나눠
|
||||
맡길 때는 사람이 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). 다른 스킬이
|
||||
하위 에이전트를 띄우라고 하면 그 단계는 같은 세션이 직접 한다.
|
||||
- `superpowers:test-driven-development`: 기능 추가와 버그 수정을 테스트 우선으로 진행할 때 사용한다.
|
||||
- `superpowers:systematic-debugging`: 버그, 실패한 테스트, 예상 밖 동작을 다룰 때 사용한다.
|
||||
- `superpowers:verification-before-completion`: 완료, 수정됨, 통과함을 주장하기 전에 사용한다.
|
||||
- `superpowers:requesting-code-review`: 의미 있는 구현을 마친 뒤 병합 또는 PR 전에 사용한다.
|
||||
- `superpowers:receiving-code-review`: 리뷰 피드백을 적용하기 전에 사용한다.
|
||||
- `superpowers:finishing-a-development-branch`: 구현과 검증이 끝난 브랜치를 정리할 때 사용한다.
|
||||
- `superpowers:using-git-worktrees`: 격리된 작업 공간이 필요할 때 사용한다.
|
||||
- `superpowers:writing-skills`: 스킬을 만들거나 수정할 때 사용한다.
|
||||
|
||||
## Gradle 정책 권위
|
||||
|
||||
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로,
|
||||
Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다: 조립 루트가
|
||||
받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 SSOT는 registry다. 문서는 개수를 복제하지 않는다 —
|
||||
산문에 적힌 숫자는 leaf가 추가되는 순간 drift하기 때문이다. 이제 이걸 강제하는 태스크는 없다:
|
||||
`verifyDocumentedLeafCount`는 삭제됐다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬
|
||||
사유는 아니고, 그 태스크는 모든 `CLAUDE.md`와 `build.gradle`을 정규식으로 훑는 파서였다.
|
||||
- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어
|
||||
project를 include/mapping 한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖
|
||||
경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은
|
||||
`verifyCleanArchitectureDependencies`가 답한다 — settings에서 죽으면 실행할 수 있는 태스크가
|
||||
하나도 없다.
|
||||
- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나
|
||||
(`strictTestLanes`). leaf는 `ca.java-library` / `ca.spring-library` / `ca.platform-module` 중
|
||||
자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다.
|
||||
`ca.architecture`가 아키텍처 검증 태스크를 소유한다. 기능별 검사(notification·mongo·messaging·
|
||||
graphql·JPA readiness 등)는 build-logic이 아니라 소유 leaf의 테스트다. 테스트가 저장소 파일을 읽으면
|
||||
그 파일을 그 leaf의 test task `inputs`로 선언한다. 저장소 문서와 대조하는 테스트는 `mainStage()`
|
||||
레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다. 문서가 아닌 저장소 파일(빌드 스크립트,
|
||||
workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔
|
||||
별도 레인(app-bootstrap `repository-contract`)에 둔다. 저장소 루트(`ca.repository.root`)는 이 두
|
||||
레인에만 주므로 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다.
|
||||
- strict lane 캐시: `TEST`·`ARCHITECTURE` lane은 입력이 같으면 up-to-date·build cache를 쓴다.
|
||||
`INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼
|
||||
입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을
|
||||
입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.
|
||||
- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다: convention이 테스트 JVM에
|
||||
`performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면
|
||||
테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도).
|
||||
사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
|
||||
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의
|
||||
`ca.config-contract`다. 옛 included build `build-tools`는 지웠다(`docs/capability-status.md` 「제거된 코드」).
|
||||
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
|
||||
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
|
||||
--dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는
|
||||
단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·
|
||||
`releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`·
|
||||
`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈
|
||||
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
|
||||
lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·
|
||||
`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는
|
||||
짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다.
|
||||
(1) 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는
|
||||
파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤,
|
||||
`exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`. (2) 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌
|
||||
`&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나
|
||||
부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태
|
||||
함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만
|
||||
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore`
|
||||
필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches`
|
||||
없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이
|
||||
부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는
|
||||
job.
|
||||
(3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른
|
||||
명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤,
|
||||
`bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). 실패 메시지는 명령마다 이유를
|
||||
적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서
|
||||
시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다.
|
||||
|
||||
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
|
||||
함께 읽는다. focused test는 registry의 `gradle_path`에서
|
||||
`./gradlew <gradle-path>:test --console=plain` 형태로 파생한다. 파일 수만으로 위험을 판단하지 않고,
|
||||
변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다.
|
||||
|
||||
commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다.
|
||||
예외는 하나다: brief가 허용한 것만(commit과 push는 따로) 그 작업의 자기 브랜치에 한다. main 병합,
|
||||
다른 브랜치 push, force push는 하지 않는다(`docs/work/README.md` 「커밋」).
|
||||
|
||||
## 강제 수준
|
||||
|
||||
이 문서는 에이전트와 개발자가 따라야 할 작업 규칙을 정의하지만, 그 자체로 빌드나 테스트를 실패시키는 자동 강제 장치는 아니다.
|
||||
|
||||
이 프로젝트의 규칙은 세 단계로 관리한다.
|
||||
|
||||
1. `AGENTS.md`: 에이전트와 개발자가 따라야 할 아키텍처, 작업 순서, 검증 원칙을 정의한다.
|
||||
2. ArchUnit/Gradle/Test: 모듈 의존성, 계층 침범, 설정 바인딩, 동작 회귀를 자동으로 탐지한다.
|
||||
3. Code Review/CI: 문서와 자동 검증이 놓친 설계 품질, 운영 위험, 템플릿 일관성을 최종 확인한다.
|
||||
|
||||
에이전트는 `AGENTS.md`를 따라 작업해야 하며, 현업 수준의 스켈레톤 완성도는 반드시 자동 검증과 리뷰로 보강해야 한다.
|
||||
|
||||
## 모듈 책임
|
||||
|
||||
모든 leaf 모듈의 ID, 실제 소스 경로, Gradle path, 허용 production 의존성은
|
||||
`src/config/architecture/modules.json`이 SSOT다. focused test는 소유 leaf의 `gradle_path`에서
|
||||
파생한다. 이 문서는 leaf 목록을 복제하지 않고 family 책임만 정의한다. 작업 파일에서는 가장 가까운
|
||||
`src/**/CLAUDE.md`를 함께 읽는다.
|
||||
|
||||
- `domain-core`: 순수 도메인 모델, 불변식, 이벤트, port. Spring/JPA/transport/IO 타입 금지.
|
||||
- `application-core`: command, use case, application policy, transaction port, application 예외.
|
||||
inbound DTO, persistence entity, adapter 타입 금지.
|
||||
- `adapter:inbound:*`: HTTP/gRPC/GraphQL/WebSocket transport, DTO, validation, 인증·인가 매핑,
|
||||
error mapping. repository 직접 호출과 비즈니스 정책 금지.
|
||||
- `adapter:outbound:persistence-*`: JPA/PostgreSQL 또는 MongoDB persistence 구현과 mapping,
|
||||
migration/vendor 동작. 유스케이스 정책 금지.
|
||||
- 그 밖의 `adapter:outbound:*`: support, messaging, cache, notification, object storage,
|
||||
file server, HTTP client, identifier 능력을 port 뒤에서 구현한다. adapter 간 허용 edge는
|
||||
registry만 따른다.
|
||||
- `shared-contract`: skeleton-wide 운영 계약. business/domain 개념 저장 금지.
|
||||
- `app-bootstrap`: Spring Boot entrypoint와 composition root. 비즈니스 유스케이스 금지.
|
||||
|
||||
## 의존성 방향
|
||||
|
||||
family 수준 기본 방향:
|
||||
|
||||
```text
|
||||
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
|
||||
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
|
||||
runtime modules -> shared-contract
|
||||
```
|
||||
|
||||
개별 edge는 `src/config/architecture/modules.json`의 `allowed_dependencies`가 유일한 목록이다.
|
||||
Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억에서 leaf edge를 추론하지 않는다.
|
||||
|
||||
## 기능 개발 프로토콜
|
||||
|
||||
새 기능이나 동작 변경은 다음 순서로 진행한다.
|
||||
|
||||
1. 요구사항을 읽고 소유 계층을 판단한다.
|
||||
2. 구조나 동작이 바뀌면 `superpowers:brainstorming`으로 설계를 먼저 확정한다.
|
||||
3. 여러 단계의 작업이면 `docs/design/`에 설계 문서를 남긴다. 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다.
|
||||
4. 실행 계획이 필요하면 구현 전 `docs/history/plans/`에 둔다. 계획서도 머리 블록을 단다. 머리 블록 형식은 `docs/README.md`다.
|
||||
5. 동작 변경은 테스트를 먼저 작성한다.
|
||||
6. 새 비즈니스 개념은 `domain-core`에 먼저 둔다.
|
||||
7. 유스케이스는 `application-core` command와 use case/service method로 표현한다.
|
||||
8. 외부 연동은 registry가 가리키는 `adapter:outbound:*` leaf에서 port 구현으로 추가한다.
|
||||
9. endpoint는 마지막에 해당 `adapter:inbound:*` leaf에서 얇게 연결한다.
|
||||
10. focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다.
|
||||
|
||||
단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 `docs/manual/`, 뼈대는
|
||||
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. 실제 기능은 계층 leaf별로 나눈다.
|
||||
|
||||
## 테스트 전략
|
||||
|
||||
계층별 테스트 기준:
|
||||
|
||||
- `domain-core`: Spring 없이 순수 unit test로 도메인 규칙을 검증한다.
|
||||
- `application-core`: fake/in-memory port를 사용해 유스케이스 흐름을 검증한다.
|
||||
- `adapter:inbound:*`: transport validation, auth mapping, status/response contract를 검증한다.
|
||||
- `adapter:outbound:persistence-*`: persistence mapping, repository adapter, vendor/migration 동작을 검증한다.
|
||||
- 그 밖의 `adapter:outbound:*`: external capability adapter contract를 검증한다.
|
||||
- `app-bootstrap/settings`: configuration binding, validation, logging 설정을 검증한다.
|
||||
|
||||
테스트 작성 규칙 (새로 쓰거나 고치는 테스트에 적용):
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로
|
||||
쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
|
||||
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할
|
||||
것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다.
|
||||
예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때
|
||||
`// when & then`까지 허용). 한 줄 테스트와 ArchUnit `.check()`는 주석 없이 쓴다.
|
||||
4. `@Nested`는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다.
|
||||
5. then은 when의 결과 하나만 단언한다. 여러 필드는 `usingRecursiveComparison()` 또는
|
||||
`extracting(..).containsExactly(..)`로 한 번에 비교한다. `isNotNull`/`isPresent`/
|
||||
`doesNotThrowAnyException`만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외).
|
||||
예외는 타입과 reason/message를 함께 단언한다. 표 형태 입력은 `@ParameterizedTest`로 쓴다.
|
||||
6. 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는
|
||||
포트는 fake와 adapter가 같은 추상 계약 테스트(`XxxContract`)를 통과한다. Mockito는 프레임워크
|
||||
경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다.
|
||||
|
||||
GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고,
|
||||
실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다.
|
||||
|
||||
검증 원칙:
|
||||
|
||||
- 완료를 주장하기 전에 `superpowers:verification-before-completion`을 사용한다.
|
||||
- 실행한 명령과 결과를 최종 응답에 적는다.
|
||||
- 테스트를 실행하지 못했다면 이유와 남은 위험을 솔직히 적는다.
|
||||
|
||||
권장 절차:
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew <owner-gradle-path>:check --console=plain # 그 leaf만: 컴파일·테스트·포맷·스타일·ErrorProne
|
||||
./gradlew check # 모든 leaf의 check
|
||||
./gradlew architectureCheck # 의존 방향·domain-core/shared-contract/application-* 순수성·ArchUnit
|
||||
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
|
||||
./gradlew testQualityCheck # 같은 분석을 테스트 source set에(config/spotbugs/exclude-test.xml, main 단계·optional 빌드는 ci)
|
||||
./gradlew ci # PR 게이트 = leaf check + architecture + quality
|
||||
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
|
||||
./gradlew integrationCheck # 실제 컨테이너 integration 레인 전체(main·nightly, Docker 필요)
|
||||
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly). 상한은 항상 단언, 끄면 실패
|
||||
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p platforms/optional-build로 따로)
|
||||
./gradlew verifyPublicPathSnapshot
|
||||
./gradlew :app-bootstrap:verifyEnvKeys
|
||||
```
|
||||
|
||||
leaf의 `check`는 그 leaf만 검사한다. 저장소 전체 질문은 이름이 따로 있는 루트 태스크가 답한다.
|
||||
|
||||
소유 leaf의 정확한 Gradle path는 `src/config/architecture/modules.json`에서 읽고 focused test
|
||||
명령을 파생한다. root 문서에 leaf별 명령 목록을 복제하지 않는다.
|
||||
|
||||
## 부가 기능(capability) 모듈 규칙
|
||||
|
||||
Redis, Kafka, JPA 같은 부가 기능은 "의존성을 붙이면 켜지고, 떼면 사라지는 모듈"로 제공한다.
|
||||
각 서비스는 `app-bootstrap/build.gradle`에 필요한 모듈만 `runtimeOnly` 한 줄로 고른다.
|
||||
설계 근거는 `docs/design/2026-09-25-capability-module-packaging-design.md`.
|
||||
|
||||
템플릿 기본 조립은 web에서 쓰는 부분뿐이다: `adapter:inbound:web`, 운영 관측(actuator·metrics·
|
||||
tracing·로그), `domain-core`·`application-core`·`shared-contract`, `adapter:outbound:support`·
|
||||
`adapter:outbound:identifier`. 그 밖의 기능(JPA 포함)은 한 줄을 추가해서 켠다.
|
||||
|
||||
capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
|
||||
|
||||
1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다.
|
||||
2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled`
|
||||
설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 명시한다(`afterName`).
|
||||
3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키
|
||||
자체를 두지 않는다.
|
||||
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact
|
||||
constructor에서 한다.
|
||||
예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
|
||||
`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중
|
||||
하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/CLAUDE.md`.
|
||||
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두
|
||||
통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
|
||||
6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
|
||||
7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 스위치 목록에 등록하지
|
||||
않고, 한 줄을 지우면 기능이 완전히 사라진다.
|
||||
|
||||
모듈 설정 기본값은 `config/module-defaults/<모듈>.yml`에 두고 `adapter:outbound:support`의
|
||||
`ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. 의존성 closure에 support가 없는 leaf
|
||||
(persistence-mongo, graphql)만 자기 EPP가 `config/<이름>.yml`을 읽는다.
|
||||
|
||||
서비스 코드가 모듈 타입을 직접 호출해야 하는 라이브러리형 기능은 `runtimeOnly`로 컴파일되지
|
||||
않는다. 그런 기능은 가능한 한 포트 뒤로 옮기고, 불가피하면 서비스의 어댑터 leaf에서
|
||||
`implementation`으로 받는다.
|
||||
|
||||
## 설정과 런타임
|
||||
|
||||
설정 규칙:
|
||||
|
||||
- secrets를 코드, 테스트 fixture, 문서 예시에 하드코딩하지 않는다.
|
||||
- 새 설정 그룹은 typed settings class로 만든다.
|
||||
- 흩어진 `@Value`보다 configuration properties와 settings class를 선호한다.
|
||||
- `.env.local`은 로컬 오버라이드로 취급한다.
|
||||
- `application.yml`은 환경별로 안전한 기본값과 명확한 placeholder만 담는다.
|
||||
- 새 settings class를 만들면 binding/validation 테스트를 추가한다.
|
||||
|
||||
Docker/runtime 규칙:
|
||||
|
||||
- Dockerfile 변경 시 build context와 runtime env 요구사항을 함께 확인한다.
|
||||
- container 안에서 필요한 profile, port, env var를 문서나 예시 설정에 반영한다.
|
||||
- local-only 경로와 운영 경로를 섞지 않는다.
|
||||
|
||||
## 템플릿 재사용 체크리스트
|
||||
|
||||
이 저장소를 새 프로젝트 시작점으로 사용할 때:
|
||||
|
||||
1. `src/settings.gradle`의 `rootProject.name`을 새 프로젝트명으로 바꾼다.
|
||||
2. Java package `dev.caskeleton`을 새 organization/project package로 바꾼다.
|
||||
gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/`의
|
||||
디렉터리, 각 `.proto`의 `package`·`java_package`)도 함께 바꾸고 `buf lint`로 확인한다.
|
||||
3. `CaSkeletonApplication` 이름을 새 애플리케이션 이름으로 바꾼다.
|
||||
4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가한다.
|
||||
5. 모듈 이름과 경계는 유지한다.
|
||||
6. Docker image/application 이름을 새 프로젝트 기준으로 수정한다.
|
||||
7. `.env`, `.env.local`, `application.yml`의 예시 값을 새 런타임 요구사항에 맞춘다.
|
||||
8. README와 운영 문서를 새 프로젝트 설명으로 갱신한다.
|
||||
9. 전체 테스트를 실행한다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew test
|
||||
```
|
||||
|
||||
## 금지된 지름길
|
||||
|
||||
에이전트는 다음을 하지 않는다.
|
||||
|
||||
- `domain-core`에 Spring/JPA annotation 추가
|
||||
- controller에서 repository 직접 호출
|
||||
- application method가 web request DTO를 인자로 받게 만들기
|
||||
- application이나 domain에서 JPA entity 반환
|
||||
- mapper에 비즈니스 정책 넣기
|
||||
- filter/config/settings class에 유스케이스 넣기
|
||||
- 요청 범위 밖의 대규모 리팩터링
|
||||
- 사용자 변경사항 되돌리기
|
||||
- 명시적 요청 없는 destructive git command 실행
|
||||
- 테스트 미실행 상태에서 "완료"라고 말하기
|
||||
|
||||
## 작업 보고 규칙
|
||||
|
||||
최종 응답에는 다음을 포함한다.
|
||||
|
||||
- 변경한 파일
|
||||
- 핵심 변경 내용
|
||||
- 실행한 검증 명령
|
||||
- 실패하거나 실행하지 못한 검증
|
||||
- 남은 위험 또는 후속 작업
|
||||
|
||||
짧은 작업이라도 검증 여부는 생략하지 않는다.
|
||||
- 커밋 정책은 `human-only`다. brief가 허용한 것만 자기 브랜치에 한다(`docs/work/README.md` 4절).
|
||||
- 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
|
||||
- 일을 나눌 때는 소유자가 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). Gradle·Docker는 누가 돌려도 desktop에서다.
|
||||
|
||||
@@ -1,75 +1,6 @@
|
||||
# CLAUDE.md — 이 repo의 지도
|
||||
@AGENTS.md
|
||||
|
||||
이 파일은 세션이 처음 읽는 지도다. 규칙을 담지 않고, 어떤 일이면 무엇을 읽을지 가리킨다.
|
||||
## Claude Code에서만
|
||||
|
||||
## 1. 이 repo
|
||||
|
||||
- Java 21 + Spring Boot Gradle 멀티모듈(버전은 `src/gradle/libs.versions.toml`) Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다.
|
||||
- Gradle 루트는 `src/`다. Gradle 명령은 `src/`에서 실행한다.
|
||||
- 규칙의 정본은 `AGENTS.md`다. leaf 목록·경로·허용 의존의 정본은 `src/config/architecture/modules.json`(registry)이다. 각 leaf의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`가 정한다.
|
||||
|
||||
## 2. HARD-STOP — 하나라도 어기면 완료가 아니다
|
||||
|
||||
정본은 `AGENTS.md` 「Prime Directive」다. 두 문서가 다르면 `AGENTS.md`가 맞다.
|
||||
|
||||
1. `domain-core`가 framework·transport·database·cloud 의존성을 가진다.
|
||||
2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
|
||||
3. inbound DTO가 `application-core`나 `domain-core`로 들어간다.
|
||||
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
|
||||
5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
|
||||
6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
|
||||
7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
|
||||
|
||||
## 3. 맡은 일 → 읽을 문서
|
||||
|
||||
먼저 [docs/work/README.md](docs/work/README.md)를 읽는다. 크기 정하기, 모든 작업의 공통 단계, 커밋 규칙이 거기 있다. 그다음 맡은 일의 playbook 하나를 끝까지 읽는다.
|
||||
|
||||
| 맡은 일 | playbook |
|
||||
| --- | --- |
|
||||
| 새 업무 기능, 새 capability 모듈 | [docs/work/new-feature.md](docs/work/new-feature.md) → `docs/manual/` |
|
||||
| 리뷰, 결함 수정, 리팩터링, 성능, 구조·테스트 구조 개선 | [docs/work/improve.md](docs/work/improve.md) |
|
||||
| 바꾸기 전에 대안 비교와 소유자 결정 | [docs/work/research-design.md](docs/work/research-design.md) |
|
||||
| 매뉴얼·안내 문서 쓰기 | [docs/work/docs-writing.md](docs/work/docs-writing.md) |
|
||||
| 게이트 실행, desktop 검증, 릴리스, 파생 서비스 | [docs/work/operate.md](docs/work/operate.md) |
|
||||
| 큰 일을 나눠 다른 세션에 맡기기 | [docs/work/delegate.md](docs/work/delegate.md) |
|
||||
|
||||
brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 먼저다. playbook은 brief에 없는 공통 절차를 채운다.
|
||||
|
||||
## 4. 검증 명령과 실행 위치
|
||||
|
||||
- **실행 위치**: 소유자 환경에서는 Gradle·Docker·테스트·게이트를 desktop에서만 돌린다. 절차는 [docs/work/operate.md](docs/work/operate.md) 4.1절이다.
|
||||
- **leaf 하나**: registry에서 그 leaf의 `gradle_path`를 읽고 `./gradlew <gradle-path>:test --console=plain` 또는 `:check`를 돌린다. 기억이나 디렉터리 이름으로 Gradle path를 짐작하지 않는다.
|
||||
- **저장소 전체 질문**:
|
||||
|
||||
```bash
|
||||
./gradlew architectureCheck --console=plain
|
||||
./gradlew :app-bootstrap:architectureTest --console=plain
|
||||
./gradlew verifyPublicPathSnapshot --console=plain
|
||||
./gradlew :app-bootstrap:verifyEnvKeys --console=plain
|
||||
```
|
||||
|
||||
- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다.
|
||||
- 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다.
|
||||
- `docs/work/`, 이 파일, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다(분량, 본문 이력 ID 0, 상대 링크).
|
||||
- 문서(`.md`)나 문서가 가리키는 경로·Gradle 프로젝트를 바꿨으면 `python3 scripts/check-docs.py`를 돌린다(언어, 기록의 머리 블록, 참조, 복사한 숫자). PR마다 `docs-check` workflow가 같은 검사를 돈다. 규칙은 [docs/README.md](docs/README.md)다.
|
||||
|
||||
## 5. 코드만 보고는 헷갈리는 곳
|
||||
|
||||
- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. `scripts/check-repo-layout.py`(PR 게이트)가 허용 목록 밖의 최상위 항목을 막는다.
|
||||
- **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다.
|
||||
- **`src/platforms/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/platforms/messaging/CLAUDE.md`다.
|
||||
- **`composition:*` leaf는 조립만 한다.** outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 `runtimeOnly` 한 줄로 고른다.
|
||||
- **capability는 한 줄로 켜고 끈다.** 기본 조립은 web inbound, 운영 관측, core들, support·identifier뿐이다. JPA도 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켠다. 규칙은 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」이다.
|
||||
- **gRPC 플랫폼 라이브러리는 다른 빌드다.** `src/platforms/grpc/*`·`src/platforms/grpc-advanced/*`(registry의 `"build": "optional-grpc"`)는 `-p platforms/optional-build`로 돈다. `adapter:inbound:grpc`는 애플리케이션 adapter라 주 빌드에 있다.
|
||||
- **새 기능의 예시는 `scripts/new-feature.sh`의 출력이다.** 샘플 모듈은 2026-11-07에 지웠다. 기법 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)를 가리킨다.
|
||||
- **성능 lane에는 단언을 끄는 스위치가 없다.** convention이 상한을 매번 단언하고, `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(`AGENTS.md` 「Gradle 정책 권위」).
|
||||
- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow를 읽는 테스트는 `repository-contract`(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다.
|
||||
- **커밋 정책은 `human-only`다.** brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다.
|
||||
- **문서 위치 규칙은 [docs/README.md](docs/README.md)다.** 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 고치지 않는 기록(계획서·납품 패키지·증거·학습)은 `docs/history/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다. 기록은 맨 위 머리 블록만 고친다.
|
||||
|
||||
## 6. 소유자 환경
|
||||
|
||||
- 이 repo 소유자의 기계·세션 도구에 묶인 규칙은 두 곳에만 있다: [docs/work/operate.md](docs/work/operate.md) 4.1절(실행 위치)과 [docs/work/delegate.md](docs/work/delegate.md) 4.3절(세션). 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다.
|
||||
- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 일을 나눌 때는 delegate.md대로 별도 세션에 맡긴다.
|
||||
- 작업 사고 순서의 정본은 design-docs `conventions/work-thinking-order.md`, 커밋·PR 형식은 `conventions/commit-and-pr.md`다.
|
||||
- 보고 말투와 형식은 소유자의 전역 `~/.claude/CLAUDE.md`를 따른다.
|
||||
- 권한은 `.claude/settings.json`, 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 규칙은 그 경로의 파일을 열 때 읽힌다.
|
||||
- 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다.
|
||||
|
||||
@@ -74,7 +74,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
|
||||
- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다.
|
||||
- 줄마다 필요한 env 키와 끄는 키: [src/README.md](src/README.md) 「기능 추가 = 한 줄 + env」 표.
|
||||
- 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md).
|
||||
- capability 모듈이 지켜야 하는 규칙: [AGENTS.md](AGENTS.md) 「부가 기능(capability) 모듈 규칙」.
|
||||
- capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: [docs/manual/10-capabilities.md](docs/manual/10-capabilities.md).
|
||||
|
||||
뒷단 서비스는 `compose.yaml`의 profile로 고른다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있다.
|
||||
|
||||
@@ -110,7 +110,7 @@ cd src
|
||||
|
||||
## 새 서비스로 시작하기
|
||||
|
||||
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 전체 체크리스트는 [AGENTS.md](AGENTS.md) 「템플릿 재사용 체크리스트」다.
|
||||
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
|
||||
|
||||
1. `src/settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
|
||||
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
|
||||
@@ -122,6 +122,10 @@ cd src
|
||||
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다.
|
||||
4. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
|
||||
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
|
||||
6. gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`도 바꾼다. `src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/` 디렉터리와 각 `.proto`의 `package`·`java_package`다. `buf lint`로 확인한다.
|
||||
7. Docker 이미지 이름과 애플리케이션 이름(`spring.application.name`)을 새 서비스 기준으로 바꾼다.
|
||||
8. `src/.env.example`, `src/.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다.
|
||||
9. README와 운영 문서를 새 서비스 설명으로 고친다.
|
||||
|
||||
복사한 뒤 지워도 되는 것은 템플릿의 기록(`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`).
|
||||
|
||||
@@ -129,7 +133,7 @@ cd src
|
||||
|
||||
## 규칙과 기여
|
||||
|
||||
- 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다.
|
||||
- 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
|
||||
- 규칙의 정본이자 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 「HARD-STOP」 조건을 어기면 동작하더라도 병합하지 않는다. Claude Code 세션은 [CLAUDE.md](CLAUDE.md)가 이 파일을 가져온다.
|
||||
- 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
|
||||
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/AGENTS.md`다.
|
||||
- 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다.
|
||||
|
||||
+1
-1
@@ -19,7 +19,7 @@
|
||||
|
||||
| 폴더 | 무엇 |
|
||||
| --- | --- |
|
||||
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 |
|
||||
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `AGENTS.md` 다음에 읽는다 |
|
||||
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` |
|
||||
| `testing/` | 테스트 전략: 테스트 종류 다섯, source set, 어떤 테스트를 어디에 두나, Gradle 실행 계층 |
|
||||
|
||||
|
||||
@@ -79,7 +79,7 @@ verify-feature-scaffold.sh
|
||||
| 형태 | 결정 | 이유 |
|
||||
| --- | --- | --- |
|
||||
| `scripts/`의 bash + 텍스트 템플릿(`scripts/feature-scaffold/templates/**/*.tmpl`) | **채택** | 개발자 도구는 `scripts/`에 둔다는 repo 관례(`ca.developer-bootstrap` 플러그인을 지우고 `scripts/bootstrap-local.sh`로 옮긴 것, `src/build-logic/README.md`). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다 |
|
||||
| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`CLAUDE.md` Gradle policy). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
|
||||
| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`src/build-logic/AGENTS.md`). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
|
||||
| 생성 대신 예시 기능을 커밋해 두고 복사 | 버림 | 복사본이 하나 더 생겨 규칙과 갈라진다. 이름 바꾸기를 사람이 손으로 한다 |
|
||||
| 왕복 검사를 JUnit 안에서 javac로 컴파일 | 버림 | Spotless·Error Prone·ArchUnit 전체를 다시 구현해야 하고, 실제 게이트와 다른 것을 검사하게 된다. 실제 Gradle 게이트를 그대로 돌리는 쪽을 골랐다 |
|
||||
| 생성 뒤 자동 `spotlessApply` | 채택(끄려면 `--no-format`) | google-java-format이 Javadoc을 이름 길이에 따라 다시 접는다. 템플릿만으로는 모든 이름에서 포맷 검사를 통과시킬 수 없다 |
|
||||
@@ -90,7 +90,7 @@ verify-feature-scaffold.sh
|
||||
|
||||
| 파일 | 설정 | 왜 |
|
||||
| --- | --- | --- |
|
||||
| `src/domain-core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(AGENTS.md 테스트 규칙 6) |
|
||||
| `src/domain-core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(`.claude/rules/java-tests.md` 규칙 6) |
|
||||
| `src/application-core/build.gradle`, `src/adapter/inbound/web/build.gradle`, `src/app-bootstrap/build.gradle` | `testImplementation testFixtures(project(':domain-core'))` | 유스케이스·HTTP·조립 테스트가 그 fake를 쓴다 |
|
||||
| `src/adapter/inbound/web/build.gradle` | `implementation project(':domain-core')` | 컨트롤러가 경로 문자열을 도메인 id로 바꾼다 |
|
||||
| `src/adapter/outbound/identifier/build.gradle` | `implementation project(':domain-core')` | id adapter가 도메인 `IdFactory` 포트를 구현한다 |
|
||||
|
||||
@@ -32,7 +32,7 @@
|
||||
- **기본값**: ①. 업무 기능은 그 서비스의 존재 이유라 끌 일이 없다. 파일 추가만으로 끝나고, leaf 경계
|
||||
검사가 계층마다 걸린다.
|
||||
- **예외**: ② — 여러 서비스가 쓰는 플랫폼 기능, 배포마다 켜고 끄는 기능, 자기 설정 prefix와 자기
|
||||
저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(`AGENTS.md`, 10장).
|
||||
저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(10장).
|
||||
- **다시 볼 조건**: 파생 서비스가 둘 이상 생겨 같은 업무 기능을 공유하거나, application-core 컴파일·테스트
|
||||
시간이 문제가 되면 ①을 ②로 옮긴다.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 핵심
|
||||
|
||||
테스트 규칙의 정본은 `AGENTS.md` 「테스트 전략」이다. 이 장은 새 기능을 만들 때 그 규칙이 **어떤
|
||||
테스트 작성 규칙의 정본은 `.claude/rules/java-tests.md`이고, 계층별로 무엇을 검증하는지는 그 계층의 `AGENTS.md` 「테스트」 절이다. 이 장은 새 기능을 만들 때 그 규칙이 **어떤
|
||||
파일 배치가 되는지**와 **어느 단계(PR/main/integration)에서 도는지**를 적는다.
|
||||
|
||||
```text
|
||||
@@ -30,7 +30,7 @@ fake와 실제 adapter가 **같은 계약**을 통과해야 fake 위의 유스
|
||||
| inbound | HTTP status·Envelope·오류 코드 | 실제 유스케이스 + fake, standalone MockMvc | `<F>ControllerTest` |
|
||||
| bootstrap | 조립 조건(있을 때 켜짐, 없을 때 없음), imports 등록 | fake bean | `<F>ConfigTest` |
|
||||
|
||||
## 작성 규칙 요약 (정본은 AGENTS.md)
|
||||
## 작성 규칙 요약 (정본은 `.claude/rules/java-tests.md`)
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장. 이름이 말한 성질을 단언한다. 예: 이름에 "트랜잭션 전에"를 넣었으면
|
||||
트랜잭션이 없었다는 것도 단언하거나, 이름에서 뺀다.
|
||||
|
||||
@@ -17,7 +17,7 @@ app-bootstrap/build.gradle
|
||||
기능 XConfig의 @ConditionalOnBean(포트) → 유스케이스·엔드포인트가 켜진다
|
||||
```
|
||||
|
||||
정본: `AGENTS.md` 「부가 기능(capability) 모듈 규칙」(완료 기준 7개),
|
||||
이 장이 capability 규칙과 완료 기준 7개의 정본이다. 설계 근거는
|
||||
`docs/design/2026-09-25-capability-module-packaging-design.md`, 현황은 `docs/capability-status.md`.
|
||||
|
||||
## 켜기
|
||||
@@ -49,11 +49,23 @@ app-bootstrap/build.gradle
|
||||
| 1 | 서비스는 포트만 호출 | `runtimeOnly`로 컴파일되는가 |
|
||||
| 2 | 자기 `AutoConfiguration.imports`, 필요하면 `enabled` 스위치, 순서는 `afterName` | 모듈 자동 설정 테스트 |
|
||||
| 3 | 켜면 완전히 동작. 동작하지 않는 설정 키는 두지 않는다 | 설정 바인딩 테스트 |
|
||||
| 4 | 설정 prefix 하나(`app.<모듈>`), `StrictSettingsBinder`, 검증은 record compact constructor | Redis만 예외(AGENTS.md 기준 4) |
|
||||
| 4 | 설정 prefix 하나(`app.<모듈>`), `StrictSettingsBinder`, 검증은 record compact constructor | Redis만 예외(아래) |
|
||||
| 5 | 포트 계약 테스트를 fake와 실제 adapter가 모두 통과, 실 벤더(Testcontainers) 1개 이상 | strict lane(08장) |
|
||||
| 6 | README: 제공하는 것, 추가할 한 줄, env 키 | |
|
||||
| 7 | 이 모듈을 아는 곳은 모듈 자신뿐. bootstrap scan·스위치 목록에 등록하지 않는다 | 줄을 지우면 기능이 완전히 사라지는가 |
|
||||
|
||||
7개를 모두 충족해야 "포장 완료"다. 표의 뜻을 풀면 이렇다.
|
||||
|
||||
1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다.
|
||||
2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled` 설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 밝힌다(`afterName`).
|
||||
3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키 자체를 두지 않는다.
|
||||
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor에서 한다. 예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중 하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/AGENTS.md`.
|
||||
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 adapter가 모두 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
|
||||
6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
|
||||
7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 스위치 목록에 등록하지 않고, 한 줄을 지우면 기능이 완전히 사라진다.
|
||||
|
||||
모듈 설정 기본값은 그 모듈의 `src/main/resources/config/module-defaults/<모듈>.yml`에 두고 `adapter:outbound:support`의 `ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. 의존성 closure에 support가 없는 leaf(persistence-mongo, graphql)만 자기 EPP가 `config/<이름>.yml`을 읽는다.
|
||||
|
||||
등록할 공용 파일: `src/config/architecture/modules.json`(leaf와 허용 edge), `src/settings.gradle`이 읽는
|
||||
디렉터리 매핑, app-bootstrap의 허용 edge, 새 leaf lockfile. registry가 허용하지 않은 edge는
|
||||
`architectureCheck`(의존 방향)가 막는다.
|
||||
|
||||
@@ -40,14 +40,15 @@
|
||||
|
||||
| 무엇 | 정본 |
|
||||
| --- | --- |
|
||||
| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.md`) |
|
||||
| 계층 경계·금지 규칙 | `AGENTS.md`와 가장 가까운 `src/**/AGENTS.md` |
|
||||
| 테스트 작성 규칙 | `.claude/rules/java-tests.md` |
|
||||
| leaf 목록·허용 의존 | `src/config/architecture/modules.json` |
|
||||
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
|
||||
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/AGENTS.md` 「Canonical use case shape」「Allowed transactional shapes」 |
|
||||
| HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` |
|
||||
| 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` |
|
||||
| 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` |
|
||||
| capability 완료 기준 7개 | `AGENTS.md` 「부가 기능(capability) 모듈 규칙」 |
|
||||
| capability 완료 기준 7개 | [10-capabilities.md](10-capabilities.md) |
|
||||
|
||||
이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 **따른 결과**를 보여 줄 뿐이고,
|
||||
규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(`scripts/feature-scaffold/templates/`)이 규칙과
|
||||
|
||||
@@ -196,7 +196,7 @@ PERFORMANCE lane은 상한을 매번 단언한다. 측정만 하고 통과하는
|
||||
|
||||
## 9. application-core 포트의 공유 계약 현황 (review 2026-11-01 01-05·TEST-F-1)
|
||||
|
||||
규칙(`AGENTS.md` 테스트 규칙): 포트마다 fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와
|
||||
규칙(`.claude/rules/java-tests.md` 규칙 6): 포트마다 fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와
|
||||
모든 adapter가 같은 추상 계약 테스트(`*Contract`)를 상속한다. 실제 adapter의 계약 테스트는 그
|
||||
adapter leaf의 실 DB·Redis lane에서 돈다. fake가 실제와 다르게 동작하면 유스케이스 테스트가 거짓
|
||||
녹색이 되기 때문이다.
|
||||
|
||||
@@ -12,3 +12,5 @@
|
||||
| # | 바뀐 것 | 서비스가 할 일 |
|
||||
| --- | --- | --- |
|
||||
| 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src/<leaf>/CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) |
|
||||
| 2 | 루트 `AGENTS.md`가 규칙 정본이자 지도(40줄 이하: 비전·HARD-STOP·지도·맡은 일·검증·일하는 방식)가 됐다. 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄이다. 옛 `AGENTS.md`의 절은 옮겨 갔다: 「Gradle 정책 권위」 → `src/build-logic/AGENTS.md`, 「테스트 전략」의 작성 규칙 → `.claude/rules/java-tests.md`(계층별 기준은 각 계층 `AGENTS.md` 「테스트」), 「모듈 책임」 → `src/adapter/inbound/AGENTS.md`·`src/adapter/outbound/AGENTS.md`·각 core `AGENTS.md`, 「부가 기능(capability) 모듈 규칙」 → `docs/manual/10-capabilities.md`, 「설정과 런타임」 → `.claude/rules/settings-and-runtime.md`, 「템플릿 재사용 체크리스트」 → 루트 `README.md` 「새 서비스로 시작하기」. 「Superpowers Workflow」·「강제 수준」·「금지된 지름길」·「작업 보고 규칙」은 HARD-STOP·전역 규칙과 같은 말이라 지웠다 | 서비스가 루트 `AGENTS.md`나 `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 서비스 고유의 줄은 새 `AGENTS.md`의 같은 절(40줄 안)이나 위 새 자리에 옮긴다. 서비스 문서가 옛 절 이름(「Gradle 정책 권위」 등)을 가리키면 새 자리로 바꾼다 |
|
||||
| 3 | `.claude/rules/`(경로별 규칙)를 추적한다. `.gitignore`에 `!.claude/rules/`를 더했다 | 서비스 `.gitignore`가 `.claude/*`를 무시하면 같은 줄을 더한다 |
|
||||
|
||||
+5
-5
@@ -1,7 +1,7 @@
|
||||
# 작업 매뉴얼
|
||||
|
||||
이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다.
|
||||
읽는 순서는 하나다: 루트 `CLAUDE.md`(지도) → 이 README → 맡은 일의 playbook 하나.
|
||||
읽는 순서는 하나다: 루트 `AGENTS.md`(지도) → 이 README → 맡은 일의 playbook 하나. Claude Code 세션에서는 루트 `CLAUDE.md`가 `AGENTS.md`를 가져온다.
|
||||
규칙의 정본은 `AGENTS.md`와 registry(`src/config/architecture/modules.json`)다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다.
|
||||
|
||||
## 1. 어떤 playbook인가
|
||||
@@ -32,7 +32,7 @@
|
||||
1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다.
|
||||
2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
|
||||
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다.
|
||||
4. 스킬을 고른다. 정본은 `AGENTS.md` 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다.
|
||||
4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다([delegate.md](delegate.md) 4.3절).
|
||||
5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
|
||||
6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다.
|
||||
7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
|
||||
@@ -72,6 +72,6 @@
|
||||
|
||||
## 8. 이 폴더를 고칠 때
|
||||
|
||||
- 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 `AGENTS.md`와 `src/**/CLAUDE.md`도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다.
|
||||
- 이 폴더, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 규칙·스킬·서브에이전트 문서도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다.
|
||||
- 이 폴더, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
|
||||
@@ -68,7 +68,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
| `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 |
|
||||
| `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 |
|
||||
| `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 |
|
||||
| `AGENTS.md`, 루트 `CLAUDE.md`, `docs/work/` | 모든 세션이 읽는다 |
|
||||
| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/` | 모든 세션이 읽거나 모든 세션에 걸린다 |
|
||||
| `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 |
|
||||
|
||||
나눌 때 지킬 것:
|
||||
|
||||
@@ -36,7 +36,7 @@
|
||||
7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다.
|
||||
8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다.
|
||||
9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(지도 3절: brief가 먼저다).
|
||||
10. `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다.
|
||||
10. `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다.
|
||||
11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다.
|
||||
12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`.
|
||||
- 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어 `--history`로 돌린다. `docs/reviews/**` 밖 전체(`git ls-files '*.md' ':!docs/reviews'`)에도 돌려 새로 걸린 줄을 모두 읽는다. 검사 대상 파일의 오탐은 패턴을 좁혀 없애고, 대상 밖의 오탐은 보고에 적는다.
|
||||
@@ -52,7 +52,7 @@
|
||||
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
|
||||
- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다.
|
||||
- 정본을 복사한 문장이 없다. 가리키는 줄만 있다.
|
||||
- `docs/work/`·루트 `CLAUDE.md`·`AGENTS.md`·`src/**/CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
|
||||
- `docs/work/`·루트 `AGENTS.md`·`CLAUDE.md`·`src/**/AGENTS.md`·`.claude/` 아래 문서를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
|
||||
- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그).
|
||||
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
|
||||
|
||||
|
||||
@@ -61,7 +61,7 @@
|
||||
- RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다.
|
||||
4. 가장 작은 수정으로 GREEN을 본다.
|
||||
5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다. 찾은 자리가 brief 영역 안이고 공개 동작이 바뀌지 않으면 함께 고치고 보고에 적는다. 공개 동작이 바뀌거나 brief 영역 밖이면 고치지 않고 「범위 밖에서 본 것」에 권하는 안과 함께 적는다. 묶음 상한(4.4절)도 지킨다.
|
||||
6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`CLAUDE.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다.
|
||||
6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`AGENTS.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다.
|
||||
7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 적고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. 문서에 이미 적힌 규칙을 검사가 더 엄하게 지키게 되어 그 규칙을 어기던 코드가 새로 실패하는 것도 여기에 든다(규칙은 이미 정해져 있어 크기는 올리지 않는다).
|
||||
- 안내의 범위(머리 「범위」)가 아직 main에 합쳐지지 않았으면 파생 서비스는 그 행을 받기 전이다. 같은 표면의 행이 있으면 그 행을 고쳐 최종 동작을 적고, 머리 「커밋:」 목록에 이번 커밋을 더한다. main에 합쳐진 안내는 고치지 않고 새 행을 더한다.
|
||||
8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)).
|
||||
@@ -102,7 +102,7 @@
|
||||
- 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과).
|
||||
- 구조 변경: `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`가 통과한다. 문서에 leaf 개수를 적지 않았다.
|
||||
- 테스트 구조: 변이가 잡혔다. 새 lane이 단계에 속한다. `testQualityCheck`가 통과한다.
|
||||
- `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
|
||||
- `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
|
||||
|
||||
## 6. 하지 말 것
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@
|
||||
|
||||
1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다.
|
||||
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/AGENTS.md` 「Package ownership」)와 겹치지 않는지 본다.
|
||||
3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다.
|
||||
3. capability 모듈이면 `docs/manual/10-capabilities.md`의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다.
|
||||
4. 뼈대를 만든다: `scripts/new-feature.sh <FeatureName>`(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」).
|
||||
5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다.
|
||||
6. 기능에 필요한 장만 더 읽는다: 저장(04), 재시도될 쓰기(05), 오류(06), 권한(07), 테스트 배치(08), 이벤트(09).
|
||||
|
||||
@@ -105,8 +105,8 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree'
|
||||
- 파생 서비스는 이 템플릿을 받아 도메인을 채운 repo다. 템플릿 변경을 두 방식으로 받는다: 기준 커밋을 적은 tracked snapshot에 3-way로 반영하거나(`template.lock.json`), `git merge upstream/main`을 한다.
|
||||
- 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다.
|
||||
- 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다.
|
||||
- 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md` 지도에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다.
|
||||
- `.claude/settings.json`(Agent 도구 금지)은 추적 파일이라 함께 넘어간다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다.
|
||||
- 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다.
|
||||
- `.claude/`의 추적 파일(`settings.json`의 Agent 도구 금지, `rules/`)은 함께 넘어간다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다.
|
||||
- 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다.
|
||||
|
||||
## 5. 완료 기준
|
||||
|
||||
@@ -32,10 +32,10 @@
|
||||
|
||||
| 주제 | 결정 | 누가 | 날짜 | 출처 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 |
|
||||
| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「일하는 방식」 |
|
||||
| 커밋 예외 | brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다. main 병합·main 또는 다른 브랜치 push·force push는 하지 않는다 | 소유자(2026-11-06), 커밋과 push를 나눠 읽는 것은 기본값(2026-11-06) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」, `docs/work/README.md` 4절, `docs/work/evidence.md` 9절 |
|
||||
| 리뷰 README 분담 | 리뷰어는 리뷰 폴더 README에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면(독립 리뷰어 둘 포함) 색인 절도 총괄이 쓰고, 리뷰어는 보고의 색인 표를 `check-review-index.py --extra-index`로 대조해 rc=0을 보인다 | 기본값 | 2026-11-06, 2026-11-07 | `docs/work/evidence.md` 9·11절 |
|
||||
| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`. 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 |
|
||||
| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`(2026-11-07부터 `src/**/AGENTS.md`, 루트 `CLAUDE.md`, `.claude/` 아래 문서). 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 |
|
||||
| 커밋 단위 | 커밋 하나에 논리 변경 하나(`conventions/commit-and-pr.md` 3.1절). 수정 묶음은 브랜치 하나이고 결함(또는 같은 원인)마다 커밋을 나눈다. 나눈 커밋마다 그 커밋이 바꾼 leaf `check`를 돌리고, 무거운 묶음은 마지막 트리에서 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 |
|
||||
| 넘어온 「범위 밖」 항목 | 수정 세션의 「범위 밖에서 본 것」은 총괄이 README 남은 항목으로 옮기고(멈춤 기준 4가 센다), 다음 확인 리뷰가 brief를 받아 판정한다. 「정한 기본값」은 처리 표와 이 색인 기본값 행으로 옮긴다 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 |
|
||||
| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/operate.md` 4.1절 |
|
||||
@@ -47,15 +47,17 @@
|
||||
| 무거운 실행 위치 | 노트북에서 Gradle·Docker를 돌리지 않는다. desktop에서 브랜치를 받아 돌린다 | 소유자 | 2026-11-05 | `1103` 17.1절 |
|
||||
| desktop 공유 잠금 | desktop의 Gradle·Docker 실행은 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 프론트와 부하·포트(4173·4174)가 겹치지 않게 | 총괄 지시 | 2026-11-05 | 2026-11-05 총괄 세션 brief, design-docs `conventions/delegation-loop.md` 11절 |
|
||||
| 세션 분업 | 총괄 세션은 지휘만, 실제 작업은 하위 세션 | 소유자 | 2026-11-05 | design-docs `conventions/delegation-loop.md` 2절 |
|
||||
| 하위 에이전트 | Agent 도구(세션 안의 하위 에이전트)를 쓰지 않는다. 막는 장치는 두 템플릿 repo의 프로젝트 설정(`.claude/settings.json`) | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D5 |
|
||||
| 매뉴얼 체계 | 짧은 지도(`CLAUDE.md`) + 작업 종류별 playbook(`docs/work/`) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작 | 소유자 | 2026-11-06 | 같은 문서 D1, D4 |
|
||||
| 하위 에이전트 | ~~Agent 도구(세션 안의 하위 에이전트)를 쓰지 않는다. 막는 장치는 두 템플릿 repo의 프로젝트 설정(`.claude/settings.json`)~~ → 아래 「서브에이전트와 하위 세션」 행에서 바꿈 | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D5 |
|
||||
| 서브에이전트와 하위 세션 | Agent 금지를 푼다. 결과만 받는 일(검색, 구조 리뷰, 직접 돌려 보는 검증, 코드 단순화 제안)은 서브에이전트(`.claude/agents/`)에 맡기고, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션에 맡긴다. Gradle·Docker는 서브에이전트도 desktop에서만 | 소유자 | 2026-11-07 | design-docs `harness/01-harness-design.md` 13절 Q5 |
|
||||
| 매뉴얼 체계 | ~~짧은 지도(`CLAUDE.md`) + 작업 종류별 playbook(`docs/work/`) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작~~ → 아래 「지침 배치」 행에서 바꿈 | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D1, D4 |
|
||||
| 지침 배치 | 정본은 루트 `AGENTS.md`(40줄 이하: 비전·지도·HARD-STOP), 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄. 폴더 규칙은 그 폴더 `AGENTS.md`(`CLAUDE.md`가 가져옴), 폴더를 가로지르는 파일 종류 규칙은 `.claude/rules/`, 특정 시점 절차는 모델이 부르는 스킬(`.claude/skills/`), 예외 없는 규칙은 훅(편집 직후 넛지, 되돌릴 수 없는 것만 차단)·게이트. 편집 훅은 그 파일 하나만 Gradle 없이 포맷한다 | 소유자 | 2026-11-07 | design-docs `harness/01-harness-design.md` 13절 Q1·Q2·Q3·Q6·Q9 |
|
||||
| 크기별 생략 | 작음·중간·큼으로 사고 순서 단계를 줄인다. 크기는 맡기는 쪽이 정하고 맡은 쪽은 올리기만 한다 | 소유자 | 2026-11-06 | 같은 문서 D2, design-docs `conventions/work-thinking-order.md` |
|
||||
| 매뉴얼 검사 장치 | 이력 ID·분량 검사와 리뷰 색인 검사는 Gradle 밖 `scripts/`(`check-work-docs.py`, `check-review-index.py`) | 소유자 | 2026-11-06 | 같은 문서 D6 |
|
||||
| 규칙 ID | 규칙마다 ID(`R-…`)는 아직 붙이지 않는다. 원장이 생길 때 붙인다 | 소유자 | 2026-11-06 | 같은 문서 D7 |
|
||||
| 옛 개선 매뉴얼 | 브랜치 `claude/improvement-manual-6ae516`은 병합하지 않고 재료로만 쓴다 | 소유자 | 2026-11-06 | 같은 문서 D12 |
|
||||
| 개선 매뉴얼을 먼저(지난 것) | 다음 개선 작업 전에 repo마다 개선 매뉴얼을 만든다 → 2026-11-06 「매뉴얼 체계」로 바뀜 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 brief |
|
||||
| 스킬 | 리뷰·수정에 알맞은 스킬을 쓴다 | 소유자 | 2026-11-05 | `1103` 2절 |
|
||||
| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `AGENTS.md` 테스트 작성 규칙 2 |
|
||||
| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `.claude/rules/java-tests.md` 규칙 2 |
|
||||
| 학습 문서(지난 것) | 삭제된 코드를 설명하는 학습 문서(지금 `docs/history/study/*.ko.md`, `docs/history/packages/*-superpowers-package/`)는 현재 코드에 맞게 갱신 → 2026-11-07 갱신하지 않고 기록으로 보관(머리 블록만 단다)으로 바뀜 | 소유자 | 2026-09-25 | 결정 6, design-docs `repo-structure/README.md` 3.2절 |
|
||||
| 문서 체계 | 문서를 수명으로 나눈다. 살아 있는 문서는 제자리에 두고 한국어로 옮긴다. 기록은 `docs/history/`, 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`에 둔다. 폴더 이름은 짝 프론트와 같이 쓴다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, 적용은 `docs/README.md` |
|
||||
| 한국어의 범위 | 살아 있는 문서는 본문까지 한국어로 쓴다. 기록 문서는 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달고 본문은 원문 그대로 둔다. 상태는 한국어 고정 어휘다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
|
||||
@@ -74,7 +76,7 @@
|
||||
| --- | --- | --- | --- |
|
||||
| outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 `composition:*` 모듈 | 소유자 | 결정 3 |
|
||||
| 새 leaf | `composition:durable-operation`, `adapter:inbound:messaging` 등록 승인 | 위임 | `1101` 15절 |
|
||||
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`·`grpc:*`)는 복사본을 두고 family `CLAUDE.md`에 이유 | 위임 | `1101` 15절(01-11) |
|
||||
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`·`grpc:*`)는 복사본을 두고 family `AGENTS.md`에 이유 | 위임 | `1101` 15절(01-11) |
|
||||
| caller 트랜잭션 guard | `persistence-notification`·`persistence-fileserver` → `persistence-jpa` edge, `CallerTransaction` 하나 | 소유자 | 결정 33 |
|
||||
| id 포트 | notification·fileserver id 포트를 domain `IdFactory`로 옮기지 않음(보류) | 소유자 | 결정 34 |
|
||||
| 소비자 없는 필드 | principal tenant, GraphQL Spring Security resolver, 가명화 키 분리는 하지 않음(보류) | 소유자 | 결정 35 |
|
||||
@@ -170,7 +172,7 @@
|
||||
| 개발 compose Redis | lane Redis에 ACL 계정, "기동 WARN 없음" 검사 유지 | 위임 | `1101` 15절(r3-J) |
|
||||
| 서블릿 오류 디스패치 | 보안 체인이 ERROR 디스패치만 허용 | 기본값 | `1103` 6절 r4-b, 8절 |
|
||||
| 설정 prefix | `app.*`로 통일, `APP_*` env 키 유지 | 소유자 | 결정 16 |
|
||||
| Redis prefix 예외 | `app.redis.*`·`app.capabilities.*`·`app.rate-limit.*` 세 트리 유지, 네 번째 금지 | 위임 | `1101` 15절(05-18), `AGENTS.md` capability 기준 4 |
|
||||
| Redis prefix 예외 | `app.redis.*`·`app.capabilities.*`·`app.rate-limit.*` 세 트리 유지, 네 번째 금지 | 위임 | `1101` 15절(05-18), `docs/manual/10-capabilities.md` 기준 4 |
|
||||
| 로그 설정 | logback이 `app.logging.*`을 읽음, `APP_CACHE_REDIS_TTL_JITTER` deprecated | 위임 | `1101` 15절(07) |
|
||||
| 빈 env 값 | 선택 숫자 설정의 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 | 위임 | `1101` 15절 |
|
||||
| `APP_FLYWAY_ENABLED` | dev·prod에도 적용 | 위임 | `1101` 15절(r3-F) |
|
||||
@@ -191,8 +193,8 @@
|
||||
| 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 |
|
||||
| lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) |
|
||||
| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② |
|
||||
| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `AGENTS.md` 「Gradle 정책 권위」 |
|
||||
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `AGENTS.md` 「Gradle 정책 권위」 |
|
||||
| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `src/build-logic/AGENTS.md` 「lane 캐시와 성능 lane」 |
|
||||
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `src/build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」 |
|
||||
| MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) |
|
||||
| Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | `1101` 15절(09-11) |
|
||||
| httpclient reactive | 삭제 | 소유자 | 결정 9 |
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다.
|
||||
|
||||
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
|
||||
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 의존 방향)와 family·leaf의 책임·금지 절을 담은 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
|
||||
|
||||
## 패턴
|
||||
|
||||
@@ -45,7 +45,7 @@
|
||||
|
||||
- **모양**: 이름이 말한 성질을 단언하지 않는다. 지키려는 코드를 지워도 통과한다. 시간 제한 대기의 결과를 버린다. 계약 케이스를 skip한다.
|
||||
- **막는 기준**: [review-criteria.md](review-criteria.md) 7절 점검표. 변이로 확인한다. skip은 0이거나 설계 이유를 적는다.
|
||||
- **장치**: 포트당 fake와 공유 계약 상속(`AGENTS.md` 테스트 작성 규칙 6), `rejectSkipped`.
|
||||
- **장치**: 포트당 fake와 공유 계약 상속(`.claude/rules/java-tests.md` 규칙 6), `rejectSkipped`.
|
||||
|
||||
### A7. 거짓 통과 게이트
|
||||
|
||||
|
||||
@@ -48,9 +48,9 @@
|
||||
| env 키 | `:app-bootstrap:verifyEnvKeys` |
|
||||
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` |
|
||||
| 의존성 | `verifyDependencyLocks` |
|
||||
| 문서(`docs/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` |
|
||||
| 문서(`docs/**`, `AGENTS.md`·`CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` |
|
||||
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) |
|
||||
| `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md` | `python3 scripts/check-work-docs.py` |
|
||||
| `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` |
|
||||
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
|
||||
| build-logic·workflow | `-p build-logic check javadoc`, 두 빌드의 `verifyStrictLaneStages --dry-run` |
|
||||
| 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) |
|
||||
@@ -177,7 +177,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
|
||||
|
||||
## 5. 성능 lane
|
||||
|
||||
- performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `AGENTS.md` 「Gradle 정책 권위」와 `docs/testing/TESTING_STRATEGY.md`의 PERFORMANCE 문단이다.
|
||||
- performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `src/build-logic/AGENTS.md` 「lane 캐시와 성능 lane」과 `docs/testing/TESTING_STRATEGY.md`의 PERFORMANCE 문단이다.
|
||||
- strict lane convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣는다. leaf나 lane은 이 값을 선언하지 않는다.
|
||||
- 빌드(`-P`, `GRADLE_OPTS`)나 lane이 `true` 아닌 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다. `-Pperformance.assertions.enabled=true`는 받지만 줄 필요가 없다.
|
||||
- 그래서 desktop에서 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
|
||||
@@ -199,7 +199,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
|
||||
| --- | --- |
|
||||
| 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) |
|
||||
| optional 빌드를 보지 않음 | optional 빌드도 같은 검사 |
|
||||
| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `AGENTS.md` 「Gradle 정책 권위」의 세는 규칙 |
|
||||
| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `src/build-logic/AGENTS.md` 「`verifyStrictLaneStages`가 세는 명령」 |
|
||||
| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 |
|
||||
| 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) |
|
||||
| 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 |
|
||||
|
||||
@@ -70,7 +70,7 @@
|
||||
|
||||
| 수준 | 이 repo의 증거 | 주장할 수 없는 것 |
|
||||
| --- | --- | --- |
|
||||
| E0 설명·주장 | README, `CLAUDE.md`, Javadoc, 리뷰 문서의 이전 실행 기록, 묶음 보고의 "통과" | 현재 커밋의 동작 |
|
||||
| E0 설명·주장 | README, `AGENTS.md`·`CLAUDE.md`, Javadoc, 리뷰 문서의 이전 실행 기록, 묶음 보고의 "통과" | 현재 커밋의 동작 |
|
||||
| E1 정적 확인 | 현재 커밋의 코드·설정·`build.gradle`·workflow를 `file:line`으로 읽음, `--dry-run` 그래프 | 실행 결과 |
|
||||
| E2 테스트 실행 | 이름을 댄 테스트, leaf `check`, `ci`가 현재 커밋에서 통과(명령, rc, 테스트 수) | 실 vendor, 부하, 장애 |
|
||||
| E3 통합·실험 | Testcontainers 실 PostgreSQL·Redis·Kafka·MinIO lane, `java -jar`·compose 실제 기동, 부하·장애 주입·동시 요청 실험 | 운영 환경, 운영 기간 |
|
||||
@@ -147,7 +147,7 @@
|
||||
|
||||
## 7. 테스트가 증명해야 하는 것
|
||||
|
||||
정본: 테스트 작성 규칙은 `AGENTS.md` 「테스트 전략」, 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`(기계 기준 `TestLaneCategory`), 새 기능의 테스트 배치는 `docs/manual/08-testing.md`다.
|
||||
정본: 테스트 작성 규칙은 `.claude/rules/java-tests.md`, 계층별 검증 기준은 그 계층의 `AGENTS.md` 「테스트」 절, 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`(기계 기준 `TestLaneCategory`), 새 기능의 테스트 배치는 `docs/manual/08-testing.md`다.
|
||||
|
||||
| 점검 | 결함 모양 |
|
||||
| --- | --- |
|
||||
|
||||
@@ -43,7 +43,7 @@
|
||||
python3 scripts/check-docs.py --only head # 하나만 (language, head, reference, number, map, readme)
|
||||
python3 -m unittest discover -s scripts/tests # 이 검사의 시험
|
||||
|
||||
Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(AGENTS.md 「Gradle 정책 권위」).
|
||||
Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(src/build-logic/AGENTS.md 「저장소 파일을 읽는 테스트」).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
추적 파일만 본다(git ls-files). build 출력과 IDE 폴더는 처음부터 대상이 아니다.
|
||||
|
||||
새 최상위 항목이 정말 필요하면 아래 목록과 루트 CLAUDE.md 5절 「최상위 폴더는 정해진 것만 둔다」를 같은
|
||||
새 최상위 항목이 정말 필요하면 아래 목록과 루트 AGENTS.md 「지도」의 최상위 줄을 같은
|
||||
변경에서 고친다. 최상위 폴더를 만들거나 옮기는 일은 파일 하나여도 큰 일이다(docs/work/README.md 2절).
|
||||
|
||||
Gradle 밖에 둔다: 빌드는 저장소 배치를 판단하지 않는다(scripts/check-work-docs.py와 같은 자리).
|
||||
@@ -38,7 +38,7 @@ REGISTRY = "src/config/architecture/modules.json"
|
||||
# 저장소 루트: 문서·스크립트·CI·개발 환경과 Gradle 루트(src)뿐이다.
|
||||
ROOT_ALLOWED = {
|
||||
# 폴더
|
||||
".claude": "에이전트 세션 설정(추적되는 settings.json)",
|
||||
".claude": "Claude Code 세션 설정(추적: settings.json의 권한·훅, rules·skills·agents)",
|
||||
".github": "workflow와 공용 action",
|
||||
"compose": "compose.yaml이 마운트하는 보조 파일",
|
||||
"docs": "문서",
|
||||
@@ -50,8 +50,8 @@ ROOT_ALLOWED = {
|
||||
".lycheeignore": "링크 검사(lychee)가 건너뛸 URL. lychee는 저장소 루트의 이 이름만 읽는다",
|
||||
".tool-versions": "JDK 버전 고정",
|
||||
".trivyignore.yaml": "취약점 검사 예외",
|
||||
"AGENTS.md": "규칙 정본",
|
||||
"CLAUDE.md": "작업 지도",
|
||||
"AGENTS.md": "규칙 정본이자 작업 지도",
|
||||
"CLAUDE.md": "Claude Code 진입점(AGENTS.md를 가져온다)",
|
||||
"README.md": "저장소 소개",
|
||||
"compose.yaml": "개발 환경(하나뿐)",
|
||||
"renovate.json": "의존성 갱신 봇 설정",
|
||||
@@ -195,8 +195,8 @@ def main() -> int:
|
||||
print(f"FAIL: {failure}", file=sys.stderr)
|
||||
print(
|
||||
"check-repo-layout: a new top-level entry changes the repository's shape. If it is "
|
||||
"wanted, add it to the allow list in scripts/check-repo-layout.py and to CLAUDE.md "
|
||||
"section 5 in the same change.",
|
||||
"wanted, add it to the allow list in scripts/check-repo-layout.py and to the map in "
|
||||
"AGENTS.md in the same change.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
|
||||
+44
-21
@@ -1,18 +1,22 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Fail when the work manual stops being readable without history or grows past its size limits.
|
||||
|
||||
The work manual is the root `CLAUDE.md` (the map) plus `docs/work/`. A session that has never seen
|
||||
this repository's history reads the map, `docs/work/README.md` and one playbook, and must be able
|
||||
to finish the job from those alone. Two things break that, and both are mechanical:
|
||||
The work manual is the root `AGENTS.md` (the map and the rule book) plus `docs/work/`. A Claude Code
|
||||
session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and adds a few
|
||||
Claude-only lines. A session that has never seen this repository's history reads the map,
|
||||
`docs/work/README.md` and one playbook, and must be able to finish the job from those alone. Two
|
||||
things break that, and both are mechanical:
|
||||
|
||||
1. History IDs in the body. A sentence such as "fixed as in 1101/05-01" means nothing to a reader
|
||||
who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference
|
||||
files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`).
|
||||
The same rule covers the other files a new session reads first: the rule book `AGENTS.md` and
|
||||
every `src/**/AGENTS.md` (owner decision 2026-11-07). Module READMEs, design documents and
|
||||
`docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository.
|
||||
2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a
|
||||
total limit, so a session reads the whole path instead of skimming it.
|
||||
The same rule covers the other files a new session reads first: the root `AGENTS.md` and
|
||||
`CLAUDE.md`, and every folder rule book `src/**/AGENTS.md` (owner decision 2026-11-07). Module
|
||||
READMEs, design documents and `docs/reviews/**` keep their IDs, because a reader can follow them
|
||||
from inside the repository.
|
||||
2. Length. Each entry file has a line limit, and the entry path (map + root `CLAUDE.md` + README +
|
||||
one playbook) has a total limit, so a session reads the whole path instead of skimming it. The
|
||||
map limit is 40 lines (owner decision 2026-11-07: vision, map and HARD-STOP only).
|
||||
|
||||
It also checks that every playbook keeps the shared nine-section skeleton, that the
|
||||
"common mistakes" section stays short, and that relative links in the checked files resolve.
|
||||
@@ -34,8 +38,10 @@ import sys
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
MAP = REPO_ROOT / "CLAUDE.md"
|
||||
RULE_BOOK = REPO_ROOT / "AGENTS.md"
|
||||
MAP = REPO_ROOT / "AGENTS.md"
|
||||
CLAUDE_ENTRY = REPO_ROOT / "CLAUDE.md"
|
||||
IMPORT_LINE = "@AGENTS.md"
|
||||
CLAUDE_FOLDERS = ("rules", "skills", "agents")
|
||||
WORK = REPO_ROOT / "docs/work"
|
||||
README = WORK / "README.md"
|
||||
|
||||
@@ -58,7 +64,8 @@ EVIDENCE = "evidence.md"
|
||||
# Files that may name history, relative to docs/work/. Everything else must not.
|
||||
HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-patterns.md"}
|
||||
|
||||
MAP_LIMIT = 120
|
||||
MAP_LIMIT = 40
|
||||
CLAUDE_ENTRY_LIMIT = 10
|
||||
README_LIMIT = 80
|
||||
PLAYBOOK_LIMIT = 150
|
||||
ENTRY_PATH_LIMIT = 350
|
||||
@@ -134,7 +141,7 @@ def line_count(path: Path) -> int:
|
||||
|
||||
|
||||
def check_exists(errors: list[str]) -> bool:
|
||||
expected = [MAP, RULE_BOOK, README, WORK / EVIDENCE]
|
||||
expected = [MAP, CLAUDE_ENTRY, README, WORK / EVIDENCE]
|
||||
expected += [WORK / name for name in PLAYBOOKS + REFERENCES]
|
||||
missing = [rel(path) for path in expected if not path.is_file()]
|
||||
for name in missing:
|
||||
@@ -143,12 +150,12 @@ def check_exists(errors: list[str]) -> bool:
|
||||
|
||||
|
||||
def check_limits(errors: list[str], report: list[str]) -> None:
|
||||
for path, limit in [(MAP, MAP_LIMIT), (README, README_LIMIT)]:
|
||||
for path, limit in [(MAP, MAP_LIMIT), (CLAUDE_ENTRY, CLAUDE_ENTRY_LIMIT), (README, README_LIMIT)]:
|
||||
lines = line_count(path)
|
||||
report.append(f"{rel(path)}: {lines}/{limit}")
|
||||
if lines > limit:
|
||||
errors.append(f"{rel(path)}: {lines} lines, limit {limit}")
|
||||
base = line_count(MAP) + line_count(README)
|
||||
base = line_count(MAP) + line_count(CLAUDE_ENTRY) + line_count(README)
|
||||
for name in PLAYBOOKS:
|
||||
path = WORK / name
|
||||
lines = line_count(path)
|
||||
@@ -158,7 +165,7 @@ def check_limits(errors: list[str], report: list[str]) -> None:
|
||||
errors.append(f"{rel(path)}: {lines} lines, limit {PLAYBOOK_LIMIT}")
|
||||
if entry > ENTRY_PATH_LIMIT:
|
||||
errors.append(
|
||||
f"{rel(path)}: entry path CLAUDE.md + docs/work/README.md + this file is {entry} lines,"
|
||||
f"{rel(path)}: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {entry} lines,"
|
||||
f" limit {ENTRY_PATH_LIMIT}"
|
||||
)
|
||||
|
||||
@@ -195,19 +202,33 @@ def check_skeleton(errors: list[str]) -> None:
|
||||
)
|
||||
|
||||
|
||||
SKIPPED_PARTS = {"build", ".gradle", "node_modules"}
|
||||
|
||||
|
||||
def module_guides() -> list[Path]:
|
||||
"""Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output.
|
||||
The src/**/CLAUDE.md beside it is one line, `@AGENTS.md`, so Claude Code reads the same book."""
|
||||
skipped = {"build", ".gradle", "node_modules"}
|
||||
"""Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output."""
|
||||
return sorted(
|
||||
path
|
||||
for path in (REPO_ROOT / "src").rglob("AGENTS.md")
|
||||
if not skipped.intersection(path.relative_to(REPO_ROOT).parts)
|
||||
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts)
|
||||
)
|
||||
|
||||
|
||||
def check_claude_entry(errors: list[str]) -> None:
|
||||
"""The root CLAUDE.md starts with the import, so a Claude Code session reads the map."""
|
||||
lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines()
|
||||
if not lines or lines[0].strip() != IMPORT_LINE:
|
||||
errors.append(f"{rel(CLAUDE_ENTRY)}: the first line must be '{IMPORT_LINE}'")
|
||||
|
||||
|
||||
def claude_documents() -> list[Path]:
|
||||
"""The tracked Claude Code documents a session reads: path rules, skills, subagent definitions.
|
||||
Only these folders: the rest of .claude/ is local state (worktrees, settings.local.json)."""
|
||||
return sorted(path for folder in CLAUDE_FOLDERS for path in (REPO_ROOT / ".claude" / folder).rglob("*.md"))
|
||||
|
||||
|
||||
def history_checked_files() -> list[Path]:
|
||||
files = [MAP, RULE_BOOK]
|
||||
files = [MAP, CLAUDE_ENTRY] + claude_documents()
|
||||
for path in sorted(WORK.rglob("*.md")):
|
||||
if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED:
|
||||
files.append(path)
|
||||
@@ -266,7 +287,8 @@ def check_history(errors: list[str], report: list[str]) -> None:
|
||||
|
||||
|
||||
def check_links(errors: list[str], report: list[str]) -> None:
|
||||
checked, broken = broken_links([MAP, RULE_BOOK] + sorted(WORK.rglob("*.md")))
|
||||
checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + module_guides()
|
||||
+ claude_documents())
|
||||
for path, number, target in broken:
|
||||
errors.append(f"{rel(path)}:{number}: broken relative link '{target}'")
|
||||
report.append(f"relative links checked: {checked}")
|
||||
@@ -311,6 +333,7 @@ def main() -> int:
|
||||
report: list[str] = []
|
||||
if check_exists(errors):
|
||||
check_limits(errors, report)
|
||||
check_claude_entry(errors)
|
||||
check_skeleton(errors)
|
||||
check_history(errors, report)
|
||||
check_links(errors, report)
|
||||
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
# src — 빌드 스크립트 / 환경 변수 참조
|
||||
|
||||
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
|
||||
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다.
|
||||
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [AGENTS.md](../AGENTS.md),
|
||||
모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다.
|
||||
|
||||
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
|
||||
결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# adapter:inbound:* — inbound adapter family 공통 규칙
|
||||
|
||||
모든 inbound leaf에 같은 규칙만 적는다. leaf마다 자기 폴더의 `AGENTS.md`가 그 leaf의 자세한 규칙(등록 정보, 허용·금지, 테스트 명령)을 둔다. 루트 `AGENTS.md` HARD-STOP이 이 문서와 leaf 문서보다 먼저다.
|
||||
|
||||
## 책임
|
||||
|
||||
- HTTP·gRPC·GraphQL·WebSocket·메시지 수신 같은 transport, 요청·응답 DTO, 입력 검증, 인증·인가 매핑, 오류 매핑.
|
||||
- 요청 DTO를 `application-core`의 command·query로 바꿔 유스케이스를 부른다. 엔드포인트는 얇게 둔다.
|
||||
|
||||
## 금지
|
||||
|
||||
- repository·Spring Data interface·persistence entity를 직접 쓴다(HARD-STOP 2).
|
||||
- inbound DTO를 `application-core`·`domain-core`로 넘긴다(HARD-STOP 3).
|
||||
- 업무 정책을 controller·mapper·filter에 둔다(HARD-STOP 4).
|
||||
- registry `allowed_dependencies`에 없는 leaf에 기댄다(HARD-STOP 5).
|
||||
|
||||
## 테스트
|
||||
|
||||
- transport 검증, 인증·인가 매핑, 상태 코드와 응답 계약을 검증한다.
|
||||
- 작성 규칙은 `.claude/rules/java-tests.md`다.
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -344,7 +344,7 @@ resolver 마다 deadline 을 검사하게 하는 방법은 adopter 가 기억해
|
||||
|
||||
아래 타입은 auto-configuration 이 빈으로 만들지 않는다. 서비스가 자기 GraphQL 어댑터 leaf 에서
|
||||
`implementation project(':adapter:inbound:graphql')` 로 받아 resolver 안에서 직접 생성·호출한다
|
||||
(AGENTS.md capability 규칙의 라이브러리형 예외). 켜는 설정 키는 없다.
|
||||
(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외). 켜는 설정 키는 없다.
|
||||
|
||||
| 기능 | 진입점 | 테스트 |
|
||||
| --- | --- | --- |
|
||||
|
||||
@@ -16,7 +16,7 @@ implementation project(':adapter:inbound:web-advanced')
|
||||
|
||||
registry(`src/config/architecture/modules.json`)의 그 leaf `allowed_dependencies` 에
|
||||
`adapter-inbound-web-advanced` 를 더한다. 서비스 코드가 타입을 직접 부르므로 `runtimeOnly` 로는 안 된다
|
||||
(AGENTS.md capability 규칙의 라이브러리형 예외).
|
||||
(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외).
|
||||
|
||||
## 제공하는 것
|
||||
|
||||
|
||||
@@ -107,7 +107,7 @@ simple broker는 한 프로세스 안의 best-effort 전달이다. 영속·트
|
||||
## 라이브러리 API — 서비스의 어댑터 leaf에서 직접 조립
|
||||
|
||||
설정 키도 자동 설정도 없다. 서비스의 어댑터 leaf가 `implementation project(':adapter:inbound:websocket')`로
|
||||
받아 아래 타입을 직접 만든다(AGENTS.md capability 규칙의 라이브러리형 예외).
|
||||
받아 아래 타입을 직접 만든다(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외).
|
||||
|
||||
| 진입점 | 역할 |
|
||||
| --- | --- |
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# adapter:outbound:* — outbound adapter family 공통 규칙
|
||||
|
||||
모든 outbound leaf에 같은 규칙만 적는다. leaf마다 자기 폴더의 `AGENTS.md`가 그 leaf의 자세한 규칙(등록 정보, 허용·금지, 테스트 명령)을 둔다. 루트 `AGENTS.md` HARD-STOP이 이 문서와 leaf 문서보다 먼저다.
|
||||
|
||||
## 책임
|
||||
|
||||
- `persistence-*`: JPA·PostgreSQL 또는 MongoDB 영속 구현과 mapping, migration·vendor 동작.
|
||||
- 그 밖의 leaf: support, messaging, cache, notification, object storage, file server, HTTP client, identifier 능력을 application이 가진 port 뒤에서 구현한다.
|
||||
|
||||
## 금지
|
||||
|
||||
- 유스케이스 정책을 adapter에 둔다(HARD-STOP 4).
|
||||
- registry `allowed_dependencies`에 없는 adapter끼리의 edge(HARD-STOP 5). 허용 edge는 registry만 정한다.
|
||||
- 이미 적용된 migration 파일을 고친다. 새 버전 파일을 더하고 `persistence-jpa`의 `src/test/resources/db/applied-migrations.sha256`에 한 줄을 더한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
- `persistence-*`: persistence mapping, repository adapter, vendor·migration 동작을 실제 DB로 검증한다.
|
||||
- 그 밖의 leaf: port 계약(fake와 adapter가 같은 추상 계약 테스트를 상속)과 외부 능력 adapter 계약을 검증한다.
|
||||
- 작성 규칙은 `.claude/rules/java-tests.md`다.
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -83,4 +83,4 @@ transport 포트(`BlockingTransportProvider`)에는 test fixtures에 추상 계
|
||||
`testkit/BlockingTransportProviderContract`가 있다. engine은 실제 socket 위에서 그것을 통과하고
|
||||
(`StableTransportProviderContractTest`, 계약 lane, 고른 transport마다 한 번), gateway 시험이 딛고 서는 각본
|
||||
fake는 기본 lane에서 그것을 통과한다(`ScriptedTransportContractTest`). 새 transport나 `ScriptedTransport`의
|
||||
변경은 사본이 아니라 같은 클래스를 상속한다(AGENTS.md 규칙 6).
|
||||
변경은 사본이 아니라 같은 클래스를 상속한다(`.claude/rules/java-tests.md` 규칙 6).
|
||||
|
||||
@@ -133,7 +133,7 @@ generation 준비, traffic 전환, 옛 lease 비우기, 닫기 — 는 `MongoCli
|
||||
`MongoAdvancedCapabilityFlags`와 guard를 만든다. Stable 자동 구성은 `..advanced..` 아래의 어떤 것도 참조하면 안
|
||||
된다.
|
||||
- 이 leaf가 바인딩하는 모든 설정 키는 동작을 바꿔야 한다. 아무것도 읽지 않는 키나, 효과가 기동 실패뿐인 키는
|
||||
문서로 남기지 않고 지운다(AGENTS.md capability 규칙 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다.
|
||||
문서로 남기지 않고 지운다(`docs/manual/10-capabilities.md` 기준 3). `docs/capability-status.md`가 무엇을 왜 지웠는지 적는다.
|
||||
- 인터페이스는 이 leaf 안에 구현이 있을 때만 싣는다. Search, vector, time series, GridFS는 계약만 있었고
|
||||
2026-09-25에 지웠다.
|
||||
- observation tag는 `MongoObservationConvention`의 허용 목록으로 제한한다.
|
||||
|
||||
@@ -147,7 +147,7 @@ Mongo auto-configuration 이름을 Boot 자신의 등록 파일에서 읽어 배
|
||||
## 라이브러리 API — 서비스의 어댑터 leaf에서 `implementation`으로 받아 직접 호출
|
||||
|
||||
bean으로 등록되지 않고 설정 키도 없다. 서비스의 Mongo 어댑터 leaf가 이 leaf를 `implementation`으로
|
||||
받아 생성자로 만든다(AGENTS.md capability 규칙의 라이브러리형 예외). 테스트 열은 그 진입점을 검증하는 이 leaf의 테스트다.
|
||||
받아 생성자로 만든다(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외). 테스트 열은 그 진입점을 검증하는 이 leaf의 테스트다.
|
||||
|
||||
소비 leaf를 만드는 절차(레지스트리 edge, Gradle 줄, collection profile 등록, 예외 변환, 정책을 우회하는
|
||||
경로)는 [`docs/mongodb/consumer-leaf-guide.md`](../../../../docs/mongodb/consumer-leaf-guide.md)에 있다.
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
|
||||
**capability가 아니라 라이브러리다.** 이 leaf가 classpath에 있다고 켜지는 것은 없다: `AutoConfiguration.imports`가
|
||||
없고, bean을 만들지 않고, 자기 `enabled` 스위치가 없다. 서비스 코드가 그 타입을 직접 부르므로 `runtimeOnly`로
|
||||
받을 수 없다(AGENTS.md, capability 규칙의 라이브러리 타입 예외).
|
||||
받을 수 없다(`docs/manual/10-capabilities.md` 「판단」의 라이브러리형 예외).
|
||||
|
||||
## 더하기
|
||||
|
||||
|
||||
@@ -114,6 +114,9 @@
|
||||
|
||||
## 테스트
|
||||
|
||||
- `settings` 패키지: 설정 바인딩, 값 검증, 로깅 설정을 검증한다. 새 settings 클래스에는 바인딩·검증 테스트를 더한다.
|
||||
- 설정·런타임·Docker 규칙은 `.claude/rules/settings-and-runtime.md`다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :app-bootstrap:test
|
||||
|
||||
+1
-1
@@ -309,7 +309,7 @@ class DeveloperExperienceContractTest {
|
||||
@DisplayName("루트 안내 문서는 아키텍처 suite를 그 source set의 태스크 이름으로 안내한다")
|
||||
void guidanceNamesTheArchitectureSourceSetTask() throws IOException {
|
||||
// when
|
||||
String guidance = read("CLAUDE.md");
|
||||
String guidance = read("AGENTS.md");
|
||||
|
||||
// then
|
||||
assertThat(guidance)
|
||||
|
||||
@@ -326,6 +326,9 @@ hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
|
||||
|
||||
## 테스트
|
||||
|
||||
- fake·in-memory 포트로 유스케이스 흐름을 검증한다. Spring context를 띄우지 않는다.
|
||||
- 포트마다 fake 하나와 추상 계약 테스트(`*Contract`)를 이 모듈 testFixtures에 둔다. 작성 규칙은 `.claude/rules/java-tests.md`다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :application-core:test
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
# build-logic — Gradle 정책 권위
|
||||
|
||||
registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. `src/build-logic/`, `src/settings.gradle`, `src/build.gradle`, `src/config/architecture/modules.json`을 고칠 때 읽는다. 루트 `AGENTS.md` HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 `docs/work/reference/gates.md`다.
|
||||
|
||||
## 정본 넷
|
||||
|
||||
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
|
||||
- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
|
||||
- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.
|
||||
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전·리비전.
|
||||
|
||||
## 저장소 파일을 읽는 테스트
|
||||
|
||||
- 테스트가 저장소 파일을 읽으면 그 파일을 그 leaf의 test task `inputs`로 선언한다.
|
||||
- 저장소 문서와 대조하는 테스트는 `mainStage()` 레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다.
|
||||
- 문서가 아닌 저장소 파일(빌드 스크립트, workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔 별도 레인(app-bootstrap `repository-contract`)에 둔다.
|
||||
- 저장소 루트(`ca.repository.root`)는 이 두 레인에만 준다. 그래서 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다.
|
||||
- 문서를 파싱해 대조하는 Gradle 검사는 두지 않는다. 문서 검사는 Gradle 밖 `scripts/check-docs.py`·`scripts/check-work-docs.py`다.
|
||||
|
||||
## lane 캐시와 성능 lane
|
||||
|
||||
- `TEST`·`ARCHITECTURE` lane은 입력이 같으면 up-to-date·build cache를 쓴다. `INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼 입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을 입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.
|
||||
- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다. convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
|
||||
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 `ca.config-contract`다.
|
||||
|
||||
## `verifyStrictLaneStages`가 세는 명령
|
||||
|
||||
`verifyStrictLaneStages --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀 lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다.
|
||||
|
||||
1. 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, `exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`.
|
||||
2. 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌 `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나 부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태 함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore` 필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches` 없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job.
|
||||
3. 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤, `bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`).
|
||||
|
||||
실패 메시지는 명령마다 이유를 적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서 시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
- `./gradlew -p build-logic test --console=plain`(`src/`에서). build-logic은 Spotless 대상이 아니다.
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,12 @@
|
||||
# composition:* — 조립 leaf family 공통 규칙
|
||||
|
||||
`composition:*` leaf는 조립만 한다. outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼, 서비스 실행 환경처럼 `app-bootstrap`에서 떼어 낸 조립이다. 서비스는 `src/app-bootstrap/build.gradle`에서 필요한 것만 `runtimeOnly` 한 줄로 고른다. leaf마다 자기 폴더의 `AGENTS.md`나 README가 자세한 규칙을 둔다.
|
||||
|
||||
## 금지
|
||||
|
||||
- 업무 규칙과 SQL. 조립에 필요한 타입만 쓴다.
|
||||
- registry `allowed_dependencies`에 없는 edge. 어떤 adapter를 아는지는 그 leaf의 registry 행이 정한다. outbox relay·멱등성은 포트만 알고, 알림·파일 서버 플랫폼은 자기 adapter를 함께 조립한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
- 설정 바인딩, 기동 거절 조건, 종료 순서처럼 조립이 가진 것만 검증한다. 업무 동작은 core와 adapter의 테스트가 맡는다.
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -32,6 +32,9 @@
|
||||
|
||||
## 테스트
|
||||
|
||||
- Spring 없이 순수 unit test로 도메인 규칙과 불변식을 검증한다.
|
||||
- 도메인이 가진 포트의 fake와 추상 계약 테스트(`*Contract`)는 이 모듈 testFixtures에 둔다. 작성 규칙은 `.claude/rules/java-tests.md`다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :domain-core:test
|
||||
|
||||
Reference in New Issue
Block a user