docs(agents): 스킬 선택과 실행 우선순위를 정한다

AGENTS.md

@@ -71,16 +71,9 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
 
 ## 지시 우선순위
-충돌 시 항상 더 높은 우선순위의 지시를 따른다.
+우선순위는 1) system/developer 지시와 플랫폼 도구 권한, 2) 사용자의 명시적 요청, 3) 이 저장소의 CORE EXECUTION PRINCIPLES 및 적용 가능한 프로젝트 규칙, 4) 아래 프로젝트 실행 생명주기, 5) 활성화된 전문 스킬의 작업 범위, 6) 플러그인 실행 선호와 기본 모델 동작 순이다. 상위 역할의 지시와 도구 권한을 Markdown으로 변경하거나 우회하지 않는다. 사용자 요청도 상위 지시 및 도구 권한을 넘을 수 없다.
 
-1. 사용자 직접 지시
-2. `AGENTS.md`
-3. 프로젝트별 제약 조건
-4. `oh-my-openagent` 플러그인의 `agents` / `workflows` / `hooks`
-5. `superpowers` skills
-6. 기본 모델 동작
-
-사용자 직접 지시가 명확할 경우 사용자 지시가 최우선이다. plugin / skill / workflow 지시가 `CORE EXECUTION PRINCIPLES`와 충돌하면 `CORE EXECUTION PRINCIPLES`를 따른다. 불확실하거나 모호한 경우 추측하지 말고 확인하거나, 가능한 최소 범위의 안전한 조치를 취한다.
+프로젝트가 통제하는 절차에서는 Superpowers가 주 생명주기이며, 전문 스킬은 해당 단계의 좁은 전문 영역을 맡는다. 플러그인은 도구와 실행 보조를 제공할 뿐 별도의 경쟁 절차를 만들지 않는다. 플러그인에 주입된 상위 역할 지시는 이 문서로 덮어쓸 수 없다. 불확실하면 근거를 확인하고 최소 안전 범위에서 진행한다.
 
 ## 커뮤니케이션 규칙
 - **"질문에 대한 답변과 설명은 한국어로 한다."**
@@ -109,24 +102,42 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 - 최소 변경
 - 단순한 구현
 - 검증 가능한 결과
+- 요청이 구체적이면 불필요한 인터뷰 없이 관련 생명주기의 첫 미완료 단계부터 시작한다.
 
 ### 확장 모드
-- 사용자가 명시적으로 요청한 경우에만 사용한다.
-- 대규모 리팩토링, 브레인스토밍, 다중 에이전트 실행, 병렬 workflow를 허용한다.
+- 대규모 리팩터링, 다중 에이전트 실행, 병렬 workflow 확장은 사용자가 명시적으로 허용한 경우에만 한다. 작은 작업은 단일 경로로 처리한다.
 
-## oh-my-openagent 제어 정책
-- `oh-my-openagent`는 opencode의 플러그인 기반 실행 오케스트레이션 계층이다.
-- `oh-my-openagent`는 의사결정 권한이 아니라 실행 보조 권한만 가진다.
-- 작은 작업에는 multi-agent 실행이나 과도한 workflow를 사용하지 않는다.
-- 병렬 실행은 명확한 이득이 있을 때만 사용한다.
-- 모든 `oh-my-openagent` 동작은 `CORE EXECUTION PRINCIPLES`를 따라야 한다.
+## Skill Orchestration
 
-## superpowers 사용 정책
-- `superpowers`는 선택적 스킬 계층이다.
-- `superpowers` skill은 필요한 경우에만 사용한다.
-- `superpowers`가 과도한 리팩토링, 불필요한 범위 확장, 가정 기반 실행을 유도하면 따르지 않는다.
-- `superpowers`를 사용할 때도 최소 변경, 단순성, 검증 가능성을 우선한다.
-- 모든 `superpowers` 동작은 `CORE EXECUTION PRINCIPLES`를 따라야 한다.
+작업을 시작할 때 질문/조사, 신규 설계, 불명확한 요구사항, 버그, 아키텍처, API, 보안, 리뷰, 테스트/검증, 기존 작업 이어하기 중 하나 이상으로 분류한다. 활성 하위 단계마다 주 소유 스킬 하나를 정하고, 필요한 좁은 보완 스킬만 추가한다. 현재 호스트에서 발견·접근 가능한 스킬만 사용하고, implicit 선택이 허용된 경우에도 `deny`/`ask` 및 agent/tool 권한을 준수한다. 스킬이 없거나 접근이 막히면 한계를 알리고 가능한 부분만 수행한다. 호스트가 현재 해석한 설치 스킬 본문을 먼저 읽는다. 이미 로드된 동일 본문과 끝난 질문·계획·리뷰 결과는 재사용하며 되풀이하지 않는다. 일반 질문·조사·문서 작업은 제품 구현 생명주기를 자동 시작하지 않는다.
+
+| 작업 | 주 생명주기와 선택 스킬 |
+|---|---|
+| 새 기능/설계 | Superpowers `brainstorming`으로 설계. 필요할 때만 `deep-interview`, `domain-modeling`, `codebase-design`을 좁게 보완한다. |
+| 요구사항이 중요하게 미정 | 임시 소유자 `deep-interview`; 아래 종료 기준을 만족하면 요약을 기존 PRD에 통합하고 설계 단계로 이동한다. |
+| 도메인 용어/사업 모델 변경 | 실제 용어집 또는 도메인 모델 변경이면 `domain-modeling`; 단순 조회에는 호출하지 않는다. |
+| REST/API 설계 | `brainstorming` 설계 단계 안에서 `api-and-interface-design`으로 계약을 구체화하고, 인증/신뢰 경계가 관련되면 `security-and-hardening`을 보완한다. |
+| 버그 | `systematic-debugging` → 재현 회귀 테스트/TDD → 단일 실행 경로 → 해당 시 `requesting-code-review` → `verification-before-completion`. |
+| 아키텍처 검토 | 목적에 맞는 읽기 전용 분석. 구체적 대안 설계는 `codebase-design`; 별도 사용자 요청 없이는 HTML/그릴 워크플로를 자동 호출하지 않는다. |
+| 계획 | `writing-plans`. 승인된 설계와 유효한 계획이 함께 있으면 첫 미완료 단계부터 이어가고, 설계만 확정됐다면 새 인터뷰 없이 빠진 계획만 작성한다. |
+| 계획 실행 | `executing-plans` 또는 `subagent-driven-development` 중 하나만 사용한다. 실제 도구가 지원하고 사용자가 고른 방법 및 독립성에 맞춘다. 둘을 중첩하지 않는다. |
+| 구현 테스트 단계 | `test-driven-development`; 버그 경로에서는 `systematic-debugging`이 진단을 소유하고 TDD는 회귀 테스트 단계만 맡는다. |
+| 코드 리뷰/피드백 | 완료된 작업의 단일 리뷰는 `requesting-code-review`; 보안 기준이 필요하면 범위를 좁혀 보완한다. 받은 피드백의 기술적 평가는 `receiving-code-review`. |
+| CI/CD, UI, 운영성, 성능 | 실제 pipeline 변경에는 `ci-cd-and-automation`, UI/accessibility 작업에는 `frontend-ui-engineering`, telemetry에는 `observability-and-instrumentation`, 측정된 bottleneck에는 `performance-optimization`을 조건부 보완으로 사용한다. |
+| 검증/통합 | 완료 주장 전 `verification-before-completion`. `finishing-a-development-branch`는 통합이 실제 범위일 때만 사용하며, 요청 없는 commit/push/정리를 하지 않는다. |
+| 격리/병렬 읽기 | 실제 구현 경로가 필요할 때 기존/native 격리 수단을 먼저 확인하는 `using-git-worktrees`. 독립 읽기 트랙 병렬화는 허용된 경우에만 `dispatching-parallel-agents`; SDD 구현자를 별도로 병렬 중첩하지 않는다. |
+
+`deep-interview`는 목표, 범위, 제약, 성공 기준, 맥락 중 중요한 미해결 사항이 있거나 해석이 충돌/핵심 조건이 빠졌거나 사용자가 명시한 경우에만 잠시 소유한다. 질문은 한 번에 하나씩 한다. 해당 점수법에서 전체 불확실성 0.20 이하뿐 아니라 모든 중요한 결정이 해결되어야 종료하며, 중요한 차원 하나라도 0.50 이하로 충분히 확정되지 않으면 계속한다. 해결된 문제를 반복 인터뷰하지 않는다. 이 스킬은 산출물/의존성을 정하지 않는다. 자동 `.scratch`나 별도 명세를 만들지 말고 요약을 기존 PRD에 반영한다.
+
+`grilling`은 계획·결정·아이디어 전반에 대한 스트레스 테스트이며 아키텍처 전용이 아니다. 사용자가 원하거나 구체적인 아키텍처 대안을 비교할 때 주로 쓴다. 회차마다 의존 조건이 해결된 질문을 묶어 묻고 답변을 기다리며, 종료 시 사용자의 공유 이해 확인을 받는다. 그릴의 다중 질문 회차와 다른 스킬의 한 번에 하나 질문 규칙을 동시에 적용하지 않는다. `codebase-design`은 모듈 규모와 무관한 depth/seam/locality 및 exposed interface를 다루고, `api-and-interface-design`은 내부·외부 API 계약의 안정성/errors/compatibility를 다룬다. 두 skill을 internal/public로만 나누지 않는다. 둘 다 별도의 전체 설계나 인터뷰 절차를 대체하지 않는다.
+
+### 자동 선택과 실행 경계
+
+- Codex 스킬 자동 호출은 설치 정의의 `agents/openai.yaml` `policy.allow_implicit_invocation: false`로 막을 수 있다(기본값은 true). 명시적 호출은 별개다.
+- OpenCode의 `metadata['opencode/autoinvoke']='false'`는 모델 자동 선택 노출을 숨기지만 직접 호출을 막지 않는다. `permission.skill`의 deny/ask와 agent/tool 권한은 별도 제어다. `disable-model-invocation`은 OpenCode의 문서화된 동등 설정이 아니다.
+- `improve-codebase-architecture`와 `setup-matt-pocock-skills`는 `disable-model-invocation: true` 및 Codex implicit false가 있다. OpenCode autoinvoke metadata는 없어 광고될 수 있다. 프로젝트 정책상 명시 전용이지만 Markdown이 OpenCode backend/hook 차단을 강제하는 것은 아니다. “기존 코드 구조 개선 후보 찾기”나 일반 HTML 요청만으로 실행하지 않는다. 사용자가 skill 이름으로 명시 호출한 경우에만 그 workflow를 고려하며, 요청 범위를 넘어 HTML 생성/브라우저 열기/grilling을 흉내 내지 않는다. 허용된 읽기 전용 `codebase-design` 분석은 별개다. `setup-matt-pocock-skills`는 별도 일회성 명시 요청에만 쓴다.
+- 빠진 스킬이나 필수 참고 파일이 있으면 한계를 알리고 가능한 부분 확인만 한다. 완전한 절차를 수행했다고 주장하지 않는다. 스킬 설치나 메타데이터 변경으로 제한을 우회하지 않는다. gstack은 어느 단계에서도 사용하거나 설치하지 않는다.
+- 웹 대상 스킬의 예시는 적용 가능한 통제만 참고한다. iOS 코드에 서버 cookie/CSP 등을 옮겨 적용하지 않으며 SodaLive의 실제 API와 스타일을 따른다.
 
 ## 에이전트 동작 원칙
 - 추측하지 말고 근거 파일을 읽고 결정한다.
@@ -140,7 +151,7 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 - iOS 코드 스타일은 `docs/agent-guides/code-style.md`를 참조한다.
 - Cursor/Copilot 규칙은 `docs/agent-guides/sodalive-ios-development.md`를 참조한다.
 - 커밋 상세 가이드/절차는 `.opencode/skills/commit-policy/SKILL.md`를 단일 기준으로 사용한다.
-- 커밋 작업 시작 시 `skill` 도구로 `commit-policy`를 먼저 로드한다.
+- 커밋 작업 시작 시 `commit-policy`를 먼저 로드한다. OpenCode에서는 `skill` 도구를 사용하고, Codex에서는 발견된 `SKILL.md` 또는 `.opencode/skills/commit-policy/SKILL.md`를 읽는다.
 - 기본 커밋 형식은 `<type>(scope): <description>`를 사용하고, 제목(description)은 한글 명령형/간결한 현재형으로 작성한다.
 - `git commit` 직후 `work/scripts/check-commit-message-rules.sh`를 실행해 규칙 준수 여부를 확인한다.