개인지식 시스템

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

정적 사이트용 간단 게이트입니다. 강한 보안은 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 관계를 일관되게 적재하는 것입니다.

기본 라우팅:

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. 새 note는 60-schemas/의 frontmatter와 required section을 따릅니다.
  6. Obsidian wikilink는 탐색 가치가 있는 대상에만 겁니다.
  7. 80-indexes/는 필요할 때 갱신하되 source of truth로 취급하지 않습니다.
  8. 변경 후 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/에서 사람이 읽을 수 있는 경로로 큐레이션합니다.

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 구조로 정제되어야 합니다.