개인지식 시스템

지정된 접근 문자를 입력하면 이 브라우저에서 열람이 허용됩니다.

정적 사이트용 간단 게이트입니다. 강한 보안은 Cloudflare Access를 권장합니다.

← All Notes

Root Root README.md

README

Agent Knowledge Base

GitHub + Markdown + Obsidian 기반의 개인/에이전트 공용 지식관리 시스템입니다.

이 저장소의 목적은 단순 노트 저장이 아니라, Hermes, Claude Code, OpenCode 같은 에이전트들이 같은 규칙으로 지식을 축적·갱신·검색할 수 있는 canonical knowledge layer를 만드는 것입니다.

Core Architecture

Markdown Git repo = source of truth
Obsidian = human graph/navigation UI
AGENTS.md = agent operating constitution
Vector DB / RAG index = derived artifact, rebuildable from Markdown
Agents = maintainers/operators of the knowledge system

Agent Entry Point

모든 에이전트(Hermes, Claude Code, OpenCode, Codex 등)는 이 저장소를 수정하기 전에 반드시 다음 순서로 읽습니다.

  1. AGENTS.md — 공통 헌법이자 최상위 ingest/write 규칙
  2. 자기 도구별 wrapper 파일 — 예: CLAUDE.md, OPENCODE.md
  3. 60-schemas/ — 문서 타입별 frontmatter/section schema
  4. 70-agent-skills/ — 에이전트별 반복 workflow

README.md는 사람과 에이전트가 빠르게 구조를 이해하기 위한 안내서이고, 실제 write authority는 AGENTS.md입니다.

Document Types

  • source: 원본 자료 단위. 유튜브, 글, 논문, 회의록, 대화 등.
  • concept: 오래 유지되는 개념 페이지.
  • insight: 자료나 대화에서 나온 재사용 가능한 통찰.
  • decision: 설계/운영 방향에 대한 결정 기록.
  • map: 특정 주제에 대한 큐레이션 지도(MOC, Map of Content).
  • project: 프로젝트별 맥락과 지식.

Directory Structure

00-inbox/        # 아직 정제되지 않은 임시 입력. 처리 후 비우는 것을 원칙으로 함
10-sources/      # 출처 단위 원본/정제 자료. source note가 모든 durable claim의 근거
20-insights/     # 재사용 가능한 비자명한 인사이트. source-backed claim만 저장
30-concepts/     # durable concept pages. 중복 금지, aliases/frontmatter로 통합
40-maps/         # 주제별 지도 / MOC. 사람이 읽는 탐색 경로
50-decisions/    # ADR 스타일 결정 기록. 왜 이 방향을 택했는지 보존
60-schemas/      # 문서 타입별 스키마와 템플릿. 새 note 작성 전 확인
70-agent-skills/ # Hermes/Claude/OpenCode 등 에이전트 워크플로우
80-indexes/      # 수동/자동 인덱스. 원장이 아니라 탐색 보조물
90-archive/      # 오래되었거나 대체된 문서

Ingestion Contract

새 데이터를 넣을 때 핵심은 폴더에 맞게 버리는 것이 아니라 source → claim → concept/insight/decision/map 관계를 일관되게 적재하는 것입니다.

중요: 개인지식관리 서비스에 저장되는 Markdown 문서의 본문은 항상 한국어로 작성합니다. 영어/외국어 자료를 ingest하더라도 핵심 주장, 인사이트, 개념 설명, 한계, 열린 질문은 한국어로 정리합니다. 단, 원문 제목, 고유명사, 제품명, 코드/API 이름, URL, 정확한 인용구처럼 의미 보존이 필요한 표현은 원어를 유지할 수 있습니다.

기본 라우팅:

Input Primary write Secondary updates
YouTube / article / paper / book / meeting / chat 10-sources/ 30-concepts/, 20-insights/, 40-maps/, 80-indexes/
비자명한 통찰 1개 20-insights/ 관련 30-concepts/, 근거 10-sources/ 링크
오래 유지될 용어/개념 30-concepts/ aliases, 관련 source/insight 링크
사용자 또는 팀의 방향성 결정 50-decisions/ 관련 concept/map 업데이트
특정 주제를 훑는 탐색 문서 40-maps/ concept/source/insight 링크 큐레이션
아직 분류 못 한 raw 입력 00-inbox/ 이후 처리하면서 위 구조로 이동

에이전트는 저장 시 다음을 지킵니다.

  1. 먼저 AGENTS.md를 읽고 현재 규칙을 확인합니다.
  2. 기존 30-concepts/와 aliases를 검색해 중복 concept 생성을 피합니다.
  3. raw source와 해석을 분리합니다.
  4. 오래 유지될 claim에는 source note 링크를 붙입니다.
  5. Markdown 본문은 한국어로 작성하고, 필요할 때만 원어 제목/고유명사/코드/API/직접 인용을 유지합니다.
  6. 새 note는 60-schemas/의 frontmatter와 required section을 따릅니다.
  7. Obsidian wikilink는 탐색 가치가 있는 대상에만 겁니다.
  8. 80-indexes/는 필요할 때 갱신하되 source of truth로 취급하지 않습니다.
  9. 변경 후 git diff/git status로 검증합니다.

Getting Started

  1. 이 레포를 Obsidian vault로 엽니다.
  2. 에이전트는 작업 전 반드시 AGENTS.md를 읽습니다.
  3. 새 자료는 먼저 10-sources/에 source note로 저장합니다. 미분류 raw 입력만 00-inbox/에 둡니다.
  4. source에서 claim/concept/insight/decision/map 후보를 뽑아 각 폴더에 반영합니다.
  5. 큰 주제는 40-maps/에서 사람이 읽을 수 있는 경로로 큐레이션합니다.

Quick Start (운영 시작 3줄)

npm install
npm run quality
npm run dev
  • npm install 시 prepare 스크립트가 자동으로 .githooks/pre-commit를 연결합니다.
  • 이후 커밋마다 지식 품질 체크가 자동 수행됩니다.

Quality Gates

지식 원장 품질을 자동으로 유지하기 위해 아래 스크립트를 제공합니다.

npm run kb:schema-lint     # note 타입별 frontmatter/필수 섹션 검증
npm run kb:dupes           # concept title/aliases 중복 검사
npm run kb:ingest-check    # source -> graph 연결성/깨진 링크 점검
npm run kb:indexes         # 80-indexes 자동 재생성
npm run kb:indexes:check   # 인덱스 최신 상태 검증
npm run kb:lint            # schema+dupe+ingest 통합 검사
npm run quality            # indexes:check + kb:lint + build

또한 CI에서는 다음 3개 Job이 실행됩니다.

  • kb-index-check
  • kb-quality
  • web-build

Web UI

이 저장소는 Astro 정적 사이트로도 빌드됩니다. GitHub 앱/모바일 Markdown 뷰가 불편할 때 Cloudflare Pages에 배포해 개인지식 시스템을 웹으로 볼 수 있습니다.

npm install
npm run dev      # local preview
npm run build    # static build to dist/

기본 기능:

  • 10-sources/, 20-insights/, 30-concepts/, 40-maps/, 50-decisions/ 등 폴더별 탐색
  • 전체 note 클라이언트 검색
  • Markdown frontmatter 파싱
  • Obsidian wikilink <span class="missing-link">Note Name</span>을 웹 링크로 변환
  • 간단한 접근 문자 gate

접근 문자는 정적 사이트 환경변수로 지정합니다.

PUBLIC_ACCESS_CODE=your-access-code

주의: 이 gate는 클라이언트 JS에 포함되는 간단한 하드코딩형 장벽입니다. 강한 보안이 필요하면 Cloudflare Pages 앞에 Cloudflare Access를 붙입니다.

Cloudflare Pages Deploy

권장 설정:

Framework preset: Astro
Build command: npm run build
Build output directory: dist
Environment variable: PUBLIC_ACCESS_CODE=<지정 문자>

GitHub repo를 Cloudflare Pages에 연결하면 main에 push될 때마다 자동 배포됩니다. Wrangler 인증이 되어 있는 환경에서는 아래 명령으로 수동 배포도 가능합니다.

npm run deploy:cloudflare

Non-Negotiable Principle

검색 가능한 쓰레기장을 만들지 말 것. 모든 자료는 가능한 한 source → claim/concept/insight/decision/map 구조로 정제되어야 합니다.