docs(agents): 스킬 선택과 오케스트레이션 규칙을 정리한다

docs/20261019_스킬오케스트레이션/audit.md

@@ -0,0 +1,164 @@
+# Skill orchestration 근거 감사
+
+## 범위와 판정
+
+읽기 전용 조사 기준일은 2026-10-19다. 설치, 설정 등록, host discovery, skill 선택 metadata, 실제 모델 invocation은 서로 다른 사실이다. 조사에서 확인한 설치 상태만 기록하며 자동 invocation 성공을 테스트했다고 주장하지 않는다.
+
+## 저장소 및 지침 baseline
+
+| 항목 | 관찰 증거 |
+|---|---|
+| cwd / git root | `/Users/klaus/Develop/sodalive/Server/sodalive_` (동일) |
+| baseline HEAD | `bf252795ed9efb9362d273c58dc7f573ba9351a4` |
+| 루트 `AGENTS.md` SHA-256 | `eb99f0fa50609aa6cad7c03a546bfffc6da981348b7ee5cf59b48628e6c40331` |
+| 루트 `AGENTS.md` 크기 | 5,608 bytes, 122 lines |
+| baseline worktree | clean, branch `test`가 `origin/test`보다 3 commit 앞서 있음 |
+| 계층 조사 | `/`, `/Users`, `/Users/klaus`, `/Users/klaus/Develop`, `/Users/klaus/Develop/sodalive`, `/Users/klaus/Develop/sodalive/Server`에 추가 AGENTS/override/CLAUDE 지침 없음. 저장소에는 루트 AGENTS만 있고 child/override/CLAUDE, `opencode.json/jsonc`, `.opencode` 설정이 없었음. |
+| 전역 지침 조사 | `~/.codex/AGENTS.md`, `~/.codex/AGENTS.override.md`, `~/.config/opencode/AGENTS.md`, `~/.claude/CLAUDE.md` 없음. 조사된 범위 한정. |
+
+루트 `AGENTS.md`의 CORE/충돌 규칙은 lines 8-78, 한국어 보고는 80-83, 프로젝트 가이드와 공개 API 경계는 92-102, PRD/plan 선행 규칙은 104-107, issue/domain docs 안내는 114-122다. 요청 문서인 `docs/agent-guides/작업절차.md`, `문서유지보수.md`, `docs/sample/sample-prd.md`, `sample-plan-task.md`도 읽었다. 기존 문서 절차는 구현 전 PRD와 plan, goal/phase gate, TDD 또는 문서 작업의 대체 검증, focused test 우선과 실행 결과 기록을 이미 규정한다. 새 정책은 이를 대체하지 않는다.
+
+기존 routing baseline은 작업 유형별 stage 선택, 중복 책임, implicit invocation 제약을 루트에서 연결하지 않는 문서 공백이다. 이는 runtime 실패 판정이 아니다. 가이드의 Markdown 참조가 자동으로 instruction에 import된다고 간주하지 않는다. 루트 `AGENTS.md`의 경로 안내 오기 `.../sodalive` 대 실제 `.../sodalive_`는 관찰 사실이며 이번 요청의 변경 범위가 아니므로 수정하지 않는다.
+
+## Host/설정 계층과 범위
+
+설치 조사에서 확인한 host는 Codex `0.163.0`, OpenCode `1.19.3`이다. `CODEX_HOME`, `XDG_CONFIG_HOME`은 조사 환경에서 설정되지 않았다. 실제 실행 시 CLI arguments/profile은 미확인이다.
+
+| 경로/집합 | 범위 판정 및 확인 내용 |
+|---|---|
+| `~/.codex/config.toml` | trusted project, model/approval/sandbox 설정은 관찰됐으나 skill routing permission과 혼동하지 않는다. multi_agent/plugins 및 `omo@sisyphuslabs` 사용 설정 확인. 명시적 Superpowers enabled 항목, `skills.config` disable/policy override, project doc budget/fallback/instruction override는 관찰되지 않았다. |
+| `~/.codex/agents/*.toml` | 13개 role별 TOML 경로가 확인됐다. 대표 경로 `default.toml`, `explorer.toml`, `plan.toml`, `librarian.toml`, `metis.toml`, `momus.toml`, `lazycodex-code-reviewer.toml`, `lazycodex-gate-reviewer.toml`. 이들은 전역 repo 우선순위가 아니라 해당 subagent 역할 지침이다. 후자의 두 reviewer role은 `remove-ai-slops`/`programming`을 role 내부에서만 언급한다. |
+| `~/.config/opencode/opencode.json` | Superpowers, Ponytail, OMO plugin 선언 확인. 명시적 instructions/skills/permission 설정은 관찰되지 않았다. |
+| `~/.config/opencode/agents/` 및 `oh-my-openagent` | 전역 agents 폴더는 비어 있음. OMO 디렉터리의 `native-nudge.json`은 state이며 universal instructions가 아니다. |
+| repo `.agents/skills`, `.opencode/skills` | `.agents/skills`는 비어 있고 `.opencode/skills`는 없다. `.opencode/` 자체는 존재하며 package 메타데이터와 node_modules만 있고 활성 지침/설정은 없다. |
+| `~/.codex/skills` | `.system`만 있음. 이는 plain `system` 이름의 skill과 다르다. |
+| `/etc/codex` | 경로 없음. |
+| `~/.claude/skills` | 없음. `~/.config/opencode/skills/commit-with-validation`은 별도 user skill이며 이번 routing catalog와 혼동하지 않는다. |
+
+Codex role별 TOML은 repo/global instruction hierarchy에 속하지 않는 role-specific guidance다. 전역 설정 파일이 있다는 사실도 skill을 자동 실행한다는 보장이 아니다.
+
+## 공식 문서 및 참조
+
+다음 문서/저장소 주소를 조사 근거로 사용했다. host 동작은 설치 버전과 문서 버전을 구분한다.
+
+- Codex AGENTS: <https://learn.chatgpt.com/docs/agent-configuration/agents-md>
+- Codex skills: <https://learn.chatgpt.com/docs/build-skills.md>
+- OpenCode rules: <https://opencode.ai/docs/rules/>
+- OpenCode skills: <https://opencode.ai/docs/skills/>
+- Superpowers: <https://github.com/obra/superpowers>
+- Matt Pocock skills: <https://github.com/mattpocock/skills>
+- Addy Osmani skills: <https://github.com/addyosmani/agent-skills>
+- Addy upstream skills index: <https://github.com/addyosmani/agent-skills/blob/main/README.md>
+
+Codex AGENTS 문서는 global override/fallback, repo-root→cwd 지침 계층과 32 KiB 기본 예산을 설명한다. OpenCode rules v1은 cwd 상위 탐색과 instruction 결합을 설명하며 v2 문서를 설치된 v1.19.3에 혼합하지 않는다. Codex skills는 `agents/openai.yaml`의 `policy.allow_implicit_invocation: false` 및 skills 설정을 설명한다. OpenCode skills 문서의 key 표기는 `metadata["opencode/autoinvoke"]`다. OpenCode v1 공식 문서는 Codex식 top-level `disable-model-invocation` 호환을 약속하지 않는다. 명시적 요청 의도는 host가 같은 통제를 보장한다고 추정하지 않고 루트 routing에서도 존중한다.
+
+Codex는 전역에서 비어 있지 않은 `AGENTS.override.md`를 먼저 선택하고 없으면 `AGENTS.md`를 사용한다.
+프로젝트는 Git root부터 cwd까지 디렉터리마다 override, AGENTS, 설정된 fallback 순으로 최대 한 파일을 선택한다.
+루트에서 하위 방향으로 결합하며 더 가까운 지침이 앞선 지침을 구체화한다.
+OpenCode v1은 cwd에서 상위로 로컬 AGENTS/CLAUDE를 찾고 같은 범주에서는 먼저 일치한 파일을 선택한다.
+전역 AGENTS가 없으면 Claude 전역 지침으로 fallback하며, 설정의 `instructions`는 발견한 지침과 결합한다.
+OpenCode v1 문서는 `AGENTS.override.md` 지원을 명시하지 않는다. 이 파일 발견 규칙은 아래 스킬의 단계별 책임 순서와 별개다.
+
+## Superpowers 설치 및 역할
+
+경로 표기:
+
+- `SP=/Users/klaus/.cache/opencode/packages/superpowers@git+https:/github.com/obra/superpowers.git/node_modules/superpowers`
+- `CSP=/Users/klaus/.codex/plugins/cache/openai-curated-remote/superpowers/6.4.2`
+- `U=/Users/klaus/.agents/skills`
+
+OpenCode의 `SP/skills/<name>/SKILL.md`에서 확인된 실제 15개:
+
+1. `using-superpowers`
+2. `brainstorming`
+3. `writing-plans`
+4. `executing-plans`
+5. `subagent-driven-development`
+6. `dispatching-parallel-agents`
+7. `using-git-worktrees`
+8. `test-driven-development`
+9. `systematic-debugging`
+10. `requesting-code-review`
+11. `receiving-code-review`
+12. `verification-before-completion`
+13. `finishing-a-development-branch`
+14. `diagnosing-superpowers`
+15. `writing-skills`
+
+`deep-interview`는 별도 사용자 skill이며 이 15개 Superpowers 목록에 포함되지 않는다. Codex cache `CSP/skills/<name>/SKILL.md`에도 15개가 있으나 cache 존재는 plugin 활성/실제 호출을 증명하지 않는다. OpenCode plugin `.opencode/plugins/superpowers.js` lines 219-264는 `skills.paths` 등록, 첫 top-level 사용자 메시지에 `using-superpowers` 절차 주입, child session 제외를 수행한다. Codex에서 Superpowers 활성화/자동 invocation 성공은 미확인이다. OpenCode parent의 available skill catalog는 여러 skill을 노출하지만 CLI `debug skill`은 일부만 관찰됐다. 부분 listing으로 부재를 추정하지 않는다. OpenCode 복사본과 Codex 캐시 복사본은 동일하지 않으며 brainstorming/systematic-debugging/requesting-code-review 차이가 조사됐다.
+
+선택 원칙: 필요한 작업에서 `using-superpowers`가 이미 주입된 경우 같은 절차를 중복 로드하지 않는다. 새 설계는 brainstorming, 계획은 `writing-plans`, 실행은 `executing-plans` inline 또는 `subagent-driven-development` 중 하나, 구현 중 TDD, 필요 시 debugging, 요청된 리뷰, 완료 전 fresh verification 순으로 연결한다. `finishing-a-development-branch`는 통합 판단이 실제 필요할 때만 쓴다. worktree는 필요한지 확인하는 것과 자동 생성하는 것을 구분하며 자동 commit은 없다. runtime tool/skill permission은 계속 우선한다.
+
+## 사용자 영역 skill 목록과 메타데이터
+
+### Matt Pocock set
+
+| 정확한 경로 | 책임/선택 | 발견된 invocation metadata |
+|---|---|---|
+| `U/domain-modeling/SKILL.md` | domain terminology, `GLOSSARY.md`, ADR 기록/수정. | `agents/openai.yaml` display metadata만, policy block 없음. |
+| `U/codebase-design/SKILL.md` | module/interface 경계, deepening/seam 설계 어휘. | display metadata만, policy block 없음. |
+| `U/grilling/SKILL.md` | plan/idea/decision을 충분히 구체화한 뒤 선택지를 stress-test하는 질문. | SKILL frontmatter에 `name`, `description`만. `agents/openai.yaml`은 display metadata만. disable/policy invocation 제한 없음. |
+| `U/improve-codebase-architecture/SKILL.md` | architecture 후보를 시각 보고서로 제시, 후보 선택 뒤 정해진 후속 흐름. | `disable-model-invocation: true`와 `agents/openai.yaml`의 `policy.allow_implicit_invocation: false`. explicit 요청 없이 자동 선택 금지. |
+| `U/setup-matt-pocock-skills/SKILL.md` | 해당 engineering skill set 초기 설정. setup 완료 상태. | `disable-model-invocation: true`와 `policy.allow_implicit_invocation: false`. explicit 요청 없이 재실행 금지. |
+
+정확한 경로는 위 표의 `U=/Users/klaus/.agents/skills` 치환이다. `grilling`의 일반 언어 요청 trigger는 stress-test plan/decision/idea이며 정확한 skill 이름을 요구하지 않는다. 다만 구조화된 인터뷰가 아니라 매 라운드에 정착된 전체 frontier를 질문하며 사용자의 응답을 기다리고, frontier가 비고 사용자가 확인할 때 끝난다. 이는 요구사항 discovery를 위한 단일 불확실성 질문 루프와 목적이 다르다.
+
+### `deep-interview` 상세 근거
+
+- 경로: `U/deep-interview/SKILL.md` (127 lines); 조사된 디렉터리에는 `SKILL.md`만 있다. Frontmatter는 `name`, `description`, `argument-hint`; `disable-model-invocation`, `agents/openai.yaml`, OpenCode autoinvoke metadata, file/tool-specific dependency가 발견되지 않았다.
+- Trigger: 모호한 goal/scope/constraints/success/context, 명시적인 deep-interview 또는 생각 정리 요청. 구체적이고 작은 수정/테스트 보강에서는 제외한다.
+- 순서: 기존 코드/근거로 답할 수 있으면 먼저 조사하고 사용자에게 반복 질문하지 않는다. 라운드마다 가장 큰 미해결 질문 하나를 묻고 답을 반영해 점수를 갱신한다.
+- Dimensions: Goal, Scope, Constraints, Success, Context 각 0..1. `Context`는 기존 코드베이스를 변경하는 경우에만 평가한다. 새 프로젝트 가중치는 `.35/.25/.15/.25`; 기존 코드베이스 작업 가중치는 `.30/.20/.15/.20/.15`다. 모호성은 1에서 가중 명확성 합을 뺀 판단 보조값이지 객관적인 측정값이 아니다.
+- 종료: ambiguity `<=.20`이고 중요한 unknown이 해결됐을 때 종료한다. 중요한 dimension이 `<=.50`이면 중요 미결점이 남아 라운드를 계속할 수 있다.
+- 출력: 최종 score, dimensions, decisions, open questions를 chat에 출력한다. 고정 산출 파일 작성이나 파일 변경은 요구되지 않는다.
+- 적용 한계: 정적 skill 경로상 host의 implicit invocation은 가능할 수 있지만 실제 Codex/OpenCode invocation은 테스트되지 않았다. 이 문서 작성 요청은 이미 명확하므로 이번 작업에서 skill을 실제 호출하지 않았다.
+
+brainstorming은 새로운 동작/선택의 제품 의도를 정리하는 기본 설계 단계다. deep-interview는 특히 모호한 요구사항에만 필요한 조건부 discovery 도구다. grilling은 충분히 정해진 선택지/결정을 압박 시험하는 user-triggered 다중 질문 절차다. 이 세 가지를 모든 작업마다 순차 실행하거나 동일한 단일 질문 인터뷰로 취급하지 않는다.
+
+### 추가 specialist 6개
+
+| 정확한 경로 | 선택 조건 | upstream 확인 경계 |
+|---|---|---|
+| `U/api-and-interface-design/SKILL.md` | 공개 API/module contract 변경, 호환성, 오류, boundary input. | Upstream 동일 이름 파일 확인: `https://github.com/addyosmani/agent-skills/blob/main/skills/api-and-interface-design/SKILL.md`. 이름 대응은 검증됐지만 local provenance/byte identity는 보장하지 않는다. |
+| `U/security-and-hardening/SKILL.md` | auth, sensitive data, external integrations, CORS, uploads, rate limit, elevated roles. | `https://github.com/addyosmani/agent-skills/blob/main/skills/security-and-hardening/SKILL.md`; 동일한 한계. |
+| `U/ci-cd-and-automation/SKILL.md` | CI/CD/build/deploy pipeline 자동화. | `https://github.com/addyosmani/agent-skills/blob/main/skills/ci-cd-and-automation/SKILL.md`; 동일한 한계. |
+| `U/observability-and-instrumentation/SKILL.md` | 운영 logging, metrics, tracing, alerting. | `https://github.com/addyosmani/agent-skills/blob/main/skills/observability-and-instrumentation/SKILL.md`; 동일한 한계. |
+| `U/performance-optimization/SKILL.md` | 성능 목표/측정 병목/명시 최적화. | `https://github.com/addyosmani/agent-skills/blob/main/skills/performance-optimization/SKILL.md`; 동일한 한계. |
+| `U/frontend-ui-engineering/SKILL.md` | 사용자 frontend UI/page/component. | `https://github.com/addyosmani/agent-skills/blob/main/skills/frontend-ui-engineering/SKILL.md`; 동일한 한계. |
+
+Addy README 및 `using-agent-skills` mapping에서 같은 이름이 확인됐다. 이는 upstream correspondence만 검증하며 로컬 설치 출처/byte identity는 증명하지 않는다. 위 여섯 로컬 skill에서 invocation 제한 metadata는 관찰되지 않았지만, host가 실제로 자동 호출한다는 보장은 아니다. 예시 specialist 선택은 기존 Kotlin/Spring naming, DTO, API contract를 대체하거나 rename하지 않는다.
+
+`U/deprecation-and-migration/SKILL.md`, `U/debugging-and-error-recovery/SKILL.md`는 존재하지 않는다. 이 참조를 active routing target으로 취급하지 않는다.
+
+## 중복 라우팅 판정: 여섯 쌍
+
+| 조합 | 겹치는 부분 | 고유 책임 | 선택 predicate / owner |
+|---|---|---|---|
+| `brainstorming` / `deep-interview` | 새 요구의 불확실성 정리. | brainstorming은 새 동작의 선택/설계; deep-interview는 모호한 목표·범위·수용기준의 인터뷰. | 설계 시작이 main; 요구 핵심이 불명확할 때만 deep-interview 먼저, 답 반영 후 brainstorming. |
+| `brainstorming` / `grilling` | 아이디어와 tradeoff를 다룰 수 있음. | brainstorming은 설계를 만들고 선택; grilling은 정착된 결정 frontier를 stress-test한다. | 새 설계에서 brainstorming owner; 사용자가 결정 스트레스테스트를 요청할 때만 grilling 추가. 정확 skill명 불필요. |
+| `brainstorming` / `codebase-design` | 설계 옵션을 분석할 수 있음. | brainstorming은 제품 동작/요구 선택; codebase-design은 구조적 seam/module boundary 평가. | 새 동작 설계 주체는 brainstorming; 구조 boundary가 요청/실질 이슈일 때 codebase-design 보조. |
+| `codebase-design` / `api-and-interface-design` | module/interface 경계와 계약. | codebase-design은 모듈 깊이/seam; API skill은 소비자-facing 계약, 호환성, request/response/error. | 구조 평가 owner는 codebase-design; 공개 contract 하위 작업이 있을 때 API specialist만 해당 하위 범위 owner. |
+| `requesting-code-review` / `security-and-hardening` | 위험과 결함 검토. | requesting-code-review는 리뷰 실행/완료 gate 프로세스; security skill은 threat model 및 보안 기준. | review delegation이 적용되면 단일 main review process, security는 criteria/specialist 보조. 같은 변경을 중복 full review하지 않고 자동 수정 금지. |
+| `systematic-debugging` / general exploration | 문제 원인 조사. | debugging은 재현된 실패의 hypothesis/causal test loop; general exploration은 요청된 read-only code understanding. | 재현 가능한 오류/실패가 main이면 systematic-debugging; 광범위한 이해 질문만 있으면 일반 조사, 무관한 debugging 절차를 붙이지 않음. |
+
+## checklist 결손과 sign-off
+
+- 다음 네 공유 문서는 모두 없다: `/Users/klaus/.agents/references/security-checklist.md`, `/Users/klaus/.agents/references/accessibility-checklist.md`, `/Users/klaus/.agents/references/performance-checklist.md`, `/Users/klaus/.agents/references/observability-checklist.md`.
+- `U/security-and-hardening/references/`에는 `hardening-patterns.md`만 있다.
+- 전역 파일을 생성/수정하거나 설치하지 않는다. 해당 checklist가 필요한 audit/sign-off는 그 참조 부분에 대해 완전하다고 주장하지 않고 결손을 보고한다. 확인 가능한 자체 코드/skill guidance 검토는 별도로 수행할 수 있지만 누락된 기준을 대체한다고 주장하지 않는다.
+
+## 후속 루트 정책의 제한 영역
+
+루트 요약은 Skill Orchestration, Skill Priority and Selection, Requirements Discovery, Skill Routing by Task Type, Conflict and Duplication Resolution, Automatic Invocation Constraints, Verification and Completion의 7개 주제를 짧게 다룬다. skill body를 복제하지 않는다. 프로젝트 CORE/가이드/기존 naming·contract 우선, 권한, 한국어 설명, PRD/plan, focused test, no automatic commit/install을 유지한다.
+
+## 미확인 및 비보장 사항
+
+이번 범위에서 전역 설정·설치 파일은 변경하지 않았다. 후속으로 Codex Superpowers의 활성 상태를 확인하고
+필요하면 공식 관리 절차로 활성화하거나, 설치 버전에 맞는 전문 스킬의 누락 참조를 복구하는 작업은 별도 승인이 필요하다.
+호출 제한을 풀거나 우회하기 위해 frontmatter를 바꾸는 제안은 하지 않는다.
+
+- Codex에서 Superpowers plugin의 실제 자동 활성/호출 성공, OpenCode 전체 runtime catalog와 각 모델 invocation.
+- 조사 순간 이후의 config, 실행 CLI arguments/profile, tool permission 및 skill precedence.
+- 캐시와 installed skill 간 byte identity; Addy upstream name correspondence는 확인됐으나 local provenance는 확인되지 않음.
+- missing checklist를 사용하는 complete sign-off. 이는 결손으로 확인됨.
+- 사용자 routing scenario의 runtime 재현/자동 invocation 성공.