docs: 리뷰 후속 반영 현황표와 실행 계획
2026-09-24 두 리뷰의 모든 항목을 6d27356e 기준으로 다시 판정한 현황표(812행)와
Wave 1-5 실행 계획, 소유자 결정 20건을 기록한다.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
6d27356e2b
commit
fe80bb3ff3
@@ -0,0 +1,121 @@
|
||||
# 새 세션용 프롬프트 — 2026-09-24 리뷰 남은 항목 전부 반영
|
||||
|
||||
> 사용법: 새 세션에서 아래 「프롬프트 본문」을 그대로 붙여 넣거나, `/goal docs/reviews/2026-09-25-review-followup-prompt.md 를 읽고 그대로 진행하자` 로 시작한다.
|
||||
> 「사용자가 정할 것」 절의 기본값이 마음에 들지 않으면 붙여 넣기 전에 고친다.
|
||||
|
||||
---
|
||||
|
||||
## 프롬프트 본문
|
||||
|
||||
### 0. 배경 (이미 끝난 일)
|
||||
|
||||
- 입력 리뷰 두 개:
|
||||
- 1차(결함 중심): `docs/reviews/2026-09-24-src-module-code-review.md` — Critical 15 / Required 76 / Consider 약 55, 그룹 A–O
|
||||
- 2차(구조·유지보수): `docs/reviews/2026-09-24-src-maintainability-review.md` — BUILD, TEST, X1, X2, S1–S7
|
||||
- 2026-09-25 capability 포장 작업이 끝났고 `main`에 커밋 `6d27356e`로 들어가 있다. 설계는 `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md`, 실행 기록은 `docs/superpowers/plans/2026-09-25-capability-module-packaging.md`(맨 아래 「진행 기록」 표)에 있다.
|
||||
- 그 작업에서 반영된 것:
|
||||
- 1차 리뷰 **Critical 15건 전부** + L-2(prod 에러 상세), L-3(sample loggers) + 알림 admin 결과 codec의 jsonb 공백 결함
|
||||
- 2차 리뷰 결정 D1–D6: 리팩터링 잔재·실험용 자리 삭제(D1), outbox 한 세대 + v1 fencing `V17`(D2), 멱등성 V2 정본화(D3), WebFlux 삭제(D4), 빌드 "바로 할 것" 1–12와 O3 일부(D5), 테스트 규칙을 `AGENTS.md`에 고정하고 sample에만 적용(D6)
|
||||
- 부가 기능을 "있으면 켜지는 capability 모듈"로 포장, 기본 조립은 web·identifier·support·코어만, 나머지는 `app-bootstrap/build.gradle`의 주석 한 줄로 선택
|
||||
- 반영되지 **않은** 것: 1차 리뷰 Required 76건과 Consider 대부분(체계적으로 처리하지 않음 — 코드 삭제로 같이 사라진 것만 있음), 2차 리뷰의 구조 권고 중 D1–D6 밖의 것(에러 어휘 통합, SRP 분해, 공통 유틸, tenant 값 타입, 나머지 모듈의 테스트 규칙 적용 등), 그리고 아래 5절의 알려진 남은 문제.
|
||||
|
||||
### 1. 목표
|
||||
|
||||
두 리뷰에 적힌 **모든 항목**(Critical·Required·Consider·Nit, 2차의 모든 Finding과 권고)을 현재 코드 기준으로 다시 판정하고, 남은 것은 전부 반영한다. 반영하지 않기로 한 항목은 이유와 승인자를 남긴다. "전부"의 정의는 3절 현황표의 모든 행이 `완료` / `해당 없음` / `보류(사유·승인자)` 중 하나로 끝나는 것이다.
|
||||
|
||||
### 2. 먼저 읽을 것
|
||||
|
||||
1. `AGENTS.md` 전체 — HARD-STOP 7개, 「부가 기능(capability) 모듈 규칙」(완료 기준 7개, 모듈 기본 설정 로딩 규칙), 「테스트 전략」의 테스트 작성 규칙 6개
|
||||
2. `CLAUDE.md`, 작업할 leaf의 가장 가까운 `src/**/CLAUDE.md`
|
||||
3. 위 리뷰 두 개, 계획서 `2026-09-25-capability-module-packaging.md`의 「진행 기록」, `docs/capability-status.md`(상태표 + 「제거된 코드 (2026-09-25 리팩터링)」 표)
|
||||
4. `src/README.md`의 「기능 추가 = 한 줄 + env」 표
|
||||
|
||||
주의: 리뷰의 경로와 줄 번호는 `208077fd` 기준이다. 그 뒤로 코드가 많이 옮겨졌다(예: bootstrap의 startup helper → `adapter:outbound:support` `support.startup`, JPA startup/Flyway/validator → persistence-jpa `startup`, 알림 조립 → `composition:notification-platform`, web 알림 HTTP → `adapter:inbound:web-notification`, web 라이브러리 → `adapter:inbound:web-advanced`, redis-sdk 테스트 → redis-sdk leaf). 항목마다 **현재 코드에서 다시 찾는다.**
|
||||
|
||||
### 3. 1단계 — 반영 현황표 (구현 전에 끝낸다)
|
||||
|
||||
`docs/reviews/2026-09-25-review-followup-status.md`를 만든다. 한 행 = 리뷰 항목 하나.
|
||||
|
||||
| 열 | 내용 |
|
||||
|---|---|
|
||||
| ID | 1차: `A-1`, `B-3`, … (그룹 문자 + 번호). 2차: `S2-#4`, `X1-#6`, `X2-P2-1`, `BUILD-바로할것-7`, `TEST-제안-3` 등 |
|
||||
| 심각도 | Critical / Required / Consider / Nit / 권고 |
|
||||
| 요약 | 한 줄 |
|
||||
| 상태 | `완료` / `해당 없음(코드 삭제)` / `남음` / `결정 필요` |
|
||||
| 근거 | 완료면 커밋·테스트 이름, 해당 없음이면 「제거된 코드」 표의 행, 남음이면 현재 `file:line` |
|
||||
| Wave | 남음인 항목을 배정할 묶음 |
|
||||
|
||||
- 판정은 grep·코드 읽기로 한다. 추측으로 `완료`나 `해당 없음`을 적지 않는다.
|
||||
- 리뷰 항목이 여러 결함을 묶고 있으면 행을 나눈다.
|
||||
- 서로 같은 결함(예: 1차 A-4 = I-1)은 한 행으로 합치고 ID를 둘 다 적는다.
|
||||
- 병렬로 하면 그룹 단위로 나눠 읽기 전용 조사 에이전트에 맡기고, 결과만 표로 합친다.
|
||||
|
||||
### 4. 2단계 — 실행 계획 후 실행
|
||||
|
||||
`docs/superpowers/plans/` 에 `writing-plans` 형식으로 계획을 쓰고 Wave 순서대로 끝까지 실행한다. 권장 순서:
|
||||
|
||||
1. **보안·데이터 손실** (남은 Required 중 security/data): 예) 1차 A-1(예외 메시지 로그의 PII·비밀값), B-7(알림 admin reconcile tenant 검사), C-2(QUARANTINE 판정이 staged bytes 삭제), C-8(파일 권한이 role tier만 확인), H-2~H-4(httpclient dynamic target의 trace 헤더·리다이렉트·API key 헤더), E-6(tenant 규칙이 필드 이름 기반) 등
|
||||
2. **정합성** (correctness): 예) B-3~B-6, C-3~C-6·C-9, E-3~E-5, H-5·H-6, 1차 I·J·K·M·N 그룹의 Required
|
||||
3. **구조** (2차 리뷰): 에러 어휘·응답 형식 하나로(X2 P2-1~P2-3), shared 예외에 `ApiErrorCarrier`(P2-2), traceparent 파싱 하나로(P2-4), tenant 값 타입(P2-6), caller 트랜잭션 guard 하나로(X1-#4), 공통 유틸(`Sha256`, `Backoff`), SRP 분해(`NotificationDispatchService`, `LocalPersistentControlPlane`, `GraphQlPlatformAutoConfiguration`, `RedisTopologyClientFactory` 등), 구현 1개짜리 인터페이스 정리, 이름 규칙(outbound `*Port`, inbound `*UseCase`)
|
||||
4. **테스트 규칙 확산**: 포트별 추상 계약 테스트(`XxxContract`)를 fake와 adapter가 함께 통과(`IdempotencyStorePort` — fake·Redis·PostgreSQL 공통 계약 포함), 약한 단언 정리, 계층별 모범 모듈(2차 TEST 「Migration과 enforcement 계획」)
|
||||
5. **문서 drift·Nit**: 리뷰의 docs/Nit 항목, leaf CLAUDE.md/README와 코드 불일치
|
||||
|
||||
각 Wave 시작 때 계획서에 그 Wave의 상세 Task를 추가하고, 끝나면 「진행 기록」에 검증 결과를 남긴다.
|
||||
|
||||
### 5. 이미 알고 있는 남은 문제 (현황표에 행으로 넣는다)
|
||||
|
||||
- CI compose smoke 18 lane을 실제로 돌리지 못함(정적 검사만). `scripts/run-compose-runtime-smoke.sh`는 이제 `/actuator/health`만 확인하고 `compose-profile-contracts.json`의 `expectedSwitchesOn`·`expectedPersistenceVendor`를 읽지 않음. 새 CI 잡(`build-logic.yml`, `integration-main.yml` 추가분)도 GitHub에서 미실행
|
||||
- outbox relay 조립(`OutboxConfig`)과 멱등성 executor 조립(`IdempotencyProviderSelectionConfig`)이 아직 app-bootstrap에 있음(capability 완료 기준 7 일부 미충족). sample은 `SampleIdempotencyConfig`로 조립을 따로 복사
|
||||
- fileserver 보상 트랜잭션에서 30초 트랜잭션 타임아웃이 사라짐(`PolicyTransactionPort` 제거의 부작용)
|
||||
- Kafka: truststore/keystore 설정 키 없음, `MUTUAL_TLS` 미지원, producer 주소가 `spring.kafka.bootstrap-servers`만 읽음, credential rotation 미반영
|
||||
- Redis 실제 lane 기존 실패 4건(`LiveRedisSemanticPortsTest`: 테스트 ACL에 `TIME` 권한 없음, 시계 +1h). idempotency·lease adapter가 lane 거부를 `Indeterminate`로 분류
|
||||
- `S3AsyncResponseBodyBridgeTest`가 부하가 높을 때 간헐 실패
|
||||
- durable operation: 같은 operationId 재시도 시 outbox 중복 append. `SubmitDurableOperationUseCase`와 Get/Cancel use case를 쓰는 HTTP 어댑터·운영 조립 없음
|
||||
- 알림: reconcile `Unsupported`·모든 attempt 완료 행이 DISPATCHING에 남음(1차 B-4)
|
||||
- GraphQL 요청 단계 에러가 `GraphQlWireErrorMapper`를 거치지 않음(2차 S5-#6). `shared-contract`의 `OperationalRecordStorePort` 사용처 0
|
||||
- web: JSON 엄격성(중복 키 등), CORS origin 기동 검증, 신뢰하지 않는 forwarded 헤더 거부가 운영 경로에 없음. web fixture 앱 2개와 sample 테스트가 `WebAdapterAutoConfiguration`을 이름으로 제외(자동 설정을 나누면 같이 고쳐야 함)
|
||||
- fileserver를 JPA 줄 없이 고르면 Boot 관계형 자동 설정이 여전히 동작(문서에만 "JPA 필요")
|
||||
- `bootstrap.autoconfigure` 패키지가 component scan 범위 안에 있음(루트가 아닌 `@Configuration`을 두면 조건 없이 등록됨)
|
||||
- 빌드: `verifyEnvKeys`·JPA evidence/readiness(`ca.jpa-evidence`, `ca.jpa-qualification`)·redis topology lane을 leaf로 옮길지 미결. API surface 검사가 `mainCheck`로 옮겨가 PR에서 바로 안 잡힘. `messagingSampleContractQualificationTest`가 어떤 집계 태스크에도 묶여 있지 않음
|
||||
- `docs/study/*.ko.md`, `docs/*-superpowers-package/`가 삭제된 코드를 설명(학습 기록이라 남겨 둔 것 — 정리 여부 결정)
|
||||
|
||||
### 6. 사용자가 정할 것 (시작 전에 AskUserQuestion으로 한 번에 묻는다 — 괄호는 기본값)
|
||||
|
||||
1. 커밋 방식 (브랜치 `refactor/review-followup`에 Wave마다 커밋, `main` 병합·push는 사용자 확인 후)
|
||||
2. HTTP 에러 응답 형식 (Envelope 하나로 통일, fileserver의 problem+json도 Envelope로 — tus 프로토콜이 요구하는 헤더만 유지)
|
||||
3. outbox relay·멱등성 executor 조립 위치 (capability 모듈로 옮기되, ArchUnit `PERSISTENCE_DOES_NOT_DEPEND_ON_APPLICATION_SERVICES` 때문에 persistence-jpa가 아니라 별도 `composition:*` 모듈로)
|
||||
4. 빌드 게이트 이동 (`verifyEnvKeys`는 bootstrap에 유지, JPA evidence manifest는 폐기하고 leaf 테스트로, redis topology lane은 유지)
|
||||
5. `@DisplayName` 언어 (영어 유지)
|
||||
6. 삭제된 코드를 설명하는 학습 문서 (삭제하지 않고 머리에 "208077fd 기준 기록" 한 줄 추가)
|
||||
|
||||
### 7. 작업 규칙과 지난 세션에서 배운 것
|
||||
|
||||
- **TDD:** 결함 수정은 재현 테스트를 먼저 쓰고 FAIL 출력을 기록한 뒤 고친다. fake가 결함을 숨긴 포트는 추상 계약 테스트로 fake와 adapter를 함께 돌린다.
|
||||
- **아키텍처:** `modules.json` 밖의 project edge 금지. 새 leaf는 registry 등록 + README(제공·한 줄·env). capability는 "있으면 켜짐, `enabled=false`면 완전히 꺼짐(Boot 자동 설정까지 exclude)".
|
||||
- **migration:** 적용됐을 수 있는 versioned migration은 수정 금지. 새 버전을 추가하고 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 한 줄 추가(`AppliedMigrationImmutabilityTest`).
|
||||
- **재생성 태스크:** lockfile `./gradlew <path>:resolveAndLockAll --write-locks`, API surface `update*ApiSurface -Papprove*` (notification은 `-PapproveNotificationApiSurfaceChange`), 확인 `verifyDependencyLocks`.
|
||||
- **삭제 기록:** 지운 코드는 `docs/capability-status.md` 「제거된 코드」 표에 `| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |`로 한 행씩(이번에는 커밋 `6d27356e`).
|
||||
- **병렬 작업:** 서로 다른 leaf를 건드리는 묶음은 `rsync`로 만든 작업 복사본에서 병렬로 돌리고, 같은 시각의 baseline 복사본과 `diff -ruN`(제외: `build/`, `.gradle/`, `bin/`, `.git/`, `.approval_tests_temp/`, `.jqwik-database`)으로 변경분을 뽑아 `patch -p1 -E`로 main에 반영한다. Gradle은 한 작업 트리에서 동시에 하나만 돌린다.
|
||||
- **적용 실패를 조용히 넘기지 않는다.** 지난 세션에 `patch --dry-run && patch ...; echo applied`로 dry-run 실패가 가려져 한 묶음이 통째로 빠진 적이 있다. 적용 스크립트는 실패 시 멈추게 하고, 반영 후 복사본과 main 파일을 `cmp`로 대조한다.
|
||||
- `docs/capability-status.md`, `docs/registries/env-keys.yaml`, `src/.env.example`, `app-bootstrap/build.gradle`, lockfile은 여러 묶음이 함께 고치므로 충돌을 예상하고, lockfile은 손으로 합치지 말고 재생성한다.
|
||||
- **에이전트 도구:** 셸 heredoc으로 파일을 쓰다 에이전트가 멈춘 적이 있다. 파일은 파일 쓰기 도구로 쓰고, 긴 Gradle 실행은 `timeout`을 건다.
|
||||
- **검증 (Wave 종료마다, 결과 수치를 기록):**
|
||||
```bash
|
||||
cd src
|
||||
./gradlew check --continue
|
||||
./gradlew ci verifyDependencyLocks --warning-mode=fail
|
||||
./gradlew mainCheck --continue
|
||||
./gradlew architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck
|
||||
./gradlew :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest
|
||||
./gradlew -p build-logic test && ./gradlew -p build-tools test && ./gradlew -p optional-platforms ci
|
||||
./gradlew :app-bootstrap:qualificationBootJar
|
||||
# 건드린 영역의 실제 벤더 lane (Docker): persistence-jpa jpaPlatform*Test / postgresql*IntegrationTest,
|
||||
# persistence-mongo mongo*Test, messaging starter integrationTest, redisTopologyTest, objectstorage MinIO lane
|
||||
```
|
||||
- **보고:** 전역 `CLAUDE.md`의 상사 보고 형식(변경 / 확인 / 남은 문제). Wave마다 Slack `#clean-architecture-전체`에 템플릿 1로 브리핑.
|
||||
|
||||
### 8. 완료 조건
|
||||
|
||||
- `docs/reviews/2026-09-25-review-followup-status.md`의 모든 행이 `완료` / `해당 없음` / `보류(사유·승인자)`
|
||||
- 계획서 「진행 기록」에 Wave별 검증 결과
|
||||
- 7절의 검증 명령이 main(또는 작업 브랜치)에서 전부 통과
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,222 @@
|
||||
# 2026-09-24 리뷰 남은 항목 전부 반영 — 실행 계획
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** `docs/reviews/2026-09-25-review-followup-status.md`의 `남음` 행(544행)을 전부 `완료` / `해당 없음` / `보류(사유·승인자)`로 닫는다.
|
||||
|
||||
**Architecture:** 행 하나의 구체적 수정 방향은 현황표의 「수정 방향」 열이 정본이다(현재 `file:line` 포함). 이 계획은 그 행들을 소유 영역별 작업 묶음(package)으로 나누고, Wave 순서(보안·데이터 → 정합성 → 구조 → 테스트 → 문서)대로 실행·검증·커밋하는 방법을 정한다. 계획은 rolling-wave다: 전체 구조와 Wave 1–2 묶음은 지금 확정하고, Wave 3–5의 상세 Task는 그 Wave를 시작할 때 이 문서에 추가한다.
|
||||
|
||||
**Tech Stack:** Java 21, Spring Boot 4.0.8, Gradle 멀티모듈(registry `src/config/architecture/modules.json`), JUnit 5 + AssertJ + ArchUnit, Testcontainers(PostgreSQL·Redis·Kafka·Mongo·MinIO), Flyway.
|
||||
|
||||
**Spec:** 입력 리뷰 `docs/reviews/2026-09-24-src-module-code-review.md`(1차), `docs/reviews/2026-09-24-src-maintainability-review.md`(2차), 실행 지시 `docs/reviews/2026-09-25-review-followup-prompt.md`, 소유자 결정은 현황표 「소유자 결정」 절.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- HARD-STOP 7개(`AGENTS.md`)는 모든 Wave에서 유지한다. 모든 project 의존성은 `modules.json`의 `allowed_dependencies` 안에 있어야 한다. 새 edge가 필요하면 registry에 먼저 추가하고 이유를 커밋 메시지에 적는다.
|
||||
- 커밋: 브랜치 `refactor/review-followup`에 Wave마다 커밋(소유자 결정 1). `main` 병합·push는 사용자 확인 후.
|
||||
- 이미 적용됐을 수 있는 Flyway versioned migration은 바이트를 바꾸지 않는다. 새 버전을 추가하고 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 한 줄 추가한다(`AppliedMigrationImmutabilityTest`).
|
||||
- 결함 수정은 재현 테스트를 먼저 쓰고 FAIL을 확인한 뒤 고친다. fake가 결함을 숨긴 포트는 추상 계약 테스트(`XxxContract`)로 fake와 어댑터를 함께 돌린다.
|
||||
- 새로 쓰거나 고치는 테스트는 `AGENTS.md` 테스트 작성 규칙 6개를 따른다. 단 `@DisplayName` 언어는 **한국어**(소유자 결정 5, AGENTS.md 규칙 2는 Wave 4에서 문구 수정).
|
||||
- capability 규칙: "있으면 켜짐, `enabled=false`면 완전히 꺼짐", 설정 prefix 하나, `StrictSettingsBinder` + compact constructor 검증, 동작하지 않는 옵션은 키를 두지 않는다.
|
||||
- 지운 코드는 `docs/capability-status.md` 「제거된 코드」 표에 `| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |`로 한 행씩 남긴다(마지막 커밋은 `6d27356e`).
|
||||
- 재생성 태스크: lockfile `./gradlew <path>:resolveAndLockAll --write-locks`, API surface `update*ApiSurface -Papprove*`(notification은 `-PapproveNotificationApiSurfaceChange`), 확인 `verifyDependencyLocks`. lockfile은 손으로 합치지 않고 재생성한다.
|
||||
- Gradle은 한 작업 트리에서 동시에 하나만. 긴 실행에는 `timeout`을 건다. 파일은 파일 쓰기 도구로 쓴다(셸 heredoc 금지).
|
||||
- 문서에 leaf 개수를 적지 않는다(registry가 SSOT).
|
||||
|
||||
## Review Focus
|
||||
|
||||
사용자가 가장 먼저 부딪힐 입력·조건과 기대 동작. 각 줄의 테스트는 해당 묶음에 넣는다.
|
||||
|
||||
1. **fileserver에서 같은 역할 등급의 다른 사용자가 남의 fileId로 조회·다운로드·삭제** → 403(또는 404)이어야 한다. (P4 C-8a: 소유자 검사 계약 테스트)
|
||||
2. **외부 API 호출 중 cross-origin redirect** → `Authorization`·API-key·`traceparent`가 다음 host로 가지 않아야 한다. (P11 H-2·H-3c·H-4a)
|
||||
3. **`X-Forwarded-For`를 위조한 비인증 요청으로 rate-limit 우회** → trusted proxy가 아니면 XFF를 무시해야 한다. (P10 I-5a·NEW-10c)
|
||||
4. **Mongo 검색 API에 `{"$ne": null}` 같은 operator 객체가 값으로 들어옴** → 거부해야 한다. (P12 F-1a·F-1b)
|
||||
5. **Kafka broker가 사설 CA·SASL을 요구** → 설정한 truststore·credential로 연결되고, 설정이 없으면 기동이 실패해야 한다(평문 fallback 금지). (P1 M-2e·NEW-4b)
|
||||
|
||||
---
|
||||
|
||||
## 실행 방식
|
||||
|
||||
### 작업 단위와 병렬
|
||||
|
||||
- 묶음(package) 하나 = 구현 subagent 하나. subagent는 `isolation: worktree`로 자기 git worktree에서 일한다(같은 작업 트리에서 Gradle 동시 실행 금지 규칙을 worktree 분리로 지킨다).
|
||||
- 동시에 도는 묶음은 **최대 3개**(이 머신의 여유 메모리 약 5GB). Gradle은 `--max-workers=2`로 돌린다.
|
||||
- subagent는 자기 worktree에서 커밋한다. 커밋은 묶음 안에서 `D`(결정된 삭제) → `W1` → `W2` 순서로 나눈다. 메시지 형식: `review-followup <P번호> <D|W1|W2>: <요약>`.
|
||||
- 통합은 오케스트레이터가 한다: Wave 1은 모든 묶음의 `D`·`W1` 커밋을 `git cherry-pick -n`으로 모아 검증 후 한 커밋, Wave 2는 `W2` 커밋을 같은 방식으로. cherry-pick 충돌·실패는 멈추고 해결한다(조용히 넘기지 않는다). 적용 뒤 worktree 파일과 main 파일을 `git diff <worktree-branch> -- <path>`로 대조한다.
|
||||
- 여러 묶음이 함께 고치는 파일(`docs/capability-status.md`, `docs/registries/env-keys.yaml`, `src/.env.example`, `app-bootstrap/build.gradle`, lockfile)은 충돌을 예상한다. `docs/capability-status.md`와 현황표는 subagent가 고치지 않고 결과 파일에 적는다(아래). lockfile은 통합 뒤 재생성한다.
|
||||
|
||||
### subagent 결과 파일
|
||||
|
||||
각 묶음은 `<scratchpad>/results/<P번호>.md`에 아래 세 절을 쓴다. 오케스트레이터가 이것으로 현황표와 「제거된 코드」 표를 갱신한다.
|
||||
|
||||
```markdown
|
||||
## 행 결과
|
||||
| ID | 결과 | 근거 |
|
||||
|---|---|---|
|
||||
| C-2a | 완료 | `FileVerdictServiceTest.quarantineKeepsStagedBytes` FAIL→PASS, `path/File.java:88` |
|
||||
| H-5a | 해당 없음(코드 삭제) | P11 D 커밋에서 reactive 스택 삭제 |
|
||||
| X-1 | 보류 | 사유: … / 승인자: 저장소 소유자 결정 필요 |
|
||||
| Y-2 | 남음 | 이유: … (다음 Wave로) |
|
||||
|
||||
## 제거된 코드
|
||||
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
|
||||
|
||||
## 새로 발견한 결함
|
||||
(현황표에 없는 결함. ID는 `<P번호>-new-1`…)
|
||||
```
|
||||
|
||||
### Wave 종료 검증 (결과 수치를 「진행 기록」에 남긴다)
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew check --continue
|
||||
./gradlew ci verifyDependencyLocks --warning-mode=fail
|
||||
./gradlew mainCheck --continue
|
||||
./gradlew architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck
|
||||
./gradlew :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest
|
||||
./gradlew -p build-logic test && ./gradlew -p build-tools test && ./gradlew -p optional-platforms ci
|
||||
./gradlew :app-bootstrap:qualificationBootJar
|
||||
# 건드린 영역의 실제 벤더 lane (Docker): persistence-jpa jpaPlatform*Test / postgresql*IntegrationTest,
|
||||
# persistence-mongo mongo*Test, messaging starter integrationTest, redisTopologyTest, objectstorage MinIO lane
|
||||
```
|
||||
|
||||
Wave마다 Slack `#clean-architecture-전체`에 템플릿 1로 브리핑한다.
|
||||
|
||||
## Wave 개요
|
||||
|
||||
| Wave | 내용 | 대상 행 | 완료 기준 |
|
||||
|---|---|---|---|
|
||||
| 1 | 결정된 삭제(`D`) + 보안·데이터 손실(`W1`) | `W1` 55행 + 결정된 삭제 | 삭제 대상 main 참조 0, W1 행마다 재현 테스트 FAIL→PASS, Wave 종료 검증 통과 |
|
||||
| 2 | 정합성(`W2`) | 139행 | 행마다 재현 테스트(또는 결정된 기능 추가의 계약 테스트), Wave 종료 검증 통과 |
|
||||
| 3 | 구조(`W3`) — 공통 작업(에러 어휘·prefix·outbox·composition·공통 유틸) 먼저 순차, 그다음 영역별 | 196행 | 결정 7–20 반영, capability 완료 기준 7 충족, Wave 종료 검증 통과 |
|
||||
| 4 | 테스트 규칙(`W4`) — 포트 계약 테스트, 약한 단언, 계층별 모범 모듈, AGENTS.md DisplayName 규칙 | 56행 | 포트마다 fake·어댑터 공통 계약, Wave 종료 검증 통과 |
|
||||
| 5 | 문서 drift·Nit(`W5`) + 학습 문서 현재 코드 기준 갱신(결정 6) | 98행 | 문서가 가리키는 타입·경로가 전부 존재, 현황표 전 행 종료 |
|
||||
|
||||
**결정된 삭제를 Wave 1 앞에 두는 이유:** httpclient reactive(결정 9), 알림 provider 5종, object storage direct·multipart, gRPC 상수 gate는 지울 코드다. 그 코드의 W1·W2 결함을 먼저 고치면 버릴 작업이 된다. 삭제로 사라진 행은 `해당 없음(코드 삭제)`로 닫는다.
|
||||
|
||||
**legacy Kafka seam(`X1-지도-Kafka producer`, `X1-#1f`, `NEW-4a`):** 결정 7(outbox canonical 통일)로 경로 자체가 삭제된다. Wave 3 공통 작업 3-C에서 닫는다. Wave 1에서는 손대지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## Wave 1–2 묶음
|
||||
|
||||
각 묶음의 subagent는 Wave 1 행(`W1`)을 먼저 끝내고 커밋한 뒤 Wave 2 행(`W2`)으로 넘어간다. 행별 수정 방향은 현황표의 「수정 방향」 열을 따르고, 코드를 읽어 보니 방향이 틀렸으면 더 작은 올바른 수정을 하고 결과 파일 근거에 이유를 적는다.
|
||||
|
||||
### P1: messaging (vendored `messaging:*`, `adapter:outbound:messaging`, `adapter:outbound:messaging-kafka`)
|
||||
|
||||
- W1: `M-2c`, `M-2d`, `M-2e`, `M-2f`, `NEW-4b`, `NEW-4d` (legacy seam 3행은 Wave 3)
|
||||
- W2: `M-2b`, `M-3`, `M-4a`, `M-4b`, `M-4c`, `M-5a`, `M-5b`, `M-6`, `M-7`, `M-11`, `S6-#2b`, `S6-lead-3`, `S7-lead-3`, `NEW-4c`
|
||||
- 검증: 소유 leaf `check`, messaging starter integrationTest(Kafka Testcontainers), `architectureCheck`
|
||||
|
||||
### P2: object storage (`application-objectstorage`, `adapter:outbound:objectstorage`)
|
||||
|
||||
- D: `D-7a`, `D-7b`, `D-7c` — direct·multipart 조립 안 된 코드 삭제(현황표 「소유자 결정」 끝 문단)
|
||||
- W1: `D-1a`, `D-1b`, `D-1c`, `D-6a`, `D-6b`, `X2-P1-1a`
|
||||
- W2: `D-2a`, `D-2b`, `D-2c`, `D-3a`, `D-3b`, `D-3c`, `D-3d`, `D-5 / X1-#8b`, `D-9`, `D-10`, `NEW-6`(`S3AsyncResponseBodyBridgeTest` 간헐 실패)
|
||||
- 검증: 소유 leaf `check`, MinIO lane, sample-portfolio `check`(poster image 경로가 object storage를 씀)
|
||||
|
||||
### P3: notification (`application-notification`, `adapter:outbound:notification`, `adapter:inbound:web-notification`, `composition:notification-platform`)
|
||||
|
||||
- D: `S4-#3a` — 미조립 provider 5종(APNs·FCM·Twilio·WebPush·Webhook)과 참조 0인 `SesSuppressionUpdater` 삭제, `ProviderType`에서 5종 제거
|
||||
- W1: `B-2e`, `B-6`, `B-7a`, `B-7b`, `X2-P2-7b`
|
||||
- W2: `B-3`, `B-4a`, `B-4b`, `B-5a`, `B-5b`, `B-7c`, `B-9a`, `B-9b`, `X1-#6e`, `S4-#3b`, `NEW-8a`, `NEW-8b`
|
||||
- 검증: 소유 leaf `check`, notification PG lane, `:adapter:outbound:notification` API surface 재승인
|
||||
|
||||
### P4: file server (`application-fileserver`, `adapter:outbound:persistence-fileserver`, `adapter:outbound:fileserver`, `adapter:inbound:web-fileserver`, `composition:fileserver-platform`)
|
||||
|
||||
- W1: `C-2a`, `C-2b`, `C-5a`, `C-5c`, `C-8a`(결정 14 — `ownerPrincipalId` 새 migration, 기본 정책이 소유자·tenant 검사), `C-8b`, `C-8c`
|
||||
- W2: `C-3a`, `C-3b`, `C-3c`, `C-3d`, `C-4a`, `C-4b`, `C-5b`, `C-6`, `C-7a`, `C-7b`, `C-9a`, `C-9b`, `C-11`, `S1-#5`, `S1-lead-6`, `NEW-3`(보상 트랜잭션 30초 timeout 복원), `NEW-11`(composition이 persistence-jpa를 `runtimeOnly`로)
|
||||
- 검증: 소유 leaf `check`, fileserver PG lane, `architectureCheck`
|
||||
|
||||
### P5: realtime + gRPC (`adapter:inbound:websocket`, `adapter:inbound:grpc`, `src/grpc*` — optional-platforms 별도 build)
|
||||
|
||||
- D: `S7-#4` — gRPC 상수 gate·guard·`GrpcStableModuleCatalog`(이전 계획 Wave 2 표 2-G) 삭제
|
||||
- W1: `K-11a`, `N-3`, `N-4`
|
||||
- W2: `K-6`, `K-10b`, `N-2`, `N-5a`, `N-5b`, `N-5c`, `N-5d`, `N-5e`, `N-6a`, `N-6b`, `N-6c`, `N-7`, `N-8a`, `N-8b`, `N-8c`, `N-11a`, `N-11b`, `X1-지도-Admission / in-flight`, `X1-#10a`, `X2-P1-3b`
|
||||
- 검증: websocket·grpc adapter `check`, `./gradlew -p optional-platforms ci`, gRPC ledger PG lane
|
||||
|
||||
### P6: Redis (`adapter:outbound:redis-runtime`, `adapter:outbound:redis-sdk`, `adapter:outbound:cache-redis`)
|
||||
|
||||
- W1: `NEW-5a` (ACL `+time` + 실제로 `TIME`을 부르는 probe)
|
||||
- W2: `G-1b`, `G-1c`, `G-2a`, `G-3a`, `G-3b`, `G-9a`, `G-9b`, `G-10a`, `G-10b`, `S3-#4a`, `S6-#6b`, `NEW-5c`, 그리고 `NEW-5b`(테스트 시계 +1h 버그)
|
||||
- 검증: 소유 leaf `check`, `redisTopologyTest`, `LiveRedisSemanticPortsTest` 4건 통과
|
||||
|
||||
### P7: core + bootstrap/sample (`domain-core`, `shared-contract`, `application-core`, `adapter:outbound:support`, `adapter:outbound:identifier`, `app-bootstrap`, `sample-portfolio`)
|
||||
|
||||
- W1: `A-1a`, `TEST-F-2c`(PII 테스트를 실제로 실패할 수 있게 — `A-1b`와 함께)
|
||||
- W2: `A-7a`, `A-7b`, `A-8b`, `X1-#1d`, `S4-#4a`, `S4-#14a`, `L-7a`, `L-8a`, `L-8b`
|
||||
- 검증: 소유 leaf `check`, `:app-bootstrap:integrationTest`, `:sample-portfolio:systemTest`
|
||||
|
||||
### P8: GraphQL (`adapter:inbound:graphql`)
|
||||
|
||||
- W1: `J-8`
|
||||
- W2: `J-2`, `J-3a`, `J-4a`, `J-4b`, `J-9a`, `J-12 / X2-P2-6b`, `S5-#6a`, `S5-lead-3`, `NEW-9a`
|
||||
- 검증: graphql `check`, graphql 실제 lane
|
||||
|
||||
### P9: JPA / PostgreSQL + durable operation (`adapter:outbound:persistence-jpa`, `application-core` operation 패키지, `adapter:inbound:web` operation 엔드포인트)
|
||||
|
||||
- W1: `E-10a`, `E-10c`
|
||||
- W2: `E-2b`, `E-3a`, `E-4a`, `E-4b`, `E-5a`, `E-5b`, `E-7`, `E-8a`, `E-8b`, `S6-#3b`, `NEW-7a`, `NEW-7b`(결정 15 — `POST /operations`(202)·`GET`·`DELETE /operations/{id}`)
|
||||
- 검증: persistence-jpa `check`, `jpaPlatform*Test`·`postgresql*IntegrationTest`, web `check`, `verifyPublicPathSnapshot`(새 경로 승인)
|
||||
|
||||
### P10: web (`adapter:inbound:web`, `adapter:inbound:web-advanced`)
|
||||
|
||||
- W1: `I-2a`, `I-2b`, `I-5a`, `I-8b`, `NEW-10a`, `NEW-10b`, `NEW-10c`
|
||||
- W2: `I-3b`, `I-4a`, `I-4b`, `I-6a`(결정 13 — category 필수, 판정은 유스케이스), `S6-#11b`
|
||||
- 검증: web·web-advanced·web-notification `check`, `verifyPublicPathSnapshot`
|
||||
|
||||
### P11: HTTP client (`adapter:outbound:httpclient`)
|
||||
|
||||
- D: `S3-#1` — reactive(WebClient·Reactor Netty) 스택과 webflux·reactor 의존 삭제(결정 9). `H-5a`–`H-5c`, `H-7b`, `S3-#2a`는 이 삭제로 닫힌다(남은 blocking 경로에 같은 결함이 없는지 확인 후).
|
||||
- W1: `H-2`, `H-3a`, `H-3b`, `H-3c`, `H-4a`
|
||||
- W2: `H-6a`, `H-6b`, `H-8`, `H-9`, `S3-#13b`
|
||||
- 검증: httpclient `check`, lockfile 재생성, `verifyDependencyLocks`
|
||||
|
||||
### P12: MongoDB (`adapter:outbound:persistence-mongo`)
|
||||
|
||||
- W1: `F-1a`, `F-1b`, `F-5a`, `F-5b`, `F-5c`, `X2-P1-1b`(registry edge 추가 필요 — 이유를 커밋에)
|
||||
- W2: `F-2a`, `F-2b`, `F-4a`, `F-4b`, `F-8`
|
||||
- 검증: persistence-mongo `check`, `mongo*Test` 실제 lane
|
||||
|
||||
### P13: build / CI (`src/build-logic`, `src/build-tools`, root Gradle, `.github/workflows`, `scripts/`)
|
||||
|
||||
- W1: `O-5b`
|
||||
- W2: `O-3a`, `O-3b`, `O-3c`, `NEW-1a`(compose smoke가 켜진 capability·DB 벤더를 health component·info로 확인). `NEW-1b`(18 lane 실제 실행)는 Wave 4에서.
|
||||
- 검증: `./gradlew -p build-logic test`, `./gradlew -p build-tools test`, `ci`, 로컬에서 compose smoke 1개 lane 이상 실제 실행
|
||||
|
||||
### 실행 순서
|
||||
|
||||
동시 3개. 삭제가 있는 묶음을 먼저 돌린다: P11 · P3 · P2 → P1 · P4 · P10 → P5 · P6 · P9 → P7 · P8 · P12 · P13. 앞 묶음이 끝나면 다음 묶음을 바로 넣는다.
|
||||
|
||||
- [ ] Wave 1–2 묶음 13개 실행, 결과 파일 13개 수집
|
||||
- [ ] `D`·`W1` 커밋 통합 → Wave 종료 검증 → 현황표·「제거된 코드」 갱신 → 커밋 `review-followup Wave 1` → Slack 브리핑
|
||||
- [ ] `W2` 커밋 통합 → Wave 종료 검증 → 현황표 갱신 → 커밋 `review-followup Wave 2` → Slack 브리핑
|
||||
|
||||
---
|
||||
|
||||
## Wave 3 — 구조 (시작할 때 상세 Task 추가)
|
||||
|
||||
공통 작업(여러 leaf를 한 번에 바꿔서 순차로 한다):
|
||||
|
||||
- 3-A 에러 어휘: Envelope 하나(결정 2), `ApiErrorCode` 하나, shared 예외에 `ApiErrorCarrier`, `Category`별 한국어 문구 표(결정 11), IAE는 모든 전송 400, Draft-12 offset 문서만 예외(결정 12). X2 P2-1~P2-3, S5 관련 행.
|
||||
- 3-B 설정 prefix `app.*` 통일(결정 16).
|
||||
- 3-C outbox canonical 통일(결정 7) + outbox relay·멱등성 executor 조립을 `composition:*` 모듈로(결정 3, `NEW-2`) + legacy Kafka seam 삭제(`X1-#1f`, `NEW-4a`) + sample `SampleIdempotencyConfig` 복사본 제거.
|
||||
- 3-D 공통 유틸: `Sha256`, `Backoff`, traceparent 파싱, tenant 값 타입, caller 트랜잭션 guard, 서명 헬퍼.
|
||||
|
||||
그다음 영역별: Kafka 소비(결정 10), SES → AWS SDK(결정 17), gRPC protobuf 플러그인 + Buf(결정 18), `persistence-notification` leaf 추출, SRP 분해, 구현 1개 인터페이스 정리, 이름 규칙, 빌드 게이트 이동(결정 4, API surface → `check` 결정 20).
|
||||
|
||||
## Wave 4 — 테스트 규칙 (시작할 때 상세 Task 추가)
|
||||
|
||||
`AGENTS.md` 규칙 2를 한국어로 수정, 포트별 추상 계약 테스트(lock·lease 포함, 결정 8), 약한 단언 정리, 계층별 모범 모듈.
|
||||
|
||||
## Wave 5 — 문서 (시작할 때 상세 Task 추가)
|
||||
|
||||
W5 행 전부, `docs/study/*.ko.md`·`docs/*-superpowers-package/`를 현재 코드 기준으로 갱신(결정 6), 현황표 마감.
|
||||
|
||||
---
|
||||
|
||||
## 진행 기록
|
||||
|
||||
| Wave | 상태 | 검증 | 커밋 | 비고 |
|
||||
|---|---|---|---|---|
|
||||
| 준비 | 완료 (2026-09-25) | 기준 `./gradlew check --continue` 통과(481 task) | - | 현황표 812행(완료 161 / 해당 없음 106 / 남음 544 / 보류 1), 소유자 결정 20건 |
|
||||
Reference in New Issue
Block a user