Files
clean-architecture-backend-…/docs/history/packages/web-superpowers-package/VALIDATION.md
T
DongHyeonka 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +09:00

5.4 KiB

기록 · 납품 패키지 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 보관
  • 작성일: 2026-08-28
  • 요약: 웹 inbound HTTP 설계 패키지 묶음을 받을 때 한 정적 검증 결과다.
  • 현재 정본: docs/web/http-contract.md

Web Superpowers 문서 정적 검증 결과

검증 기준일: 2026-08-13

1. 검증 대상

문서 행 수
web-inbound-http-api-execution-platform-design.md 1,656
web-inbound-http-api-execution-platform-implementation-plan.md 4,762
web-advanced-capabilities-expansion-plan.md 1,532
원본 심층 리서치 1,597

2. 구조 검증

항목 결과
실행 검사 1,097
통과 1,097
실패 0
Stable Task 58
Advanced Task 19
Stable Create 경로 289
Advanced Create 경로 94
Stable Task 번호 연속성 PASS
Advanced Task 번호 연속성 PASS
모든 Task의 Files·Interfaces PASS
모든 Task의 Implementation requirements PASS
모든 Task의 Step 1~5 PASS
모든 Task의 실패·통과 예상 결과 PASS
모든 Task의 Git commit 명령 PASS
Stable Create 경로 중복 없음
Advanced Create 경로 중복 없음
Stable·Advanced Create 경로 충돌 없음
Markdown code fence 균형 PASS
TODO·TBD·FIXME 없음

검증 명령:

cd /mnt/data
./validate_web_docs.py

실행 결과:

checks=1097 passed=1097 failed=0

3. 설계 핵심 계약 검증

다음 계약이 설계서와 계획서에 모두 존재하는지 확인했습니다.

W1 / W2 / W3 / W4 공개 계층
MVC와 WebFlux Starter 상호 배타성
Request / Application / Response Evidence 분리
APPLICATION_COMMITTED와 HTTP response delivery 분리
RFC 9457 Problem Details
400 / 422 분리
409 / 412 분리
OpenAPI 3.1.2 Stable
Path major API version
HMAC keyset cursor
ETag / If-Match
Idempotency semantic fingerprint
Redis가 DB commit evidence의 유일한 source가 아님
Business mutation + JPA idempotency evidence same transaction
Application commit 후 response-loss fault test
Durable acceptance 이후에만 202
Trusted Nginx forwarded-header boundary
Tomcat / Jetty / Reactor Netty / Nginx 실제 gate
Rate limit 429와 Admission 503 분리
Low-cardinality metric·access log
Stable·Advanced dependency 격리

4. 계획 완결성 검증

Stable 계획은 다음 단계로 구성됩니다.

Task 1~14
→ Core·HTTP·JSON·Problem·Architecture Foundation

Task 15~22
→ MVC·Tomcat·Jetty·WebFlux·Reactor Netty

Task 23~30
→ Security·Proxy·Versioning·Route·OpenAPI

Task 31~36
→ Collection Query·Cursor·Conditional·Evidence

Task 37~43
→ Idempotency·JPA Evidence·Redis Gate·Response Loss

Task 44~48
→ Durable Operation·Outbox·HTTP Resource·Cache

Task 49~55
→ Budget·Rate·Admission·CORS/CSRF·Order·Observability·Nginx

Task 56~58
→ Cross-stack Contract·Performance·Stable Release

Advanced 계획은 다음 단계로 구성됩니다.

Task 1~3
→ Module isolation·Virtual Thread·Controlled Blocking Bridge

Task 4~5
→ JSON Merge Patch·JSON Patch

Task 6~13
→ Streaming Core·SSE·NDJSON·JSON Sequence·Drain·Replay

Task 14~18
→ Functional WebFlux·CBOR·XML·OpenAPI 3.2·RateLimit Draft

Task 19
→ Soak·Rollback·Promotion Gate

5. 검증 범위의 한계

현재 검증은 문서의 구조, 요구사항 추적성, 내부 계약, 파일 경로, 작업 순서에 대한 정적 검증입니다.

실제 Backend Skeleton 저장소가 이번 입력에 포함되지 않았으므로 다음은 실행한 상태가 아닙니다.

Gradle configuration·compile
Spring Boot ApplicationContext 기동
Tomcat·Jetty·Reactor Netty 실제 contract
PostgreSQL JPA idempotency transaction
Redis concurrent gate
Messaging outbox operation
Nginx TLS·Forwarded topology
commit 후 TCP reset fault injection
OpenAPI generated client compile
abuse·load·graceful shutdown
Git commit

계획서의 경로와 package는 다음 명시적 가정을 사용합니다.

Java 21
Gradle Kotlin DSL
Spring Boot 4.1 BOM
root package: io.backend.skeleton.web
stable module root: modules/web
advanced module root: modules/web-advanced

6. 패키지 무결성 검증

패키지 조립 후 다음 검증을 추가로 수행했습니다.

Package-local validator
→ checks=1104 passed=1104 failed=0

MANIFEST.sha256
→ 모든 7개 파일 OK

ZIP CRC
→ No errors detected

독립 문서와 패키지 내부 문서
→ byte 단위 일치

검증 명령:

cd /mnt/data/web-superpowers-package
./validate_web_docs.py
sha256sum -c MANIFEST.sha256

cd /mnt/data
unzip -t web-superpowers-package.zip
cmp web-inbound-http-api-execution-platform-design.md \
    web-superpowers-package/docs/superpowers/specs/2026-08-13-web-inbound-http-api-execution-platform-design.md
cmp web-inbound-http-api-execution-platform-implementation-plan.md \
    web-superpowers-package/docs/superpowers/plans/2026-08-13-web-inbound-http-api-execution-platform-implementation-plan.md
cmp web-advanced-capabilities-expansion-plan.md \
    web-superpowers-package/docs/superpowers/plans/2026-08-13-web-advanced-capabilities-expansion-plan.md