공개 문서
learn/canonical/knot/schema.md
아래는 learn/canonical/knot/schema.md 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# knot — 규약 정본 (schema)
> Upstream [netwaif/knot](https://github.com/netwaif/knot)는 “vault” 용어를 쓴다. **로컬 LAB 폴더명**은 `knot-wiki/`, env는 `KNOT_WIKI`.
평문 마크다운 지식 그물 vault. 이 파일이 **유일 정본 규약**이며, 모든 에이전트는 어떤 작업이든 이 파일을 먼저 정독한 뒤 시작한다.
## vault 레이아웃 (schema / raw / wiki / ops)
| 영역 | 경로 | 역할 |
|------|------|------|
| **schema** | `schema/schema.md`, `schema/index.md`, `schema/log.md`, `schema/README.md`, `schema/OBSIDIAN.md` | 규칙·색인·연대기·온보딩 |
| **raw** | `raw/inbox/` · `raw/archive/` · `raw/quarantine/` **만** (하위 3개) | 미처리 큐 · ingest 완료 원본 · PII·비준수 격리 |
| **wiki** | `wiki/*.md` **flat, 하위 폴더 금지** | 정리 지식 — **핵심 3문서:** `llm-wiki`, `knot-wiki`, `harness-multiagent` |
| **ops** | `ops/prompts/`, `ops/scripts/` | ingest/query/lint 프롬프트 · lint.py · drain.sh |
**금지:** wiki 하위 분류 폴더 · stub 전용 wiki 파일 · ingest로 4번째 wiki 생성 · **PII 포함 raw의 wiki 승격** · raw 자동 삭제.
## 구조와 소유권
| 영역 | 소유자 | 규칙 |
|------|--------|------|
| `raw/inbox/` | 사람 | 미처리 소스 큐. 에이전트는 읽기 + 처리 완료 후 archive로 이동만 |
| `raw/archive/` | 사람 | 처리 완료 원본 보관. **내용 불변** — 에이전트는 읽기 전용 |
| `raw/quarantine/` | 사람 | PII·비준수 원본 격리. **ingest·wiki 승격 금지** |
| `wiki/`, `schema/index.md`, `schema/log.md` | 에이전트 | 사람은 읽고 지시. 직접 고쳐도 되지만 보통 에이전트 경유 |
| `schema/schema.md`, `ops/prompts/`, `ops/scripts/` | 사람 | 에이전트는 제안만, 수정은 사람 승인 후 |
inbox→archive 이동 시 파일명에 `YYYY-MM-DD-` prefix. 경로: `raw/archive/YYYY-MM-DD-<name>`. 이동만 허용, 내용 수정 절대 금지.
## 페이지 타입 (4종 고정)
| type | 용도 |
|------|------|
| `source` | raw 소스 1건의 요약·takeaway·열린 질문. ingest마다 1개 |
| `entity` | 사람·도구·프로젝트·조직 등 고유 대상 |
| `concept` | 기법·아이디어·패턴 |
| `note` | query 답변 중 보존 가치 있는 합성물 |
타입을 늘리지 않는다. 필요가 증명되면 schema 개정(사람 승인)으로만.
## frontmatter (전 페이지 공통)
```yaml
---
type: source # source | entity | concept | note
created: 2026-06-10
updated: 2026-06-10 # 내용 수정 시마다 갱신
sources: [raw/archive/2026-06-10-foo.md] # 근거: raw/archive/ 경로 또는 URL. 빈 리스트 허용
aliases: [] # 선택: 동의어·약칭
---
```
`related` 같은 링크 필드는 두지 않는다 — 링크는 본문에만 둔다.
## 강사 callout (선택 — SkoolChef·강의 소스)
강의·컨설팅·수강생 대상 소스(`audience: instructor` 또는 inbox 파일명에 `lecture`·`teaching`·`instructor` 포함)의 **`source` 페이지**에만 적용한다. MAS/harness ops 소스는 생략한다.
- 위치: YAML frontmatter **바로 아래**, `# 제목` **위**
- 형식 (Obsidian 호환):
```markdown
> [!tip] 강사·컨설턴트 관점 핵심 Takeaway
> 강의·컨설팅에 바로 쓸 수 있는 포인트 1~3줄.
```
- frontmatter 선택 필드: `audience: instructor` (강사 소스일 때)
- callout은 frontmatter 대체가 아님 — `## 열린 질문`·`[[링크]]` 규칙은 동일
- 가이드 SSOT: `WORKSPACE_CLEAN/CLAUDE/PROJECTS/SKOOLCHEF-LLM-WIKI/CLAUDE.md` (vault 실체는 `KNOT_WIKI`)
## 파일명·[[링크]] 규칙
- 파일명 = 슬러그: kebab-case, 영문 권장(한글 허용), `wiki/<슬러그>.md`. wiki/는 flat(하위폴더 없음)
- 링크 표기 `[[슬러그]]`, 표시명 필요 시 `[[슬러그|표시명]]`
- 모든 링크는 wiki/ 내 실재 파일을 가리켜야 한다. 아직 없는 페이지를 의도적으로 가리킬 때만 그 줄에 `<!-- stub -->` 표기
- 연결이 본문 문맥에 안 녹으면 페이지 끝 `## 관련` 절에 모은다
- 모든 페이지는 `schema/index.md`에 정확히 1번 등재된다
- Obsidian 전용 문법(dataview 등) 금지 — 평문 호환 유지
## schema/index.md / schema/log.md
- `schema/index.md`: type별 섹션, 페이지당 한 줄 — `- [[슬러그]] — 한 줄 요약 (updated)`
- `schema/log.md`: append-only 연대기. 항목 prefix `## [YYYY-MM-DD] ingest|query|lint — 제목`. 수정·삭제 금지
## ingest 정책 (wiki 3문서)
ingest는 **신규 wiki 파일을 만들지 않는다.** `llm-wiki`, `knot-wiki`, `harness-multiagent` 중 관련 문서의 **섹션만 갱신**한다.
## 워크플로
| 작업 | 따를 파일 |
|------|----------|
| ingest — inbox 소스 처리 | `ops/prompts/ingest.md` |
| query — 질문 답변·합성 | `ops/prompts/query.md` |
| lint — 건강검진 | `ops/prompts/lint.md` |
| 기계 검사만 | `python3 ops/scripts/lint.py` (ERROR 존재 시 exit 1) |
## git 규약
- vault를 변경하는 실행(save(inbox에 자료 추가), ingest, 자동수정 있는 lint, note를 저장한 query)은 **git commit으로 마무리**한다. git이 감사·복구·동시성 탐지 층이다.
- 실행 시작 시 working tree가 더러우면(미커밋 변경 존재) 다른 실행이 진행 중일 수 있으므로 **중단하고 보고**한다.
- 커밋 메시지: `ingest: <제목>` / `lint: <요약>` / `query: <제목>`. 트레일러에 실행한 실제 모델명을 남긴다 — 예: `Co-Authored-By: <실제 모델명>`
- **push 금지** — 로컬 전용. 원격 연결은 사람이 결정한다.
## 소스 포맷
벤더중립은 **텍스트 소스(md·txt)에서 보장**된다. rich 포맷(PDF·이미지 등)은 읽기 능력이 벤더마다 다르므로, 지원하는 벤더로만 ingest한다.
## 무인 운용 (참고 — 등록 여부는 사람이 결정)
```bash
cd "$KNOT_WIKI" && claude -p "schema/schema.md와 ops/prompts/ingest.md를 정독하고 그대로 실행하라"
```
`raw/inbox/`가 비어 있으면 즉시 "할 일 없음"으로 종료.
공개 문서 변환 코드 (HTML)
<h1>knot — 규약 정본 (schema)</h1>
<blockquote>
<p>Upstream <a href="https://github.com/netwaif/knot">netwaif/knot</a>는 “vault” 용어를 쓴다. <strong>로컬 LAB 폴더명</strong>은 <code>knot-wiki/</code>, env는 <code>KNOT_WIKI</code>.</p>
</blockquote>
<p>평문 마크다운 지식 그물 vault. 이 파일이 <strong>유일 정본 규약</strong>이며, 모든 에이전트는 어떤 작업이든 이 파일을 먼저 정독한 뒤 시작한다.</p>
<h2>vault 레이아웃 (schema / raw / wiki / ops)</h2>
<table>
<thead>
<tr>
<th>영역</th>
<th>경로</th>
<th>역할</th>
</tr>
</thead>
<tbody><tr>
<td><strong>schema</strong></td>
<td><code>schema/schema.md</code>, <code>schema/index.md</code>, <code>schema/log.md</code>, <code>schema/README.md</code>, <code>schema/OBSIDIAN.md</code></td>
<td>규칙·색인·연대기·온보딩</td>
</tr>
<tr>
<td><strong>raw</strong></td>
<td><code>raw/inbox/</code> · <code>raw/archive/</code> · <code>raw/quarantine/</code> <strong>만</strong> (하위 3개)</td>
<td>미처리 큐 · ingest 완료 원본 · PII·비준수 격리</td>
</tr>
<tr>
<td><strong>wiki</strong></td>
<td><code>wiki/*.md</code> <strong>flat, 하위 폴더 금지</strong></td>
<td>정리 지식 — <strong>핵심 3문서:</strong> <code>llm-wiki</code>, <code>knot-wiki</code>, <code>harness-multiagent</code></td>
</tr>
<tr>
<td><strong>ops</strong></td>
<td><code>ops/prompts/</code>, <code>ops/scripts/</code></td>
<td>ingest/query/lint 프롬프트 · lint.py · drain.sh</td>
</tr>
</tbody></table>
<p><strong>금지:</strong> wiki 하위 분류 폴더 · stub 전용 wiki 파일 · ingest로 4번째 wiki 생성 · <strong>PII 포함 raw의 wiki 승격</strong> · raw 자동 삭제.</p>
<h2>구조와 소유권</h2>
<table>
<thead>
<tr>
<th>영역</th>
<th>소유자</th>
<th>규칙</th>
</tr>
</thead>
<tbody><tr>
<td><code>raw/inbox/</code></td>
<td>사람</td>
<td>미처리 소스 큐. 에이전트는 읽기 + 처리 완료 후 archive로 이동만</td>
</tr>
<tr>
<td><code>raw/archive/</code></td>
<td>사람</td>
<td>처리 완료 원본 보관. <strong>내용 불변</strong> — 에이전트는 읽기 전용</td>
</tr>
<tr>
<td><code>raw/quarantine/</code></td>
<td>사람</td>
<td>PII·비준수 원본 격리. <strong>ingest·wiki 승격 금지</strong></td>
</tr>
<tr>
<td><code>wiki/</code>, <code>schema/index.md</code>, <code>schema/log.md</code></td>
<td>에이전트</td>
<td>사람은 읽고 지시. 직접 고쳐도 되지만 보통 에이전트 경유</td>
</tr>
<tr>
<td><code>schema/schema.md</code>, <code>ops/prompts/</code>, <code>ops/scripts/</code></td>
<td>사람</td>
<td>에이전트는 제안만, 수정은 사람 승인 후</td>
</tr>
</tbody></table>
<p>inbox→archive 이동 시 파일명에 <code>YYYY-MM-DD-</code> prefix. 경로: <code>raw/archive/YYYY-MM-DD-<name></code>. 이동만 허용, 내용 수정 절대 금지.</p>
<h2>페이지 타입 (4종 고정)</h2>
<table>
<thead>
<tr>
<th>type</th>
<th>용도</th>
</tr>
</thead>
<tbody><tr>
<td><code>source</code></td>
<td>raw 소스 1건의 요약·takeaway·열린 질문. ingest마다 1개</td>
</tr>
<tr>
<td><code>entity</code></td>
<td>사람·도구·프로젝트·조직 등 고유 대상</td>
</tr>
<tr>
<td><code>concept</code></td>
<td>기법·아이디어·패턴</td>
</tr>
<tr>
<td><code>note</code></td>
<td>query 답변 중 보존 가치 있는 합성물</td>
</tr>
</tbody></table>
<p>타입을 늘리지 않는다. 필요가 증명되면 schema 개정(사람 승인)으로만.</p>
<h2>frontmatter (전 페이지 공통)</h2>
<pre><code class="language-yaml">---
type: source # source | entity | concept | note
created: 2026-06-10
updated: 2026-06-10 # 내용 수정 시마다 갱신
sources: [raw/archive/2026-06-10-foo.md] # 근거: raw/archive/ 경로 또는 URL. 빈 리스트 허용
aliases: [] # 선택: 동의어·약칭
---
</code></pre>
<p><code>related</code> 같은 링크 필드는 두지 않는다 — 링크는 본문에만 둔다.</p>
<h2>강사 callout (선택 — SkoolChef·강의 소스)</h2>
<p>강의·컨설팅·수강생 대상 소스(<code>audience: instructor</code> 또는 inbox 파일명에 <code>lecture</code>·<code>teaching</code>·<code>instructor</code> 포함)의 <strong><code>source</code> 페이지</strong>에만 적용한다. MAS/harness ops 소스는 생략한다.</p>
<ul>
<li>위치: YAML frontmatter <strong>바로 아래</strong>, <code># 제목</code> <strong>위</strong></li>
<li>형식 (Obsidian 호환):</li>
</ul>
<pre><code class="language-markdown">> [!tip] 강사·컨설턴트 관점 핵심 Takeaway
> 강의·컨설팅에 바로 쓸 수 있는 포인트 1~3줄.
</code></pre>
<ul>
<li>frontmatter 선택 필드: <code>audience: instructor</code> (강사 소스일 때)</li>
<li>callout은 frontmatter 대체가 아님 — <code>## 열린 질문</code>·<code>[[링크]]</code> 규칙은 동일</li>
<li>가이드 SSOT: <code>WORKSPACE_CLEAN/CLAUDE/PROJECTS/SKOOLCHEF-LLM-WIKI/CLAUDE.md</code> (vault 실체는 <code>KNOT_WIKI</code>)</li>
</ul>
<h2>파일명·[[링크]] 규칙</h2>
<ul>
<li>파일명 = 슬러그: kebab-case, 영문 권장(한글 허용), <code>wiki/<슬러그>.md</code>. wiki/는 flat(하위폴더 없음)</li>
<li>링크 표기 <code>[[슬러그]]</code>, 표시명 필요 시 <code>[[슬러그|표시명]]</code></li>
<li>모든 링크는 wiki/ 내 실재 파일을 가리켜야 한다. 아직 없는 페이지를 의도적으로 가리킬 때만 그 줄에 <code><!-- stub --></code> 표기</li>
<li>연결이 본문 문맥에 안 녹으면 페이지 끝 <code>## 관련</code> 절에 모은다</li>
<li>모든 페이지는 <code>schema/index.md</code>에 정확히 1번 등재된다</li>
<li>Obsidian 전용 문법(dataview 등) 금지 — 평문 호환 유지</li>
</ul>
<h2>schema/index.md / schema/log.md</h2>
<ul>
<li><code>schema/index.md</code>: type별 섹션, 페이지당 한 줄 — <code>- [[슬러그]] — 한 줄 요약 (updated)</code></li>
<li><code>schema/log.md</code>: append-only 연대기. 항목 prefix <code>## [YYYY-MM-DD] ingest|query|lint — 제목</code>. 수정·삭제 금지</li>
</ul>
<h2>ingest 정책 (wiki 3문서)</h2>
<p>ingest는 <strong>신규 wiki 파일을 만들지 않는다.</strong> <code>llm-wiki</code>, <code>knot-wiki</code>, <code>harness-multiagent</code> 중 관련 문서의 <strong>섹션만 갱신</strong>한다.</p>
<h2>워크플로</h2>
<table>
<thead>
<tr>
<th>작업</th>
<th>따를 파일</th>
</tr>
</thead>
<tbody><tr>
<td>ingest — inbox 소스 처리</td>
<td><code>ops/prompts/ingest.md</code></td>
</tr>
<tr>
<td>query — 질문 답변·합성</td>
<td><code>ops/prompts/query.md</code></td>
</tr>
<tr>
<td>lint — 건강검진</td>
<td><code>ops/prompts/lint.md</code></td>
</tr>
<tr>
<td>기계 검사만</td>
<td><code>python3 ops/scripts/lint.py</code> (ERROR 존재 시 exit 1)</td>
</tr>
</tbody></table>
<h2>git 규약</h2>
<ul>
<li>vault를 변경하는 실행(save(inbox에 자료 추가), ingest, 자동수정 있는 lint, note를 저장한 query)은 <strong>git commit으로 마무리</strong>한다. git이 감사·복구·동시성 탐지 층이다.</li>
<li>실행 시작 시 working tree가 더러우면(미커밋 변경 존재) 다른 실행이 진행 중일 수 있으므로 <strong>중단하고 보고</strong>한다.</li>
<li>커밋 메시지: <code>ingest: <제목></code> / <code>lint: <요약></code> / <code>query: <제목></code>. 트레일러에 실행한 실제 모델명을 남긴다 — 예: <code>Co-Authored-By: <실제 모델명></code></li>
<li><strong>push 금지</strong> — 로컬 전용. 원격 연결은 사람이 결정한다.</li>
</ul>
<h2>소스 포맷</h2>
<p>벤더중립은 <strong>텍스트 소스(md·txt)에서 보장</strong>된다. rich 포맷(PDF·이미지 등)은 읽기 능력이 벤더마다 다르므로, 지원하는 벤더로만 ingest한다.</p>
<h2>무인 운용 (참고 — 등록 여부는 사람이 결정)</h2>
<pre><code class="language-bash">cd "$KNOT_WIKI" && claude -p "schema/schema.md와 ops/prompts/ingest.md를 정독하고 그대로 실행하라"
</code></pre>
<p><code>raw/inbox/</code>가 비어 있으면 즉시 "할 일 없음"으로 종료.</p>