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:
DongHyeonka
2026-11-07 22:20:18 +09:00
parent 37c88fedd4
commit 59dff0041c
44 changed files with 128 additions and 47 deletions
+46 -3
View File
@@ -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]: