개인지식 시스템

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

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

← All Notes

Root Root AGENTS.md

AGENTS

Agent Rules for Agent Knowledge Base

이 문서는 Hermes, Claude Code, OpenCode, Codex 등 모든 에이전트가 이 저장소를 수정할 때 따라야 하는 공통 헌법입니다.

Core Principle

This repository is the canonical personal/agent knowledge layer. Do not dump generic summaries. Convert sources into reusable knowledge objects: source, concept, insight, decision, map, and project.

The most important invariant is not “write a Markdown file somewhere.” The invariant is consistent knowledge loading:

source note -> source-backed claims -> concept / insight / decision / map updates

Vector DBs, search indexes, and RAG chunks are derived artifacts. The Markdown graph is the source of truth.

Non-Negotiable Rules

  1. Do not dump generic summaries. 요약만 남기지 말고 재사용 가능한 지식 단위로 정제한다.
  2. Every durable claim must cite a source. 오래 유지될 주장은 반드시 source note를 인용한다.
  3. Search before creating concepts. 새 concept note를 만들기 전에 30-concepts/와 aliases를 먼저 확인한다.
  4. Use Obsidian wikilinks. 관련 개념, 출처, 인사이트는 <span class="missing-link">Note Name</span>으로 연결한다.
  5. Separate raw source from interpretation. 원본 자료와 해석/인사이트를 섞지 않는다.
  6. Prefer small, reviewable changes. 큰 재구성은 별도 commit/PR 단위로 나눈다.
  7. RAG indexes are derived artifacts. 벡터DB/검색 인덱스는 원장이 아니라 Markdown에서 재생성 가능한 캐시다.
  8. Mark uncertainty. 불확실한 내용은 fact로 쓰지 말고 hypothesis/open question으로 표시한다.
  9. Preserve folder semantics. 폴더는 단순 분류가 아니라 데이터 적재 계약이다. 잘못된 폴더에 넣는 것은 검색/추론 품질을 깨뜨린다.
  10. Update the graph, not only the new file. 새 source를 추가했다면 관련 concept, insight, map, index도 필요한 만큼 갱신한다.

Directory Rules

  • 00-inbox/: 임시 입력. 처리 후 가능하면 비운다. 영구 보관 위치가 아니다.
  • 10-sources/: 자료 하나당 source note 하나. 모든 durable claim의 근거 계층이다.
  • 20-insights/: 대화/자료에서 나온 비자명하고 재사용 가능한 통찰. 반드시 source 또는 conversation 근거를 링크한다.
  • 30-concepts/: 오래 유지되는 개념. 중복 금지. aliases 사용. 여러 source에서 축적되는 지식의 중심 노드다.
  • 40-maps/: 사람이 읽는 주제별 내비게이션 문서. source/concept/insight를 큐레이션한다.
  • 50-decisions/: ADR 스타일 결정 기록. 결정 배경, 대안, 결과를 보존한다.
  • 60-schemas/: 문서 구조와 템플릿. 새 note 작성 전 해당 schema를 확인한다.
  • 70-agent-skills/: 에이전트별 ingest/update workflow. 반복 작업 절차를 보존한다.
  • 80-indexes/: claim/concept/source 등 인덱스. 원장이 아니라 탐색 보조/derived artifact다.
  • 90-archive/: 더 이상 active하지 않은 문서. 삭제 대신 archive가 필요한 경우 사용한다.

Data Loading Contract

Every ingestion task must classify the input and route it through this matrix:

Input kind Required primary artifact Required checks Optional secondary artifacts
YouTube / article / paper / book / podcast 10-sources/<slug>.md source metadata, key claims, concepts, caveats, open questions 20-insights/, 30-concepts/, 40-maps/, 80-indexes/
Meeting / chat / conversation 10-sources/ if source-like, otherwise 20-insights/ or 50-decisions/ who/when/context, durable claim source, decision owner if applicable concept/map updates
Standalone reusable idea 20-insights/<slug>.md why non-obvious, evidence/source link, applicability related concept updates
Durable term/model/framework 30-concepts/<canonical-name>.md duplicate title/alias search, source-backed definition map/index updates
Strategy/design/operational decision 50-decisions/<slug>.md context, decision, alternatives, consequences related concepts/maps
Navigation over a topic 40-maps/<topic>.md links are curated, not exhaustive dumps concept/source/insight index updates

If classification is uncertain, put raw material in 00-inbox/ only temporarily and create a follow-up note or TODO explaining what must be classified.

Ingestion Workflow

When adding a new source:

  1. Read this AGENTS.md and the relevant schema in 60-schemas/.
  2. Create or update a source note in 10-sources/.
  3. Record metadata in YAML frontmatter: type, status, created, updated, source_type, title, author, url/date/language/tags when available.
  4. Extract key claims, concepts, caveats, and open questions.
  5. Search existing 30-concepts/ and aliases before creating new concept notes.
  6. Update relevant concept notes with source-backed claims.
  7. Create insight notes only for reusable, non-obvious ideas.
  8. Create decision notes when the user makes or confirms a durable decision.
  9. Update map notes if the new material changes the navigational picture.
  10. Update 80-indexes/ when helpful.
  11. Show git diff before finalizing when interactive.

Write Patterns

Source note

Use for raw external or conversational material. A source note should contain enough metadata for future agents to identify the source, but should not pretend to be the final interpretation.

Required sections are defined in 60-schemas/source.schema.md.

Minimum semantic sections:

  • Metadata
  • Raw Summary or Extracted Notes
  • Key Claims
  • Extracted Concepts
  • Caveats / Limits
  • Open Questions
  • Links Created

Concept note

Use one canonical page per durable concept. Add aliases instead of creating duplicate concept files. Concept notes aggregate multiple source-backed claims over time.

Insight note

Use only for reusable, non-obvious takeaways. Do not create insight notes for obvious summaries or one-off facts.

Decision note

Use when the user chooses a durable direction, policy, architecture, or operating rule. Decision notes must explain context and consequences, not only the final answer.

Map note

Use to create a human-readable route through a topic. Maps should curate links and explain relationships.

Wikilink Rules

Use Obsidian wikilinks:

  • <span class="missing-link">Concept Name</span>
  • <span class="missing-link">Source Title</span>
  • <span class="missing-link">display text</span>

Do not link every occurrence of a word. Link only meaningful concepts and navigational targets.

Frontmatter Rules

Every note must include at least:

---
id: unique-stable-id
type: source|concept|insight|decision|map|project
status: active|draft|archived
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: []
---

Use stable IDs that survive title changes. Prefer readable IDs:

src-youtube-<slug>
concept-<slug>
insight-<slug>
decision-<slug>
map-<slug>

Commit Rules

Use small commits. Suggested commit prefixes:

  • source: add ...
  • concept: update ...
  • insight: add ...
  • decision: record ...
  • map: update ...
  • schema: update ...
  • agent: update rules ...

Quality Bar

Before committing, verify:

  • No duplicate concept note was created.
  • New durable claims cite a source.
  • Wikilinks resolve or intentionally point to planned notes.
  • The change improves future retrieval or reasoning.
  • The note is useful to both humans and agents.
  • Raw source, interpretation, and decision records are not collapsed into one undifferentiated summary.
  • git status and git diff were reviewed.