Files
clean-architecture-backend-…/AGENTS.md
T
DongHyeonka d46bab9659
pr / gradle (pull_request) Successful in 16m42s
pr / vulnerabilities (pull_request) Successful in 37s
pr / done (pull_request) Canceled after 0s
ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).

소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.

- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
  `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
  (trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
  configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
  PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
  jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
  레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
  앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
  `needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
  저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
  계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
  바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
  선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
  run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
  needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
  working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
  하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
  (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
  TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
  트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
  손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
  포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
  RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
  .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
  AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
  docs/upgrade B-57~B-61.

버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.

위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.

BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
2026-11-08 21:55:43 +09:00

3.8 KiB

AGENTS.md — 백엔드 템플릿의 정본

Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 src/gradle/libs.versions.toml, 기본 패키지 dev.caskeleton). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다.

HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다

  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. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.

지도

  • 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.

맡은 일

먼저 docs/work/README.md, 그다음 맡은 일의 playbook 하나를 끝까지 읽는다(모두 docs/work/): 새 기능 new-feature.md · 리뷰·수정·리팩터링 improve.md · 대안 비교와 소유자 결정 research-design.md · 문서 docs-writing.md · 게이트·릴리스·파생 서비스 operate.md · 일 나누기 delegate.md. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.

검증

  • 진입점은 scripts/verify.sh <단계>다. 단계 이름은 workflow와 같다(pr·main·nightly·release, 그리고 docs·leaf·app·round). Gradle·Docker가 드는 단계는 스크립트가 desktop으로 옮겨 잠금 아래에서 돌린다.
  • leaf 하나: scripts/verify.sh leaf <gradle-path>. 경로는 registry의 gradle_path다. 기억이나 폴더 이름으로 짐작하지 않는다.
  • 저장소 전체: ./gradlew architectureCheck, ./gradlew :app-bootstrap:architectureTest, verifyPublicPathSnapshot·:app-bootstrap:verifyEnvKeys(그 표면을 바꿨을 때, src/에서), 단계 묶음은 scripts/verify.sh pr 등. 게이트 고르기는 docs/work/reference/gates.md.
  • 문서·지침을 고쳤으면 scripts/verify.sh docs(노트북에서 돈다).

일하는 방식

  • 커밋 정책은 human-only다. brief가 허용한 것만 자기 브랜치에 한다(docs/work/README.md 4절).
  • 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
  • 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(docs/work/delegate.md).