genos-knowledge-capture

name	genos-knowledge-capture
description	Use when GenOS 작업에서 얻은 재사용 가능한 지식(플랫폼 패턴·함정·고객사 결정)을 개인 Obsidian vault(Projects/GenonAI)에 기록할 가치가 생겼거나, GenOS 작업 맥락에서 사용자가 "지식 캡처", "vault에 정리/기록", "MOC", "읽는 순서", "field note", "/genos-knowledge-capture"를 요청할 때 사용. Do NOT use for: GenOS와 무관한 노트, 웹 리서치 기반 일반 개념 노트, 단순 진행상황·세션 상태.

GenOS Knowledge Capture

GenOS 현장 작업(FDE)에서 한 번 배운 걸 다음 세션·다음 고객사에서 다시 파헤치지 않도록 만드는 개인 스킬이다. AI의 세션 기억은 끊기지만, vault에 원자적 노트로 남기고 MOC(허브)와 카테고리별 읽는 순서에서 엮어두면 새 세션이 필요한 노트를 발견하고, 처음 읽을 순서까지 빠르게 잡는다.

이 스킬은 사용자 개인 자산(~/.claude/skills/)이다. 회사 레포의 .claude/skills/genos-*(genos-session-close 등)는 회사 공유 자산이라 절대 건드리지 않는다. 세션 상태는 회사 HANDOFF가, 재사용 지식은 이 스킬이 담당한다 — 둘은 분리된 관심사다.

노트 본문 형식(frontmatter 규약, 8섹션 spine, Mermaid·문체 규칙)은 references/note-format.md에 있다. 워크플로우 4단계에서 그 파일을 읽고 따른다.

핵심 원칙 (왜 이렇게 하나)

① 온보딩 가속의 실체는 MOC + 읽는 순서다. "그래프뷰가 예쁜 것"이 아니라 작은 진입점(MOC)을 먼저 읽고, 거기서 오늘 필요한 노트를 발견한 뒤, 카테고리별 읽는 순서로 무엇부터 볼지 정하는 것이다. AI는 Obsidian 그래프를 순회하지 못한다. 그래서 이 스킬은 늘 세 가지를 함께 한다: 원자적 노트 작성 + MOC에 링크 추가 + [[GenOS 카테고리별 읽는 순서]] 반영 검토. MOC에 안 걸린 노트는 발견되지 않고, 읽는 순서에 안 걸린 노트는 처음 보는 사람이 언제 읽어야 할지 모른다.

② 재사용 가능한 일반화만 담는다. 토큰 절감은 "재탐색(re-grep·재독)을 대체할 때 + 선택적으로 1~2개만 읽을 때"만 생긴다. 그러니 노트엔 패턴·함정·결정만 담고, "오늘 무슨 파일 고쳤는지" 같은 휘발성 상태는 vault에 넣지 않는다(노이즈만 쌓인다).

③ 1차 독자는 "이 기술을 처음 보는 사람"이다. 노트는 입사 직후의 동료나 다음 세션의 AI가 이 문서 한 장만으로 개념을 잡고 GenOS에서의 위치를 이해할 수 있는 자기완결 field note다. 먼저 사람이 읽는 흐름으로 열고, 판단·분기·함정은 bullet·표·Mermaid로 스캔 가능하게 만든다. 형식 상세는 references/note-format.md.

3계층 — 무엇을 캡처하고 무엇을 버리나

캡처 후보가 생기면 먼저 어느 계층인지 판별한다. 계층을 섞지 않는 것이 vault가 비대해져도 길을 잃지 않는 유일한 규칙이다.

계층	무엇	저장 위치	캡처?
플랫폼	GenOS 자체 구조·패턴·함정 (모든 고객사 재사용)	Projects/GenonAI/GenOS/	✅
고객사	특정 고객 커스텀 결정·맥락 (삼성카드 등)	Projects/GenonAI/<고객사>/ 또는 GenonAI/ loose	✅
세션 상태	오늘 진행/대기/다음 작업	vault 밖 — GenOS 레포 HANDOFF_NOW.md	❌

판단 기준: "이걸 6개월 뒤 다른 세션·다른 고객사에서 다시 보면 시간을 아껴줄까?" Yes면 플랫폼/고객사 노트, No(이번 작업에만 유효)면 캡처하지 않는다.

• Vault 루트: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Note
• GenOS 영역: <vault>/Projects/GenonAI/

워크플로우

순서엔 실제 의존성이 있다(중복 확인 → 작성 → MOC 갱신 → 카테고리별 읽는 순서 검토). 비협상은 셋이다: ② 작성 전 중복 확인, ⑤ MOC 갱신, ⑥ 읽는 순서 검토와 결과 보고. 나머지는 상황에 맞게 조정한다(후보가 하나면 계획 제시를 짧게, 명백하면 확인 생략).

1. 후보 추출 — 이번 세션에서 일반화 가능한 것만

좋은 후보: 비자명한 패턴, 빠지기 쉬운 함정, 협의로 확정된 설계 결정, "문서엔 X라는데 실제론 Y"인 사실. 나쁜 후보: 진행상황, 파일 목록, 커밋 해시, 이번 한정 상태.

2. 계층 판별 + 중복 확인 (비협상)

각 후보가 플랫폼/고객사 중 어디인지 정하고, 기존 노트를 먼저 검색한다:

ls "<vault>/Projects/GenonAI/GenOS/" "<vault>/Projects/GenonAI/"
grep -rl "<핵심 키워드>" "<vault>/Projects/GenonAI/"

같은 주제 노트가 있으면 새로 만들지 말고 그 노트를 갱신한다(원자성 유지, 중복 금지).

3. 캡처 계획 제시 → 확인

글을 쓰기 전, 무엇을 어디에 쓸지 짧게 보여주고 확인받는다. 길게 묻지 말고 목록만:

[캡처 계획]
- GenOS/<제목>.md (플랫폼·신규)  — <한 줄 요지>
- <고객사>/<제목>.md (고객사·기존 갱신) — <무엇 추가>
- MOC: "패턴·함정" 섹션에 링크 추가
- 읽는 순서: "<카테고리명>" 아래 <앞/뒤 기준 노트> 근처에 링크 추가 또는 불필요 사유 기록

사용자가 "그냥 해" 류면 확인 생략 가능.

4. 노트 작성 — 형식은 references/note-format.md

references/note-format.md의 frontmatter 규약·8섹션 spine·Mermaid·문체 규칙을 따른다. obsidian-note와 frontmatter 규약은 공유하되 본문 spine은 별도다(저쪽은 Zettelkasten, 이쪽은 입문자 자기완결 field note). Tavily 웹 리서치는 생략한다 — 출처는 웹 개념이 아니라 이 세션의 실작업·레포다.

핵심만 여기 박아둔다:

• 1차 독자는 처음 보는 사람. ## 먼저 알아야 할 개념으로 선행지식을 깔아 자기완결로 만든다.
• 그 섹션은 길어도 좋다(서사로 풀어 읽는 재미). 단 일반 튜토리얼 금지 — 판정은 분량이 아니라 착지다: "이 문단이 GenOS와 무관하게도 성립하면 위키 복붙이다 — 잘라내거나 GenOS로 당겨온다."

5. MOC 갱신 (비협상, 생략 금지)

<vault>/Projects/GenonAI/GenOS/GenOS 지식 MOC.md를 열어 적절한 섹션(코드 온보딩 / 운영·장애 / 패턴·함정 / 고객사별 / 학습)에 - [[새 노트]] — 한 줄 요지 추가. 새 노트의 related_notes에도 [[GenOS 지식 MOC]]를 넣어 양방향으로 엮는다.

6. 카테고리별 읽는 순서 검토 + 필요 시 갱신 (검토는 비협상)

<vault>/Projects/GenonAI/GenOS/GenOS 카테고리별 읽는 순서.md를 열어 새 노트나 갱신된 노트가 들어갈 카테고리를 판단한다. 이 노트는 MOC를 대체하는 허브가 아니라 MOC companion이다. 역할을 섞지 않는다.

이 단계의 비협상은 파일을 열고, 위치를 판단하고, 결과를 보고하는 것이다. 실제 수정은 새 노트가 카테고리별 온보딩 순서에 들어가야 하거나, 기존 노트 갱신으로 읽는 순서의 의미가 달라질 때만 한다.

판단 순서:

1. 새/갱신 노트가 어떤 카테고리의 첫 독서 흐름에 들어가는지 정한다.
2. 해당 카테고리의 기존 순서에서 "이 노트를 읽기 전에 알아야 하는 노트"와 "이 노트 다음에 읽을 노트"를 잡는다.
3. 적절한 numbered list 위치에 [[새 노트]]를 추가하거나, 기존 노트 갱신만으로 순서 변경이 불필요하면 결과 보고에 불필요 사유를 남긴다.

역할 구분:

• [[GenOS 지식 MOC]]: 전체 허브와 discoverability.
• [[GenOS 카테고리별 읽는 순서]]: MOC 링크를 카테고리별 독서 순서로 재배열한 companion map.
• [[GenOS 학습 로드맵 - FDE 온보딩 순서]]: FDE 현장 대응 역량을 쌓는 curriculum. 새 노트를 무조건 여기에 넣지 않는다.

7. 검증 + 결과 보고

• 검증: Mermaid를 썼으면 렌더 검증, related_notes의 모든 [[wikilink]]는 vault 실존(또는 이번에 함께 만드는 노트)을 확인한다. 추가로 MOC 링크와 GenOS 카테고리별 읽는 순서 링크/불필요 사유를 확인한다.
• 보고: 작성/갱신한 노트 목록, MOC 변경, 읽는 순서 변경(또는 불필요 사유), 검증 결과를 요약한다.

평가 시나리오 — 스킬이 제대로 동작하는지 보는 법

스킬을 수정했거나 동작 품질이 의심되면 아래 케이스로 판단한다. 전부 통과해야 "좋은 GenOS 지식 캡처"다.

시나리오	기대 행동
새 플랫폼 패턴 캡처	기존 노트를 먼저 검색하고, 없으면 GenOS 영역에 새 노트를 만들고, MOC와 읽는 순서 위치까지 검토한다.
기존 주제 보강	비슷한 주제 노트를 새로 만들지 않고 기존 노트에 흡수한 뒤, MOC/읽는 순서 변경 필요 여부를 보고한다.
MOC만 충분한 변경	새 링크가 MOC discoverability에는 필요하지만 읽는 순서 변경은 불필요하다고 판단하면, 읽는 순서 파일을 수정하지 않고 이유를 남긴다.
세션 상태 캡처 요청	"오늘 무엇을 했다" 수준이면 vault 노트로 만들지 않고 GenOS 레포 HANDOFF 대상으로 분리한다.
GenOS 외 일반 개념 요청	이 스킬을 쓰지 않고 obsidian-note나 다른 적절한 노트 스킬로 라우팅한다.

Gotchas — 여기서 실제로 틀린다

규칙이 아니라 왜 틀리는지로 기억하라.

• MOC 갱신을 빼먹는다 (1번 실패 모드). 노트만 쓰고 만족하기 쉽다. MOC에 링크를 안 걸면 새 세션은 그 노트의 존재 자체를 모른다 — AI는 그래프뷰를 못 보고 MOC만 진입점으로 읽기 때문이다. 작성한 노트는 반드시 MOC에 한 줄 추가하고 끝낸다.
• 카테고리별 읽는 순서를 빼먹는다. MOC에 링크만 있으면 발견은 되지만, 처음 보는 사람은 언제 읽어야 하는지 모른다. 작성한 노트는 GenOS 카테고리별 읽는 순서에 넣을 위치를 항상 검토하고, 필요할 때만 수정하며, 넣지 않는다면 왜 순서 변경이 불필요한지 보고한다.
• 중복 노트를 새로 만든다. 비슷한 주제가 이미 있는데 검색을 건너뛰면 지식이 두 곳에 갈라져 둘 다 신뢰를 잃는다. 작성 전 grep -rl로 먼저 찾고, 있으면 갱신한다.
• 세션 상태를 지식으로 착각한다. "오늘 chat_service 3줄 고쳤다"는 패턴이 아니라 상태다. "6개월 뒤 다른 고객사에서 시간을 아껴줄까?"를 통과 못 하면 HANDOFF로 보낸다.
• 존재하지 않는 노트를 [[링크]]한다. related_notes의 모든 wikilink는 실존 노트 + 이번에 함께 만드는 노트여야 한다. 미존재 링크는 깨진 그래프를 만든다.
• 입문자 친화를 일반 튜토리얼로 만든다. ## 먼저 알아야 할 개념이 길어지는 건 괜찮지만, 매 문단이 "그래서 GenOS에선 ○○"로 착지하지 않으면 위키 복붙이다. 길이가 아니라 착지로 판정한다.
• 근거 경로가 본문을 잡아먹는다. 코드 근거가 많아 설명문에 file:line이 섞이면 읽는 사람이 핵심을 놓친다. 판단은 본문에, 경로는 ## 코드·근거로 분리한다.
• 고객사 노트 위치가 혼재한다. 현재 삼성카드 노트는 GenonAI/ loose에 있다. 한 고객사 노트가 3장 이상 쌓이면 GenonAI/<고객사>/ 폴더 분리를 제안하되, 기존 파일 이동은 사용자 확인 후에만 — 임의로 옮기면 다른 노트의 [[링크]]가 깨진다.
• 회사 자산을 건드린다. 캡처 자동화가 아쉬워도 회사 레포 .claude/skills/genos-*는 절대 수정하지 않는다. 모든 자동화는 이 개인 스킬(~/.claude/) 안에서 끝낸다.
• Mermaid를 장식으로 넣는다. diagram은 하나의 질문(책임 경계·요청 순서·상태 변화·데이터 관계)에 답해야 한다. 줄여주지 못하면 텍스트나 표가 낫다.

예시

예시 1 — 플랫폼 패턴 캡처 세션에서 "외부 시스템 전송은 BackgroundTasks + dry-run 플래그로 한다"는 패턴을 적용함. → GenOS/GenOS admin-api 외부 시스템 로그 연동 패턴.md (tags: type/pattern, backend/integration), MOC "패턴·함정"에 링크, GenOS 카테고리별 읽는 순서의 Observability/operations 계열에 배치 검토.

예시 2 — 고객사 결정 캡처 "삼성카드 고객관리번호는 CST_MNGT_NO로 넘어오고, 컬럼은 삼성카드 DB에만 추가"가 확정됨. → 삼성카드 PIMS 행위로그 연동.md 기존 노트 갱신(중복 생성 X), tags customer/samsung-card feature/pims.

예시 3 — 캡처 거부 "오늘 chat_service_service.py 3줄 고치고 커밋함" → 세션 상태. 캡처하지 않고 HANDOFF로 안내.