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

docs/20261019_스킬오케스트레이션/routing-scenarios.md

@@ -0,0 +1,143 @@
+# Skill routing 시나리오
+
+## 판정 기준
+
+각 요청 문구는 사용자가 지정한 원문 그대로다. 아래는 확인된 skill 책임을 적용한 문서상 routing 기대이며 모델 실행 결과가 아니다. 각 `관찰/검증` 필드의 PENDING은 해당 가상 업무와 모델 자동 호출을 실행하지 않았다는 뜻이다. 수정된 `AGENTS.md`와의 논리 대조는 아래 결과표에 별도로 기록한다. Host에서 해당 skill을 발견하고 도구 권한이 허용되어야 선택할 수 있다.
+
+## 1. 로그인 기능
+
+**요청:** 사용자 로그인 기능을 만들어줘.
+
+- **분류:** 신규 사용자 기능, 인증/보안 경계 및 API 가능성이 있는 구현.
+- **주 skill:** `brainstorming`.
+- **보조 skill:** 인증/민감 정보 경계에 `security-and-hardening`; 공개 API가 포함될 때 `api-and-interface-design`; frontend가 범위일 때 `frontend-ui-engineering`.
+- **실행 순서:** 요구/승인된 로그인 동작 정리 → 해당 보안/API/frontend 하위 범위 검토 → 기존 PRD/plan → 실행 경로 하나 → 구현 시 TDD → 변경 리뷰 → 완료 전 verification.
+- **제외/중복:** 요구가 명료하면 `deep-interview` 제외. explicit stress-test가 아니면 `grilling` 제외. 보안 리뷰만 요청한 것이 아니므로 review skill로 구현을 대체하지 않는다.
+- **조건부 자동 선택:** host discovery/permission이 허용하면 필요한 specialist만 선택 가능. 이는 자동 호출이 검증됐다는 뜻이 아니다.
+- **승인/명시 요청:** 인증 방식, token lifecycle, scope 등 미정 정책을 임의 결정하지 않는다. 실제 기능 구현은 요청됐지만 보안 설계의 미결값은 해결이 필요하다.
+- **관찰/검증:** PENDING. scenario simulation only; 실행 또는 자동 호출 증거 없음.
+
+## 2. 모호한 신규 서비스
+
+**요청:** 요구사항이 아직 모호한 신규 서비스를 설계해줘.
+
+- **분류:** 모호한 목표/범위/성공 기준의 신규 설계.
+- **주 skill:** `brainstorming`.
+- **보조 skill:** ambiguity를 codebase/기존 문서로 해결할 수 없을 때만 `deep-interview`.
+- **실행 순서:** 확인 가능한 기존 근거 확인 → 중요한 요구 unknown이 남으면 한 번에 가장 불확실한 질문을 하는 deep-interview → 응답 반영 → brainstorming으로 설계 정리.
+- **제외/중복:** 모든 작업에서 deep-interview를 기본 실행하지 않는다. 정착된 결정 frontier를 사용자가 stress-test하라고 하지 않으면 `grilling` 제외. 구현 요청이 없으면 plan/실행/TDD 생략.
+- **조건부 자동 선택:** deep-interview는 의미상 모호한 요청 조건에 맞을 수 있으나 실제 host/model 호출은 검증되지 않았다. grilling은 의미상 stress-test 요청일 때만 선택하며 명시적 skill 이름은 필수 아님.
+- **승인/명시 요청:** 미정 제품 선택은 사용자에게 남기고 확정된 것처럼 기록하지 않는다.
+- **관찰/검증:** PENDING. scenario simulation only; 인터뷰를 수행하지 않았다.
+
+## 3. 결제 도메인 용어와 상태
+
+**요청:** 결제 도메인의 용어와 상태를 정리해줘.
+
+- **분류:** 결제 도메인 어휘와 state model 정리 요청.
+- **주 skill:** `domain-modeling`.
+- **보조 skill:** 상태 전이가 코드 구조/모듈 seam 평가를 요구할 때만 `codebase-design`.
+- **실행 순서:** 현재 결제 코드/문서 용례를 조사 → 용어와 상태 의미를 분리해 정리 → 필요할 경우 현재 domain doc convention에 반영.
+- **제외/중복:** glossary 언급만으로 ADR 작성, API 변경, 기능 구현, brainstorming-기반 신규 서비스 설계를 강제하지 않는다. 기술 seam이 없는 한 codebase-design 생략.
+- **조건부 자동 선택:** glossary/domain model을 실제로 수정하는 범위면 domain-modeling이 관련된다. 파일 read-only 설명만 요청됐다면 수정 workflow로 넘어가지 않는다.
+- **승인/명시 요청:** 용어의 의미/상태 전이가 코드와 다르면 제품 의미를 추측하지 말고 근거 및 미결점을 보고한다. ADR은 별도 결정 기록 필요가 있을 때만.
+- **관찰/검증:** PENDING. scenario simulation only; domain 파일을 변경/검증하지 않았다.
+
+## 4. 모듈 의존성 설계 검토
+
+**요청:** 이 모듈의 의존성 설계를 검토해줘.
+
+- **분류:** 기존 구조의 read-only architecture/interface evaluation.
+- **주 skill:** `codebase-design`.
+- **보조 skill:** 새 동작/구조 대안을 실제로 결정해야 할 때만 `brainstorming`.
+- **실행 순서:** 의존성 및 호출자 근거 조사 → seam/ownership/tradeoff 평가 → 사실과 제안 분리 보고.
+- **제외/중복:** 일반 architecture review는 `improve-codebase-architecture` explicit invocation을 뜻하지 않는다. HTML 보고서, `grilling`, 수정/리팩터링을 자동 시작하지 않는다.
+- **조건부 자동 선택:** 일반 탐색 및 codebase-design은 질문의 구조 검토 의도에 맞는다. skill 선택은 host discovery/permission에 따라 다르며 runtime 미검증.
+- **승인/명시 요청:** 파일 이동/코드 변경은 요청되지 않았으므로 읽기 전용으로 유지한다. 보고서 artifact도 임의 생성하지 않는다.
+- **관찰/검증:** PENDING. scenario simulation only; 실제 의존성 분석은 수행하지 않았다.
+
+## 5. 새 REST API 설계
+
+**요청:** 새로운 REST API를 설계해줘.
+
+- **분류:** 신규 API 동작 및 public contract 설계.
+- **주 skill:** `brainstorming`이 system behavior/요구 설계를 소유한다.
+- **보조 skill:** `api-and-interface-design`은 contract substage(호환성, request/response/error, 입력 경계)를 소유한다. 실제 trust/security boundary가 있으면 `security-and-hardening` 보조.
+- **실행 순서:** 사용자/소비자 의도와 기존 contract 확인 → 필요한 신규 동작 brainstorming → API specialist의 제한된 contract 분석 → 보안 경계가 있으면 보안 검토 → 설계 결과 보고. 구현 요청이 추가되면 PRD/plan 이후 실행.
+- **제외/중복:** API specialist가 전체 제품 의도나 전체 구현을 대신하지 않는다. 설계만 요청된 경우 코드/migration/test 구현은 제외.
+- **조건부 자동 선택:** API contract substage가 존재할 때 API specialist 선택 가능; 보안은 경계가 있는 경우에 한한다. host discovery/permission 필요, 실제 invocation 미검증.
+- **승인/명시 요청:** 기존 public schema compatibility를 깨는 변경과 미확정 error/validation 정책을 추정하지 않는다.
+- **관찰/검증:** PENDING. scenario simulation only; API 계약/runtime 검증을 수행하지 않았다.
+
+## 6. 인증 취약점 검토
+
+**요청:** 인증 과정에 보안 취약점이 있는지 검토해줘.
+
+- **분류:** 인증 security review, read-only.
+- **주 skill:** `requesting-code-review`는 review delegation/검토 단계가 적용되는 경우 단일 main review process다.
+- **보조 skill:** `security-and-hardening`은 threat model 및 security criteria를 제공한다. main review를 중복 실행하지 않는다.
+- **실행 순서:** 허용 범위/인증 경계 조사 → 단일 review process로 evidence 기반 finding → 보안 기준에 따라 영향/완화안 구분 보고 → 요청된 검증만 실행.
+- **제외/중복:** 자동 fix, `test-driven-development`, 구현용 brainstorming은 수정 요청이 별도로 없으면 제외한다. 두 번째 전체 security review를 같은 목적에 중복하지 않는다.
+- **조건부 자동 선택:** 보안 경계 때문에 security specialist가 관련되지만 host discovery/permission에 의존한다. invocation은 미검증.
+- **승인/명시 요청:** review는 수정 승인이 아니다. 체크리스트 참조가 필요한 sign-off는 checklist 결손을 밝히고 full sign-off로 표현하지 않는다.
+- **관찰/검증:** PENDING. scenario simulation only; 코드 review/security test는 수행하지 않았다.
+
+## 7. 테스트 실패 버그 수정
+
+**요청:** 테스트에 실패하는 버그를 수정해줘.
+
+- **분류:** 실패를 재현하고 근본 원인을 고쳐야 하는 bugfix.
+- **주 skill:** `systematic-debugging`.
+- **보조 skill:** 구현 변경이면 TDD 절차 및 단일 실행 경로; 마무리에 적절한 review와 fresh verification.
+- **실행 순서:** 실패 재현/원인 증거 → 최소 회귀 test → 의도한 실패 확인 → 최소 수정/통과 → 직접 영향 회귀 → review → 완료 전 verification.
+- **제외/중복:** 실패 원인이 명료하면 brainstorming/deep-interview/grilling을 추가하지 않는다. 일반 탐색을 별도 full process로 중복하지 않는다. 테스트 삭제/완화 금지.
+- **조건부 자동 선택:** 실제 재현된 failure가 있을 때 systematic-debugging 관련. host discovery/permission 및 호출은 미검증.
+- **승인/명시 요청:** 범위 변경은 기존 plan 갱신 후 진행한다. 수정 요청이므로 재현된 범위의 fix는 승인됐다.
+- **관찰/검증:** PENDING. scenario simulation only; 테스트/코드 변경은 수행하지 않았다.
+
+## 8. 기존 코드베이스 구조 개선 후보
+
+**요청:** 기존 코드베이스에서 구조 개선 후보를 찾아줘.
+
+- **분류:** 기존 시스템의 read-only exploratory review.
+- **주 skill:** 일반 조사; 구조/경계 판단이 필요할 때 `codebase-design`.
+- **보조 skill:** 일반 요청만으로는 explicit-only인 `improve-codebase-architecture`를 선택하지 않는다.
+- **실행 순서:** 관련 코드/의존성 근거를 읽기 → 개선 후보/비용/근거를 설명 → 보고서/후속 작업 형식이 필요하면 사용자에게 opt-in 명시 호출을 안내.
+- **제외/중복:** skill 주도의 HTML report workflow, 후보 선택 대기, `grilling`, 구현/commit을 자동 시작하지 않는다.
+- **조건부 자동 선택:** `codebase-design`은 구조 평가에 조건부. `improve-codebase-architecture`는 사용자가 해당 스킬을 이름으로 명시하거나 host의 skill 선택기에서 직접 선택한 뒤에만 실행한다. 일반적인 보고서 요청도 명시 호출 제한을 우회하지 않는다.
+- **승인/명시 요청:** 일반 후보 탐색은 읽기 전용 요청이다. HTML 산출물과 skill workflow의 explicit invocation은 별도 opt-in이다.
+- **관찰/검증:** PENDING. scenario simulation only; 실제 repository review나 skill invocation은 수행하지 않았다.
+
+## 9. 확정 설계 뒤 구현 재개
+
+**요청:** 기존 설계가 확정되었으니 구현을 계속해줘.
+
+- **분류:** 결정된 요구사항/기존 plan에 따른 연속 구현.
+- **주 skill:** 하나의 plan execution path만 선택: inline 수행이면 `executing-plans`, subagent 방식이 실제 선택된 경우 `subagent-driven-development`.
+- **보조 skill:** 구현 단계의 TDD, 필요한 debugging, 변경 review, fresh verification.
+- **실행 순서:** 기존 PRD/plan·Decision Log 및 저장소 상태 확인 → 기존 미완료 task 실행 → 구현 시 TDD → review → 새 상태/검증 기록.
+- **제외/중복:** blocker/새로운 critical gap 없이 brainstorming, deep-interview, 재계획, grilling을 반복하지 않는다. 두 execution path를 같이 실행하지 않는다.
+- **조건부 자동 선택:** host에서 discover되고 permission이 허용되는 절차만 사용한다. Codex/OpenCode 자동 invocation 실제 결과는 미검증.
+- **승인/명시 요청:** 기존 설계와 task를 따르는 구현은 요청됨. 새로운 제품 결정, scope expansion, 자동 commit은 포함하지 않는다.
+- **관찰/검증:** PENDING. scenario simulation only; 구현/test/호출은 수행하지 않았다.
+
+## 공통 host/승인 경계
+
+### 문서상 논리 대조 결과 - 2026-10-19
+
+| 시나리오 | AGENTS.md 대조 기준 | 논리 판정 | 런타임 자동 호출 |
+|---|---|---|---|
+| 1 | 신규 기능 흐름과 보안/API specialist 조건 | PASS | 미실행 |
+| 2 | Requirements Discovery의 선택적 인터뷰와 설계 복귀 | PASS | 미실행 |
+| 3 | Domain 용어/상태 및 glossary 소비/수정 구분 | PASS | 미실행 |
+| 4 | 기존 dependency read-only 평가와 구조 어휘 | PASS | 미실행 |
+| 5 | API 설계 main과 contract substage 책임 분리 | PASS | 미실행 |
+| 6 | 단일 보안 review process와 criteria/checklist 한계 | PASS | 미실행 |
+| 7 | 재현 가능한 실패의 원인 조사/TDD와 테스트 완화 금지 | PASS | 미실행 |
+| 8 | 일반 조사와 explicit-only 스킬의 명시 선택 제한 | PASS | 미실행 |
+| 9 | 기존 미완료 Task 재개와 중복 설계/인터뷰 금지 | PASS | 미실행 |
+
+판정 방법: 부모 에이전트가 각 요청의 분류·주/보조 책임·순서·제외·승인 경계를 현재 루트 지침과 직접 대조했다.
+`test`/`rg`로 9개 요청 원문과 8개 필드(총 72개)도 확인했다. PASS는 정책 논리의 일치만 뜻하며 실제 업무 실행이나 자동 호출 성공이 아니다.
+
+모든 `조건부 자동 선택`은 모델이 실제로 자동 호출할 것이라는 보장이 아니다. Host가 skill을 발견하고 도구 권한이 허용될 때만 가능하다. 일반 언어상 grilling 요청은 stress-test 의도를 뜻할 수 있으며, skill 이름을 정확히 입력해야만 한다고 제한하지 않는다. 반대로 `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 확인된 explicit-only metadata 때문에 일반 주제 언급만으로 선택하지 않는다. 9개 모든 관찰/검증은 PENDING이다.