132 lines
7.1 KiB
Markdown
132 lines
7.1 KiB
Markdown
# LLM Wiki — 작업 가이드
|
|
|
|
원본 자료(`raw/`)를 검증된 실무 기술 문서로 바꾸는 문서 파이프라인입니다. 거기서 면접·블로그·포트폴리오 같은 외부 산출물을 만들어 냅니다. Obsidian vault 이자 Claude Code 자동화 저장소입니다.
|
|
|
|
처음 오셨다면 이 README만 읽으면 작업을 시작할 수 있습니다. 운영 규칙의 전체 정의(SSOT)는 [CLAUDE.md](CLAUDE.md) 에 있습니다.
|
|
|
|
---
|
|
|
|
## 핵심 원칙 (이것만 기억하면 됩니다)
|
|
|
|
```
|
|
raw 자료 = 증거 (출처 보존)
|
|
wiki/concepts = 검증된 일반 개념
|
|
wiki/projects = 내 프로젝트에 적용된 검증 사실
|
|
wiki/interview·blog·portfolio = 위 canonical 에서 파생된 외부 산출물
|
|
```
|
|
|
|
이 순서는 거꾸로 갈 수 없습니다. 외부 산출물(블로그·면접 문서 등)은 raw나 메모에서 바로 만들지 않고 **반드시** `wiki/concepts` 또는 `wiki/projects` 를 거쳐서 나옵니다.
|
|
|
|
또 하나의 원칙은 **근거 없는 단정을 쓰지 않는다**입니다. 모든 결정은 출처(Claim ID)로 뒷받침하거나 근거가 없으면 `UNSUPPORTED_DECISION` 으로 솔직히 표시합니다.
|
|
|
|
---
|
|
|
|
## 빠른 시작
|
|
|
|
가장 흔한 작업 흐름은 이렇습니다.
|
|
|
|
```bash
|
|
# 1) 새 작업을 시작합니다 (빈 branch-note 스캐폴드 생성)
|
|
/branch feature-keycloak-oidc-flow
|
|
|
|
# 2) 참고할 공식 문서 / 대기업 블로그 URL 을 근거로 저장합니다
|
|
# → Claude 에게 "이 URL 을 근거로 저장해줘" 라고 요청
|
|
|
|
# 3) branch-note 를 채웁니다 (자동 조사 + 깊이 검증까지 한 번에)
|
|
/branch-spec feature-keycloak-oidc-flow
|
|
# → Ready 가 나오면 코딩 시작. Not ready 면 알려주는 부분을 채우고 다시 실행
|
|
|
|
# 4) 구현이 끝나면 검증된 결과를 wiki 로 올립니다
|
|
/ingest raw/branch-notes/feature-keycloak-oidc-flow.md
|
|
|
|
# 5) 품질을 점검합니다
|
|
/lint # 보고만
|
|
/lint --fix-plan # 수정 계획 + 승인 후 적용
|
|
|
|
# 6) 외부 산출물을 만듭니다 (canonical 이 reviewed 이상일 때)
|
|
/interviewize wiki/projects/...
|
|
/blogify wiki/concepts/...
|
|
```
|
|
|
|
---
|
|
|
|
## 작업 흐름 5단계
|
|
|
|
```
|
|
① 캡처 /daily · /branch → raw/ 에 빈 노트
|
|
② 근거 조사 URL → 근거 자료 저장 → raw/official-docs · company-tech-blogs
|
|
③ 노트 채움 /branch-spec → 자동 /depth → 되묻지 않을 수준의 branch-note
|
|
④ wiki 승급 /ingest → wiki/concepts · projects (canonical)
|
|
⑤ 외부 산출물 /interviewize · /blogify → wiki/interview · blog · portfolio
|
|
```
|
|
|
|
1. **캡처** — 하루는 `/daily` 로, 새 작업은 `/branch <slug>` 로 시작합니다. 슬러그는 *무엇을 구현하는지* 를 영문 kebab-case 4~8단어로 적습니다(`feature-`, `fix-`, `chore-`, `experiment-` 중 하나로 시작). 번호 계층(`-1`, `-2`)은 쓰지 않습니다.
|
|
2. **근거 조사** — 공식 문서·대기업 블로그 URL 을 저장하면 원문에서 핵심 인용을 그대로(verbatim) 발췌합니다. 실제 존재하는지 `grep` 으로 검증한 뒤 `raw/` 에 보관합니다. 각 자료에는 `Claims Extracted` 표(Claim ID 가 붙은 사실 목록)가 있습니다.
|
|
3. **노트 채움** — `/branch-spec` 이 source 의 Claim 에서 결정과 대안을 채우고 근거가 없으면 먼저 자동으로 공식 문서·대기업 블로그를 조사합니다. 그래도 없으면 추측 대신 `UNSUPPORTED_DECISION` 으로 표시합니다. 마지막에 `/depth` 가 자동으로 돌아 **Ready / Not ready** 를 판정합니다. Ready 일 때 코딩을 시작하면 구현 중 되묻을 일이 없습니다.
|
|
4. **wiki 승급** — 구현이 끝나면 `status_label` 을 `review` 나 `merged` 로 올립니다. 그 뒤 `/ingest` 를 실행하면 검증된(`actually-implemented` 이상) 결과만 `wiki/projects/` 로 추출됩니다.
|
|
5. **외부 산출물** — canonical 문서가 `reviewed` 이상이면 `/interviewize`·`/blogify` 로 면접 답변·블로그 초안을 만듭니다. 본문 문체는 [rules/prose-style.md](rules/prose-style.md) 를 따릅니다(존댓말, 적당히 긴 길이, 개발 용어만 영어).
|
|
|
|
---
|
|
|
|
## 디렉토리 구조
|
|
|
|
| 위치 | 역할 |
|
|
|---|---|
|
|
| `CLAUDE.md` | 운영 규칙 SSOT (전체 정의) |
|
|
| `raw/` | 가공 전 원본 자료. 출처 보존. 영구 보관 |
|
|
| `wiki/` | 정리된 재사용 가능 지식 (canonical + derived) |
|
|
| `rules/` | 방법론 규칙 (linking, naming, tag, depth, prose-style 등) |
|
|
| `templates/` | 문서 카테고리별 출력 형식 |
|
|
| `docs/` | 설계 기록 등 메타 문서 |
|
|
|
|
`raw/` 하위: `branch-notes` · `daily-notes` · `official-docs` · `company-tech-blogs` · `project-notes` · `errors` · `interviews` · `job-postings` · `blog-topics` · `lectures` · `daily-tasks` · `diagrams`
|
|
|
|
`wiki/` 하위: `concepts` · `projects` (canonical) / `interview` · `blog` · `portfolio` (derived) / `llm-wiki.md`(vault MOC) · `log.md`
|
|
|
|
---
|
|
|
|
## 명령어 한눈에
|
|
|
|
| 그룹 | 명령 | 용도 |
|
|
|---|---|---|
|
|
| **캡처** | `/daily` | 오늘 일일 노트 생성 |
|
|
| | `/branch <slug>` | 빈 branch-note 스캐폴드 |
|
|
| | `/branch-spec <slug>` | branch-note 채움 + 자동 조사 + 자동 `/depth` |
|
|
| **변환·품질** | `/ingest <raw 경로>` | raw → `wiki/concepts`·`wiki/projects` |
|
|
| | `/depth <slug>` | branch-note 가 코딩 착수해도 될 만큼 깊은지 판정 |
|
|
| | `/tag` | wiki 문서 태그 보정 |
|
|
| | `/lint [--fix-plan]` | 품질 검사 (과장·출처·stale). `--fix-plan` 은 수정 계획 |
|
|
| | `/query` | wiki 기반 질의응답 |
|
|
| **출력** | `/projectize` | 개념 → 내 프로젝트 적용 문서 |
|
|
| | `/interviewize` | canonical → 면접 답변 |
|
|
| | `/blogify` | canonical → 블로그 초안 |
|
|
|
|
---
|
|
|
|
## 자동 안전장치 (저장할 때마다 자동 실행)
|
|
|
|
직접 신경 쓰지 않아도 다음이 자동으로 동작합니다.
|
|
|
|
- **저장 전 차단** — 근거 구조(Claims Extracted, Decision Evidence Map)를 우회하는 저장을 막습니다.
|
|
- **저장 후 검사** — 깨진 link 는 항상 경고합니다. 섹션 누락·빈 선택조건 같은 *완성도* 검사는 문서를 `review`·`merged` 로 완성 선언했을 때만 하므로 작성 중에는 방해하지 않습니다.
|
|
|
|
전체 검사는 언제든 직접 돌릴 수 있습니다.
|
|
|
|
```bash
|
|
python3 .claude/hooks/wiki_structure_lint.py --all # 전체 구조·링크 검사
|
|
python3 .claude/hooks/wiki_structure_lint.py --file <경로>
|
|
```
|
|
|
|
---
|
|
|
|
## 꼭 지켜야 하는 규칙 (요약)
|
|
|
|
- 출처 없는 단정 금지. 결정은 Claim ID 로 뒷받침하거나 `UNSUPPORTED_DECISION` 으로 표시합니다.
|
|
- 공식 문서와 기술 블로그를 혼동하지 않습니다(블로그는 사례이지 공식 best practice 가 아닙니다).
|
|
- `documented-only`·`planned`·`needs-confirmation` 은 외부 산출물에 절대 쓰지 않습니다.
|
|
- 외부 산출물은 canonical 을 거쳐서만 만듭니다.
|
|
- 외부 URL 은 링크만 두지 말고 핵심 인용 3~5문장을 `raw/` 본문에 발췌 보존합니다.
|
|
|
|
전체 규칙과 그 이유는 [CLAUDE.md](CLAUDE.md) 와 `rules/` 폴더를 보시면 됩니다. 자동화 설계 배경은 `docs/superpowers/specs/` 에 기록되어 있습니다.
|
|
</content>
|