rules-that-must-be-followed

name	rules-that-must-be-followed
description	42jerrykim.github.io Hugo 블로그의 모든 글쓰기·편집 작업에 적용되는 전역 필수 규칙. frontmatter(draft, tags, description, title), 날짜 확인, 본문 링크 검증, 독자용 본문 원칙, Mermaid 다이어그램 문법, 알고리즘 코드 주석 규칙, 직접 인용 검증을 포함한다. 글 작성·수정, 새 포스트 생성, 컬렉션 글 작업 시 항상 적용한다.

전역 필수 규칙

content/ 아래 마크다운을 새로 만들거나 수정할 때는 항상 아래 항목을 확인한다.

1. Frontmatter 체크리스트

• draft: 새 md 파일을 만들 때 draft: true로 시작한다. 배포 전 검토 후 필요 시 draft: false로 변경한다.
• tags: 25개 이상. data/tags.yaml은 실제로 병용되는 영/한 쌍을 영어(한글) 형식의 단일 승인 태그로 통합했으므로(Phase 8), 더 이상 같은 개념을 영어·한글 두 줄로 나눠 태그 수를 채우지 않는다. 최소 10개는 data/tags.yaml 승인 태그를 표기 그대로(대소문자·하이픈·괄호 포함) 사용해 다른 글과 실제로 연결되게 한다. 문제 ID·인물명·명령어명처럼 글마다 고유한 태그는 나머지 자리를 채우되, 승인 태그를 임의로 변형(소문자화, 띄어쓰기 변경 등)하지 않는다 — 표기가 갈리면 같은 개념이 서로 다른 태그 페이지로 쪼개진다. 부족하면 목록을 참고해 새 태그를 추가한다.
• description: 약 150자 분량(허용 범위 약 120~170자)으로 작성한다.
• title: 70자 이하로 작성한다.

CI 자동검증: title(≤70자)·tags(≥25개)·태그 표기가 data/tags.yaml 승인 태그와 대소문자 단위로 일치하는지를 .github/workflows/lint-content.yml(script/lint_frontmatter.py)이 PR에서 신규 md 파일에 한해 자동으로 검사한다(위반 시 CI 실패). description 길이는 경고만, 기존 파일 수정은 강제하지 않는다 — 과거 콘텐츠 다수가 이 규칙 이전에 작성됐기 때문이다. 태그 파편화 배경과 50→25 기준 재조정 근거는 tag-consolidation-plan.md Phase 8 참고.

2. 날짜 확인

새 콘텐츠의 작성일·수정일·lastmod 등 날짜가 필요하면 추측하지 말고, 터미널에서 오늘 날짜를 확인한 뒤 그 값을 사용한다.

• PowerShell: Get-Date -Format "yyyy-MM-dd"
• CMD: echo %date%

3. 본문 링크 검증

1. 본문에 외부 링크를 추가하기 전, 해당 URL에 HTTP 요청(또는 브라우저·도구)을 보내 접근 가능한지 확인한다.
2. 404·5xx·접근 불가 응답인 URL은 추가하지 않는다.
3. 기존 링크가 404 등으로 확인되면 제거하거나 접근 가능한 대체 URL로 교체한다.

4. 독자용 본문 원칙

• 저장소에 존재하지 않는 파일·자료를 본문에서 인용하지 않는다.
• "게시 전 자가 점검", "평가 기준 재확인: 충족" 같은 작성자용 메타·자기인증 블록은 독자용 본문에 남기지 않는다. 검수는 본문 밖에서 수행한다.

5. Mermaid 다이어그램 문법

• 노드 ID는 공백 없이 camelCase·PascalCase로 작성하고, 예약어(end, subgraph, graph 등)는 노드 ID로 사용하지 않는다.
• 노드 라벨·엣지 라벨에 대괄호, 등호, 비교 연산자, 수식, 괄호 등이 포함되면 항상 ""(double quote)로 전체 라벨을 감싼다. HTML 엔티티·특수문자는 가능한 한 지양하고, 필요 시 따옴표로 감싼다.
  • 예: F["changes = sum D[l+1..r]"], A["입력 n"], D -->|"type 2: 2 l r"| F[...]
• 줄바꿈은 \n 대신 </br>을 사용한다 (렌더러에 따라 <br/>도 허용될 수 있음).

6. 알고리즘 코드 주석

알고리즘 문제 정답 코드의 상단에는 다음 주석을 추가한다:

42jerrykim.github.io에서 더 많은 정보를 확인할 수 있다

7. 직접 인용 검증

• 본문에 저자·매체를 명시한 직접 인용(blockquote)을 넣을 때는 게시 전 원문을 WebFetch(차단 시 insane-search)로 대조해 정확한 문장·발행일인지 확인한다.
• 대조 결과 문장이 원문에 없거나 날짜가 다르면, 인용부호를 버리고 패러프레이즈로 바꾸거나 실제로 대조된 문장으로 교체한다.
• 채점 단계(post-quality-loop)가 아니라 작성 시점에 이 확인을 해야 한다 — AI가 그럴듯하지만 실재하지 않는 문장을 실존 인물에게 귀속시키는 환각은, 다른 사실 오류와 달리 겉으로는 매우 자연스러워 보여 뒤늦게 발견되면 이미 게시된 뒤일 수 있다.