Files
clean-architecture-backend-…/docs/history/packages/graphql-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

3.9 KiB
Raw Blame History

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

  • 상태: 보관
  • 작성일: 2026-08-13
  • 요약: GraphQL 설계 패키지 묶음을 받을 때 한 정적 검증 결과다.
  • 현재 정본: src/adapter/inbound/graphql/README.md

GraphQL Superpowers 문서 정적 검증 결과

  • 검증 시각 기준: 2026-08-12
  • 검증 대상: 설계서 1개, Stable 구현 계획서 1개, Advanced·Experimental 확장 계획서 1개
  • 검증 명령: python3 validate_graphql_docs.py
  • 결과: PASS
  • 실행 검사: 1,475
  • 통과: 1,475
  • 실패: 0

문서 규모

문서 행 수 크기
GraphQL API 실행 플랫폼 설계서 2,553 93,359 bytes
Stable 구현 계획서 4,560 209,041 bytes
Advanced 확장 계획서 1,976 105,717 bytes

계획 구조

항목 Stable Advanced
Task 수 48 19
Create 경로 수 227 113
Task 번호 연속성 PASS PASS
모든 Task의 Files·Interfaces PASS PASS
모든 Task의 Implementation Requirements PASS PASS
모든 Task의 Step 1–5 PASS PASS
실패·통과 예상 결과 PASS PASS
Task별 Git commit 명령 PASS PASS
Create 경로 중복 없음 없음
Stable·Advanced 경로 충돌 없음 없음

핵심 계약 검증

SDL-first external contract
Single Executable Schema Stable default
HTTP POST Stable profile
application/graphql-response+json preferred
Validation 이후 Field Error·Partial Data는 HTTP 200
Draft 294는 Stable에서 제외
JPA Entity·MongoDB Document 직접 노출 금지
GraphQL Multipart Upload 미지원·Fileserver 사용
request-wide database transaction 금지
DataLoader request scope
Finite Fetch Profile
HMAC-signed cursor
Mutation idempotency·expected version 분리
Parser·shape·complexity·runtime response budget
Actor·Field·Object·Tenant authorization
Low-cardinality observability
Stable/Advanced dependency isolation
Persisted Operation·WebSocket·SSE·Federation 분리
RSocket·HTTP GET·Incremental Delivery Experimental

위 계약은 설계서와 계획서의 필수 문자열·모듈 경로·Task별 파일·테스트를 대조해 검증했습니다.

입력 리서치 추적성

  • 첨부된 GraphQL API 실행 플랫폼 심층 리서치 원문 전체가 설계서의 부록 B에 포함되어 있습니다.
  • 설계 본문은 원문의 용어와 결론을 유지하면서 구현 판단을 Stable·Advanced·Experimental로 고정합니다.
  • 설계서와 입력 원문의 exact text 포함 검사를 별도로 통과했습니다.

패키지 검증 항목

문서 파일 존재
Markdown code fence 균형
Task 1–48 / 1–19 연속성
Task별 테스트·명령·commit
정확한 Create 경로
Placeholder 금지
Stable module에 WebSocket·Federation·Persisted Operation 경로 부재
Advanced module에 feature flag와 capability 경로 존재
금지 API pattern 부재
문서 SHA-256 계산

검증 범위의 한계

현재 PASS는 문서의 정적 구조, 요구사항 추적성, 내부 계약과 실행 계획의 완결성을 의미합니다. 실제 Backend Skeleton 저장소가 입력으로 제공되지 않았으므로 다음은 실행하지 않았습니다.

Gradle configuration·compile
Spring Boot ApplicationContext 기동
SchemaMappingInspector 실제 결과
GraphQlTester HTTP·WebFlux contract
JPA·MongoDB statement/query-count integration
query bomb·complexity load test
Virtual Thread·event-loop blocking test
WebSocket·SSE soak test
Federation composition·router integration
actual Git commit

실제 구현에서는 Stable Task 1–48을 먼저 수행해 Stable Release Gate를 통과한 뒤 Advanced Task 1–19를 시작해야 합니다.