본문으로 건너뛰기

ny-wiki — 나만의 지식 위키 운영 규칙

이 저장소는 사용자(Storage 회사 System SW 팀, NVMe FDP/HC-SSD × AI 인프라 담당)의 개인 지식/노하우를 축적하는 나무위키 스타일의 마크다운 wiki다. Claude는 이 규칙에 따라 자료를 정리하고 질문에 답한다.

폴더 구조​

ny-wiki/
├── CLAUDE.md             # 이 파일. 운영 규칙.
├── raw/                  # 원본 자료 보관. 소스(private) 폴더구조 미러. 사용자가 넣고 Claude는 읽기만.
└── wiki/                 # 정리된 지식. Claude가 작성/유지보수.
    ├── index.md          # 전체 목차.
    ├── log.md            # 작업 이력.
    ├── work/             # 진행 중인 업무. 완료되면 파일명 앞에 [Done] 표시.
    │   ├── issues/       # 팀 GitHub 이슈·PR watch
    │   └── reviews/      # raw_block PR 카탈로그 (변경내용 + 아키텍처 관점 지적)
    ├── 00-mission/       # 미션 & 방향성 (안정적 참고자료)
    ├── 10-lmcache/       # LMCache (AI Cache SW)
    │   └── raw_block/    # raw_block 지식 (우리 핵심 영역)
    ├── 20-ai-inference/  # AI 추론 기초
    ├── 30-nvme-ssd/      # NVMe / SSD 기초
    ├── 40-storage-stack/ # Storage Stack & System SW
    └── 50-gpu-storage/   # GPU × Storage 연동
  • raw/는 소스(private/) 폴더구조를 그대로 미러한다 (2026-06-04 개정 — 소스가 계층화되며 플랫 규칙 폐기). wiki/는 카테고리별 하위 폴더로 분류 (번호 prefix로 정렬 순서 유지).
  • 새 페이지는 가장 잘 맞는 카테고리 폴더에 넣는다. 어디에도 잘 안 맞으면 99-misc/ 신설 검토.
  • 2단계 중첩은 카테고리가 커질 때 허용 (2026-06-04 개정 — 기존 "중첩 금지"에서 완화). 현재 하위폴더: work/issues/(이슈·PR watch), work/reviews/(raw_block PR 카탈로그), 10-lmcache/raw_block/(raw_block 지식 클러스터). 3단계 이상은 여전히 금지. 위키링크는 폴더 무관이라 이동해도 안 깨짐.
  • 위키링크는 [[페이지명]] (파일명만, 확장자/경로 없이) — Obsidian이 폴더와 무관하게 resolve.
  • 카테고리 분류 자체는 wiki/index.md에서도 정리한다 (index는 사람이 빠르게 훑는 용도).

사용자 컨텍스트 (항상 염두)​

  • 소속: Storage 회사 System SW 팀
  • 업무: NVMe FDP/HC-SSD를 AI 인프라(특히 LMCache)에 최적화, LMCache에서 raw block 성능 개선, io_uring 지원
  • 포지션: LMCache 입문자 → 쉬운 설명 필요
  • 3대 방향:
    1. FDP/HC-SSD가 LMCache에서 WAF/TTFT/처리량을 얼마나 개선하는가
    2. Storage Stack 각 레이어 (FS / Block / NVMe / SSD) 튜닝
    3. LMCache upstream 기여: ① raw_block backend 개선 (현재 진행 중) + ② FDP/io_uring Backend 추가
  • 모든 설명은 Storage Stack / System SW 관점으로 연결한다.

4가지 운영 방법​

① 자료 넣기 (Ingest)​

사용자: "이 자료 넣어줘" / "raw/에 넣었어, 읽고 정리해줘" / 파일 경로 지정

Claude의 절차:

  1. raw/에 있는 새 파일을 읽는다. raw/는 절대 수정·이동·삭제하지 않는다 (read-only).
  2. 자료의 핵심 개념을 식별하고, 각 개념마다 위키 페이지로 만든다.
    • 이미 존재하는 페이지면 갱신·보완한다 (덮어쓰지 말고 통합).
    • 새 개념이면 새 페이지를 만든다.
  3. 교차참조 ([[wikilink]])는 기본적으로 추가하지 않는다. 사용자가 명시적으로 요청할 때만 적용한다 (예: "이 페이지에 교차참조 넣어줘", "관련 페이지 연결해줘"). 페이지 본문은 해당 페이지가 담는 내용만으로 자족적이게 작성한다.
  4. 각 페이지는 페이지 작성 규칙을 따른다.
  5. wiki/index.md에 새 페이지를 알맞은 카테고리에 추가한다.
  6. wiki/log.md에 작업 이력을 한 줄 추가한다 (날짜, 자료명, 생성/갱신된 페이지 목록).

② 질문하기 (Query)​

사용자: "X가 뭐야?" / "Y는 어떻게 동작해?" / "Z 페이지에서 본 거 다시 설명"

Claude의 절차:

  1. 먼저 wiki/에서 관련 페이지를 검색해 읽는다. 답이 wiki에 있으면 wiki를 인용하며 답한다.
    • 인용 시 [페이지명](wiki/페이지명.md) 형식으로 링크를 단다.
  2. wiki에 없거나 부족하면 답하면서 동시에 wiki에 페이지를 추가·보완한다.
  3. 답변은 LMCache 입문자 눈높이 + Storage Stack 관점 두 축을 항상 유지한다.
  4. 새 페이지가 생기거나 갱신되면 index.md, log.md에 반영한다.

③ 건강검진 (Health Check)​

사용자: "건강검진 해줘" / "위키 점검" / "정리 좀"

Claude의 절차:

  1. 링크 무결성: 모든 [[wikilink]]가 실제 페이지를 가리키는지 점검. 깨진 링크 또는 고아 페이지 보고.
  2. 중복 점검: 같은 주제가 여러 페이지에 흩어져 있으면 통합 후보 제안.
  3. 누락 점검: 자주 등장하지만 페이지가 없는 개념(붉은 링크) 식별.
  4. 분류 점검: index.md의 카테고리 분류가 현재 페이지 수/주제에 비해 적절한지 확인.
  5. takeaway 점검: 모든 페이지 맨 앞에 > [!tldr] 콜아웃이 있는지, 내용이 미션과 연결되는지 확인.
  6. 결과 보고: log.md에 점검 결과 요약, 사용자에게 액션 아이템 제시.

④ Private 동기화 (Sync)​

사용자: "private 업데이트해줘" / "싱크해줘" / "private 동기화"

소스: /home/ny/LMCache/private/ (git repo — remote가 alt 계정 nayeoniikim-alt/private private. pull 필요 시 gh auth switch로 전환→pull→원복). 대상: ny-wiki/raw/ (md/비-md 구분 없이, 소스 폴더구조 그대로 미러)

Claude의 절차: 0. 필요 시 소스를 remote에서 pull(git -C private). 워킹트리 미커밋 있으면 stash 보호.

  1. 소스(/home/ny/LMCache/private, .git 제외)와 대상(ny-wiki/raw/)을 비교해 추가·변경된 파일을 파악한다.
  2. 소스 트리를 ny-wiki/raw/에 폴더구조 보존하여 복사(rsync -a --exclude=.git --exclude=CLAUDE.md). 소스의 CLAUDE.md는 가져오지 않는다 (private repo 운영용이라 wiki와 무관). 이미 있으면 변경이 있을 때만 갱신. 옛 flat 잔재가 새 구조와 중복되면 정리(byte동일은 자동, 그 외는 사용자 확인).
  3. 새로 들어온 파일(md 포함)은 ① Ingest 절차로 wiki 페이지 생성/갱신한다.
  4. 변경 요약(추가 N개, 갱신 N개)을 사용자에게 보고하고, log.md에 기록한다.

페이지 작성 규칙​

필수 구조​

모든 wiki 페이지는 다음 구조를 따른다:

# 페이지 제목

> [!tldr] 업무 관점 takeaway
> (사용자 미션 — FDP/HC-SSD × LMCache 최적화 — 관점에서
> 이 내용에서 가져가야 할 핵심 1~3줄. 첫 문단에서 즉시 보이게.)

(이후 본문)
  • 첫 callout은 반드시 사용자 미션 관점의 takeaway여야 한다. 단순 요약이 아니라 "이 개념이 내 업무에 왜/어떻게 중요한가"를 적는다.
  • callout 종류는 [!tldr]로 통일.
  • 본문은 마크다운으로 작성. 표/코드블록/다이어그램 적극 활용.

교차참조 규칙 (요청 시에만 적용)​

기본 원칙: 교차참조는 사용자가 명시적으로 요청할 때만 추가한다. 자동으로/적극적으로 박아 넣지 않는다.

요청을 받았을 때의 규칙:

  • [[페이지명]] 위키링크 문법. 페이지명은 파일명에서 .md를 뺀 것 (예: wiki/30-nvme-ssd/NVMe-FDP.md → [[NVMe-FDP]]).
  • 페이지 끝에 "관련 페이지" 섹션을 두는 것은 OK — 강하게 연결된 페이지만 나열.
  • 의외의 연결을 발견하면 별도 > [!note] 콜아웃으로 강조. 예: > [!note] 의외의 연결: FDP RUH ↔ LMCache LRU bucket — 둘 다 "수명별 그룹화" 패턴이다.
  • 인용 형태([페이지명](경로))도 동일 — 사용자가 답변 중 인용을 원할 때만 단다.

페이지명/파일명 규칙​

  • 한글 또는 영문, 케밥/공백 혼용 가능. 단, Obsidian 위키링크와 매칭되는 정확한 파일명을 유지한다.
  • 약어는 대문자 유지 (예: LMCache-아키텍처.md, NVMe-FDP.md, WAF.md).
  • 동의어가 있으면 본문 또는 alias 섹션에 명시.
  • 파일명은 카테고리 폴더 안에서도 고유해야 한다 (Obsidian이 이름으로만 resolve하므로). 같은 이름의 페이지가 두 카테고리에 있으면 안 됨.

길이/스타일​

  • 한 페이지에 너무 많이 담지 말 것. 하위 개념이 커지면 별도 페이지로 분리.
  • LMCache 입문자에게 친절한 톤. 비유와 예시를 적극 사용.
  • 모든 기술 설명은 가능한 한 Storage Stack 어디에 위치하는가를 명시한다.

index.md 운영 규칙​

  • 카테고리별 섹션으로 구성. 각 항목은 - [[페이지명]] — 한 줄 요약 형식.
  • 카테고리 예시:
    • 미션 & 방향성
    • LMCache (AI Cache SW)
    • AI 추론 기초
    • NVMe / SSD 기초
    • Storage Stack & System SW
    • GPU × Storage 연동
    • 작업·기여 트래킹
  • 새 카테고리가 필요해지면 자유롭게 추가하되, 추가/이동은 log.md에 기록.

log.md 운영 규칙​

  • 최신 항목이 위로 오는 역시간순.
  • 한 항목은 다음 형식: 
    ## 2026-05-15 — (작업 유형)
    - **자료**: (raw 파일명 또는 질문 요지)
    - **생성**: [[페이지A]], [[페이지B]]
    - **갱신**: [[페이지C]] (추가된 섹션)
    - **메모**: (선택)

금지/주의 사항​

  • raw/ 폴더는 읽기 전용. 사용자가 넣거나 싱크로 들어온 원본 자료. Claude는 읽기만 하고 절대 수정·이동·삭제하지 않는다.
  • 페이지를 새로 만들 때 기존 페이지와 주제가 90% 겹치면 새로 만들지 말고 기존 페이지에 섹션 추가.
  • 사용자 미션(FDP/HC-SSD × LMCache)과 무관한 일반 IT 잡지식은 위키에 넣지 않는다. 단, 미션 이해에 보조가 되는 기초 개념(예: NAND Flash 기초, KV Cache 기초)은 OK.
  • 작업 중간에 임의로 폴더 구조를 바꾸지 않는다. 구조 변경이 필요하면 사용자에게 먼저 제안.