문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때
기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰
기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가
가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰
문서 여러 곳에 흩어져 있다.
방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은
다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md,
TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다.
정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함
정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션
분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에
「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와
docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다.
버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용
가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접
쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다).
위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지
않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소
밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드
표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로
넣기)는 [제안]으로 표시했다.
검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절
번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖
가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는
DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로
둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.
방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.
위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).
검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.