위키 작성 표준¶

이 위키를 어느 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톤 통일)¶

의미	그룹 배경	노드 배경	노드 테두리	텍스트
🔵 로컬·시작	`#eff6ff`	`#dbeafe`	`#2563eb`	`#1e3a8a`
🟠 다리·전환	`#fff7ed`	`#fed7aa`	`#ea580c`	`#7c2d12`
🟢 결과·목적지	`#f0fdf4`	`#bbf7d0`	`#16a34a`	`#14532d`

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. 타입별 권장 분량¶

타입	권장 줄 수	권장 글자 수	비고
source (`src-*`)	50~120줄	1.5K~4K	원본 1개의 요약
concept (`concept-*`)	100~250줄	4K~10K	정의 + 함정 + 패턴 연결
entity (`entity-*`)	100~250줄	3K~9K	도구·인물·기술 — 공식 정보 + 활용
synthesis/guide (`guide-*`)	150~400줄	6K~15K	실습 step-by-step 또는 종합
comparison	100~250줄	4K~10K	비교 대상 ≥ 2개

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: YYYY-MM-DD
---

# 제목

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

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

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

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

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

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

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

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

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

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

이유
가로폭	들여쓰면 코드 폭이 좁아짐 → 전체 폭 확보
표 안정성	마크다운 표를 리스트 안에 넣으면 python-markdown에서 깨짐
복붙	앞 공백이 따라오지 않아 깔끔
일관성	"이건 종속?" 판단 불필요 — 규칙 1개

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

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

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

```java
...
```

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

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

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

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

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

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

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

유형	원래 배치가 담던 의미	전환 형태
비교형 (상속 vs 합성)	열 = 나란한 대안	열이 대안인 표 — 첫 열에 비교 관점 라벨(원문에 없으면 생략 가능, 과잉 창작 금지)
진행형 (A → B → C)	좌→우 = 시간·단계 순서	행이 단계인 표(첫 열 `1단계, 2단계…`) 또는 굵은 리드인 번호 목록 — 순서 축을 잃지 않게
대응형 (질문 → 답)	왼쪽 조건 ↔ 오른쪽 결과	2열 표 (조건 \| 결과)

적용 사례: 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: YYYY-MM-DD                  # 필수 (수정 시 갱신)
---

3-2. raw 인용 방식¶

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

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

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

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

예시:

## 같은 인사이트 패턴 — "기본값과 가정의 함정"

| 페이지 | 위험한 기본값 | 실무 권장 |
|--------|-------------|----------|
| **이 페이지** | ... | ... |
| [[concept-cronjob-concurrency-trap]] | K8s Allow | Forbid + activeDeadlineSeconds |
| [[concept-keepalive-timeout-race]] | 서버 < LB | 서버 > LB |
| [[concept-db-connection-pool]] | 무한 수명 | maxLifetime < wait_timeout |

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

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

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

## 관련 페이지

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

4. mkdocs nav 분류 기준¶

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

카테고리	들어가는 주제
위키·지식관리	Obsidian·Marp·Dataview 같은 PKM 도구, Memex 등 개념
하네스·AI 에이전트	Claude Code, CLAUDE.md, Hooks, 멀티 에이전트, AI 도구 비용
Java·Spring·DDD	Spring 코어/Boot/Framework, JPA, DDD, 디자인 패턴, 자바
DB·운영·인프라	DB 운영, 네트워크, K8s, 인프라 함정

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

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

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

4-3. 하위 그룹¶

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

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

raw 저장 — raw/<채널>/<주제>.md 형식. 타임스탬프 보존.
wiki 페이지 작성 — type 결정 (source vs concept). 분량 기준 준수.
같은 패턴 찾기 — 이미 위키에 있는 비슷한 페이지와 비교표 작성.
mkdocs.yml 메뉴 추가 — 적합한 카테고리·하위.
index.md 추가 — 해당 type 카테고리에 한 줄.
log.md 추가 — 작업 기록.
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. 문서군별 종결어미 매트릭스¶

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

문서군	산문 본문	예외 슬롯 (평어 유지)
챕터 `java-study-*`	합니다체	🎯 목표 한 줄(~한다) · ✏️ 직접 해보기 명령(~하라) · "따라 하는 법" 콜아웃 · `예상 결과` 펜스 내부 서술
가이드 `guide-*`	합니다체	붙여넣기 프롬프트(~해줘) · 독자 안내 박스(~하세요)
강의노트 `lecture-*`	개조식	비유 인용박스만 경어 (장면 묘사 문단 + "~도 같은 순서입니다" 매핑 문단, 완결 문장)

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

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

7-2. 독자 지시 표준¶

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

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

기본형: WIKI_STASH_12markdown

실습 순서

파일 생성 — hello-java 프로젝트에 src/main/java/com/example/ch02/practice/TypePractice.java를 만듭니다.

뼈대 입력 — 아래 뼈대를 그대로 입력합니다.

package com.example.ch02.practice;

public class TypePractice {
    public static void main(String[] args) {
        // 1) int·double·String 변수를 선언하고 출력한다
        // 2) (int) 형 변환 결과를 출력한다
        // 3) ==와 equals 비교 결과를 출력한다
    }
}

하나씩 구현 — 주석의 과제를 한 항목씩 구현합니다.
실행·확인 — mvn compile exec:java -Dexec.mainClass="com.example.ch02.practice.TypePractice" — 추가할 때마다 다시 실행해 출력을 확인합니다.

````

수정형 과제는 뼈대 없이 단계만 씁니다: 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규칙:

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

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