# Plan - DOCS ## 이 파일을 읽는 구현 에이전트에게 문서/config/test-rule 정리 뒤 `CODE_REVIEW-local-G04.md`를 채운다. secret, token, private endpoint 원문은 tracked 파일에 남기지 않는다. ## 배경 SDD S06은 dev-runtime guide와 config 예시에서 Mac CLI resource와 MLX vLLM provider resource가 `providers[]` 한 곳에 나열되고, `adapters` 중복 선언을 기본 경로로 요구하지 않는 상태를 요구한다. ## 사용자 리뷰 요청 흐름 사용자 리뷰는 Milestone lock 결정만 파일에 기록한다. 환경값 누락은 blocker/evidence gap으로 기록한다. ## Roadmap Targets - Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md` - Task ids: - `dev-runtime-docs`: provider-first dev-runtime inventory, config examples, guide, test rules - Completion mode: check-on-pass ## 분석 결과 ### 읽은 파일 - `agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md` - `configs/edge.yaml` - `docs/edge-local-dev-guide.md` - `agent-test/local/rules.md` - `agent-test/local/edge-smoke.md` - `agent-test/local/node-smoke.md` - `agent-test/local/platform-common-smoke.md` - `agent-test/local/testing-smoke.md` ### SDD 기준 대상 Acceptance Scenario는 S06이다. Evidence Map은 docs/inventory/stale-reference check를 요구한다. tracked docs는 최신 사람용 guide만 담고 환경값/secret은 남기지 않는다. ### 테스트 환경 규칙 `test_env=local`. docs/config 정리이므로 `rg --sort path` stale-reference check와 `go test ./packages/go/config` config example coverage를 사용한다. ### 테스트 커버리지 공백 `configs/edge.yaml:63` 이후 `model_routes`와 `nodes[].adapters` 중심 설명이 기본 경로처럼 길게 남아 있다. guide도 provider-first default와 legacy compat의 경계가 불충분하다. ### 심볼 참조 rename/remove 없음. ### 분할 판단 `05+01_dev_runtime_docs`는 schema source 완료 뒤 실행하는 문서/config/test-rule 정리 task다. compile/compat와는 병렬 가능하지만 final schema 없이 문서가 흔들리지 않도록 `01_schema_source`를 선행 조건으로 둔다. full-cycle smoke evidence는 `06+04,05_full_cycle_smoke`로 분리한다. ### 범위 결정 근거 실제 dev-runtime deployment 변경과 원격 smoke 실행은 제외한다. 이 plan은 tracked 예시/가이드/test rule 정합성만 다룬다. ### 빌드 등급 `local-G04`: 문서와 예시 중심이며 stale-reference check로 검증 가능하다. ## 의존 관계 및 구현 순서 이 subtask는 디렉터리명 `05+01_dev_runtime_docs`에 따라 같은 task group의 `01_schema_source`가 `complete.log`를 만든 뒤 구현한다. ## 구현 체크리스트 - [ ] `configs/edge.yaml`을 provider-first 예시 중심으로 재정렬하고 legacy `adapters`/`model_routes`는 compat 섹션으로 낮춘다. - [ ] `docs/edge-local-dev-guide.md`가 provider-first config, config check, refresh 기준을 안내하도록 갱신한다. - [ ] `agent-test/local/*smoke.md`의 provider pool/dev-runtime 기준 문구가 provider-first source of truth와 맞는지 정리한다. - [ ] `rg --sort path "model_routes|nodes\\[\\]\\.adapters|adapter:" configs docs agent-test/local` 결과에서 남은 legacy reference가 의도적 compat 설명인지 확인한다. - [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. ### [DOCS-1] Provider-First Examples And Stale References #### 문제 `configs/edge.yaml:63`부터 legacy route catalog 설명이 길고, `configs/edge.yaml:193`의 node 예시는 `adapters`를 기본처럼 보여준다. SDD는 provider-first를 기본 경로로 요구한다. #### 해결 방법 첫 예시를 `models[]` + `nodes[].providers[]`로 바꾸고 provider type별 필드를 한 resource 안에 넣는다. legacy `adapters`와 `model_routes`는 "compat only" heading 아래로 내려 stale reference check에서 의도적 예외로 분류 가능하게 만든다. #### 수정 파일 및 체크리스트 - [ ] `configs/edge.yaml`: provider-first default example. - [ ] `docs/edge-local-dev-guide.md`: dev-runtime provider-first workflow. - [ ] `agent-test/local/edge-smoke.md`: dev-runtime provider pool 기준 문구. - [ ] `agent-test/local/platform-common-smoke.md`: config contract check 문구. #### 테스트 작성 코드 테스트는 추가하지 않는다. 문서/config 정리이며 stale-reference check와 config loader test를 사용한다. #### 중간 검증 ```bash rg --sort path "model_routes|nodes\\[\\]\\.adapters|adapter:" configs docs agent-test/local ``` 기대 결과: 남은 항목은 legacy/compat 설명 또는 OpenAI-compatible surface adapter 필드처럼 의도된 경계로 설명 가능해야 한다. ## 수정 파일 요약 | 파일 | 항목 | |------|------| | `configs/edge.yaml` | DOCS-1 | | `docs/edge-local-dev-guide.md` | DOCS-1 | | `agent-test/local/edge-smoke.md` | DOCS-1 | | `agent-test/local/platform-common-smoke.md` | DOCS-1 | ## 최종 검증 ```bash rg --sort path "model_routes|nodes\\[\\]\\.adapters|adapter:" configs docs agent-test/local ``` ```bash go test ./packages/go/config ``` Go test cache output is acceptable for package test unless config fixtures changed in a way that requires fresh rerun. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.