위키 · 구현 참조
지식을 저장하고 찾기
이 문서는 지식이 어디에 보존되고, 작업에 맞는 후보가 어떻게 검색되며, 원문과 현재 상태를 어떻게 확인하는지 답합니다.
여기 나오는 경로와 명령은 로컬 운영 확장의 좌표이며 p-hermes 공개 저장소에는 포함되지 않습니다. 구성별 범위와 출처 →
1. 지식의 종류와 정본 위치
orchestration/CLASSIFICATION.md가 각 정보 종류의 정본 위치와 쓰임을 정합니다. 동일 내용을 여러 곳에 복사하기보다 단일 정본을 읽고, 근거가 되는 사건 기록은 JOB 폴더에서 확인합니다.
| 정보 | 정본 | 사용 |
|---|---|---|
| 절차 — 지금 어떻게 하는가 | 주제별 SKILL.md와 references/ | 작업 트리거에 맞는 절차를 불러옵니다. |
| 사건·교훈 — 무슨 일이 왜 있었나 | knowledge/lessons/<id>_lessons.md, 검색용 lessons/index.md, 근거 원문은 JOB | 색인에서 후보를 찾고 교훈 원문 및 연결된 근거를 읽습니다. |
| 현재 사실 — 지금 무엇이 있는가 | 실물 정본인 STRUCTURE.md, catalogs, registry, config, 스크립트 | 요약 대신 현재 파일을 직접 확인합니다. |
| 사용자 선호 | MEMORY.md | 세션에 로드된 내용을 참고합니다. |
| 역할·권한·금지 규칙 | POLICY.md와 WORKER.md | 각 진입 문서가 가리키는 규칙을 따릅니다. |
knowledge/wiki/와 concepts/는 읽을 수 있지만 새 정본을 쓰는 위치가 아닙니다. jobs-index/, processed/는 스크립트가 만드는 파생물입니다. daily-synthesis는 현재 검색 입력에서 제외된 퇴역 경로입니다. 매일 위키 요약을 만드는 절차로 취급하지 않습니다.
2. 언제 읽고 검색하나
| 시점 | 행동 |
|---|---|
| 세션 시작 | 진입 문서가 가리키는 규칙을 읽고, 사용자 선호는 로드된 메모리에서 확인합니다. |
| 파일 요청 작업 전 | dispatcher가 관련 교훈·결정 후보를 담은 자료 묶음을 만들고 CONTEXT_PACK 경로를 전달합니다. 요청을 받은 쪽은 그 파일을 먼저 읽습니다. 상태가 no_match, search_error, source_missing이거나 자료가 잘렸으면(partial) 핵심어로 한 번 직접 검색해 확인합니다. |
| 직접 시작하는 JOB | 작업을 시작할 때 요청서를 입력으로 자료 묶음을 생성합니다. |
| 새 질문이 생겼을 때 | 이미 전달된 후보를 반복 검색하지 않고, 비어 있거나 잘린 부분 또는 새로 생긴 질문만 검색합니다. |
| 작업을 마친 뒤 | 다시 쓸 가치가 있는 사건·교훈이 있을 때 후보 기록을 작성하고, JOB 결과에서 연결합니다. |
3. 자료 묶음과 출처 상태
자료 묶음은 요청 제목·목표를 검색 질의로 만들어 교훈과 결정 저장소에서 후보를 모읍니다. 요청에 지정된 프로젝트가 있으면 해당 프로젝트 저장소도 후보 풀에 추가합니다. 결과에는 최대 5개 후보를 싣고 전체 출력은 4,800자 이내로 제한합니다. 파일 요청에서는 자동 생성되고, 직접 JOB을 시작할 때는 다음 형태로 생성할 수 있습니다.
python3 <로컬 운영 루트>/core/scripts/context_pack.py <JOB>/request.md --out <JOB>/artifacts/context-pack.md첫 줄은 검색 결과와 수집 상태를 표시합니다. 후보가 있다는 사실은 사실성이나 적용 승인을 뜻하지 않습니다.
| 필드·값 | 해석 |
|---|---|
found | 후보가 실렸습니다. 후보 원문과 현재 실물을 확인합니다. |
no_match | 검색은 수행됐지만 표시할 후보가 없었습니다. 관련 지식이 없다는 증명은 아닙니다. |
search_error, source_missing, blocked_sensitive | 검색 오류, 검색 원본 부재, 민감 요청 제한 상태입니다. 누락 구간을 검색 결과로 오인하지 않습니다. |
completeness=partial, truncated, timed_out | 일부 원본을 읽지 못했거나 출력이 잘렸거나 시간 제한에 걸렸습니다. 핵심어로 추가 확인합니다. |
path_errors, search_errors, semantic_errors | 파일명 인코딩 문제, 검색 실행 오류, 선택적 의미 검색 오류 진단 수치입니다. |
unknown, stale | 날짜·출처 정보가 없으면 unknown이 될 수 있습니다. stale은 기준일보다 오래됐다는 신호이며, 내용이 틀렸다는 판정은 아닙니다. |
출처 판정은 문서 본문 확보 여부, 검증 표기, 지식 상태, 날짜, 원문·참조 경로의 도달 가능성을 구분합니다. 예를 들어 validation_status: candidate는 검토 후보를 나타내며 검증 완료를 뜻하지 않습니다. 경로가 열리는 것만으로 내용의 사실 여부가 확인되지는 않습니다.
| 출처 상태 필드 | 실제 값과 읽는 법 |
|---|---|
body_status | acquired는 의미 있는 본문이 있음, not_acquired는 본문을 확보하지 못함, unknown은 판정할 수 없음입니다. |
validation_status | validated, unverified, rejected, unknown으로 판정합니다. front matter의 candidate는 이 분류에서 unverified로 읽힙니다. |
knowledge_status | candidate, current, superseded, conflicted, unknown입니다. |
source_state | current, superseded, invalid, unknown입니다. 검증 불가만으로 current가 되지는 않습니다. |
acquisition_scope | locator, summary, excerpt, full, unknown으로 확보 범위를 표시합니다. |
source_resolution, source_locator_resolution | 로컬 원문 경로는 resolved, missing, unsafe, unknown 등으로 나뉩니다. 외부 locator는 external일 수 있습니다. |
stale | 기준 기간을 넘었으면 true, 넘지 않았으면 false, 날짜를 판단할 수 없으면 null입니다. |
4. 검색 방식과 한계
hybrid-search.sh는 Markdown을 대상으로 질의 문자열을 정규화하고 단어 일치율, 문서 크기, 사용 점수 기준을 결합해 최대 10개를 순위화합니다. 집계 페이지, 본문이 없는 URL 스텁, 퇴역한 요약 경로는 기본 후보에서 제외됩니다. 의미 검색은 별도 선택으로 호출할 수 있고, 자동 대체는 기본 동작이 아닙니다.
- 핵심 단어가 겹치지 않는 동의어·바꿔 말하기는 빠질 수 있습니다. 검색 결과가 없거나 적어도 자료 부재를 단정하지 않습니다.
- 점수는 관련성의 증명이 아닙니다. 여러 파일명이 같으면 일부 점수 보정이 적용되지 않을 수 있습니다.
- 회귀 문제집은 positive·negative 질의를 함께 두어 찾을 자료를 회수하는지와 무관한 결과가 섞이는지를 점검합니다. 10월 11일 개선 회귀 기록에서는 positive 18개 회수 및 negative 4개 오탐 0을 기록했습니다. 이는 해당 시점의 시험 결과이며 이후 성능을 보증하지 않습니다.
- 판단할 때는 자료 묶음 후보 → 교훈 원문 → 현재 실물 순서로 확인합니다. 전달되거나 열람된 것과 실제 판단에 사용한 것을 구분해 기록합니다.
운영 모니터는 회귀·활용 지표와 본문 수집 대기열을 함께 다룹니다. knowledge-daily-monitor.sh는 단순 조회 전용 명령이 아니며 대기열 처리를 실행할 수 있으므로, 실행 전에 현재 동작과 범위를 확인합니다. daily-knowledge-process.sh는 세션·JOB 처리와 의미 색인 갱신 등을 수행하며, daily-synthesis 요약 생성과는 다른 경로입니다.
5. 교훈 작성, 정리와 승격
실패 원인과 해결, 사용자 교정, 새로 확인한 사실처럼 반복해서 쓸 가치가 있을 때만 교훈을 남깁니다. 원고에는 다음에 검색할 수 있도록 증상·상황 단서를 포함하고, 비어 있지 않은 언제 쓰나 절을 둡니다.
python3 <로컬 운영 루트>/core/scripts/write-lesson.py --id <id> --body-file <JOB의 교훈 원고>스크립트는 교훈 파일을 기존 파일에 덮어쓰지 않고 생성하며, validation_status: candidate를 기록한 뒤 검색 색인을 재생성합니다. ID는 경로 구분자가 없는 파일명 slug여야 합니다. 이 단계는 후보 등록이며 검증·정본 승격을 자동 확정하지 않습니다. 색인 행은 직접 편집하지 않습니다.
- 같은 교훈이 두 번 이상 확인되면 기존 스킬의 해당 절차를 일반화해 갱신합니다. 스킬 본문에 JOB별 사례를 계속 덧붙이지 않습니다.
- 스킬에서 내려온 상세 사례는 해당 reference나 lesson으로 옮겨 보존합니다. 변경된 규칙·현재 사실은 각각 해당 정본에서 갱신합니다.
- 낡거나 대체된 기록은 출처와 대체 경로를 확인해 처리합니다. 동결·파생 위치를 정본처럼 갱신하거나, 출처 확인 없이 기록을 삭제하지 않습니다.
- JOB을 마칠 때
result.md에 교훈 파일을 연결하고, 응답서에는 실제 생성된 경로를 기록합니다.
6. 점검 방법과 근거 파일
점검은 검색 품질, 출처 실물, 그리고 실제 사용 흔적을 나누어 확인합니다. 모니터가 요약한 정상 상태만으로 내용을 검증했다고 보지 않습니다.
- 교훈 색인에서 증상이나 오류 핵심어를 찾아 교훈 원문과 연결된 근거를 엽니다.
knowledge_source_status.py로 후보의 출처·검증·날짜 분류를 읽고, 근거 경로가 가리키는 실제 파일도 확인합니다.knowledge-retrieval-regression.py의 positive 회수율과 negative 오탐을 함께 봅니다. 검색 문제집 자체가 현행 내용을 대표하는지도 검토합니다.worker-reference-metrics.py의used,rejected,n-a, 미분류 건수를 구분해 후보가 실제 판단에 기여했는지 확인합니다.- 대기열 수와 처리 시도·획득·실패·잔량, 조정 기록의 실제 검토 여부를 별도로 확인합니다. 수집·커서 진행만으로 원문 검토나 효과를 주장하지 않습니다.
| 대상 | 정본 경로 |
|---|---|
| 정보 분류 | orchestration/CLASSIFICATION.md, knowledge/README.md |
| 사용·기록 계약 | orchestration/WORKER.md 3절, POLICY.md (f) |
| 자료 묶음·출처 상태 | core/scripts/context_pack.py, core/scripts/knowledge_source_status.py |
| 검색·교훈 작성 | core/scripts/hybrid-search.sh, core/scripts/write-lesson.py, core/scripts/rebuild-lessons-index.py |
| 회귀·모니터 | core/scripts/knowledge-retrieval-regression.py, core/scripts/worker-reference-metrics.py, core/scripts/knowledge-daily-monitor.sh |
| 개선 근거 | JOB 결과 중 지식 시스템 개선 기록, knowledge/lessons/retrieval-regression.json |
확인 기준: 2026-10-13. 운영 절차와 검색 동작은 참조된 파일의 현재 내용을 기준으로 확인합니다.