문제: 저장소 전체 ArchUnit suite가 약속한 것을 막지 못하는 길이 다섯이다.
1. controller가 domain repository 포트(생성 명령이 aggregate 옆
dev.caskeleton.domain.<feature>에 두는 <Aggregate>Repository)를 주입해도
걸리지 않는다. 규칙은 ..repository.. 패키지와 Spring Data·JPA 타입만 본다.
gRPC 서비스는 controller 판정에 들지 않는다(HARD-STOP 2).
2. ..adapter.inbound.. 밖의 사용자 전송(조립 모듈의 controller 등)이
@SystemInvoked 유스케이스를 new로 만들어 부르거나, 표시 없는 중간 클래스를
거쳐 부르면 통과한다. 매뉴얼 07은 이것을 "빌드 실패"라고 약속한다. app
AGENTS의 "bootstrap에 controller 금지"도 검사가 없다.
3. web 패키지 밖에 둔 Spring Security 요청 경로 확장점(JWT converter,
AuthorizationManager, AuthenticationProvider, 필터 chain DSL)은 servlet 타입을
쓰지 않아 사용자 전송으로 보이지 않는다.
4. 설정이 interceptor를 자기 클래스 타입 필드로 쥐고
registration.interceptors(x)로 넘기면, ArchUnit 1.3은 ChannelRegistration
(설정용 타입)만 기록해 설정이 사용자 전송이 되지 않는다.
5. capabilityProjects에 :adapter:inbound:messaging이 없어 저장소 전체 suite가
MessagingInboxAutoConfiguration을 읽지 않는다("suite가 모든 모듈을 본다"는
주석과 다름).
고른 방법:
1. ENDPOINTS_DO_NOT_HOLD_PERSISTENCE_PORTS: controller와 gRPC 서비스는
..domain..·..application..의 *Repository·*StorePort·*QueryPort에 의존하지
않는다.
2. CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS, 그리고
USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS의 전이 대상에 @SystemInvoked
유스케이스 자신을 더한다.
3. org.springframework.security.web·config.annotation.web·
oauth2.server.resource·oauth2.jwt 패키지와 AuthenticationProvider·
AuthorizationManager를 사용자 전송·요청 처리기 목록에 더한다.
4. 설정이 의존하는 프로젝트 클래스가 요청 처리기 타입을 상속·구현하면 그
설정도 사용자 전송으로 본다.
5. capabilityProjects와 주석 처리된 runtimeOnly 줄에 inbound messaging을 더한다.
매뉴얼 07 표와 app AGENTS를 같이 고쳤다. 지금 운영 코드에 걸리는 곳은
없다(inbound가 그런 포트를 import한 곳 0, 조립 모듈 controller 0).
버린 대안: inbound가 application *Port 전부를 못 쓰게 하기 — web이
AuthorizationPort·CorrelationIdPort를 구현하고 쓰므로 맞는 코드가 걸린다.
IdFactory는 지금 DurableOperationController가 쓰고 있어 이번 규칙에서 뺐다
(그 controller의 id 생성은 리뷰 RR9-05-13로 따로 고친다).
위험·한계: 규칙 3·4는 목록·클래스 의존 방식이라, 목록에 없는 보안 타입이나
타입 이름이 남지 않는 길(bean 이름 조회, 함수로 감싸 넘기기)은 여전히
못 본다(매뉴얼 07 「규칙이 못 보는 길」). gRPC 서비스 fixture는 io.grpc가
architectureTest 컴파일 classpath에 없어 두지 않았다 — 판정은
BindableService 이름으로 한다.
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 새 fixture와 시험(새 규칙 대신 기존 규칙을 부르는
변형)만으로 ArchitectureViolationFixtureTest 204건 중 5건 실패 — 다섯 위반
모두 기존 규칙에 안 걸림. 허용 시험은 통과.
- GREEN: :app-bootstrap:resolveAndLockAll --write-locks(잠금 변화 없음),
spotlessApply 뒤 :app-bootstrap:architectureTest 259건 실패 0,
:app-bootstrap:testQualityCheck, :app-bootstrap:spotlessCheck,
:verifyDependencyLocks, :architectureCheck rc=0. 로그 desktop
~/r9-be-logs/b14-{red,green2}.log.
Refs: docs/reviews/2026-11-12-round9-review RR9-05-01~05
docs
저장소의 모든 문서는 이 폴더 아래에 있다. 이 README는 두 가지를 정한다.
- 어떤 문서가 어느 폴더에 있나: 아래 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
- 문서의 수명에 따라 무엇을 어떤 언어로 고치나: 「문서 수명과 언어」.
파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.
문서 지도
- 표의 첫 칸이 폴더다(
docs/기준 경로). - 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
python3 scripts/check-docs.py의map검사가 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(「문서 검사」).
매뉴얼
일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.
| 폴더 | 무엇 |
|---|---|
work/ |
작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 AGENTS.md 다음에 읽는다 |
manual/ |
개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(scripts/new-feature.sh). 입구는 work/new-feature.md |
ledger/ |
예측·실측 장부: 작업마다 착수 예측(p30·p50·p80과 근거)과 끝 실측을 한 줄씩 쌓는다(ledger/estimates.jsonl, 형식은 ledger/README.md) |
testing/ |
테스트 전략: 테스트 종류 다섯, source set, 어떤 테스트를 어디에 두나, Gradle 실행 계층 |
계약과 스냅숏
코드와 테스트가 대조하는 정본이다. 바꾸면 공개 계약이 바뀔 수 있다(work/README.md 2절).
| 폴더 | 무엇 |
|---|---|
registries/ |
레지스트리: env 키, 오류 코드, 메트릭, HTTP 헤더, 로그(MDC) 키, 비밀 분류, use case capability, 객체 저장소 준비도. 테스트가 코드와 대조한다 |
web/ |
HTTP wire 계약(web/http-contract.md), PATCH·스트리밍 계약, 선택형 web 기능(web-advanced), web 장애 대응 |
architecture/ |
공개 API 표면 스냅숏(*-api-surface.txt). API surface 검사가 대조한다 |
security/ |
기본 공개 경로 스냅숏. verifyPublicPathSnapshot이 대조한다 |
observability/ |
구조화 로그 필드 사전 |
영역 운영 문서
capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마이그레이션이다. 코드와 같은 변경에서 고친다.
httpclient/는 scripts/verify-httpclient-docs.py가 코드에서 뽑은 이름과 대조한다.
| 폴더 | 무엇 |
|---|---|
fileserver/ |
파일 서버 |
httpclient/ |
외부 HTTP 호출(HTTP client 플랫폼) |
jpa/ |
JPA·PostgreSQL 영속성 |
mongodb/ |
MongoDB 문서 영속성 |
mongodb/advanced/ |
MongoDB 고급 기능(암호화, 멀티 테넌시, 샤딩). 설정 키가 아니라 라이브러리 API로 켠다 |
mongodb/runbooks/ |
MongoDB 장애 대응 |
mongo/ |
MongoDB 영속성 설정 예시 파일(Spring이 읽지 않는 예시) |
notification/ |
알림 전달 플랫폼 |
objectstorage/ |
객체 저장소의 설정 필드와 env 이름 표(env-fields.yaml) |
redis/ |
Redis 캐시·세션 |
websocket/ |
WebSocket handler 장애 대응 |
운영과 전달
| 폴더 | 무엇 |
|---|---|
runbooks/ |
오류 코드별 장애 대응 런북(runbooks/template.md 형식) |
ci-cd/ |
CI/CD 경계: 검증·빌드(CI)와 배포(CD)의 경계, 템플릿과 파생 서비스가 각각 돌릴 검증 |
upgrade/ |
파생 서비스용 변경 안내: 템플릿 변경을 받을 때 서비스가 할 일 |
roadmap/ |
아직 구현하지 않은 다음 단계와 그 조건 |
결정 기록
| 폴더 | 무엇 |
|---|---|
adr/ |
결정 기록(ADR). 영역마다 파일 이름 앞머리가 다르다(ADR-JPA-, NOTIF-ADR- 등) |
설계와 기록
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
| 폴더 | 무엇 |
|---|---|
design/ |
설계서. YYYY-MM-DD-<주제>-design.md |
history/plans/ |
구현·확장 계획서. YYYY-MM-DD-<주제>-plan.md |
history/packages/ |
외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
history/evidence/ |
작업 단계별 증거·체크포인트 |
history/study/ |
학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 |
reviews/ |
코드 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나 |
history/packages/<어댑터>/는 설계서가 처음 전달됐을 때의 안내와 VALIDATION.md 검증 이력을
남긴 기록 보관소다. 설계서·계획서 본문은 전부 design/과 history/plans/에 있으므로 이 폴더에서
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
history/packages/*-superpowers-package/ 셋은 납품된 묶음 그대로이고, 그 안의 MANIFEST.sha256은
납품 당시 바이트의 해시다.
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 repository-adaptation.md 또는
module-mapping.md가 기록한다. 계획서를 나중에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라
결과를 계획처럼 보이게 만든 글이 되기 때문이다.
폴더 밖 문서
| 문서 | 무엇 |
|---|---|
| build.md | 빌드 스크립트(build.gradle의 게이트 태스크)와 환경 변수(.env.example) 참조(2026-11-11 재배치 전에는 src 폴더의 README였다) |
| capability-status.md | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) |
| storage-capability-boundary.md | 파일 서버와 객체 저장소가 각각 맡는 경계 |
| vision.md | 비전: 누구의 어떤 문제를 푸나, 성공하면 무엇이 달라지나, 속도보다 먼저 지킬 것(세 문장, 소유자가 쓴다. 에이전트는 읽기만 한다) |
| problem-statement.md | 문제 정의: 고객의 말 그대로, 지금 버티는 법, 하지 않는 것, 잴 수 있는 성공 기준 |
문서 수명과 언어
규칙의 정본은 design-docs conventions/docs-system.md다. 이 절은 이 repo에 적용한 내용이고,
이 템플릿을 받은 파생 서비스도 이 절을 따른다.
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
|---|---|---|---|---|
| 살아 있음 | README, CLAUDE.md, AGENTS.md, 매뉴얼(manual/, work/), 영역 운영 문서, registries/, runbooks/, upgrade/ |
제자리 | 한국어 | 코드와 같은 변경에서 고친다 |
| 결정 | 결정 기록(ADR) | adr/ |
한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 |
| 기록 | 설계서, 계획서, 납품 패키지, 증거, 학습 문서, 리뷰 | design/, history/, reviews/ |
머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
- 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다.
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
- 살아 있는 문서와 ADR 본문은 2026-11-07에 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(「문서 검사」).
- ADR 본문의 번역은 뜻을 바꾸지 않은 옮김이다. 옮기기 전 원문은 커밋
03a313ed에 있다(알림 ADR은 그때 다른 폴더에 있었다. 옛 경로는docs/upgrade/2026-11-docs-records.md).
기록 문서의 머리 블록
design/, history/, adr/의 .md 파일은 맨 위에 이 블록을 둔다.
블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다). ADR만은 본문을 한국어로 옮겼다(「문서 수명과 언어」).
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 구현됨
- 작성일: 2026-08-11
- 요약: 한국어 한 문장
- 현재 정본: `docs/jpa/repository-adaptation.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
-
종류는 폴더가 정하고 둘째 줄에 굵게 적는다:
design/설계서,history/plans/계획서,history/evidence/·history/plans/evidence/증거,history/packages/납품 패키지,history/study/학습 문서. ADR의 둘째 줄은> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.다. -
상태는 종류마다 고정 어휘다.
종류 상태 설계서 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함 결정 기록 제안 · 채택 · 채택(보완) · 폐기 · 대체됨 계획서 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함 납품 패키지 · 증거 · 학습 문서 보관 -
「현재 정본」은 지금 동작을 설명하는 살아 있는 문서의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.
-
「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.
-
상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다.
-
2026-11-07에 처음 단 상태는 문서의 원래 상태 줄을 바꾼 값이다: Accepted·Approved·확정·승인 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 보완 메모가 있는 ADR → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.
capability-status.md「제거된 코드」로 지운 것이 확인된 설계서 다섯은 「폐기」다. -
리뷰(
reviews/)는 아직 머리 블록을 요구하지 않는다.
모듈 README
leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것(정본은 design-docs conventions/docs-system.md 6.2절):
- 책임 한 문장과 소유하지 않는 것
- 공개 표면(포트·API·설정 prefix)
- 조립: 더할 한 줄, 끄는 키, 필요한 env 키
- 테스트: registry의 Gradle 경로로 만든 명령(숫자·버전을 복사하지 않는다)
- 더 읽을 곳: 그 폴더의
AGENTS.md(지역 규칙), 영역 운영 문서
문서와 코드를 같은 변경에서 고친다
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법:
grep -rn '<바꾼 이름>' docs src --include=*.md. - 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·태스크는
capability-status.md「제거된 코드」나upgrade/에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면> 이력으로 시작하는 인용 블록 안에 쓴다. - 숫자·버전을 복사하지 않는다. Spring Boot 버전은
gradle/libs.versions.toml, leaf 목록과 개수는 registry(gradle/modules.json)를 가리킨다. - 루트 README는 「프로젝트 구조」(최상위 폴더와
src/폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이 어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docsconventions/docs-system.md6.1절이고,readme검사가 그 목록(scripts/check-docs.py의README_SECTIONS)을 본다.
문서 검사
python3 scripts/check-docs.py가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 workflow docs-check가
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
문서를 낡게 만든다.
| 검사 | 보는 것 |
|---|---|
language |
살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
head |
기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
reference |
살아 있는 문서의 인라인 코드 안 경로(src/, docs/, scripts/, compose/, .github/, .gitea/로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, > 이력 인용 블록, 제거 표, upgrade/는 보지 않는다 |
number |
살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), Spring Boot 칸이 있는 표 행의 세 자리 버전, 정본(gradle/libs.versions.toml의 springBoot)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, upgrade/는 보지 않는다 |
map |
이 README의 「문서 지도」가 docs/ 아래 모든 폴더를 덮는가(표 첫 칸의 폴더/). 파일 없이 폴더만 가진 묶음 폴더(history/)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
readme |
루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 ## 절을 정해진 순서로 가지는가 |
link |
살아 있는 문서의 마크다운 상대 링크가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·> 이력 인용 블록은 보지 않는다 |
style |
살아 있는 문서의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안의 인용은 보지 않는다 |
- 하나만 돌리기:
python3 scripts/check-docs.py --only head. - 소스 세트의 resources 폴더 아래
.md(src/**/src/<세트>/resources/)는 테스트가 읽는 입력이라 문서로 보지 않는다. - 예외 목록
scripts/check-docs-exceptions.txt는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서 더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다. - 줄을 지우면 같은 변경에서
scripts/check-docs.py의FROZEN에서 그 줄의 지문도 뺀다. 남겨 두면 실패한다(남은 지문은 지운 줄을 다시 더하는 길이다). 2026-11-07 번역 단계에서 목록과FROZEN이 모두 비었다. - 검사 자신의 시험:
python3 -m unittest discover -s scripts/tests. - 상대 링크는
link검사가 살아 있는 문서 전부(src/**/AGENTS.md,.claude/아래 문서 포함)를 본다. 외부 URL은 lychee(main.yml의linksjob)가 본다. 기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의.lycheeignore에 더한다.
여기에 없는 것
- 실행되는 검증 스크립트는 문서가 아니다.
scripts/(workflow가 부르는 것은scripts/ci/)에 있다. - 모듈 레지스트리·Gradle 정책은
gradle/modules.json과build.gradle이 소유한다. - 각 모듈의 지역 규칙은 해당 모듈의
src/**/AGENTS.md가 소유한다.