120 lines
5.2 KiB
Markdown
120 lines
5.2 KiB
Markdown
---
|
|
description: "기존 raw/source/branch/wiki 문서를 Claim ID 기반 template 구조로 단계적 마이그레이션"
|
|
---
|
|
|
|
사용자가 `/migrate-claims <scope: all | raw-sources | branch-notes | wiki-concepts | path>` 를 입력하면 아래 절차를 수행한다.
|
|
|
|
기존 문서를 Claim Traceability 구조로 마이그레이션합니다.
|
|
|
|
**대상:** <scope: all | raw-sources | branch-notes | wiki-concepts | path>
|
|
|
|
## 원칙
|
|
|
|
이 명령은 좋은 마이그레이션 순서를 강제합니다. branch-note를 먼저 고치지 않습니다. 먼저 source claim을 만들고, 그 다음 branch decision을 연결하고, 마지막에 wiki FACT를 승격합니다.
|
|
|
|
## Phase 0 — Scope Inventory
|
|
|
|
1. 대상 scope를 확정합니다.
|
|
- `all`: `raw/official-docs/`, `raw/company-tech-blogs/`, `raw/branch-notes/`, `wiki/concepts/`
|
|
- `raw-sources`: `raw/official-docs/`, `raw/company-tech-blogs/`
|
|
- `branch-notes`: `raw/branch-notes/`
|
|
- `wiki-concepts`: `wiki/concepts/`
|
|
- 특정 path: 해당 파일 또는 디렉터리
|
|
2. 파일 목록을 정렬합니다.
|
|
3. Evidence Matrix를 먼저 만듭니다.
|
|
4. 10개 초과 파일이면 `wiki-research-lane` 또는 병렬 subagent slice로 나눕니다.
|
|
|
|
## Phase 1 — Raw Source Claim Migration
|
|
|
|
대상: `raw/official-docs/`, `raw/company-tech-blogs/`
|
|
|
|
각 파일에 대해:
|
|
|
|
1. 기존 본문을 삭제하지 않습니다.
|
|
2. `templates/raw-source-template.md`를 기준으로 누락 섹션만 보강합니다.
|
|
3. `## 핵심 인용` 또는 기존 quote/summary를 읽고 `## Claims Extracted`를 작성합니다.
|
|
4. Claim ID를 안정적으로 부여합니다.
|
|
- 형식: `<SOURCE-SLUG-UPPER>-C<number>`
|
|
- 예: `KEYCLOAK-OIDC-C1`, `STRIPE-IDEMP-C2`
|
|
5. `Strength`를 보수적으로 지정합니다.
|
|
- official docs: `official-standard`, `official-vendor-doc`, `official-reference`
|
|
- company blog: 기본 `company-case-study`
|
|
- 불확실하면 `needs-confirmation`
|
|
6. `Does not prove`와 `Usage Boundaries`를 반드시 채웁니다.
|
|
7. 원문 quote가 있으면 `grep -nF` 또는 `sed -n` proof를 남깁니다.
|
|
|
|
완료 조건:
|
|
|
|
- 모든 source 문서에 `## Claims Extracted` 존재
|
|
- 모든 Claim row에 `Claim ID`, `Claim`, `Evidence quote`, `Strength`, `Applies to`, `Does not prove` 존재
|
|
- 회사 블로그 Claim을 공식 best practice로 승격하지 않음
|
|
|
|
## Phase 2 — Branch Decision Mapping
|
|
|
|
대상: `raw/branch-notes/`
|
|
|
|
Phase 1이 끝나지 않았으면 BLOCKED입니다. branch-note는 source Claim ID 없이는 정상 마이그레이션할 수 없습니다.
|
|
|
|
각 파일에 대해:
|
|
|
|
1. 기존 `## 결정 사항`, `## Sources / 근거`, `완료 후 정리`를 읽습니다.
|
|
2. 중요한 구현 결정을 `Decision ID`로 분리합니다.
|
|
- 형식: `D<number>` 또는 `<BRANCH-SLUG-UPPER>-D<number>`
|
|
3. `## Decision Evidence Map`에 결정별 Supporting Claims를 연결합니다.
|
|
4. 연결 가능한 Claim이 없으면 추측하지 않고 `UNSUPPORTED_DECISION`으로 둡니다.
|
|
5. 확인해야 할 내용은 `## Claims To Verify`에 남깁니다.
|
|
|
|
완료 조건:
|
|
|
|
- 모든 branch-note에 `## Decision Evidence Map` 존재
|
|
- 모든 중요한 decision은 Claim ID 또는 `UNSUPPORTED_DECISION`으로 분류
|
|
- 존재하지 않는 Claim ID 참조 없음 (`BROKEN_CLAIM_REFERENCE` 0)
|
|
|
|
## Phase 3 — Wiki Concept / Project Promotion Check
|
|
|
|
대상: `wiki/concepts/`, 필요 시 `wiki/projects/`
|
|
|
|
1. `## Claim-backed Knowledge`를 추가합니다.
|
|
2. source Claim 또는 branch Decision으로 뒷받침되는 내용만 `FACT`로 둡니다.
|
|
3. 근거가 약한 설명은 `INFERENCE`, `needs-confirmation`으로 낮춥니다.
|
|
4. 회사 기술 블로그 단독 근거는 case-study로 표현합니다.
|
|
|
|
완료 조건:
|
|
|
|
- wiki FACT는 Supporting Claims를 가짐
|
|
- unsupported decision이 wiki FACT로 승격되지 않음
|
|
|
|
## Phase 4 — Controller Verification
|
|
|
|
최종 보고 전 다음을 기계적으로 계측합니다.
|
|
|
|
```bash
|
|
find raw/official-docs raw/company-tech-blogs -maxdepth 1 -type f -name '*.md' | sort
|
|
# 미마이그레이션 파일 목록 (주의: rg 의 -L 은 --follow 다 — files-without-match 는 긴 플래그만 존재)
|
|
rg --files-without-match '^## Claims Extracted' raw/official-docs raw/company-tech-blogs
|
|
rg --files-without-match '^## Decision Evidence Map' raw/branch-notes
|
|
rg -n 'UNSUPPORTED_DECISION|BROKEN_CLAIM_REFERENCE|MISSING_CLAIMS_EXTRACTED' raw wiki docs
|
|
```
|
|
|
|
보고서에는 반드시 다음을 포함합니다.
|
|
|
|
| Metric | Expected | Actual | Status |
|
|
|---|---:|---:|---|
|
|
| Raw source files with Claims Extracted | N | M | PASS/FAIL |
|
|
| Branch notes with Decision Evidence Map | N | M | PASS/FAIL |
|
|
| Broken Claim references | 0 | B | PASS/FAIL |
|
|
| Unsupported decisions | report count | U | INFO |
|
|
|
|
## Verdict Rules
|
|
|
|
- `COMPLETE`: Phase 1~4 완료, missing required sections 0, broken references 0
|
|
- `PARTIAL`: 지정 scope 내부는 완료했지만 전체 corpus가 아님
|
|
- `BLOCKED`: source Claim migration 없이 branch-note mapping을 시도했거나, unread files가 있음
|
|
|
|
## 금지
|
|
|
|
- source Claim 없이 branch decision을 임의로 official-supported 처리 금지
|
|
- 회사 기술 블로그만 보고 universal best practice라고 작성 금지
|
|
- 기존 본문 삭제/요약으로 손실 발생 금지
|
|
- 여러 파일을 처리하면서 Evidence Matrix 없이 완료 보고 금지
|