281 lines
15 KiB
Markdown
281 lines
15 KiB
Markdown
---
|
|
title: LLM Wiki Naming Conventions
|
|
source_type: meta
|
|
status: stable
|
|
tags: [meta, naming-conventions]
|
|
last_reviewed: 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>/` 에 저장
|