SK-Intellix Document Migration Roadmap
이 문서는 현재 docs/a2a/에 몰려 있는 상세 문서를 장기적으로 어떻게 분리할지 정리한다.
현재는 링크 안정성을 위해 파일을 바로 이동하지 않는다. 대신 문서의 논리 소유 카테고리를 먼저 정하고, evidence가 쌓인 뒤 단계적으로 이동한다.
1. 왜 바로 이동하지 않는가
| 이유 | 설명 |
|---|---|
| URL 안정성 | 이미 브라우저/문서/대화에서 docs/a2a/*.html 링크를 많이 사용 중 |
| SVG 참조 | markdown과 SVG 상대경로가 많아 대량 이동 시 깨질 수 있음 |
| 검증 비용 | 이동 후 모든 링크/이미지/검색 인덱스를 다시 확인해야 함 |
| 소유권 미확정 | 일부 문서는 A2A, On-device, DeviceAgent 경계에 걸쳐 있음 |
| 실기기 evidence 미수집 | ADB/업체 evidence가 들어오면 문서 구조가 바뀔 수 있음 |
2. 목표 디렉터리 구조
최종적으로는 아래 구조를 지향한다.
docs/sk-intellix/
index.md
book-shelf.md
category-map.md
source-evidence-catalog.md
docs/a2a/
Cloud planner/runtime 중심 상세 문서
docs/speech/
STT, dictionary, on-device/cloud LLM, TTS, E2E operation
docs/speaker-identity/
speaker enrollment, diarization, speaker_context, authority, speaker memory
docs/ondevice/
Bridge, ForegroundService, DeviceCommunicator, bundle, notification, callback relay
docs/deviceagent/
TaskManager, executor, reason code, planning context, domain binding
docs/framework-sdk/
DeviceAgent API/runtime, DeviceControlAPI, SDK candidate
docs/aosp-bsp/
QSSI/UM split build, platform vendor overlay, vendor HAL/service, init/VINTF/sepolicy, DTS/driver
docs/memory/
memory hierarchy, DB schema, sync, privacy, deletion
docs/vendor/
handoff package, acceptance checklist, evidence template, open questions
docs/validation/
benchmark, dry-run, ADB, logcat, traceability, release gate
docs/operations/
llmwiki, Codex global rule, local server, build/lint
3. 현재 문서별 논리 소유권
전체 문서의 최신 primary domain, related domain, 권장 이동 위치는 Domain Document Map을 기준으로 본다. 아래 표는 초기 migration 후보이며, 새 도메인 축이 추가된 뒤에는 Domain Document Map을 우선한다.
| 현재 문서 | 논리 카테고리 | 이동 후보 |
|---|---|---|
book-roadmap.md |
A2A | 유지 |
planner-routing.md |
A2A | 유지 |
benchmark-router.md |
A2A, Validation | docs/validation/ 복제/요약 후보 |
voice-taskmanager-closed-loop.md |
A2A, On-device, DeviceAgent | Cloud·On-device·TaskManager 폐루프 정본 |
contracts.md |
On-device, A2A, DeviceAgent | docs/ondevice/ 후보 |
scenario-walkthroughs.md |
A2A, On-device | docs/ondevice/ 후보 |
deviceagent-taskmanager-api-contract.md |
DeviceAgent, Vendor | docs/deviceagent/ 후보 |
taskmanager-complete-specification.md |
DeviceAgent/SoC | TaskManager 규범 정본 |
deviceagent-soc-domain-map.md |
DeviceAgent/SoC | docs/deviceagent/ 후보 |
source-level-implementation-guide.md |
DeviceAgent/SoC | 구현·executor wiring 정본 |
taskmanager-llm-mcp-mapping-wiki.md |
A2A, DeviceAgent | cross-domain 후보 |
legacy-command-19-workflow-example.md |
ComeToMe case | docs/cases/ 또는 docs/deviceagent/ 후보 |
cometome-deviceagent-contract.md |
ComeToMe, DeviceAgent, Vendor | docs/deviceagent/ 또는 docs/vendor/ 후보 |
memory-personalization.md |
Memory | docs/memory/ 후보 |
memory-db-sync.md |
Memory | docs/memory/ 후보 |
vendor-handoff.md |
Vendor | docs/vendor/ 후보 |
vendor-implementation-package.md |
Vendor | docs/vendor/ 후보 |
vendor-api-acceptance-checklist.md |
Vendor, Validation | docs/vendor/ 후보 |
vendor-test-evidence-template.md |
Vendor, Validation | docs/vendor/ 후보 |
vendor-open-questions.md |
Vendor | docs/vendor/ 후보 |
validation.md |
Validation | docs/validation/ 후보 |
evidence-index.md |
Validation | docs/validation/ 후보 |
requirements-traceability.md |
Validation | docs/validation/ 후보 |
status-gap-audit.md |
Validation | docs/validation/ 후보 |
documentation-quality-audit.md |
Operations, Validation | docs/operations/ 후보 |
global-wiki-operations.md |
Operations | docs/operations/ 후보 |
local-access.md |
Operations | docs/operations/ 후보 |
4. 단계별 migration 계획
Phase 0: 현재 완료
| 작업 | 상태 |
|---|---|
| SK-Intellix 최상위 허브 생성 | 완료 |
| 카테고리 landing page 생성 | 완료 |
| Source/Evidence Catalog 생성 | 완료 |
| Book Shelf 생성 | 완료 |
| 기존 A2A URL 유지 | 완료 |
Phase 1: Backlink 보강
각 기존 docs/a2a/*.md 상단 또는 하단에 다음을 추가한다.
상위 카테고리: SK-Intellix > DeviceAgent / SoC
관련 카테고리: Vendor, Validation
이 단계는 파일 이동 없이 독자 동선을 개선한다.
Phase 2: Shadow index 생성
실제 파일 이동 전에 docs/speech/index.md, docs/speaker-identity/index.md, docs/ondevice/index.md, docs/deviceagent/index.md, docs/aosp-bsp/index.md, docs/memory/index.md, docs/vendor/index.md 등을 만들고 기존 문서를 링크한다.
이 단계도 기존 URL은 그대로 둔다.
Phase 3: 선택적 파일 이동
다음 조건을 만족할 때만 실제 파일 이동을 한다.
1. 이동 대상 문서의 상위 카테고리가 확정됨
2. 내부 링크/이미지 상대경로 수정 가능
3. llmwiki build/lint 통과
4. 주요 old/new URL redirect 또는 안내 링크 제공
5. 사용자/업체 공유 링크 영향 확인
Phase 4: Evidence-driven 재정리
ADB/실기기/업체 evidence가 들어온 뒤 문서 구조를 한 번 더 정리한다.
5. 지금 당장 하지 말아야 할 것
- 기존
docs/a2a/파일을 한 번에 대량 이동하지 않는다. - source 근거가 확인되지 않은 구현 파일명을 확정 문서처럼 쓰지 않는다.
- build/lint 없이 링크 구조를 바꾸지 않는다.
- ADB/업체 evidence 없이 “통합 완료”라고 쓰지 않는다.