my-wiki

Imported from centurio1987/my-wiki (AGENTS.md). Install upstream with npx skills add centurio1987/my-wiki. Copyright stays with the author.

AGENTS.md — LLM Wiki 운영 스키마

이 문서는 LLM 에이전트가 이 위키를 어떻게 읽고, 쓰고, 유지·관리해야 하는지를 규정한다. 사용자가 새 소스를 추가하거나 질문을 던질 때, LLM은 반드시 이 문서를 먼저 읽고 여기 정의된 규칙에 따라 움직인다.

핵심 원칙

• 사용자는 소스를 큐레이션하고 질문을 던진다.
• LLM은 그 외 모든 잡일 — 요약, 상호 참조, 파일링, 일관성 유지 — 을 한다.
• 위키는 시간이 지날수록 누적되고 풍부해지는 영구 산출물이다. 매번 처음부터 다시 만들지 않는다.

1. 디렉토리 구조

my-wiki/
├── AGENTS.md            # (이 파일) LLM이 따라야 할 규칙
├── README.md            # 사용자용 안내서
├── index.md             # 위키 전체 페이지 카탈로그 (콘텐츠 지향)
├── log.md               # 활동 로그 (시간순, append-only)
│
├── raw/                 # 원본 소스 (불변 — LLM이 절대 수정하지 않음)
│   ├── assets/          # 이미지 등 첨부 파일
│   └── *.md, *.pdf, ... # 클립된 글, 논문, 노트 등
│
└── wiki/                # LLM이 생성·관리하는 마크다운 페이지
    ├── sources/         # 각 raw 소스에 대한 요약 페이지 (1:1 대응)
    ├── entities/        # 인물, 조직, 제품, 장소 등 고유 명사 페이지
    ├── concepts/        # 추상 개념, 이론, 용어 페이지
    └── syntheses/       # 비교, 분석, 종합 — 질의응답에서 파생된 페이지

• raw/는 불변이다. LLM은 이 안의 파일을 읽기만 한다. 수정·삭제 금지.
• wiki/ 아래의 모든 파일은 LLM이 소유한다. 자유롭게 생성·갱신·이동·병합한다.
• 새로운 카테고리가 필요해지면 LLM이 wiki/ 아래에 디렉토리를 추가하고 이 문서의 구조 섹션을 업데이트한다.

2. 페이지 작성 규칙

2.1 공통 규칙

• 모든 위키 페이지는 한국어로 작성한다. 단, 전문 용어·고유명사·인용은 원어를 병기할 수 있다 (예: "관찰자 패턴 (Observer Pattern)").
• 파일명은 한국어 사용 가능. 공백 대신 띄어쓰기 그대로 또는 하이픈을 사용한다. 예: 관찰자 패턴.md, vannevar-bush.md.
• 모든 페이지는 YAML frontmatter로 시작한다:

---
type: concept | entity | source | synthesis
created: 2026-05-29
updated: 2026-05-29
tags: [태그1, 태그2]
sources: [[sources/원본-요약-페이지]]   # 이 페이지를 뒷받침하는 raw 소스의 요약 페이지
---

• 모든 페이지는 frontmatter 바로 아래에 ## TL;DR 섹션을 둔다. 본론으로 들어가기 전 독자가 감을 잡을 수 있도록, 이 페이지가 다루는 개념·인물·소스의 핵심을 2~4문장으로 압축한다. 독자를 이해시키는 것이 목표이므로 전문 용어는 풀어 쓰고, 비유나 한 줄 임팩트를 활용해 직관적으로 전달한다.
• 본문 내 다른 페이지 참조는 Obsidian wikilink 문법: [[페이지 이름]].
• 외부 URL 인용은 일반 마크다운 링크: [제목](https://...).
• 페이지 끝에 ## 출처 섹션을 두어 이 페이지의 주장을 뒷받침하는 raw 소스와 외부 링크를 모두 나열한다.

2.2 카테고리별 페이지 구조

wiki/sources/{소스명}.md — raw 소스의 요약 페이지

• ## TL;DR: 이 소스가 왜 중요한지, 한 문단으로 압축
• ## 개요: 한두 문단 요약
• ## 핵심 주장: bullet로 3~7개
• ## 인상 깊은 인용: 직접 인용문 (선택)
• ## 등장하는 개념·인물: 위키링크 목록
• ## 출처: raw/ 안의 원본 파일 경로

wiki/entities/{이름}.md — 인물·조직·제품 등

• ## TL;DR: 이 인물/조직/제품이 한 마디로 무엇인지
• ## 정의
• ## 주요 사실 (bullet)
• ## 관련 개념·사건
• ## 출처

wiki/concepts/{개념}.md — 추상 개념

• ## TL;DR: 이 개념을 처음 접하는 사람도 바로 감을 잡을 수 있는 직관적 설명 (비유 적극 활용)
• ## 정의
• ## 상세 설명
• ## 관련 개념 (위키링크)
• ## 사례
• ## 출처

wiki/syntheses/{주제}.md — 비교·분석·종합

• 사용자 질의에서 파생되어 의미 있다고 판단되면 파일로 저장한다.
• 자유 형식이되 frontmatter, ## TL;DR, ## 출처는 필수.

3. 운영(Operations)

3.1 Ingest — 새 소스 추가

사용자가 raw/ 폴더에 새 파일을 떨어뜨리고 "ingest" 또는 "이거 정리해줘"라고 요청하면:

1. 읽기: 소스 전문을 읽는다. 이미지가 있으면 별도로 본다.
2. 대화: 사용자와 핵심 takeaway를 짧게 논의한다 (1~2턴). 강조점이나 관점이 있는지 확인.
3. 요약 페이지 생성: wiki/sources/{소스명}.md를 만든다.
4. 횡단 갱신:
   • 새로 등장한 인물/개념에 대해 entities/ 또는 concepts/ 페이지를 만든다.
   • 이미 존재하는 페이지는 새로운 정보로 갱신한다. 기존 주장과 모순되면 두 주장을 모두 보존하고 > ⚠️ 모순: ... 형태의 주석을 단다.
   • 새로 만들어진/갱신된 페이지마다 다른 페이지로의 위키링크를 적절히 추가한다.
5. index.md 갱신: 새/갱신 페이지를 카탈로그에 반영.
6. log.md 추가: 한 줄 항목 append.
7. 요약 보고: 사용자에게 "어떤 페이지가 생기고 갱신되었는지" 짧게 보고.

한 번의 ingest로 보통 5~15개 페이지가 만들어지거나 갱신된다. 인색하지 말 것.

3.2 Query — 질문에 답하기

사용자가 질문하면:

1. index.md를 먼저 읽는다. 위키 전체를 grep하지 않는다.
2. 관련 페이지를 식별해 읽는다. 필요시 그 페이지가 가리키는 raw 소스 원문도 확인한다.
3. 출처를 명시하며 답한다. 본문 안에 [[페이지]] 위키링크를 적극 사용한다.
4. 답변이 길거나 의미가 크면 wiki/syntheses/에 페이지로 저장할지 사용자에게 제안하거나 직접 저장한다 — 탐색의 산출물도 위키에 쌓여야 한다.
5. log.md에 query 항목 추가.

3.3 Lint — 건강도 점검

사용자가 "lint" 또는 "위키 점검"이라고 요청하면:

• 모순: 페이지 간 상충하는 주장 찾기.
• stale: 새 소스로 인해 갱신이 필요한 옛 주장 찾기.
• orphan: 다른 페이지로부터 링크되지 않은 고립 페이지 찾기.
• missing: 자주 언급되지만 자체 페이지가 없는 개념 찾기.
• gap: 웹 검색이나 추가 소스로 메울 만한 정보 공백 제안.
• 결과는 체크리스트 형태로 사용자에게 보고하고 진행 여부를 묻는다.
• log.md에 lint 항목 추가.

4. index.md 형식

• 콘텐츠 지향: 페이지가 무엇에 관한 것인지 한 줄로 보여준다.
• 카테고리별 섹션(## Sources, ## Entities, ## Concepts, ## Syntheses)으로 나누고 각 항목은:

- [[페이지 이름]] — 한 줄 요약 (선택: yyyy-mm-dd)

• ingest/lint 시마다 LLM이 자동으로 동기화한다.

5. log.md 형식

• append-only, 시간 역순(최신이 위) 또는 시간순(최신이 아래) 중 시간순 고정.
• 항목 prefix는 ## [YYYY-MM-DD] {kind} | {제목} 형식. (kind ∈ ingest, query, lint, meta)
• 이렇게 하면 grep "^## \[" log.md | tail -5로 최근 5건을 뽑을 수 있다.
• 항목 본문은 짧게: 2~5줄. 자세한 내용은 해당 페이지를 보면 된다.

예:

## [2026-05-29] ingest | Memex (V. Bush, 1945)
- sources/memex 페이지 생성
- entities/vannevar-bush 신규
- concepts/연상-기반-탐색 신규
- index 갱신

6. 모순·불확실성 표기 규약

LLM이 어떤 사실에 자신이 없거나, 두 소스가 충돌할 때는 반드시 명시적으로 표기한다. 우물우물 넘어가지 않는다.

• > ⚠️ 모순: [[소스A]]는 X라고 하지만 [[소스B]]는 Y라고 한다.
• > ❓ 불확실: 이 부분은 1차 자료가 부족함. 추가 조사 필요.
• > 🕰️ 시점 의존: 2024년 기준 X. 이후 변경 가능성 있음.

7. 사용자와의 협업 톤

• 사용자는 한국어로 질문하므로 답변도 한국어로 한다.
• 코드·툴 출력은 그대로 두되, 설명은 한국어.
• 사용자가 무엇을 강조하고 싶은지, 어떤 관점에서 보고 싶은지 묻고 작업한다. 혼자 다 결정하지 않는다.
• 한 번의 응답에 너무 많은 질문을 하지 않는다 (최대 1~2개).

8. 절대 하지 말 것 (Anti-patterns)

• ❌ raw/ 안의 파일 수정·삭제
• ❌ 출처 없이 사실을 단언
• ❌ 모순을 매끄럽게 덮기 (반드시 표기)
• ❌ index.md를 갱신하지 않고 ingest 끝내기
• ❌ "다 했습니다" 한 줄로 끝내기 — 어떤 페이지가 생기고 갱신되었는지 반드시 보고
• ❌ 위키 페이지를 raw에 저장하거나, raw 소스를 wiki에 저장하기

9. 이 문서의 진화

이 스키마는 사용자와 LLM이 함께 다듬어 가는 살아있는 문서다. 작업 중 더 나은 규칙이나 누락된 규칙을 발견하면 LLM은 사용자에게 제안하고, 합의되면 이 문서를 수정한 뒤 log.md에 meta 항목으로 기록한다.