지식베이스 운영 워크플로우 (LLM Wiki 패턴)
위치 및 적용
본 Skill은 플랫폼에 독립적인 방법론입니다. 외부 지식을 에이전트가 런타임에 호출할 수 있는 행동 규칙(Memory/규범/Skill)으로 변환합니다. 지식베이스는 단순한 북마크가 아니라 에이전트의 능력 성장 엔진입니다. 모든 수집 지식은 반드시 증류(Distillation)를 거쳐야 하며, 가치 판단의 유일한 기준은 다음과 같습니다. 이 지식이 특정 시나리오에서 에이전트의 행동 결정을 직접 변경할 수 있는가?
- 프로젝트에 자체 지식베이스 규범 파일(예:
프로젝트_규범.md)이 이미 있다면 해당 파일을 권위 있는 참조로 삼고, 충돌 시 프로젝트 규범을 우선합니다. - 다른 플랫폼/프로젝트에 적용할 때는 본 Skill의 3계층 아키텍처와 워크플로우에 따라 구현하며, 디렉토리 이름은 현지화할 수 있습니다. 본 저장소의
examples/디렉토리는 바로 실행 가능한 최소 샘플을 제공합니다.
3계층 아키텍처
| 계층 | 권장 디렉토리 | 성격 |
|---|---|---|
| Raw Sources | 원시_수집/ (문서/토론/동영상) | 읽기 전용, 수집 후 불변 |
| The Wiki | 지식베이스/ (목차.md, 수집_경험.md, 조작_로그.md) | LLM이 유지하는 파생 콘텐츠 |
| The Schema | 프로젝트_규범.md + 프로그램_파일/설정/ | 사람과 LLM이 공동 유지 |
핵심 원칙: 원시 파일은 항상 Raw Sources에 남아 있으며 Wiki로 이동하지 않습니다. 검증을 통과한 후 목차.md에 참조를 추가하는 것으로 '등록'이 완료됩니다.
역할 분리 (반드시 준수)
| 역할 | 주체 | 책임 | 금지 |
|---|---|---|---|
| Planner | 사람 | 수집 목표 설정, 가치 계약 정의, 분석 방향 안내 | 파일 직접 조작 금지 |
| Generator | LLM | 수집 실행, 메타데이터 보충, 요약 작성, 목차 및 로그 유지 | 자체 산출물 품질 평가 금지 |
| Evaluator | 검증 도구 (예: scripts/validate.py) | 포맷, 인코딩, 메타데이터, 상호 참조 검증 | 생성에 참여하지 않음 |
핵심 규칙: 모델은 스스로 점수를 매겨서는 안 됩니다. 가치 평가는 Generator가 조작 로그에 기록하고, 통과 여부는 Evaluator가 결정합니다. 사람이 이의를 제기할 경우 인간의 판단을 우선합니다. 프로젝트에 검증 도구가 없는 경우 Lint 6차원을 항목별로 수동 확인하되, 결론은 생성자가 스스로 증명해서는 안 됩니다.
Ingest (수집)
다음 체크리스트를 복사하여 진행 상황을 추적하세요:
- [ ] 1. 수집 전 가치 계약 (세 가지 질문)
- [ ] 2. 수집 및 메타데이터 보충
- [ ] 3. 콘텐츠 읽기, 핵심 정보 추출
- [ ] 4. 가치 판단 (불충족 시 중단)
- [ ] 5. 목차.md 업데이트 (요약 + 상호 참조)
- [ ] 6. 조작 로그 추가
- [ ] 7. 증류 평가 및 적용 상태 표시
- [ ] 8. Git 커밋
1단계 · 수집 전 가치 계약 — 작업 전 세 가지 질문에 답하고 기록합니다:
- 이 문서는 어떤 문제를 해결하려는가? 기존 지식과의 관계는 무엇인가? (보충/대비/확장)
- 어떤 조건에서 '가치 있다'고 판단할 수 있는가? 최소 하나를 충족해야 함: 새로운 개념 도입, 비교 관점 제공, 직접적인 실무 참고 가능
- 예상되는
목차.md내 계층은 무엇인가? (기초 이론/아키텍처 패러다임/엔지니어링 실무/도구 리소스/커뮤니티 동향)
2단계 · 수집 및 메타데이터 — 현재 플랫폼의 수집 엔진을 사용하여 원문을 획득하고('수집 엔진 추상화' 참조), Raw Sources의 해당 하위 디렉토리에 저장합니다. 파일명은 {source}_{topic}_{date}.{ext} 형식을 따릅니다(예: github_karpathy_llm_wiki_20260630.md). 필수 메타데이터 필드: URL, 수집 시간, 수집 명령; 권장 필드: By, Site, Published, 원본 출처. 수집 엔진은 일반적으로 일부 필드만 자동 추출할 수 있으므로 나머지는 반드시 보충해야 합니다.
4단계 · 가치 판단 (중단 포함) — 1단계 계약과 비교하여 평가합니다. 가치 조건을 명백히 충족하지 못하는 경우(내용이 공허함, 심각한 중복, 지식베이스 목적과 무관) 조작 로그에 중단 사유를 명확히 기록한 후 종료하며, 강제로 등록 과정을 진행하지 않습니다.
6단계 · 조작 로그 형식: ## [날짜] ingest | 제목 (append-only)
7단계 · 증류 평가 — 이 항목에 에이전트의 행동을 직접 지도할 수 있는 원자적 규칙이 포함되어 있는가?
| 표시 | 의미 | 조치 |
|---|---|---|
| 🟢 적용 완료 | 실행 가능한 원자적 규칙 존재 | 추출하여 Memory/규범/Skill에 기록, 목차.md 항목에 Memory 제목 명시 |
| 🟡 부분 적용 | 일부 있음 | 적용 완료 및 미적용 내용과 이유 명시 |
| 🔵 참조 색인 | 실행 가능한 규칙 없음 | 조작 로그에 이유 간략히 기재 |
증류 기준: 규칙은 추상적인 개념이나 참고 정보가 아닌, 특정 시나리오에서 에이전트의 행동 결정을 변경할 수 있어야 합니다.
플랫폼 간 증류 적용: Qoder에서는 증류 결과가 Memory 시스템에 기록됩니다(방법론→task_experience, 함정→common_pitfalls_experience, 아키텍처 결정→important_decision_experience 등). 다른 에이전트 플랫폼에서는 해당 플랫폼의 지속적 메모리/행동 규칙 메커니즘에 매핑하며, 판단 기준과 세 가지 색상 표시는 그대로 유지됩니다.
8단계: git add -A && git commit -m "ingest: 제목"
Query (질의)
- 먼저
지식베이스/목차.md를 읽어 관련 페이지를 찾습니다. - 관련 파일을 깊이 읽고 답변을 종합합니다.
- 좋은 답변은 새 페이지로 기록 — 탐색 자체도 복리 효과를 창출합니다.
- 조작 로그에 추가:
## [날짜] query | 질문 - 새 페이지 생성 후:
git add -A && git commit -m "query: 질문"
Lint (검사)
우선적으로 프로젝트의 검증 도구를 실행합니다(본 저장소는 의존성 없는 예제 제공: python scripts/validate.py <지식베이스 루트 디렉토리>). 도구의 판정이 수동 판단보다 우선합니다. 도구가 없으면 6차원을 항목별로 확인합니다:
- 메타데이터 완전성 — 필수 필드(URL, 수집 시간, 수집 명령)가 모두 있는가?
- 인코딩 정확성 — 이중 인코딩된 깨짐 문자, BOM, 대체 문자(U+FFFD)가 있는가?
- 포맷 규범성 — Markdown은 H1으로 시작하고 메타데이터와 본문은
---로 구분되어야 함; JSON은_metadata필드가 있어야 함 - 명명 규칙 —
{source}_{topic}_{date}패턴을 따르는가? - 상호 참조 —
목차.md의 링크가 실제 파일을 가리키는가? 고아 페이지 감지 - 출처 검증 — URL이 허용된 출처 목록에 있는가?
조작 로그에 추가: ## [날짜] lint | 검사 범위; 수정 사항이 있으면 git commit -m "lint: 검사 범위"
Harness 감소: 검증 도구와 프로세스는 모델의 약점을 보완하는 보조 메커니즘으로, 모델의 발전에 따라 단조 감소해야 합니다. Lint 시마다 확인: 더 이상 트리거되지 않는 검증 규칙은 무엇인가? 모델이 이미 내재화한 단계는 무엇인가? 제거하십시오.
수집 엔진 추상화 (플랫폼 간 적용)
핵심 프로세스는 특정 수집 도구에 종속되지 않으며, 수집 엔진은 플랫폼 가용성에 따라 선택합니다:
| 플랫폼 환경 | 수집 방식 |
|---|---|
| Windows + Edge 브라우저 | AutoCLI: autocli read "URL" -f markdown -o "출력 경로", By/Site/URL 자동 추출; PowerShell에서 stderr 진행 정보가 ExitCode=1로 잘못 보고될 수 있으나, 출력에 "Saved to ..."가 포함되면 성공 |
| 웹 읽기 기능이 있는 에이전트 플랫폼 | 웹 읽기 도구(WebFetch 등)로 직접 가져와 Markdown으로 변환 |
| 공개 API 출처 | Hacker News, Lobsters 등은 브라우저 없이 직접 API 요청 가능 |
| 네트워크 도구 없음 | 사용자가 원문을 붙여넣고 수동으로 저장, 수집 명령을 "수동 붙여넣기"로 정직하게 기록 |
어떤 엔진을 사용하든 등록 후 메타데이터, 검증, 증류 요구 사항은 완전히 동일합니다. 수집 명령 필드는 실제 사용한 엔진과 명령(다운그레이드 전환 포함)을 정직하게 기록하여 재현성을 보장합니다.
규칙 빠른 참조
- 파일명:
{source}_{topic}_{date}.{ext}, source는 소문자 - 조작 로그: append-only, 형식
## [날짜] {ingest|query|lint} | 간략 설명 - 커밋 메시지:
{ingest|query|lint}: {간략 설명}; 초기화:init: 지식베이스 베이스라인 - 함정 교훈은 구조화하여
수집_경험.md에 기록하며, 조작 로그와 혼합하지 않음