ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 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건 실패했다.
This commit is contained in:
+15
-3
@@ -140,7 +140,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서,
|
||||
`history/evidence/`·`history/plans/evidence/` 증거, `history/packages/` 납품 패키지,
|
||||
`history/study/` 학습 문서. ADR의 둘째 줄은
|
||||
`> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다.
|
||||
`> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다.
|
||||
- 상태는 종류마다 고정 어휘다.
|
||||
|
||||
| 종류 | 상태 |
|
||||
@@ -159,6 +159,16 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
`capability-status.md` 「제거된 코드」로 지운 것이 확인된 설계서 다섯은 「폐기」다.
|
||||
- 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다.
|
||||
|
||||
## 모듈 README
|
||||
|
||||
leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것(정본은 design-docs `conventions/docs-system.md` 6.2절):
|
||||
|
||||
1. 책임 한 문장과 소유하지 않는 것
|
||||
2. 공개 표면(포트·API·설정 prefix)
|
||||
3. 조립: 더할 한 줄, 끄는 키, 필요한 env 키
|
||||
4. 테스트: registry의 Gradle 경로로 만든 명령(숫자·버전을 복사하지 않는다)
|
||||
5. 더 읽을 곳: 그 폴더의 `AGENTS.md`(지역 규칙), 영역 운영 문서
|
||||
|
||||
## 문서와 코드를 같은 변경에서 고친다
|
||||
|
||||
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법:
|
||||
@@ -173,7 +183,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
|
||||
## 문서 검사
|
||||
|
||||
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여섯을 본다. PR마다 workflow `docs-check`가
|
||||
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 workflow `docs-check`가
|
||||
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
|
||||
문서를 낡게 만든다.
|
||||
|
||||
@@ -185,6 +195,8 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
|
||||
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
|
||||
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
|
||||
| `link` | 살아 있는 문서의 상대 링크(`[글](경로)`)가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 |
|
||||
| `style` | 살아 있는 문서의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안의 인용은 보지 않는다 |
|
||||
|
||||
- 하나만 돌리기: `python3 scripts/check-docs.py --only head`.
|
||||
- 소스 세트의 resources 폴더 아래 `.md`(`src/**/src/<세트>/resources/`)는 테스트가 읽는 입력이라 문서로 보지 않는다.
|
||||
@@ -194,7 +206,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
- 줄을 지우면 같은 변경에서 `scripts/check-docs.py`의 `FROZEN`에서 그 줄의 지문도 뺀다. 남겨 두면 실패한다(남은
|
||||
지문은 지운 줄을 다시 더하는 길이다). 2026-11-07 번역 단계에서 목록과 `FROZEN`이 모두 비었다.
|
||||
- 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`.
|
||||
- 마크다운 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다.
|
||||
- 상대 링크는 `link` 검사가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL은 lychee(`link-check` workflow)가 본다.
|
||||
기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다.
|
||||
|
||||
## 여기에 없는 것
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-09-07
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-24
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-31
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-24
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-15
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `auth_401_error_rate_high` 또는 `jwks_refresh_failure_spike`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `runbook_link`, `dependency_name`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `authz_cross_tenant_violation` 또는 `authz_403_spike`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `principal_id_pseudonymized`, `tenant_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `dependency_error_rate_critical` 또는 `circuit_breaker_open`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `dependency_name`, `dependency_kind`(required|optional), `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `http_5xx_error_rate_critical`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `request_id`, `traceId`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `job_dead_letter`
|
||||
- alert payload 필수 field: `error.code=JOB_DEAD_LETTER`, `job_name`, `correlation_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `executor_rejected`
|
||||
- alert payload 필수 field: `error.code=JOB_EXECUTOR_REJECTED`, `executor_name`, `policy`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `job_timeout`
|
||||
- alert payload 필수 field: `error.code=JOB_TIMEOUT`, `job_name`, `correlation_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `outbox_dead_letter`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `outbox_publish_failed_rate`, `outbox_publisher_lag` 또는 `outbox_retry_long`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `rate_limit_429_high`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `rate_limit_key_type`(ip|principal|tenant), `runbook_link`
|
||||
|
||||
+46
-3
@@ -61,7 +61,7 @@ from pathlib import Path
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt"
|
||||
REGISTRY_FILE = "src/config/architecture/modules.json"
|
||||
CHECKS = ("language", "head", "reference", "number", "map", "readme", "link")
|
||||
CHECKS = ("language", "head", "reference", "number", "map", "readme", "link", "style")
|
||||
|
||||
# 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다.
|
||||
RECORD_KINDS = [
|
||||
@@ -91,7 +91,7 @@ STATUS = {
|
||||
HEAD_START = "<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->"
|
||||
HEAD_END = "<!-- 머리 블록 끝 -->"
|
||||
RECORD_LABEL = "> **기록 · {kind}** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다."
|
||||
DECISION_LABEL = "> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다."
|
||||
DECISION_LABEL = "> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다."
|
||||
HEAD_FIELDS = ("상태", "작성일", "요약", "현재 정본")
|
||||
HEAD_OPTIONAL = ("대체", "대체됨")
|
||||
HEAD_SEARCH_LINES = 20
|
||||
@@ -152,6 +152,9 @@ LINK_TEXT = re.compile(r"\[([^\]\n]*)\]\([^)\s]*\)")
|
||||
# 정해진 경로만 보고, 그 밖의 문서(`src/**/AGENTS.md`, `.claude/**`, 루트 `AGENTS.md`)의 상대 링크는 이 검사만 본다.
|
||||
LINK_TARGET = re.compile(r"\[[^\]\n]*\]\(([^)\s]+)\)")
|
||||
URL_SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*:", re.I)
|
||||
# 문체: 살아 있는 문서는 「~한다」로 쓴다(docs/README.md 「문서 수명과 언어」). 높임 문장 끝을 잡는다.
|
||||
CORNER_QUOTED = re.compile(r"「[^」\n]*」")
|
||||
POLITE = re.compile(r"(?:습니다|합니다|입니다|됩니다|십시오|하세요|주세요)(?=[.!?)\]」\s]|$)")
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -414,6 +417,45 @@ def check_link(root: Path, files: list[str]) -> list[Problem]:
|
||||
return problems
|
||||
|
||||
|
||||
def prose_lines(lines: list[str]) -> list[tuple[int, str]]:
|
||||
"""(줄 번호, 인라인 코드를 뺀 줄) — 코드 블록과 「이력」 인용 블록 밖에서만."""
|
||||
kept, fence, history = [], None, False
|
||||
for number, line in enumerate(lines, start=1):
|
||||
match = FENCE.match(line)
|
||||
if fence:
|
||||
if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence):
|
||||
fence = None
|
||||
continue
|
||||
if match:
|
||||
fence = match.group(1)
|
||||
continue
|
||||
quoted = line.lstrip().startswith(">")
|
||||
if quoted and HISTORY_QUOTE.match(line):
|
||||
history = True
|
||||
elif not quoted:
|
||||
history = False
|
||||
if not history:
|
||||
kept.append((number, INLINE.sub("", line)))
|
||||
return kept
|
||||
|
||||
|
||||
def check_style(root: Path, files: list[str]) -> list[Problem]:
|
||||
problems = []
|
||||
for path in files:
|
||||
if not is_living(path):
|
||||
continue
|
||||
text = (root / path).read_text(encoding="utf-8")
|
||||
lines = body_lines(text)
|
||||
offset = len(text.split("\n")) - len(lines)
|
||||
for number, line in prose_lines(lines):
|
||||
# 「~합니다」처럼 낫표나 따옴표 안의 말은 이 문서의 문장이 아니라 인용이다.
|
||||
found = POLITE.search(CORNER_QUOTED.sub("", QUOTED.sub("", line)))
|
||||
if found:
|
||||
problems.append(Problem("style", path, line.strip()[:80], f"높임 문체다(「~한다」로 쓴다): …{found.group(0)}",
|
||||
number + offset))
|
||||
return problems
|
||||
|
||||
|
||||
def registry_projects(root: Path) -> set[str]:
|
||||
registry = root / REGISTRY_FILE
|
||||
if not registry.is_file():
|
||||
@@ -681,7 +723,8 @@ def check_readme(root: Path, files: list[str]) -> list[Problem]:
|
||||
|
||||
|
||||
RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number,
|
||||
"map": check_map, "readme": check_readme, "link": check_link}
|
||||
"map": check_map, "readme": check_readme, "link": check_link,
|
||||
"style": check_style}
|
||||
|
||||
|
||||
def read_exceptions(text: str) -> list[str]:
|
||||
|
||||
@@ -471,6 +471,32 @@ class LinkTest(RepositoryTestCase):
|
||||
self.assertEqual(self.repo.run(("link",)), [])
|
||||
|
||||
|
||||
class StyleTest(RepositoryTestCase):
|
||||
def errors_for(self, text: str, path: str = "docs/guide.md") -> list[str]:
|
||||
self.repo.write(path, KOREAN + text)
|
||||
return self.repo.run(("style",))
|
||||
|
||||
def test_a_polite_sentence_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for("이 runbook은 다음 alert에서 발동됩니다.\n"), "높임 문체다")
|
||||
|
||||
def test_a_polite_request_at_the_end_of_a_line_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for("- 설정을 바꾼 뒤 다시 실행하세요\n"), "…하세요")
|
||||
|
||||
def test_the_plain_style_passes(self) -> None:
|
||||
self.assertEqual(self.errors_for("이 runbook은 다음 alert가 울리면 쓴다.\n"), [])
|
||||
|
||||
def test_quoted_code_and_history_mentions_are_skipped(self) -> None:
|
||||
text = ("문체는 「~한다」다. 「~합니다」와 섞지 않는다.\n"
|
||||
"응답 본문은 \"요청을 처리할 수 없습니다.\"다. `처리합니다.`는 코드다.\n"
|
||||
"```json\n{\"message\": \"처리할 수 없습니다.\"}\n```\n"
|
||||
"> 이력: 이 문서는 예전에 「~합니다」로 썼습니다.\n")
|
||||
self.assertEqual(self.errors_for(text), [])
|
||||
|
||||
def test_a_record_is_not_checked(self) -> None:
|
||||
self.repo.write("docs/design/2026-08-11-x-design.md", head() + "이 설계는 채택되었습니다.\n")
|
||||
self.assertEqual(self.repo.run(("style",)), [])
|
||||
|
||||
|
||||
class CommandLineTest(unittest.TestCase):
|
||||
def test_an_unknown_check_is_a_usage_error(self) -> None:
|
||||
self.assertEqual(check_docs.main(["--only", "spelling"]), 2)
|
||||
|
||||
Reference in New Issue
Block a user