Files
clean-architecture-backend-…/.claude/rules/java-tests.md
T
DongHyeonka 3c73fc333c 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행.
2026-11-07 21:59:42 +09:00

3.1 KiB

paths
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절).