llm-wiki/rules/naming-conventions.md

title, source_type, status, tags, last_reviewed

title	source_type	status	tags	last_reviewed
LLM Wiki Naming Conventions	meta	stable	meta naming-conventions	2026-05-25

LLM Wiki Naming Conventions

본 문서는 파일·디렉터리·식별자의 명명 규칙을 정의한다. 일관성 없는 명명은 검색·정렬·그래프뷰에서 노이즈가 된다.

Layer: templates/ — 메타 규약. 모든 raw/wiki 문서 작성 시 본 규칙 준수.

1. 공통 원칙

• 모두 영문 kebab-case (예: feature-architecture-enforcement-rules, NOT featureArchitectureEnforcementRules, NOT feature_architecture_enforcement_rules)
• 한글 파일명 금지 — Obsidian 검색·터미널 호환·정렬 문제
• 공백 금지 — kebab 으로 대체
• 숫자 prefix 금지 (날짜 외) — 예: 01-intro.md 같은 정렬용 prefix 안 쓴다. 정렬은 frontmatter created: 또는 카테고리로
• 확장자: .md 통일 (Obsidian 표준). drawio 파일은 .drawio.svg

2. 카테고리별 명명 규칙

2.1 raw/branch-notes/<branch-name>.md

컨벤션 결정: <branch-prefix>-<content-descriptor> 단일 형식 통일. 슬러그는 구현 내용을 표현 해야 한다.

2.1.1 Prefix (필수, 4종)

branch-prefix 는 다음 4종 중 정확히 하나 사용. develop- 는 제거됨 — 기능 구현 작업은 규모 무관 feature- 사용.

Prefix	용도	예시
feature- (default)	모든 기능 구현 작업. 단일 기능이든 sub-branch 여러 개 가지는 큰 기능이든 동일하게 feature-. 일반적으로 PR 한 묶음에 머지될 단위.	feature-keycloak-oidc-integration, feature-domain-event-outbox-contract, feature-keycloak-oauth2-proxy-oidc-flow
fix-	단일 버그 수정 작업	fix-auth-token-leak, fix-jwt-iss-claim-mismatch
chore-	인프라·문서·도구 변경 (코드 동작 변경 없음). 환경 셋업·라이브러리 업그레이드·CI 설정 등	chore-update-archunit-rules, chore-local-postgres-docker-compose
experiment-	검증 목적 실험. 머지 안 할 수도 있고 결과만 기록.	experiment-tail-based-sampling, experiment-redis-vs-caffeine-cache

왜 develop- 제거: 이전엔 "큰 작업 묶음"용으로 develop-, "단일 기능"용으로 feature- 였지만, 실제 git 브랜치 워크플로우에서는 큰 작업도 feature/로 시작한다. "큰지 작은지" 판단을 prefix 결정 시점에 강요하는 것은 자연스럽지 않다. → feature-로 통합. 작업 규모는 parent_branch: 와 sub-branch 분할로 표현.

기존 develop-* 슬러그 처리: wiki-doc-author mode=migrate 로 점진적 rename 권고. 자동 mv 안 함 — wikilink 영향 검토 필요.

2.1.2 Content descriptor — 구현 내용 기반 명명 (HARD RULE)

슬러그의 prefix 뒤 부분은 그 branch 가 무엇을 구현/문서화하는지 를 4~8 단어 영문 kebab-case 로 명확히 표현한다.

좋은 예 (파일명만 보고 작업 내용 파악 가능):

• feature-keycloak-oauth2-proxy-oidc-flow ← oauth2-proxy 의 OIDC 흐름 구현
• feature-keycloak-nginx-auth-request-integration ← nginx auth_request 모듈 통합
• feature-keycloak-header-spoofing-defense ← X-Forwarded-User 헤더 spoofing 방어
• fix-keycloak-hostname-claim-mismatch ← KC_HOSTNAME 미설정 시 JWT iss claim mismatch 버그
• feature-keycloak-edge-forwardauth-no-google ← P1A 패턴 전체
• feature-domain-event-outbox-contract ← outbox 패턴 + transactional event publish 계약

나쁜 예 (금지):

• ❌ feature-project-alpha-1 — numbered hierarchy. 슬러그에서 작업 내용을 알 수 없음
• ❌ feature-project-alpha-1-2 — 2단 numbered hierarchy. 파일 listing 에서 의미 추출 불가능
• ❌ feature-foo-bar-2 — 동일 문제 (의미 없는 numeric suffix)
• ❌ develop-anything — develop- 자체가 제거된 prefix (위 §2.1.1 참조)
• ❌ feature-1-2-3 — 의미 zero

2.1.3 Hierarchy 표기 — 슬러그가 아니라 frontmatter 로

계층은 슬러그에 인코딩하지 않는다. "root branch" 라는 별도 개념도 없다 — 모든 branch 는 동등하고, 위치는 parent_branch: 필드로만 표현된다. 다음 두 곳에서만 표현:

1. frontmatter parent_branch: — 직계 부모 branch slug. project 의 직접 자식 branch 는 이 필드를 비워두고 related_projects: 만 채운다. 다른 branch 의 자식이면 부모 branch slug 명시.
2. ## Parent / 부모 (필수) 섹션 — 부모 wikilink (project 또는 parent branch) + 형제 wikilink + (선택) 조부모.

이렇게 하면 파일 시스템 listing 만 보고 "이게 무슨 작업인지" 즉시 알 수 있고, 계층 정보는 graph view / backlink / 본문 섹션에서 자연스럽게 드러난다.

2.1.4 동일 패턴 그룹 묶기 — prefix 접두어 활용

같은 큰 주제(예: keycloak 6 패턴) 의 sub-branch 들이 파일 정렬 시 인접하게 보이도록 공통 접두어 를 사용하는 것은 허용 (numbered hierarchy 아니라 content prefix 이므로):

• feature-keycloak-edge-forwardauth-no-google
• feature-keycloak-edge-forwardauth-google-federation
• feature-keycloak-cluster-internal-no-google
• ...
• feature-keycloak-oauth2-proxy-oidc-flow
• feature-keycloak-nginx-auth-request-integration

위처럼 feature-keycloak- 접두어가 동일 프로젝트 sub-branch 들을 자연 정렬하면서도, 슬러그 후반부가 각자 구현 내용을 표현한다.

2.1.5 기타 금지 패턴

• ❌ feature/blabla (슬래시 — 파일명 호환 문제)
• ❌ develop_keycloak_patterns (snake_case)
• ❌ 01-keycloak-patterns (숫자 정렬 prefix)
• ❌ keycloak-patterns (prefix 누락)
• ❌ feature-project-alpha-1 (numbered hierarchy — §2.1.2 위반)
• ❌ develop-* 어떤 슬러그든 (develop- prefix 자체 제거됨 — §2.1.1)

2.1.6 Self-check (작성·rename 시 적용)

• prefix 가 §2.1.1 표의 4종 (feature- / fix- / chore- / experiment-) 중 정확히 1개
• prefix 뒤 슬러그가 구현 내용을 4~8 단어로 표현 (§2.1.2)
• 숫자 hierarchy(-1, -1-1 등) 슬러그 후반부에 없음 (§2.1.3)
• 계층 정보가 frontmatter parent_branch: 와 ## Parent 섹션에 있음
• 영문 kebab-case · 공백·언더스코어·CamelCase 없음
• 같은 큰 주제 sub-branch 들이 공통 content prefix 로 자연 정렬

위 self-check 미통과 슬러그 = 작성·rename 거부.

2.2 raw/daily-notes/<YYYY-MM-DD>.md

• 형식: ISO-8601 날짜 그대로 (예: 2026-05-25.md)
• 다른 prefix·suffix 금지

2.2.1 raw/daily-tasks/<track>/<YYYY-MM-DD>-<implementation-slug>.md

• 형식: YYYY-MM-DD-<implementation-slug>.md
• <track> ∈ {develop, infra} (폴더로만 표현 — 슬러그 자체에는 track prefix 넣지 않는다. 파일 경로가 이미 track 을 명시)
• YYYY-MM-DD = frontmatter target_date 와 동일 (수행 예정일). created 와 다를 수 있음 — 미래 과제 미리 작성 시.
• <implementation-slug>: 무엇을 배우고 구현하는지 를 4~7 단어 영문 kebab-case 로 표현. 슬러그만 보고도 학습 내용 파악 가능해야 함.

좋은 예:

• raw/daily-tasks/develop/2026-05-29-archunit-controller-domain-return-rule.md
• raw/daily-tasks/develop/2026-05-30-jackson-fail-on-unknown-properties-policy.md
• raw/daily-tasks/infra/2026-05-29-actuator-readiness-probe-db-disconnect.md
• raw/daily-tasks/infra/2026-05-30-prometheus-pod-restart-alert-rule.md

나쁜 예 (금지):

• ❌ develop/task-1.md (의미 zero — numbered placeholder)
• ❌ develop/2026-05-29-task.md (slug 가 의미 zero)
• ❌ infra/2026-05-29-day-3-monitoring.md (day-N hierarchy)
• ❌ develop/2026-05-29-오늘과제.md (한글)
• ❌ develop/develop-2026-05-29-archunit-rule.md (track 이 경로와 중복)

Self-check:

• 경로가 raw/daily-tasks/develop/ 또는 raw/daily-tasks/infra/ 둘 중 하나
• 파일명이 YYYY-MM-DD- 로 시작 (날짜 정렬 가능)
• 날짜 뒤 슬러그가 학습 내용 4~7 단어로 명시
• frontmatter track 이 폴더와 일치
• parent_project 또는 parent_branch 중 최소 하나 채워짐

2.3 raw/errors/<short-error-slug>.md

• 형식: <문제-짧은-키워드>-<YYYY-MM-DD>.md (날짜 suffix 권장 — 같은 에러 재발 가능성)
• 예: oidc-discovery-failure-2026-05-25.md, hikari-pool-exhausted-2026-05-26.md
• 짧고 검색 가능한 슬러그 (4~6 단어 이내)

2.4 raw/interviews/<question-slug>.md

• 형식: <주제-키워드>.md (날짜 없음 — 영구 자료)
• 예: clean-architecture-vs-hexagonal.md, idempotency-key-distributed-lock.md
• 질문 원문이 길어도 슬러그는 4~7 단어 이내로

2.5 raw/job-postings/<company>-<role-slug>.md

• 형식: <회사슬러그>-<역할슬러그>-<YYYY-MM-DD>.md
• 회사 슬러그: 영문 (예: toss, kakao, naver, coupang)
• 예: toss-backend-senior-2026-05-25.md
• 한국 회사는 영문 음역 권장 (검색 일관성)

2.5.1 raw/blog-topics/<topic-slug>-<YYYY-MM-DD>.md

• 형식: <글감-주제-슬러그>-<YYYY-MM-DD>.md
• 예: clean-architecture-boundary-enforcement-2026-05-28.md
• 채용공고에서 나온 글감은 raw/job-postings/에 두고, 일반 작업·학습·트러블슈팅에서 나온 글감만 여기에 둔다.
• wiki/blog/ 파일명을 미리 wikilink로 만들지 않는다. 아직 생성되지 않은 derived 파일은 일반 경로 텍스트로만 후보 표기한다.

2.6 raw/lectures/<course-slug>-<topic-or-episode>.md

• 형식: <코스슬러그>-<주제 또는 에피소드 번호>.md
• 예: udemy-spring-security-jwt-rotation.md, kafka-summit-2024-exactly-once.md
• 강의가 시리즈면 -ep01, -ep02 또는 핵심 토픽 슬러그

2.7 raw/official-docs/<doc-slug>-<vendor>.md

• 형식: <주제 슬러그>-<벤더 슬러그>.md
• 예: actuator-endpoint-exposure-spring-official.md, oidc-discovery-keycloak-official.md
• 벤더 슬러그 끝에 -official 또는 -rfc 같은 명시적 suffix 권장 (output type 식별)
• 같은 주제의 여러 공식 자료가 있으면 -v1, -v2 또는 발행연도 suffix

2.8 raw/company-tech-blogs/<topic>-<company>.md

• 형식: <주제 슬러그>-<회사슬러그>.md
• 예: api-versioning-stripe-date-based.md, outbox-pattern-netflix.md
• 회사 슬러그 끝에 -blog suffix 안 붙임 (디렉토리가 이미 company-tech-blogs/ 라 중복)

2.9 raw/project-notes/<project-slug>.md

• 형식: <프로젝트 슬러그>.md
• 예: ca-skeleton-operational-contract.md, keycloak-patterns-overview.md
• 프로젝트 슬러그는 frontmatter related_projects: 와 일치해야 함 (cluster 정합성)

2.10 wiki/concepts/<concept-slug>.md

• 형식: <개념 슬러그>.md (단수형 권장)
• 예: idempotency.md, outbox-pattern.md, circuit-breaker.md
• 일반 개념이므로 회사·프로젝트 슬러그 prefix 금지

2.11 wiki/projects/<project-slug>/<topic>.md

• 형식: 프로젝트별 subdirectory + 토픽 슬러그
• 예: wiki/projects/ca-tmpl/config-and-adapter-templates.md
• subdirectory 이름은 raw/project-notes/ 의 슬러그와 일치
• frontmatter source_type: project 사용 (wiki-project-template.md 기반). raw/project-notes/<slug>.md 는 source_type: project-note — 두 타입은 구분된다.

2.12 wiki/interview/<question-slug>.md

• 형식: wiki/interview/<카테고리>/<질문 슬러그>.md 또는 평면 구조
• 예: wiki/interview/auth/jwt-vs-session.md
• 카테고리 권장값: auth, architecture, persistence, observability, messaging, testing, general

2.13 wiki/portfolio/<portfolio-slug>.md

• 형식: wiki/portfolio/<프로젝트 또는 주제 슬러그>.md
• 예: wiki/portfolio/ca-tmpl-clean-architecture.md

2.14 wiki/blog/<post-slug>.md

• 형식: wiki/blog/<글 슬러그>-<YYYY-MM-DD>.md (날짜 suffix 권장 — drafts vs published 구분)
• 예: wiki/blog/why-i-rejected-rfc-7807-2026-05-25.md

3. 다이어그램 파일

3.1 도구 선택 (엄격)

• 시스템 아키텍처 / 컴포넌트 구성도 / 배포 토폴로지 / 데이터 흐름 → draw.io XML (.drawio 또는 .drawio.svg)
• 시퀀스 → Mermaid sequenceDiagram (project-note 본문 inline code block)
• ER (선택) → Mermaid erDiagram (본문 inline)
• 시스템 아키텍처를 Mermaid graph TD/graph LR 로 작성 금지

3.2 draw.io 파일 명명·저장

• 저장 경로: raw/diagrams/<project-slug>/
• 명명: architecture-<viewpoint>-<YYYY-MM-DD>.drawio (또는 .drawio.svg)
• viewpoint 예: overview, deployment, data-flow, security, network, module-dependency, runtime-topology
• archived: raw/diagrams/<project-slug>/archived/
• 확장자 선택:
  • .drawio — 순수 XML (mxfile). git diff 친화, 단 Obsidian inline 렌더링은 플러그인 의존
  • .drawio.svg — SVG 래퍼 + 내부 mxfile XML. Obsidian draw.io 플러그인이 inline 이미지로 자동 렌더링
  • 권장: 처음 .drawio 로 작성 → Obsidian 에서 열어 저장하면 자동으로 .drawio.svg 변환 가능

3.3 Mermaid 명명·위치

• 별도 파일 X. 본문 inline mermaid code block.
• 시퀀스 다이어그램 1개당 1 code block. 한 파일에 여러 sequenceDiagram 가능.

4. Frontmatter title: 필드

파일명 슬러그와 별개로 사람이 읽기 좋은 title 을 frontmatter 에 적음:

• 형식: <type> / <human readable title>
• 예: branch / feature-keycloak-oauth2-proxy-oidc-flow (P1A — oauth2-proxy 구성과 OIDC 흐름)
• 예: error / OIDC discovery 실패 (2026-05-25)
• 예: official-doc / Spring Boot Actuator — Endpoint Exposure & Security Defaults

title 의 괄호 안 메타 정보(예: (P1A — ...))는 자유 형식. 슬러그가 표현하지 못하는 단계·패턴 ID 를 보완하는 용도. 슬러그 자체에 numbered hierarchy 가 들어가서는 안 된다 (§2.1.3).

5. 슬러그 생성 도우미 규칙

긴 한국어 제목을 영문 kebab-case 슬러그로:

• 동사 → 명사형 (예: "OIDC 발견 실패" → oidc-discovery-failure)
• 회사·기술명은 음역 또는 영문 그대로 (예: 토스 → toss, 카카오 → kakao)
• 4~6 단어 이내 권장
• 약어는 본 프로젝트의 tag-taxonomy.md 동의어 표 따름

6. 검증 체크리스트

문서 작성 시 self-check:

• 파일명이 영문 kebab-case
• 카테고리 디렉토리에 맞는 명명 규칙 준수
• branch-note 라면 prefix 4종 (feature- / fix- / chore- / experiment-) 중 정확히 하나
• branch-note 슬러그가 구현 내용을 표현 (§2.1.2). feature-X-1-2 같은 numbered hierarchy 금지
• develop-* prefix 사용 안 함 (§2.1.1 — 제거됨)
• branch-note 의 계층 정보는 frontmatter parent_branch: + ## Parent 섹션에만 존재 (슬러그에 인코딩 X)
• 한글 파일명 사용 안 함
• 공백·언더스코어·CamelCase 사용 안 함
• frontmatter title: 에 사람이 읽기 좋은 표제 명시
• 다이어그램 파일은 raw/diagrams/<project-slug>/ 에 저장