위키 작성 표준¶

이 위키를 어느 PC·어느 세션에서 이어가도 일관된 결과가 나오게 하는 표준입니다. CLAUDE.md의 짧은 규칙을 풀어서 설명합니다.

1. 다이어그램 작성 기준¶

1-1. Mermaid를 쓸 수 있는 경우¶

다음 조건을 모두 만족하면 mermaid를 사용합니다:

• subgraph 없는 단순 흐름 (단일 노드 + 화살표만)
• 노드 6개 이하의 트리·그래프
• 분기({...})·합류만 있는 결정 다이어그램

예: README의 "지식 구조" graph TD, "Java 챕터 맵" graph LR.

1-2. Mermaid를 쓰면 안 되는 경우 — HTML+flexbox 사용¶

subgraph 안의 노드가 subgraph 바깥과 화살표로 연결되면 mermaid는 direction LR을 무시하고 부모 그래프 방향(TB)을 따라갑니다. (mermaid 알려진 버그)

ELK 렌더러(defaultRenderer: 'elk')도 mkdocs-material 환경에서 안 먹는 경우가 있습니다.

해결: HTML + 인라인 스타일 + flexbox로 직접 작성합니다.

표준 템플릿 (행 구조 4-1-2 예시)¶

<div style="display:flex;flex-direction:column;gap:14px;align-items:center;font-family:sans-serif;margin:24px 0;">

  <!-- 행 1: 4개 노드 가로 -->
  <div style="background:#eff6ff;border:1px solid #bfdbfe;border-radius:10px;padding:16px;width:100%;box-sizing:border-box;">
    <div style="font-weight:600;margin-bottom:12px;color:#1e40af;font-size:15px;">💻 그룹 제목</div>
    <div style="display:flex;align-items:stretch;gap:10px;">
      <div style="background:#dbeafe;border:2px solid #2563eb;border-radius:8px;padding:14px 10px;flex:1;text-align:center;color:#1e3a8a;font-weight:500;">노드 1</div>
      <div style="display:flex;align-items:center;font-size:24px;color:#2563eb;font-weight:bold;">→</div>
      <div style="background:#dbeafe;border:2px solid #2563eb;border-radius:8px;padding:14px 10px;flex:1;text-align:center;color:#1e3a8a;font-weight:500;">노드 2</div>
      <!-- ... -->
    </div>
  </div>

  <div style="font-size:28px;color:#999;line-height:1;">↓</div>

  <!-- 행 2: 1개 노드 (다리) -->
  <!-- 행 3: 2개 노드 -->

</div>

색 톤 표준 (3톤 통일)¶

6톤 이상 쓰지 말 것. 의미 그룹별로 같은 톤. 마지막 목적지는 border-width:3px로 강조.

1-3. 모든 다이어그램 아래 글 풀이 추가 (2채널)¶

다이어그램만 두지 말고 단계별 글 풀이를 본문 섹션으로 추가합니다. 시각 + 텍스트로 가독성 2채널을 확보합니다.

### 단계별 자세히

**1단계 — 그룹 A**

1. **노드 1** — 이 단계에서 무엇이 일어나는지 설명
2. **노드 2** — ...

**2단계 — 그룹 B**

...

1-4. 다이어그램 점검 체크리스트¶

• subgraph 안의 노드가 외부와 연결되는가? → HTML 사용
• 색이 4톤 이상인가? → 3톤으로 통일
• 노드 모양이 섞여 있는가? (사각형 + 원 등) → 같은 모양으로
• 다이어그램 아래 글 풀이가 있는가?
• 페이지 폭에 맞춰 노드가 작아지지 않는가? (flex:1 사용)

2. 콘텐츠 분량·구조 기준¶

2-1. 타입별 권장 분량¶

2-2. 부실 판정 기준¶

다음 중 하나면 보강 대상:

• 줄 수 50줄 미만 (concept/entity 기준)
• 정의·관련 페이지 외 본문이 거의 없음
• 표·코드 예시 없음
• 공식 자료 인용·외부 URL 없음

2-3. 페이지 표준 섹션 구조¶

---
title: ...
type: source | concept | entity | synthesis | comparison
tags: [...]
sources: [<주제>/원본파일.md]
external:
  - https://공식문서
  - https://기타URL
created: YYYY-MM-DD
updated: 2026-09-28
---

# 제목

## 정의 (또는 개요·핵심)
한두 문단으로 본질을 잡고, 인용 박스(`> "..."`)로 핵심 한 줄.

## 핵심 본문 (섹션 N개)
- 표 중심으로 정리 (불릿 나열보다 표가 비교·인지 쉬움)
- 코드 예시는 Before/After 또는 안 좋은 예/좋은 예

## 같은 인사이트 패턴 (위키 내 연결)
| 페이지 | 위험 | 해결 |
|--------|------|------|
| **이 페이지** | ... | ... |
| [[다른 페이지]] | ... | ... |

## 빠른 진단 / 체크리스트
명령어·grep·체크리스트 형태로 즉시 활용 가능한 정보.

## 원본 출처
- raw: `raw/<주제>/<파일>.md`
- 공식: [링크 텍스트](URL)

## 관련 페이지
- [[다른 위키 페이지]] — 관계 한 줄 설명

2-4. 외부 자료로 보강할 때¶

• 공식 문서 우선 — 블로그·SO 답변은 부차
• WebSearch로 최신성 확인 — 버전·API 변경 잦은 주제
• 3~5개 외부 출처를 종합 — 단일 출처 위험
• frontmatter external:에 모든 출처 명시

2-5. 코드·표 표시 — 글머리에서 빼낸다 (top-level)¶

규칙: 코드블록과 표는 항상 좌측정렬(top-level)로 둡니다. 글머리(리스트) 아래로 들여쓰지 않습니다.

리스트 항목에 코드가 딸릴 때는 들여쓰지 말고, 항목을 굵은 리드인으로 바꿔 코드를 빼냅니다:

❌ 나쁨 (글머리 종속 — 폭 좁고 번호 깨질 위험)
1. 별도 Bean으로 분리:
   ```java
   ...
   ```

✅ 좋음 (굵은 리드인 + top-level 코드)
**1) 별도 Bean으로 분리**

```java
...
```

• 단순 설명 뒤 코드: 앞 줄을 :로 끝맺어 연결감을 주고, 코드는 빈 줄 뒤 top-level.
• 번호가 중요한 절차: 리스트(1.) 대신 **1) …** 굵은 단락으로 → 코드 빼내도 번호 안 깨짐.
• 예외는 없습니다. 표는 무조건 top-level로 둡니다.

2-6. 대응·비교 내용은 마크다운 표로 — 코드블록 ASCII 정렬 금지¶

규칙: "A → B" 대응 관계나 항목 간 비교를 보여줄 때, 코드블록 안에서 공백으로 열을 맞추지 않습니다. 마크다운 표로 만듭니다.

이유: 코드블록의 열 맞춤은 모든 글자가 같은 폭이라는 가정 위에 서 있는데, 한글은 고정폭 폰트에서도 영문 폭의 정확히 2배가 아니어서 폰트·환경마다 줄이 어긋납니다. 게다가 정렬용 공백은 복붙할 내용도 아니면서 텍스트에 섞여 들어갑니다. 마크다운 표는 렌더러가 열을 맞추므로 폰트와 무관하게 항상 정렬됩니다.

판별 기준: 코드블록 안에 열 맞춤용 연속 공백과 →·| 같은 구분 기호가 있고, 내용이 실행하거나 복붙할 대상이 아니라 대응 관계의 설명이면 표로 바꿀 대상입니다.

예외 (코드블록 유지): 실행 명령·실제 출력 로그·디렉터리 트리·diff처럼 내용 자체가 모노스페이스 산출물인 경우는 코드블록이 맞습니다. 이 경우에도 한글로 열을 맞추는 시도는 하지 않습니다 — 설명이 필요하면 주석 한 줄로 붙입니다.

전환 지침 — 블록의 맥락(유형)에 따라 표의 축이 다릅니다. 기계적으로 바꾸면 원래 배치가 담던 의미가 죽으므로, 먼저 블록이 무엇을 말하는지 판정합니다:

적용 사례: guide-harness-module2 Step 2 변환 예시 — .env 커밋 → STOP: ... ASCII 대응표가 줄이 어긋나 2열 마크다운 표로 전환 (2026-07-05).

3. 마킹·교차참조 패턴¶

3-1. frontmatter 필수 키¶

---
title: 페이지 제목                    # 필수
type: concept                        # 필수: source/concept/entity/synthesis/comparison
tags: [tag1, tag2]                   # 필수
sources: [<주제>/원본.md]             # source/concept/entity는 필수 (raw 경로)
external:                            # 외부 자료로 보강 시 필수
  - https://공식
created: YYYY-MM-DD                  # 필수
updated: 2026-09-28
---

3-2. raw 인용 방식¶

본문에서 raw 원본을 직접 인용할 때:

> 원본 인용 (`raw/<주제>/<파일>.md`):
> "원본의 핵심 문장."

3-3. 패턴 누적 — "같은 인사이트 패턴" 비교표¶

이 위키의 가장 큰 가치 → 비슷한 구조의 함정·해결이 여러 페이지에 흩어진 것을 한 비교표로 묶어 양방향 연결.

예시 — "기본값과 가정의 함정" 패턴은 멤버 페이지 전부가 같은 행 집합·같은 열(페이지 | 위험한 기본값·가정 | 결과 | 실무 권장) 의 표를 한 벌씩 갖고, 각 페이지는 자기 행만 **주제 (이 페이지)**로 표시합니다. 정본 표는 멤버 페이지 어느 곳에서든 확인할 수 있습니다.

• concept-transactional-rollback-policy — @Transactional 체크 예외 커밋
• concept-api-backward-compatibility — 클라이언트 JSON 파서의 관용성 가정
• concept-api-versioning — 버전 분리의 영구 유지 부담
• concept-jpa-enum-mapping — @Enumerated 기본 ORDINAL
• concept-cronjob-concurrency-trap — K8s concurrencyPolicy: Allow
• concept-keepalive-timeout-race — 웹 서버 keep-alive ≤ LB idle
• concept-db-connection-pool — maxLifetime이 인프라 idle 제한보다 긴 설정
• concept-varchar-length-prefix — 관습적 VARCHAR(255)
• concept-java-serialization-risk — ObjectInputStream의 암묵적 신뢰
• concept-id-reference-vs-object-reference — JPA 객체 참조의 경계 관통

패턴에 새 멤버를 추가할 때는 정본 행 집합에 한 행을 더하고, 모든 멤버 페이지의 표를 같은 내용으로 갱신합니다. 일부 페이지에만 행을 넣으면 표가 페이지마다 갈라집니다.

새 페이지 작성 시 기존 페이지에서 같은 패턴 찾아 양방향 추가.

3-4. 관련 페이지 섹션¶

마지막에 항상 ## 관련 페이지를 둡니다. 각 링크에 한 줄 설명을 답니다:

## 관련 페이지

- [[concept-spring-core]] — Spring DI의 기반
- [[entity-spring-boot]] — 실무 적용 환경

4. mkdocs nav 분류 기준¶

4-1. 현재 카테고리 4개¶

4-2. 새 카테고리 추가 기준¶

기존 4개에 자연스럽게 안 들어가고, 향후 같은 주제 페이지가 3개 이상 누적될 가능성 있을 때만 신규로 추가합니다.

예: "DB·운영·인프라"는 처음 1개를 추가한 뒤 나중에 누적을 보고 신설했습니다.

4-3. 하위 그룹¶

각 카테고리 안: 개념 / 도구 / 인물 / 소스 / 실습 / 환경설정 중 적합한 것.

5. ingest 워크플로 (사용자가 영상·자료 제공 시)¶

1. raw 저장 — raw/<채널>/<주제>.md 형식. 타임스탬프 보존.
2. wiki 페이지 작성 — type 결정 (source vs concept). 분량 기준 준수.
3. 같은 패턴 찾기 — 이미 위키에 있는 비슷한 페이지와 비교표 작성.
4. mkdocs.yml 메뉴 추가 — 적합한 카테고리·하위.
5. index.md 추가 — 해당 type 카테고리에 한 줄.
6. log.md 추가 — 작업 기록.
7. bash scripts/build-site.sh — 빌드.

6. 빌드·배포 워크플로¶

# 1. 빌드 (wiki/ → docs/ → site/)
bash scripts/build-site.sh

# 2. 로컬 프리뷰
.venv/bin/mkdocs serve
# → http://127.0.0.1:8000

# 3. Firebase 배포
firebase deploy --only hosting
# → https://wiki.wonslab.dev

중요: mkdocs serve는 docs/만 watch합니다. wiki/ 수정 후에는 반드시 build-site.sh를 다시 실행합니다.

선택적 자동 빌드:

fswatch -o wiki/ | xargs -n1 -I{} bash scripts/build-site.sh

7. 문체 표준¶

배경: 2026-07-02 진단에서 최근 보강분(신설 실습 섹션)이 기존 경어체 산문 한가운데 평어체로 끼어드는 "문체 섬" 현상이 반복 확인됨. 근본 원인은 이 규칙들이 명문화돼 있지 않아 세션·에이전트마다 달리 쓴 것 — 아래로 고정. 상세 진단·계획: plan-tone-consistency.

7-1. 문서군별 종결어미 매트릭스¶

전역 통일(전부 한다체) 대신 문서군별 표준을 유지합니다. 신설 산문은 소속 문서군 표준에 맞춥니다.

concept-*·entity-*(이 문서 포함)는 가이드와 동일하게 합니다체.

2026-07-02 개정: 기존에는 guide-*·concept-*·entity-*가 한다체였으나(브리핑체가 딱딱하다는 지적), 위키 독자 대상 산문 전체를 챕터와 같은 합니다체로 통일했다. backlog.md·plan-tone-consistency.md 같은 저자 전용 운영 메모(type: synthesis)는 이 규칙 밖 — 대상은 독자가 읽는 콘텐츠 페이지로 한정한다.

7-2. 독자 지시 표준¶

• 챕터 실습 지시(✏️ 직접 해보기 본문): ~하라/~해 보라 (문어체 명령). "~하세요"·"~해요"는 쓰지 않습니다.
• 가이드에서 Claude에 그대로 붙여넣는 프롬프트: ~해줘 (구어체, 실제 대화 프롬프트이므로).
• 가이드 독자 안내 박스(진행 순서 등): ~하세요.

7-3. 성공 확인 문구 표준¶

• 기본형: WIKI_STASH_11markdown

````

수정형 과제는 뼈대 없이 단계만 씁니다: 1. **파일 열기** — 위 \EncapsulationDemo.java`(2.4)/2. 수정 — …/3. 재실행 — 위 절의 실행 명령 재사용`. 박스 단계 문장은 합니다체입니다(직접 해보기 과제 문장의 하라체 예외는 박스 밖 과제 문장에만 적용).

막혔을 때 참고 (자족성): 긴 실습 절 끝에는 "자주 나는 에러 → 원인 확인" 부기를 둡니다. 외부 저장소(완성본) 없이 문서만으로 막힘에서 복구할 수 있어야 합니다.

게이트: bash scripts/scaffold-lint.sh <파일> — 파일 리드인↔package↔클래스명 정합, 리드인 블록의 다중 public 타입, public class Main을 기계 검사합니다.

7-8. 불쑥 등장 금지 — 선행 소개 원칙¶

배경: 2026-07-04 harness 가이드 피드백 — "태스크 B — 새 조회 API (10분)" 헤딩 뒤에 왜 만드는지 설명 없이 프롬프트가 나오고, [베이스라인 측정 중] 같은 표시가 정의 없이 튀어나온다는 지적. 독자가 이미 안다고 가정하고 불쑥 내미는 요소는 이해 흐름을 끊습니다.

원칙: 독자가 처음 보는 요소는 등장하기 전에 소개합니다. 판정 기준은 "이 절만 떼어 읽어도 '이게 뭐지?' 하는 순간이 없는가"입니다.

4규칙:

1. 블록 리드인 — 코드·프롬프트·측정 시트·표 블록 앞에는 무엇이고 무엇에 쓰는지 알려 주는 리드인 문장을 둡니다 (라벨형 허용: **완료 후 측정**:). 앞 블록이 끝나자마자 다음 펜스가 문장 없이 이어지면 위반입니다.
2. 표기·규약은 첫 등장에서 정의 — 프롬프트 머리 대괄호 표시([베이스라인 측정 중]), 커밋명 규약(harness(M2-D)), 판정 용어(APPROVE / CONDITIONAL REJECT) 같은 문서 내 관례는 처음 쓰는 자리에서 한 문장으로 정의합니다. 이후 줄임형을 쓰면 "같은 표시의 줄임"임을 밝힙니다.
3. 실습 태스크에는 의도 문장 — 태스크·Step 헤딩 아래에 "왜 이 태스크인가, 여기서 무엇이 드러나는가" 1~2문장을 붙입니다. 헤딩에서 프롬프트·명령으로 직행하지 않습니다.
4. 앞 문서 산출물은 반문장 재소개 — 다른 모듈·챕터의 산출물을 참조할 때 이름만 던지지 않습니다. "Module 01 Step 5에서 골라낸 시스템 문제 우선순위 표를…"처럼 그것이 무엇이었는지 반문장으로 되짚어 줍니다.

적용 범위: 독자 콘텐츠 전체 (챕터·guide-·concept-·entity-*). §7-7 실습 스캐폴드와 상보적입니다 — 7-7이 "어디에 어떤 파일을 만들지"를 보장한다면, 7-8은 "왜 지금 이것을 보는지"를 보장합니다.

8. 표준 적용 점검 (페이지 작성 후 셀프 체크)¶

• frontmatter 필수 키 모두 있나? (updated 갱신?)
• 분량이 type별 권장 범위인가?
• 다이어그램이 필요하다면 mermaid 한계 점검했나?
• 같은 인사이트 패턴 비교표가 있나? (양방향 연결?)
• 원본 출처 / 관련 페이지 섹션이 있나?
• mkdocs.yml nav 제목은 괄호 설명 없이 한 줄에 들어가게 짧게 했나? (부연·날짜·원어는 페이지 H1에만)
• mkdocs.yml nav에 추가했나? (🆕는 직접 붙이지 않음 — scripts/new_badge.py hook이 created 30일 이내 페이지에 빌드 시 자동 부착)
• index.md에 추가했나?
• log.md에 작업 기록했나?
• §7 문체 표준(종결어미·성공확인·OS분기·용어)을 지켰나?
• 실습 예제가 있다면 §7-7 스캐폴드 4요소를 갖췄나? (bash scripts/scaffold-lint.sh <파일> 통과)
• 불쑥 등장이 없나? (§7-8: 블록 리드인·표기 첫 등장 정의·태스크 의도 문장·산출물 재소개)
• 대응·비교를 코드블록 ASCII 정렬로 그리지 않았나? (§2-6: 마크다운 표로)
• bash scripts/style-lint.sh <파일> 통과하나?
• bash scripts/build-site.sh 통과하나?

관련 페이지¶

• guide-deploy-mkdocs-firebase — 배포 인프라 자체의 셋업
• concept-compounding-knowledge — 위키가 복리로 가치 쌓이는 원리
• concept-wiki-workflow — 새 소스 통합(Ingest)·위키 정비(Lint) 워크플로
• plan-tone-consistency — §7 문체 표준을 적용하는 정합 계획·실행 프롬프트