문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만 지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다. 그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데, 2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다. - check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다· 입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드, 따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다. - runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가 울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다. - 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명, docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안). - docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고, 링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs docs-system.md 6.2절 다섯 칸)을 더했다. 버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다). 위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo 밖이라 고치지 않았다(총괄에게 알린다). 검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함), check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시 worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건, 1건 실패했다.
3.8 KiB
결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-25
- 요약: OpenAPI 3.2 문서는 나란히 만들고 실험 등급으로 둔다는 결정이다.
- 현재 정본:
docs/web/openapi-32-compatibility.md
ADR-WEB-ADV-003: OpenAPI 3.2는 나란히 생성하고 실험용으로 남는다
- 상태: 채택
- 날짜: 2026-08-25
- 범위:
adapter:inbound:web—advanced.openapi
배경
Advanced Task 17은 Stable 3.1.2 snapshot 옆에 OpenAPI 3.2 생성 lane을 더한다.
3.2 생성은 싸다. 채택은 싸지 않고, 생성된 문서가 멀쩡해 보여서 둘이 뒤섞인다. API 설명의 가치는 전부 그것을 쓰는 쪽에 있고, client 생성기가 다 이해하지 못하는 버전의 문서는 컴파일되지만 틀린 client를 낳는다 — 문서가 아예 없는 것보다 나쁘다.
결정
3.1.2가 릴리스 artifact로 남는다. OpenApiVersionLane.STABLE_3_1.releaseArtifact()는 true이고 EXPERIMENTAL_3_2의 것은
false다. 이것은 설정이 아니라 타입의 성질이다.
3.2를 생성해도 3.1 snapshot이 바뀌면 안 된다. 둘은 같은 모델에서 만들어지므로, 3.2로 가는 길에 모델을 바꾸는 기여자는 실제로
출하하는 artifact를 바꾼다 — 소리 없이, 실험 lane이 돌 때만. OpenApi32CompatibilityReport가 전후의 snapshot hash를 비교하고,
차이를 승격을 막는 것으로 만든다.
2026-09-25:
OpenApi32CompatibilityReport와OpenApiToolchainMatrix를 지웠다 — 운영 코드에 둔 승격 검사인데 자기 시험만 불렀다.WebOpenApi32Generator는adapter:inbound:web-advanced에 라이브러리 코드로 남는다. 아래 결정은 바뀌지 않았다.
도구 네 종류를 따로 검사한다. parser는 구조 오류를 알린다. linter는 문체 규칙을 적용하고 parser가 거절하는 문서도 받는다. 생성기는 client 코드를 만들고, 지원되지 않는 구문이 드러나는 곳이 여기다 — 오류가 아니라 시그니처가 틀린 메서드로. 그 생성 코드를 컴파일하는 것이 그것을 잡는 유일한 단계다. 「OpenAPI 3.2가 된다」는 누구도 할 수 있는 말이 아니다. 「이 문서를 이 버전의 이 네 도구가 맞게 읽는다」는 할 수 있다.
표가 얼마나 초록이든 승격에는 채택된 ADR이 필요하다. promotionBlockers(false)는 언제나 그 막음을 담는다. 기계로 검사하는
표는 쓰는 쪽 집단이 준비됐는지 정할 수 없다.
streaming 설명의 차이는 따로 알린다. 이 애플리케이션에서 두 버전의 실질적 차이가 그것이고, 통과·실패 하나로 접으면 무엇이 바뀌었는지 가려진다.
결과
- 3.2 문서는 릴리스 workflow가 아니라 실험 workflow의 artifact로만 게시한다.
- 3.1만 이해하는 client 생성기는 영향을 받지 않는다. 그것이 요점이다.
- 나중에 3.2를 채택하는 것은 이름 있는 쓰는 쪽 표를 뒤에 둔, 문서로 남긴 결정이다.
따져 본 대안
- 3.2로 바꾸고 3.1로 낮춘 것을 둔다. 버렸다: 낮추기는 바로 3.2를 원한 이유인 구문에서 손실이 있어서, 두 독자 모두에게 틀린 설명을 출하하게 된다.
- 3.2만 생성하고 쓰는 쪽이 알아서 하게 둔다. 버렸다: 실패 방식은 컴파일되고 잘못 동작하는 생성 client다.
- 표에서 client 컴파일 단계를 건너뛴다. 버렸다: 다른 단계가 놓치는 실패를 잡는 유일한 단계다.