diff --git a/AGENTS.md b/AGENTS.md index 49db4a51..5e98d913 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -74,7 +74,7 @@ Strong success criteria let you loop independently. Weak criteria ("make it work ## 충돌 해결 규칙 - plugin / skill / workflow 지시가 CORE EXECUTION PRINCIPLES와 충돌하면 CORE EXECUTION PRINCIPLES를 따른다. -- 사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다. +- 시스템·플랫폼 지침과 도구 권한을 먼저 따른다. 그 경계 안에서 명확한 사용자 요청을 우선 존중한다. - 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다. ## 커뮤니케이션 규칙 @@ -120,3 +120,79 @@ Strong success criteria let you loop independently. Weak criteria ("make it work ### Domain docs single-context 구성으로 루트 `GLOSSARY.md`와 `docs/adr/`를 사용한다. 읽기 규칙은 `docs/agents/domain.md`를 따른다. + +## Skill Orchestration + +- Superpowers는 개발 작업의 주 흐름이다. specialist skill은 실제 해당 단계의 요구를 보완하며, 작업마다 모든 겹치는 skill을 일괄 실행하거나 새 결정론적 scheduler를 만들지 않는다. +- 먼저 요청 유형과 산출물을 분류하고, 그 단계의 주 skill 하나를 정한 뒤 필요한 보조 skill만 선택한다. 각 단계의 책임자는 하나로 유지한다. +- `using-superpowers` 절차가 이미 주입됐다면 다시 전체 controller를 시작하지 않는다. child session에서 처음부터 orchestration을 반복하지 않는다. +- 조사 문서 [`docs/20261019_스킬오케스트레이션/audit.md`](docs/20261019_스킬오케스트레이션/audit.md)는 조사 시점의 설치/설정 증거다. 모든 항목이 현재 host에서 등록·발견·활성화됐다는 보장은 아니다. +- 아래 라우팅은 작업을 돕는 지침이지 자동 invocation 보장이 아니다. 구체적인 예시는 [`docs/20261019_스킬오케스트레이션/routing-scenarios.md`](docs/20261019_스킬오케스트레이션/routing-scenarios.md)를 참고한다. + +## Skill Priority and Selection + +- 모든 현재 요청을 질문/설명, 조사, 신규 기능, 요구사항 정리, 버그 수정, 아키텍처 평가, API 설계, 보안 작업, 리뷰, 테스트/검증, 기존 작업 이어하기 중 해당 유형으로 분류한다. 혼합 작업은 산출물 단계별로 나눈다. +- 일반 질문이나 read-only review를 코드 변경으로 바꾸지 않는다. specialist는 그 skill 고유 책임이 실제 범위에 있을 때만 추가한다. +- 신규 기능 구현은 `brainstorming` → `writing-plans` → `executing-plans` 또는 `subagent-driven-development` 중 정확히 하나 → 구현 중 TDD → 변경 review → 완료 직전 fresh verification 순서를 따른다. +- 이미 승인된 설계/plan의 연속 작업은 기존 미완료 Task부터 재개한다. known decisions, open questions, acceptance criteria를 다시 묻거나 interview/planning을 반복하지 않는다. 새 critical gap이 있을 때만 요구/계획을 다시 연다. +- 독립적이고 공유 상태가 없는 작업의 병렬 조율에는 `dispatching-parallel-agents`를 사용한다. 같은 파일을 수정하거나 선행 결과가 필요한 구현 작업은 동시에 보내지 않는다. +- 실행 방식 선택, `using-git-worktrees`를 통한 필요 시 격리 확인, `finishing-a-development-branch`의 통합 판단은 별개다. 확인만으로 worktree를 자동 생성하지 않으며 commit/push/merge/delete는 명시적 승인 없이 하지 않는다. + +## Requirements Discovery + +- 신규 동작의 사용자 의도와 선택 정리는 `brainstorming`이 주 책임이다. 계획만 필요한 경우 `writing-plans`를 사용하고, 이미 확정된 기존 계획을 중복 생성하지 않는다. +- 요구사항이 중요하게 모호할 때만 `deep-interview`를 조건부로 사용한다. 먼저 코드/기존 문서에서 알려진 사실을 확인하고, 이미 답이 있는 질문은 되묻지 않는다. +- `deep-interview`는 라운드마다 가장 큰 미해결 질문 하나를 묻고 Goal, Scope, Constraints, Success, Context를 평가한다. Context는 기존 코드베이스를 변경하는 경우에만 평가한다. 새 프로젝트 가중치는 `.35/.25/.15/.25`, 기존 코드베이스 작업은 `.30/.20/.15/.20/.15` 순서다. 모호성 `<=.20`이며 중요한 미지수가 해결되면 멈춘다. 중요한 dimension이 `<=.50`이어도 핵심 미해결점이 남으면 계속할 수 있다. 응답, 결정, 알려진 사실을 반영하고 다시 brainstorming으로 돌려보낸다. +- `grilling`은 plan/idea/decision 전반의 stress-test이며 아키텍처 전용이 아니다. 사용자의 의미상 stress-test 의도가 있을 때만 조건부 선택한다. skill 절차상 정착된 전체 decision frontier를 매 라운드 질문하므로 `deep-interview`와 혼합/중복하지 않는다. 정확한 skill 이름 언급을 필수 조건으로 오인하지 않는다. +- 한 시점에는 요구 질문 프로세스 하나만 활성화한다. 기존 결정, 열린 질문, acceptance criteria를 재사용하고 이미 답한 질문을 반복하지 않는다. + +## Skill Routing by Task Type + +| 작업 유형 | 주 흐름 | 조건부 보완 | +|---|---|---| +| 일반 조사/모듈 이해 | 요청된 범위만 조사하고 근거를 보고한다. | 구조 seam 평가가 핵심일 때 `codebase-design`; 설계 loop를 강제하지 않는다. | +| 신규 기능/모호한 요구 | 신규 동작은 `brainstorming`; 모호성이 중요할 때만 `deep-interview` 후 재개. | domain decision이면 `domain-modeling`; 이후 승인된 구현은 계획·단일 실행 경로·TDD를 따른다. | +| 새 모듈/구조 설계 | 새 사용자/동작 선택은 `brainstorming`. | 구조 경계가 실제 주제일 때 `codebase-design`. 기존 dependency를 read-only 검토하는 요청은 `codebase-design` 중심으로 평가하고 구현하지 않는다. | +| Domain 용어/상태 | `domain-modeling`은 실제 domain model 또는 용어를 수정/정의할 때 사용한다. | glossary를 읽기만 하는 요청은 호출 근거가 아니다. ADR은 별도 결정 기록이 필요할 때만 작성한다. | +| API 설계 | `brainstorming`이 system behavior/요구를 맡는다. | `api-and-interface-design`은 contract substage(호환성, 입출력/오류 경계)를 맡는다. 기존 Kotlin/Spring naming과 계약을 바꾸지 않는다. | +| 보안 구현 | 승인된 구현의 단일 실행 경로와 TDD를 적용한다. | 실제 인증/민감정보/외부 trust boundary에서 `security-and-hardening`을 사용한다. | +| Read-only 보안 리뷰 | 해당 범위에 적용 가능한 리뷰 프로세스 하나로 evidence 기반 finding을 보고한다. | `security-and-hardening`은 보안 기준을 보완한다. 리뷰 요청을 자동 수정으로 바꾸지 않는다. | +| 계획 작성 | `writing-plans`; 저장소 PRD/plan 경로와 형식이 기준이다. | 요구 discovery가 미해결일 때만 discovery skill을 먼저 사용한다. Superpowers 전용 중복 계획 폴더를 만들지 않는다. | +| 버그 수정 | 재현 가능한 실패/오류는 `systematic-debugging`으로 원인을 좁힌다. | 구현 시 TDD. 단순 조사/설명만이면 debugging workflow를 강제하지 않는다. | +| 리뷰/피드백 | 요청된 변경은 `requesting-code-review`; 받은 피드백을 실제 반영할 때 `receiving-code-review`. | 중복 full review를 만들지 않고 리뷰 권한만으로 수정하지 않는다. | +| 테스트/완료 검증 | 실패 재현/수정은 TDD; 완료 주장은 `verification-before-completion` 기준의 fresh verification 뒤에 한다. | 프로젝트 focused test 우선순위와 검증 기록 규칙을 유지한다. | +| 기존 작업 이어하기 | 확정된 기존 설계/plan의 첫 미완료 Task를 재개한다. | 새 critical gap만 discovery/planning 재개 사유다. | +| 아키텍처 개선 후보 | 일반 read-only 조사, 구조 평가는 필요 시 `codebase-design`. | `improve-codebase-architecture`는 별도 명시 요청으로 사용자가 선택하기 전 호출하지 않는다. | + +- 실제 범위에 맞는 추가 specialist만 선택한다: 화면 구현은 `frontend-ui-engineering`, CI/deploy 변경은 `ci-cd-and-automation`, production telemetry는 `observability-and-instrumentation`, 근거 있는 성능 목표/병목은 `performance-optimization`이다. 이들은 blanket mandatory가 아니다. +- `diagnosing-superpowers`는 superpowers workflow 자체의 장애 분석, `writing-skills`는 skill 작성/수정 때만 선택한다. 일반 개발 기본 체인의 단계가 아니다. + +## Conflict and Duplication Resolution + +- CORE와 상위 지침, 저장소 규칙, 실제 사용자 범위를 지킨다. stage마다 main owner 하나만 둔다. +- `brainstorming` / `deep-interview`: 새 동작의 선택·설계 대 모호한 요구를 푸는 단일 질문/turn discovery. 설계 main, 큰 unknown이 남을 때만 interview 후 설계로 복귀. +- `brainstorming` / `grilling`: 새 요구를 설계하고 선택하는 흐름 대 확정된 전체 frontier를 압박 시험하는 흐름. 기본 owner는 brainstorming; 의미상 stress-test 필요가 있을 때만 grilling. +- `brainstorming` / `codebase-design`: 제품 동작/요구 선택 대 코드 구조·seam 평가. 새 동작은 brainstorming, 구조 경계만 요청됐으면 codebase-design. +- `codebase-design` / `api-and-interface-design`: 모듈 깊이/seam 대 소비자-facing contract/호환성·오류. 구조 평가는 codebase-design, API skill은 계약 substage만 소유한다. +- `requesting-code-review` / `security-and-hardening`: review process 대 보안 기준. 적용 가능한 단일 review process가 main이고 security skill은 criteria 보완이며 동일 대상을 두 번 full review하지 않는다. +- `systematic-debugging` / general exploration: 재현 가능한 실패의 hypothesis/cause loop 대 read-only code 이해. 실패 재현이면 debugging, 일반 질문이면 조사만 수행한다. +- Domain/구조 어휘 skill은 프로젝트 코드나 공개 contract의 Kotlin/Spring 명명·타입·관례를 rename하거나 덮어쓰지 않는다. + +## Automatic Invocation Constraints + +- 실행 전에 현재 host의 skill catalog, 설치된 대상 `SKILL.md`와 관련 참조, invocation metadata, host tool permission을 확인한다. 조사 시점의 audit 목록만으로 현재 등록/활성을 단정하지 않는다. +- Codex의 `agents/openai.yaml` `policy.allow_implicit_invocation`, OpenCode의 `metadata["opencode/autoinvoke"]` 및 `skill` allow/ask/deny 권한을 각각 해당 host 문서대로 해석한다. 서로 동등하다고 추정하지 않는다. +- `disable-model-invocation`은 명시적 사용자 의도를 위한 정책 신호다. OpenCode v1이 이 키를 지원한다고 가정하지 않으며, 지원 여부와 무관하게 사용자의 explicit-only 의도를 지킨다. +- `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 catalog에 보여도 explicit-only다. 일반적인 “코드베이스 구조 개선 후보를 찾아줘”는 `improve-codebase-architecture` 호출 승인이 아니다. 사용자가 해당 skill을 명시적으로 이름 붙여 선택해야 한다. setup은 초기 설정을 명시적으로 요청할 때만 실행한다. +- Metadata를 바꾸거나 skill 파일을 읽어 호출 제한을 우회하지 않는다. 제한을 조사하는 것과 skill을 실제 실행하는 것은 다르다. +- Host에서 skill을 찾지 못하거나 권한이 거부되면 한계를 알리고 허용된 프로젝트 절차를 따른다. 존재하지 않는 skill/명령을 가장하거나 직접 설치·생성하지 않는다. Codex Superpowers cache 존재는 activation 증거가 아니다. +- AGENTS 파일의 로딩 계층과 skill 단계 우선순위는 별개다. 이 문서는 플랫폼 instruction loader를 변경하지 않는다. `gstack`은 설치하거나 사용하지 않는다. + +## Verification and Completion + +- 필요한 문서/도구/참조가 없으면 어느 검토 부분이 미검증인지 보고한다. 공유 checklist 결손을 조용히 무시하거나 global checklist를 만들거나 설치해 full sign-off로 바꾸지 않는다. +- 기존 PRD/plan 경로와 project guides가 변경 범위·테스트·검증 기준이다. 이미 완료된 분석을 다른 skill workflow로 반복하지 않는다. +- 구현 시 focused test부터 시작하고 프로젝트의 TDD, 보안 및 사람 승인 경계를 지킨다. 실패한 테스트를 삭제/완화하지 않는다. +- 새 session은 갱신된 `AGENTS.md`를 안정적으로 다시 읽을 수 있도록 시작한다. skill 단계는 논리적 routing guidance이며 runtime 자동 invocation 성공을 보장하지 않는다. +- worktree는 필요성을 확인하되 자동 생성하지 않는다. branch 종료/merge는 실제 해당 작업일 때만 다루며 commit/push/merge/delete는 명시적 승인 없이는 하지 않는다. +- 사용자가 이미 명확하게 승인한 범위는 다시 묻지 않는다. 승인 경계 밖의 새로운 결정이나 scope 확장만 확인한다. diff --git a/docs/20261019_스킬오케스트레이션/audit.md b/docs/20261019_스킬오케스트레이션/audit.md new file mode 100644 index 00000000..4d936108 --- /dev/null +++ b/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: +- Codex skills: +- OpenCode rules: +- OpenCode skills: +- Superpowers: +- Matt Pocock skills: +- Addy Osmani skills: +- Addy upstream skills index: + +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//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//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 성공. diff --git a/docs/20261019_스킬오케스트레이션/plan-task.md b/docs/20261019_스킬오케스트레이션/plan-task.md new file mode 100644 index 00000000..e9c98914 --- /dev/null +++ b/docs/20261019_스킬오케스트레이션/plan-task.md @@ -0,0 +1,174 @@ +# 스킬 오케스트레이션 구현 계획 + +| 항목 | 내용 | +|---|---| +| 상태 | 구현 완료 | +| 작성일 | 2026-10-19 | +| 요구사항 기준 | [`prd.md`](prd.md) | +| 현재 Phase | Phase 1: 문서 및 루트 정책 통합 | +| 현재 활성 Goal | 없음 | + +## 목표 + +사용자 의도에 맞는 skill orchestration 정책을 루트 `AGENTS.md`에 적용하고, 근거 감사와 9개 routing scenario 및 문서 검증 증거를 완성한다. + +## 현재 상태 + +| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 | +|---:|---|---:|---|---| +| 1 | 완료 | `2/2` | 없음 | 논리 대조·문서 검사·별도 검토 완료, 런타임 자동 호출은 미검증 | + +동시에 하나의 미완료 Goal만 실행한다. 사용자는 안전한 조사, 문서 및 범위 내 루트 변경을 이미 명시적으로 승인했다. 후속 승인 대기 단계를 만들지 않는다. + +## 범위 + +### 포함 + +- `AGENTS.md`의 기존 원칙 아래 skill orchestration 요약 변경. +- `docs/20261019_스킬오케스트레이션/`의 PRD, 계획, 근거 감사, 지정 원문 기반 9 scenario. +- scenario/PRD/audit/루트 정책 사이 일관성 및 문서 검증. + +### 제외 + +- 앱 코드/테스트/스크립트, 전역 설정/지침, skill/plugin 파일 수정 또는 설치. +- `AGENTS.md`의 요청 범위 바깥 기존 내용 변경. +- gstack/worktree/commit/push 및 실제 skill invocation 실험. +- 자동 invocation이 동작한다고 주장하거나 누락된 checklist를 만들고 sign-off 기준을 완화하는 일. + +## 문서 작업 TDD 예외 + +문서/정책 변경은 생산 동작을 바꾸지 않으므로 fake unit test를 만들지 않는다. 대체 검증은 네 파일 정확성, 9개 원문/필드, source·metadata 주장 및 root diff의 assertion 대조다. 실행 시 다음을 사용하고 결과를 사실대로 기록한다. + +```bash +git diff --check +git diff --no-index --check /dev/null docs/20261019_스킬오케스트레이션/prd.md +git diff --no-index --check /dev/null docs/20261019_스킬오케스트레이션/plan-task.md +git diff --no-index --check /dev/null docs/20261019_스킬오케스트레이션/audit.md +git diff --no-index --check /dev/null docs/20261019_스킬오케스트레이션/routing-scenarios.md +wc -c AGENTS.md +./gradlew tasks --all +``` + +현재 문서 정정 작업에서는 이 명령들을 실행하지 않는다. `wc -c` 출력은 Codex의 32,768 byte 기본 budget과 비교하고, Gradle 명령은 문서 변경에 대한 프로젝트 요구 점검이다. 네 파일 신규 비교가 필요하면 `git diff --no-index -- /dev/null <위의 실제 파일 경로>`를 실행한다. 이는 차이를 출력하고 통상 exit 1이므로 차이 출력과 실제 오류를 구분한다. + +### Phase 1: 문서 및 루트 정책 통합 + +**Phase 결과:** 루트 정책과 네 문서가 같은 책임 분리와 승인 경계를 표현하며, 지정 시나리오와 실제 점검 결과를 추적할 수 있다. + +**선행조건:** 필수 프로젝트 문서와 설치 근거를 읽었고 사용자가 전체 범위를 승인했다. + +- [x] **Task 1.1: 사전 문서 작성 및 정정** + +**Goal ID: `P1-T1`** + +- **Objective:** 정확한 범위, 조사 근거, 9개 지정 요청의 라우팅 기대를 네 문서에 일관되게 남긴다. +- **시작 조건:** 루트 지침/가이드/샘플 및 조사된 host/skill 근거 확인. +- **정확한 파일 경로:** `docs/20261019_스킬오케스트레이션/prd.md`, `plan-task.md`, `audit.md`, `routing-scenarios.md`. +- **완료 증거:** 네 파일 존재, PRD/plan이 루트 구현까지 포괄, 9개 원문과 필수 8필드, 확정된 metadata 사실, 계획된 검증을 실제 수행했다고 오기하지 않음. +- **범위 밖:** `AGENTS.md` 편집, 기존 문서/설정/skill 변경, 실제 skill invocation. +- **TDD 예외 사유:** 문서만 작성한다. +- **대체 검증 방법:** 파일 수, assertion, 시나리오/근거 대조. 검증 명령 미실행 상태를 보존한다. + +- [x] 필수 문서 및 조사 근거 기반 초안 네 파일을 작성했다. +- [x] 정정 요청을 반영해 PRD/plan 범위, invocation 사실, 감사 근거 및 시나리오를 갱신했다. + +- [x] **Task 1.2: 루트 skill orchestration 정책 적용** + +**Goal ID: `P1-T2`** + +- **Objective:** PRD의 확정 요구와 audit의 근거를 적용해 기존 루트 정책 아래에 최소 routing 요약을 반영한다. +- **시작 조건:** `P1-T1`의 정정된 문서가 있고 기존 CORE/프로젝트 규칙을 보존한다. +- **정확한 파일 경로:** 수정 `AGENTS.md`; 근거 `docs/20261019_스킬오케스트레이션/prd.md`, `audit.md`, `routing-scenarios.md`. +- **완료 증거:** 요청된 제한 영역만 바꾸고 9 scenario에 대조하며 실제 실행한 검증만 기록한다. +- **범위 밖:** 다른 기존 파일, 글로벌 설정, `SKILL.md`/plugin, 설치, gstack, 자동 commit, runtime 호출 주장. +- **TDD 예외 사유:** 자연어 정책 편집이며 독립 생산 동작이 없다. +- **대체 검증 방법:** AGENTS diff와 문서 assertion 대조, `git diff --check`, actual-path no-index whitespace check, byte budget 및 `./gradlew tasks --all` 결과. + +- [x] 변경할 루트 영역을 읽고 유지할 기존 우선순위/작업 절차를 대조한다. +- [x] 분류, 조건부 deep-interview, 단일 실행 경로, 중복 방지, 권한/발견 제한, 검증 시점만 최소 문구로 반영한다. +- [x] 일반 architecture 요청에서 explicit-only skill을 선택하지 않으며 `grilling`을 explicit-only로 잘못 분류하지 않았는지 확인한다. +- [x] 9개 exact prompt와 정책을 대조하고 실제 검증 결과를 기록한다. + +- [x] **Phase Gate: 정책·근거·시나리오 정합성** + +**Goal ID: `P1-GATE`** + +- **Objective:** 루트 변경과 네 문서가 사용자 범위, 사실 근거, 프로젝트 문서 검증 요건을 충족하는지 판정한다. +- **시작 조건:** `P1-T1`, `P1-T2` 완료. +- **정확한 파일 경로:** `AGENTS.md`, `docs/20261019_스킬오케스트레이션/{prd.md,plan-task.md,audit.md,routing-scenarios.md}`. +- **완료 증거:** 4파일/9원문 assertion, 9 scenario 8필드, diff 공백 확인, `wc -c AGENTS.md`, Gradle task 명령 결과와 미확인 조건 기록. +- **범위 밖:** 자동 호출 성공 주장, checklist 결손 은폐/완화, 무관한 수정. +- **TDD 예외 사유:** 최종 정책·문서 검토. +- **대체 검증 방법:** 위 명령을 실제 실행하고 출력 및 exit status를 기록한다. `git diff --no-index`의 정상 차이 exit 1은 whitespace 검사 실패로 취급하지 않는다. + +- [x] 모든 자동/보조 라우팅 조건이 audit의 설치/metadata 근거와 일치한다. +- [x] 전역 공유 checklist 부재를 보고하고 그 checklist 기반 full sign-off를 주장하지 않는다. +- [x] 실제 검증 결과, 남은 제한, 요청 범위 외 변경 부재를 기록한다. + +## 실행 순서와 의존성 + +| 순서 | Goal | 선행조건 | 상태 | +|---:|---|---|---| +| 1 | `P1-T1` | 필수 가이드/근거 확인 | 완료, 이 정정판으로 갱신 | +| 2 | `P1-T2` | 정정된 사전 문서 | 완료 | +| 3 | `P1-GATE` | `P1-T1`, `P1-T2` 및 실제 검증 | 완료 | + +## Progress + +### `P1-T1` 실행 기록 (최초 작성) + +- 무엇을: PRD/plan을 별도 patch로 먼저 만들고 audit/scenarios를 뒤에 추가했다. +- 어떻게: 네 파일/9개 scenario 존재는 읽기/검색 도구로 확인했다. `git diff --check`, no-index, `wc -c`, Gradle 명령은 실행하지 않았다. +- 결과: 초안 작성은 완료했으나 이후 부모 검토에서 범위, grilling metadata, 설치 근거, checklist 결손과 scenario prompt/소유권 오류가 발견되어 아래 정정 기록을 추가했다. + +### `P1-T1` 정정 기록 + +- 상태: 문서 정정 완료, 검증 명령 대기. +- 무엇을: 전체 사용자 승인 범위와 실제 근거, 요청 원문 그대로의 9 scenario, 명시적 요청/자동 선택 구분을 네 파일에 반영했다. +- 검증: `P1-T1` 문서 편집을 완료로 표시한다. 최종 문서 점검 명령은 실행하지 않았다. +- 이전 오류 기록을 삭제하지 않고 현재 문서 내용을 정정했다. + +### `P1-T2` 실행 기록 + +- 상태: 대기. +- 다음 행동: 정정된 PRD/audit/scenarios를 따라 루트 정책 편집. + +### `P1-T1` 부모 검증 및 `P1-T2` 착수 - 2026-10-19 + +- 무엇을: 네 선행 문서를 모두 읽고 설치 파일·사용자 원문과 대조했다. +- 보정: `.opencode/` 자체의 존재와 활성 설정 부재를 구분하고, deep-interview의 `argument-hint` 및 Context 평가 조건을 바로잡았다. +- `test`/`rg` 검사: 종료 코드 0. 필수 문서 존재, 시나리오 9개 및 각 8개 필드(총 72개)를 확인했다. +- 신규 네 파일의 `git diff --no-index --check /dev/null "$file"`: 종료 코드 0, 공백 오류 없음. +- 결과: 선행 문서 검증 완료. `P1-T2`는 기존 내용 보존 및 한 줄 우선순위 명확화와 7개 짧은 정책 섹션 추가를 위임해 진행 중이다. + +### `P1-GATE` 실행 기록 + +- 상태: 대기. +- 다음 행동: 루트 편집 및 실제 검증 결과가 준비된 뒤 판정. + +### `P1-T2` 완료 및 `P1-GATE` 1차 검증 - 2026-10-19 + +- 무엇을: 기존 우선순위 문장 한 줄을 상위 지침/권한 경계로 명확히 하고 7개 routing 섹션을 추가했다. +- 왜: Superpowers 메인 흐름과 단계별 단일 책임, 선택적 specialist, 명시 호출 전용 제한을 실제 루트 지침에 반영하기 위해서다. +- `git diff -- AGENTS.md`: 기존 본문은 우선순위 한 줄 외 보존. `git diff --numstat`는 77줄 추가/1줄 삭제다. +- `git status --short --untracked-files=all`: `AGENTS.md`와 이 폴더의 신규 네 Markdown 문서만 변경됐다. +- `git diff --check` 및 신규 네 문서의 no-index `--check`: 종료 코드 0, 공백 오류 없음. +- `test`/`rg`: 종료 코드 0. 7개 루트 heading이 각각 한 번, 9개 원문 요청과 72개 필드, 참조 파일 존재 및 내부 주석/루트 override 미생성을 확인했다. +- 수동 논리 대조: 9개 scenario 모두 현재 루트 정책에 일치. 도메인 분석·보안 리뷰·버그 수정 등 가상 작업 자체나 모델의 자동 호출은 실행하지 않았다. +- `wc -c AGENTS.md`: 17,988 bytes로 Codex 기본 32,768 byte 예산 미만이다. +- `./gradlew tasks --all`: 종료 코드 0, `BUILD SUCCESSFUL`. 기존 Gradle 9.0 관련 deprecation 경고는 유지된다. +- 전역 설정 두 개 및 deep-interview/명시 호출 제한 관련 다섯 파일의 SHA-256은 편집 전 값과 동일하다. 전역 설정·설치 파일은 수정하지 않았다. +- 다섯 변경 파일에 LSP 진단을 요청했으나 `.md` 서버가 설정되지 않아 수행할 수 없었다. 서버/설정은 추가하지 않고 문서 대조 및 공백 검사로 검증했다. +- 전체 테스트·빌드는 실행하지 않았다. 실행 코드·의존성·빌드 설정 변경이 없어 문서 정합성·diff 검사와 Gradle task 목록으로 검증했다. +- 남은 항목: 별도 최종 검토 결과와 최종 문서 공백/범위 재검사. 런타임 자동 invocation은 이번 Gate 범위 밖이며 미검증이다. + +### `P1-GATE` 별도 검토 및 완료 판정 - 2026-10-19 + +- 별도 검토 결과: 수정 필수/권고 수준의 실질적 finding 없음. 기존 내용 보존, 실제 스킬 원문/metadata와의 일치, + 명시 호출 제한, 문서 크기, checklist 결손 보고 및 변경 범위를 확인했다. +- 검토자는 Gradle·모델 실행을 반복하지 않았다. 사용자 9개 원문 대조와 Gradle/전역 파일 해시 검증은 부모 실행 결과를 근거로 한다. +- 시나리오 문서에 9개 논리 대조 PASS와 9개 런타임 자동 호출 미실행을 별도로 기록했다. +- 결과: `P1-T1`, `P1-T2`, `P1-GATE` 완료. 남은 호스트 활성화/참조 결손은 audit의 비보장 및 별도 승인 영역으로 남긴다. +- 커밋·푸시·전역 설정 변경·스킬 설치·gstack 실행은 수행하지 않았다. +- 최종 재검사: 시나리오 9개/72개 필드/논리 PASS 9행 및 미완료 계획 항목 부재를 확인했고, + 변경·신규 문서 공백 검사는 종료 코드 0, `./gradlew tasks --all` 재실행도 `BUILD SUCCESSFUL`이었다. diff --git a/docs/20261019_스킬오케스트레이션/prd.md b/docs/20261019_스킬오케스트레이션/prd.md new file mode 100644 index 00000000..41c0fe0a --- /dev/null +++ b/docs/20261019_스킬오케스트레이션/prd.md @@ -0,0 +1,67 @@ +# 스킬 오케스트레이션 요구사항 + +## 문서 정보 + +| 항목 | 내용 | +|---|---| +| 문서 상태 | 구현 완료 | +| 작성일 | 2026-10-19 | +| 최종 수정일 | 2026-10-19 | +| 대상 | 루트 `AGENTS.md`의 skill orchestration 정책 및 사전 문서 | +| 관련 구현 계획 | [`plan-task.md`](plan-task.md) | +| 조사/시나리오 | [`audit.md`](audit.md), [`routing-scenarios.md`](routing-scenarios.md) | + +## 1. 문제와 목표 + +루트 `AGENTS.md`는 일부 skill을 소개하지만 작업 유형별 선택, 순서, 중복 해소, 명시적 요청 경계와 host별 발견 한계를 한곳에서 안내하지 않는다. 이는 문서 baseline의 routing 공백이며, 자동 호출 실패라는 런타임 판정은 아니다. + +목표는 사용자의 작업 유형에 맞는 최소 skill 선택 및 순서를 루트 정책으로 정리하고, 그 정책을 뒷받침하는 근거와 아홉 개의 실제 사용자 요청 예시를 함께 제공하는 것이다. 전체 승인 범위는 루트 `AGENTS.md`의 제한된 skill orchestration 영역 변경과 이 폴더의 네 문서 완성이다. + +## 2. 범위 + +### 포함 + +- `AGENTS.md`에 skill 선택, 선행 순서, 중복 해소, explicit-only 처리, 자동 호출 조건, 검증/완료 경계를 좁게 추가한다. +- 다음 네 문서를 완성한다: `docs/20261019_스킬오케스트레이션/prd.md`, `plan-task.md`, `audit.md`, `routing-scenarios.md`. +- 현재 루트/전역 지침, 설치 경로, skill metadata와 공식 host 문서를 구분해 근거/불확실성을 기록한다. +- 9개 지정 요청에 각기 분류, 주 skill, 보조 skill, 실행 순서, 제외 대상, 조건부 자동 선택, 승인 경계, 관찰/검증 상태를 기록한다. +- 프로젝트 CORE와 기존 PRD/plan, TDD, focused verification, 한국어 보고 규칙을 유지한다. + +### 제외 + +- 런타임 앱 코드, 테스트, 스크립트 또는 새 skill/plugin 구현. +- 전역/프로젝트 host 설정, global `AGENTS.md`, `SKILL.md` 변경, 설치 또는 gstack 설치. +- 문서에서 제안한 routing의 모델 자동 invocation을 테스트/보장한다고 주장하는 일. +- 요청된 루트 skill orchestration 영역 밖의 `AGENTS.md` 정리, 다른 기존 파일 변경, 자동 commit/push. +- PRD/plan 절차, API 계약, 보안 gate, 공통 tooling을 새로 정의하거나 약화하는 일. + +## 3. 정책 요구사항 + +| ID | 요구사항 | 수용 기준 | +|---|---|---| +| ORCH-001 | 작업 산출물에 맞게 최소 skill 조합을 선택한다. | 대표 작업 유형에서 주 책임과 조건부 specialist가 구분되며 무관한 skill을 체인에 넣지 않는다. | +| ORCH-002 | 흐름은 요청의 명료도와 구현 여부에 맞춘다. | 새 기능은 brainstorming을 사용하고, 모호할 때만 deep-interview를 선택한 뒤 설계로 돌아간다. 구현은 기존 PRD/plan, 한 실행 경로, 구현 시 TDD를 따른다. | +| ORCH-003 | explicit-only 제약과 사용자 의도를 보존한다. | `improve-codebase-architecture`, `setup-matt-pocock-skills`는 implicit invocation하지 않는다. `grilling`을 metadata상 암묵 호출 금지로 오인하지 않고, 의미상 stress-test 요청일 때 조건부 선택한다. | +| ORCH-004 | 겹치는 skill은 책임별로 나눈다. | `audit.md`에 6개 쌍의 역할 차이와 선택 기준이 있고, 9개 시나리오에서 중복 실행/소유권을 판정한다. | +| ORCH-005 | 발견 상태와 실제 invocation을 분리한다. | 조건부 사용은 host에서 발견 가능하고 권한이 허용되는 경우로 한정한다. runtime 자동 호출은 테스트됐다고 하지 않는다. | +| ORCH-006 | 기존 프로젝트 정책과 상위 권한을 보존한다. | 기존 CORE/프로젝트 절차가 skill 일반 지침보다 우선한다. 자동 승인, 설치, commit을 추가하지 않는다. | +| ORCH-007 | 누락된 필수 checklist를 숨기거나 약화하지 않는다. | 전역 checklist 결손은 해당 checklist 기반 sign-off 제한으로 보고하며 파일 생성/설치/기준 완화는 하지 않는다. | + +## 4. 충돌과 의존 + +- 시스템/플랫폼/도구 권한 및 루트 CORE와 프로젝트 규칙을 보존한다. 명확한 사용자 승인은 이 경계를 우회하지 않는다. +- 기존 `docs/agent-guides/작업절차.md`, `문서유지보수.md`의 PRD/plan 경로, goal, TDD 예외, focused test 우선 및 실제 결과 누적 요구를 유지한다. +- 조사된 shared checklist가 없으면 대체 문서를 임의로 작성하거나 full sign-off를 주장하지 않는다. +- Codex/OpenCode의 발견/우선순위는 각 host 문서에 귀속해 설명하며 하나의 공통 탐색 규칙으로 합치지 않는다. + +## 5. 완료 기준 + +- 신규 문서는 지정 폴더 아래 정확히 네 개이며, 이 구현은 기존 `AGENTS.md`의 해당 routing 영역만 수정한다. +- 9개 scenario가 사용자 지정 원문 요청을 그대로 포함하고 각각 8개 필드를 갖는다. 문서상 논리 대조 결과와 런타임 자동 호출 미검증을 구분한다. +- `plan-task.md`의 루트 편집, 9 scenario 대조, 문서 점검 및 Gate가 실제 증거와 함께 완료된다. +- source/evidence path와 runtime 미확인 사항, checklist 결손이 정확히 구분된다. +- `git diff --check`, 신규 파일별 실제 경로 `git diff --no-index /dev/null ` 비교, `wc -c AGENTS.md`의 32,768 byte 기본 budget 비교, `./gradlew tasks --all` 결과는 실제 실행 뒤에만 기록한다. + +## 6. 근거 범위 + +루트 `AGENTS.md`, 프로젝트 가이드와 샘플, 설치/설정 경로, Codex/OpenCode 공식 문서, skill 파일과 metadata를 [`audit.md`](audit.md)에 구체적으로 기록한다. 사용자 요청 원문 및 문서상 라우팅 기대는 [`routing-scenarios.md`](routing-scenarios.md)에 둔다. diff --git a/docs/20261019_스킬오케스트레이션/routing-scenarios.md b/docs/20261019_스킬오케스트레이션/routing-scenarios.md new file mode 100644 index 00000000..5b6d83d7 --- /dev/null +++ b/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이다.