docs(agents): 스킬 오케스트레이션 요구사항과 조사 근거를 기록한다
This commit is contained in:
@@ -0,0 +1,66 @@
|
||||
# 스킬 오케스트레이션 및 우선순위 자동화 PRD
|
||||
|
||||
## 문서 정보
|
||||
|
||||
| 항목 | 내용 |
|
||||
|---|---|
|
||||
| 문서 상태 | 문서 정책 구현·논리 검증 완료 |
|
||||
| 작성일 | 2026-10-19 |
|
||||
| 대상 | Codex·OpenCode 공용 프로젝트 스킬 선택 지침 |
|
||||
| 결정권자 | 저장소 사용자 |
|
||||
| 관련 구현 계획 | [plan-task.md](plan-task.md) |
|
||||
| 관련 조사 | [research.md](research.md) |
|
||||
| 관련 검증 | [scenario-validation.md](scenario-validation.md) |
|
||||
| API Contract | 해당 없음: 프로젝트 Markdown만 변경 |
|
||||
|
||||
## 1. Overview
|
||||
|
||||
Superpowers를 기본 개발 프로세스로 유지하고, 설치가 확인된 Matt Pocock·Addy Osmani·로컬 `deep-interview` 스킬을 필요한 단계에서만 보완적으로 선택한다. 사용자는 지침 조사, 설치·호출 정책 확인, 실제 `AGENTS.md` 수정과 아홉 시나리오의 논리 검증을 명시적으로 요청했다.
|
||||
|
||||
## 2. Goals
|
||||
|
||||
- 하네스의 지침 로딩 우선순위와 스킬의 작업 단계별 책임을 구분한다.
|
||||
- 스킬 명시 호출 없이 선택할 수 있는 범위만 안내하고 권한·호출 금지를 준수한다.
|
||||
- 같은 인터뷰·설계·계획·리뷰를 중복 실행하지 않으며 확정 결과를 후속 단계에서 재사용한다.
|
||||
- 기존 최소 변경, PRD·계획, 레거시 보호, 로컬 테스트·기기 제한, 보안·Git 규칙을 보존한다.
|
||||
|
||||
## 3. Non-Goals
|
||||
|
||||
- 전역 설정, 플러그인, 설치된 스킬·에이전트 파일 변경.
|
||||
- 스킬 설치, gstack 사용·설치, 소스 코드·빌드 설정 변경.
|
||||
- 실제 기능 개발, 보안 공격 실험, 기기·UI 조작, 커밋·푸시.
|
||||
- 런타임 자동 호출·동일한 하네스 동작의 보장.
|
||||
|
||||
## 4. 기능 요구사항
|
||||
|
||||
| ID | 상태 | 요구사항 | 수용 기준 | Task |
|
||||
|---|---|---|---|---|
|
||||
| ROUTE-001 | 확정 | 기존 지침을 가장 먼저 조사 | 위치·Git 루트·전역·상위·루트·하위·override·추가 지침의 경로와 범위 기록 | P1-T1 |
|
||||
| ROUTE-002 | 확정 | 실제 스킬 설치·호출 정책 조사 | 논리/실제 경로, frontmatter, 부속 정책, 발견·호출 가능 여부 구분 | P1-T1 |
|
||||
| ROUTE-003 | 확정 | deep-interview 전문 및 의존성 분석 | 질문·종료·출력·의존성과 brainstorming·grilling 역할 구분 | P1-T1 |
|
||||
| ROUTE-004 | 확정 | Superpowers 중심 단계별 단일 책임 | 작업 분류, 프로세스 우선, 좁은 전문 보완, 완료 검증 명시 | P1-T2 |
|
||||
| ROUTE-005 | 확정 | 중복 방지 | 요청한 여섯 스킬 조합의 공통·고유 책임, 조건·우선순위 기록 | P1-T2 |
|
||||
| ROUTE-006 | 확정 | 호출 제한 존중 | 명시 전용·권한 거부·미지원 기능 우회 금지, setup·아키텍처 진단 조건 명시 | P1-T2 |
|
||||
| ROUTE-007 | 확정 | 기존 AGENTS와 가이드 최소 수정 | 기존 지침 보존·충돌 문구만 조정, 공통 Markdown과 상세 참조 문서 사용 | P1-T2 |
|
||||
| ROUTE-008 | 확정 | 아홉 시나리오 논리 검증 | 원문 요청별 분류·메인·보완·순서·제외·호출·승인 조건과 판정 기록 | P1-GATE |
|
||||
| ROUTE-009 | 확정 | 출처·제약·변경 증거 보고 | 공식·로컬 출처, diff·정합성 결과, 미검증 런타임과 전역 변경 제안 기록 | P1-GATE |
|
||||
|
||||
## 5. 검증과 성공 기준
|
||||
|
||||
- 프로젝트 정책은 최신 설치 문서에서 확인된 기능·제약만 사용한다.
|
||||
- `AGENTS.md`에서 주 프로세스, 선택 순서, 요구사항 탐색, 기본 라우팅, 호출 제한을 확인할 수 있다.
|
||||
- 아홉 시나리오는 실제 스킬 실행 없이 논리적으로 대조하고 런타임 검증과 구별한다.
|
||||
- 변경은 프로젝트 Markdown으로 한정하고 문서 경로·공백·기존 안전 규칙을 검사한다.
|
||||
- 저장소 규칙에 따라 `./gradlew tasks --all`의 실제 결과를 기록한다. 앱 빌드·테스트 통과로 해석하지 않는다.
|
||||
|
||||
## 6. Open Questions
|
||||
|
||||
추가 제품 결정은 없다. 하네스별 설치·권한·호출 기능은 조사 근거로 판정하며 확인할 수 없는 항목은 미검증으로 남긴다.
|
||||
|
||||
## 7. Decision Log
|
||||
|
||||
| 날짜 | ID | 상태 | 결정 | 근거 |
|
||||
|---|---|---|---|---|
|
||||
| 2026-10-19 | DEC-001 | 확정 | 기존 설정 작업과 별개 목적이므로 새 작업 디렉터리 사용 | 사용자의 새 오케스트레이션 요구 |
|
||||
| 2026-10-19 | DEC-002 | 확정 | 상세 요구를 재인터뷰하지 않고 조사 후 안전한 범위까지 구현 | 실제 수정·검증까지 완료하라는 명시 요청 |
|
||||
| 2026-10-19 | DEC-003 | 확정 | 기존 확장 모드 제한 중 자동 설계 선택과 충돌하는 부분만 좁게 조정 | 기본 brainstorming 선택 요구, 기존 안전 제약 보존 |
|
||||
@@ -0,0 +1,271 @@
|
||||
# 스킬 오케스트레이션 및 우선순위 조사
|
||||
|
||||
> 조사 기준일: 2026-10-19
|
||||
> 범위: Codex·OpenCode의 지침 로딩 근거, 저장소·전역 설정, 지정 스킬의 설치 및 책임
|
||||
> 상태: 설치·메타데이터 대조와 Codex 플러그인 활성 조회 완료. 새 프로젝트 정책의 런타임 적용·자동 호출은 미검증.
|
||||
|
||||
## 1. 조사 결론
|
||||
|
||||
- **지침 적용 계층**은 실행 중인 하네스의 실제 상위 지침과 파일 로딩 규칙에 따른다. `AGENTS.md`로 하네스의 상위 developer/system 지침을 무효화할 수 없다.
|
||||
- **스킬 workflow 책임**은 별도 축이다. 프로젝트의 작업 분류 및 기존 필수 절차를 기준으로 Superpowers 프로세스를 주 흐름으로 두고, 설치된 전문 스킬은 해당 단계의 좁은 보완 역할에만 연결한다.
|
||||
- Codex·OpenCode 공식 문서는 파일 검색, 병합, 스킬 선택 및 권한에서 차이를 보인다. 프로젝트 문서는 공통 정책을 제시할 수 있지만 각 하네스의 실제 로딩 또는 자동 호출을 보장하지 않는다.
|
||||
- `deep-interview`는 질문을 통해 모호성을 줄이고 의사결정을 요약하는 워크플로다. 이 작업에서는 그 결과 요약을 프로젝트 PRD로 전달하는 것이 적절하며, 원래 스킬이 PRD 파일 작성을 요구한다고 해석하지 않는다.
|
||||
- 두 Superpowers 설치 루트에서 각각 동일한 15개 skill 정의가 확인됐다. `codex plugin list --json`은 Superpowers `6.4.2`의 `installed: true`, `enabled: true`를 반환했다. 이는 개별 스킬의 자동 호출 검증과 다르다.
|
||||
- 공유 skill root의 디렉터리는 19개이며, 중첩 `agora-testing-guidance`를 포함한 `SKILL.md` 파일은 20개다. 디렉터리 수와 파일 수를 같은 inventory 수치로 취급하지 않는다.
|
||||
|
||||
## 2. 증거 범위와 신뢰도
|
||||
|
||||
| 증거 종류 | 조사 범위 | 보고서에서의 취급 |
|
||||
|---|---|---|
|
||||
| 저장소 문서 | 작업 PRD·계획·루트 `AGENTS.md` | 현재 프로젝트 정책의 직접 근거 |
|
||||
| 로컬 설정·스킬 파일 | 아래에 명시한 Codex/OpenCode 설정, lockfile, 실제 스킬 전문 | 조사 시점의 로컬 존재와 내용 근거. 모든 파일의 런타임 선택 증거는 아님 |
|
||||
| 공식 문서 | §4의 Codex·OpenCode 문서 URL | 해당 날짜에 확인된 제품 동작 설명 근거 |
|
||||
| 원격 저장소 | Matt Pocock·Addy Osmani·Superpowers의 upstream 출처 | 의도·출처 확인용. 로컬 설치나 호출 가능성의 근거로 대체하지 않음 |
|
||||
| 실행 관찰 | CLI 버전, `codex plugin list --json`, 현재 OpenCode 세션의 스킬 광고 | 버전·플러그인 설치/활성·발견 증거일 뿐 개별 자동 호출이나 전체 런타임 동작을 증명하지 않음 |
|
||||
|
||||
저장소 시작 작업 트리는 깨끗했고 작업 위치와 Git root는 모두 `/Users/klaus/Develop/sodalive/Android/SodaLive`였다. 이 값은 2026-10-19 조사 기록이며 이후 상태를 보증하지 않는다.
|
||||
|
||||
실제 CLI 조회 버전은 `codex-cli 0.163.0`, OpenCode `1.19.3`이다. 현재 프로젝트 루트에는 양쪽이 발견할 수 있는 비어 있지 않은 `AGENTS.md`가 있으며 override는 없다. 하위 디렉터리 작업이나 새 세션에서는 현재 파일·권한을 다시 확인한다.
|
||||
|
||||
## 3. 지침 적용 계층
|
||||
|
||||
이 절은 **어떤 지침이 적용되는가**를 다룬다. §5는 **어떤 작업 단계에서 어떤 스킬을 고르는가**를 다루며, 두 순서를 하나의 우선순위 목록으로 합치지 않는다.
|
||||
|
||||
### 3.1 로컬 지침 탐색 결과
|
||||
|
||||
- 상위 경로 `/`, `/Users`, `/Users/klaus`, `/Users/klaus/Develop`, `/Users/klaus/Develop/sodalive`, `/Users/klaus/Develop/sodalive/Android`에서 `AGENTS.md`, override, `CLAUDE.md`, `opencode.json`, `opencode.jsonc`가 확인되지 않았다.
|
||||
- 숨김 파일 및 ignore 제외 탐색에서 `.git`, `node_modules`, `build`, `.gradle`, `.worktrees`를 제외한 결과 프로젝트 루트의 `AGENTS.md`만 확인됐다. 제외 디렉터리는 의존성·생성물·별도 worktree의 탐색 범위 밖이며, 그 안에 다른 지침이 없다는 주장은 하지 않는다.
|
||||
- 전역 경로 `/Users/klaus/.codex/AGENTS.md`, `/Users/klaus/.codex/AGENTS.override.md`, `/Users/klaus/.config/opencode/AGENTS.md`, `/Users/klaus/.claude/CLAUDE.md`는 없는 것으로 확인됐다.
|
||||
- 별도 디렉터리 확인에서 저장소 `.agents/skills`, `.codex/skills`, `.claude/skills`는 없고 `.opencode/skills`는 비어 있다. 전역 `~/.claude/skills`와 `/etc/codex/skills`도 없으며, `~/.codex/skills`에는 bundled `.system` skills가 있다. `~/.config/opencode/skills`에는 commit wrapper가 있다.
|
||||
- 환경 변수 `CODEX_HOME`, `OPENCODE_CONFIG`, `OPENCODE_CONFIG_DIR`, `OPENCODE_CONFIG_CONTENT` 및 관련 disable flag를 확인했을 때 설정되어 있지 않았다. 다른 모든 환경 변수를 전수 조사한 것은 아니다.
|
||||
|
||||
### 3.2 Codex
|
||||
|
||||
공식 자료: [Codex AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md.md), [Codex Skills](https://developers.openai.com/codex/skills.md).
|
||||
|
||||
- Codex는 세션 시작 시 지침을 읽는다. 전역 `~/.codex/AGENTS.override.md`가 전역 `AGENTS.md`보다 우선하며, 저장소 root에서 현재 디렉터리까지 하위 디렉터리 지침이 적용된다. 각 디렉터리에서는 override가 일반 `AGENTS.md`보다 우선하고, 설정된 fallback 파일은 지침 파일이 없는 경우 사용된다.
|
||||
- 여러 디렉터리 지침은 해당 경로에 적용되도록 합쳐진다. 문서가 설명하는 기본 지침 크기 한도는 32 KiB다.
|
||||
- 스킬 검색 위치는 현재 작업 디렉터리에서 저장소 루트 방향의 `.agents/skills`, `~/.agents/skills`, `/etc/codex/skills`, 시스템 제공 스킬, 플러그인 스킬이다. 실제 유효 범위와 덮어쓰기 동작은 공식 문서와 세션 맥락을 따른다.
|
||||
- `agents/default.toml`의 developer instructions는 근거를 `.omo/evidence/`에 저장하라고 하지만, 이는 선택된 agent 설정의 추가 요구이며 Codex 전역 지침 계층을 대체하지 않는다.
|
||||
- `agents/plan.toml`은 `.omo/plans/`에 단일 계획을 작성하고 병렬 조사·리뷰 등을 요구한다. 이 저장소의 PRD/계획 경로 규칙과 다를 수 있다. 어느 설정이 적용되는지는 선택한 agent에 달렸으며, 프로젝트 문서가 실제 하네스 상위 developer instruction을 무효화하지 않는다.
|
||||
- Codex skill sidecar에서 `allow_implicit_invocation`을 생략하면 기본값은 `true`다 ([공식 문서](https://developers.openai.com/codex/skills.md)). sidecar 값은 자동 선택 정책이지 실제 runtime selection 증거가 아니다. `allow_implicit_invocation: false`도 사용자 명시 호출을 차단하는 뜻은 아니다.
|
||||
|
||||
### 3.3 OpenCode
|
||||
|
||||
공식 자료: [OpenCode Rules](https://opencode.ai/docs/rules/), [OpenCode Skills](https://opencode.ai/docs/skills/).
|
||||
|
||||
- 프로젝트 `AGENTS.md`는 작업 경로에서 상위로 탐색된다. `AGENTS.md`가 없으면 대응되는 `CLAUDE.md` fallback을 찾는다. 전역 지침도 `~/.config/opencode/AGENTS.md`와 `~/.claude/CLAUDE.md` fallback 관계를 가진다.
|
||||
- 설정의 추가 instruction 파일은 함께 읽히지만 일반 Markdown에서 다른 파일을 언급하는 것만으로 그 파일 내용이 자동 포함되는 것은 아니다. 필요한 규칙 파일은 명시적으로 읽도록 안내해야 한다.
|
||||
- `metadata["opencode/autoinvoke"]: "false"`는 자동 선택 지침을 숨긴다. 접근 권한을 제어하는 설정이 아니다. `permission.skill`의 allow/ask/deny 및 agent/tool 제한은 별도의 권한 층위다.
|
||||
- `disable-model-invocation: true`는 스킬 파일에서 확인한 frontmatter다. Codex와 OpenCode의 모든 버전에서 같은 의미로 작동한다고 일반화하지 않는다. 프로젝트 정책상 명시 전용 스킬은 직접 호출하지 않는 것을 공통 규칙으로 존중하되, 설치 메타데이터를 이 작업에서 수정하지 않는다.
|
||||
|
||||
### 3.4 설정 증거 및 충돌
|
||||
|
||||
- `/Users/klaus/.config/opencode/opencode.json`은 15행이며 `superpowers@git+https://github.com/obra/superpowers.git`, `@dietrichgebert/ponytail`, `oh-my-openagent@latest` 플러그인과 로컬 Figma MCP를 선언한다. `instructions`, 별도 `skills`, `permission` 설정은 없다. OpenCode 전역 plugin 설정이 있고 현재 세션에 skill 목록이 광고되지만, 자동 호출이 실제 발생하는지는 검증되지 않았다.
|
||||
- `/Users/klaus/.config/opencode/agents/`는 빈 디렉터리다. 이 경로의 별도 사용자 agent Markdown 지침은 없지만 설치된 플러그인의 bootstrap·하네스 주입 지침까지 없다는 뜻은 아니다.
|
||||
- `/Users/klaus/.codex/config.toml`에는 Superpowers enabled 항목이 없었으나, 추가로 `codex plugin --help`와 `codex plugin list --help`에서 읽기 전용 조회 명령을 확인하고 `codex plugin list --json`을 실행한 결과 `superpowers@openai-curated-remote`, version `6.4.2`, `installed: true`, `enabled: true`가 확인됐다. 단일 config 파일의 부재만으로 비활성이라고 판단하지 않는다. 전역 설정은 변경하지 않았다.
|
||||
- `/Users/klaus/.codex/config.toml`은 이 프로젝트를 trusted로 표시하고, `default` 및 `plan` agent 파일을 참조한다. `default.toml`의 `.omo/evidence` 요구와 `plan.toml`의 `.omo/plans` 출력/병렬 조사 요구는 저장소의 단일-context·PRD 및 `docs/YYYYMMDD_.../plan-task.md` 절차와 긴장 관계가 있다.
|
||||
- 저장소 `AGENTS.md`는 구현 전 PRD와 계획 문서를 요구하고 문서 경로를 `docs/[날짜]_구현할내용한글/`로 정한다. 이는 프로젝트 workflow 정책이다. 전역 agent 설정은 실제로 선택되어 실행되면 그 세션의 추가 지침일 수 있으나, 저장소 파일만으로 선택 여부를 단정하지 않는다.
|
||||
- 저장소의 보수적 실행 및 확장 모드 문구는 자동 브레인스토밍 선택 요구와 충돌 후보가 될 수 있다. 이번 증거 보고는 해당 정책을 변경하지 않으며, P1-T2에서 PRD가 정한 범위만 최소 조정할 대상이다.
|
||||
|
||||
| 충돌 후보 | 구체적 차이 | 이 보고서의 취급 |
|
||||
|---|---|---|
|
||||
| 이전 core-principles의 포괄 override 주장 | 저장소 규칙이 system/developer 지침보다 우선한다고 오해될 수 있음 | 실제 상위 지침 우선이라는 문구로 수정된 현재 `AGENTS.md`와 일치시킨다. |
|
||||
| 명시적 brainstorming 제한 | 요청된 기본 설계 탐색과 충돌할 수 있음 | PRD가 정한 예외만 프로젝트 정책 구현에서 다룬다. |
|
||||
| 모든 프롬프트에 PRD를 요구하는 기존 문구 | 읽기 전용 질문에도 개발 루프를 반복할 수 있음 | 구현 작업에는 기존 PRD·계획 선행을 유지하고 일반 질문·조사는 불필요한 문서 생성을 제외한다. |
|
||||
| Superpowers 기본 문서 위치 | 기본 계획 출력 경로가 저장소 canonical docs 경로와 다를 수 있음 | 저장소 PRD/계획 규칙을 프로젝트 내 경로로 두되 전역 설정은 수정하지 않는다. |
|
||||
| SDD 기본 관례 | worktree, 실행 스크립트/증거 ledger, 자동 commit 등은 저장소 승인·절차와 다를 수 있음 | 해당 관례를 무조건 적용하지 않고 실제 prerequisite와 사용자 승인에 따른다. |
|
||||
| 리뷰 흐름 중복 | 요청된 review workflow가 다른 검증/리뷰와 중복될 수 있음 | 동일 범위의 리뷰 루프를 중복 생성하지 않되 완료 판정에는 최신 검증 증거를 확인한다. |
|
||||
| Codex custom planner | `.omo/plans/` 및 병렬 조사 정책이 저장소 docs 경로/승인과 충돌 가능 | 실제 적용·조정은 별도 승인 대상이다. |
|
||||
|
||||
## 4. 공식 출처와 upstream 참조
|
||||
|
||||
### 4.1 공식 문서
|
||||
|
||||
- Codex 지침 파일: <https://learn.chatgpt.com/docs/agent-configuration/agents-md.md>
|
||||
- Codex 스킬: <https://developers.openai.com/codex/skills.md>
|
||||
- OpenCode rules: <https://opencode.ai/docs/rules/>
|
||||
- OpenCode skills: <https://opencode.ai/docs/skills/>
|
||||
|
||||
위 공식 자료는 도구별 탐색·호출 모델을 설명한다. 프로젝트 정책의 권한을 확대하거나 설치 파일의 frontmatter를 덮어쓰는 근거로 쓰지 않는다.
|
||||
|
||||
### 4.2 upstream 저장소
|
||||
|
||||
- Superpowers: <https://github.com/obra/superpowers>
|
||||
- Matt Pocock skills: <https://github.com/mattpocock/skills>
|
||||
- Addy Osmani agent skills: <https://github.com/addyosmani/agent-skills>
|
||||
|
||||
이 링크는 조사된 upstream 출처다. 현재 체크아웃의 완전성, 버전 일치, 런타임 실행을 증명하는 자료가 아니다.
|
||||
|
||||
## 5. 스킬 workflow 책임 및 실제 설치 증거
|
||||
|
||||
### 5.1 확인된 로컬 설치
|
||||
|
||||
| 계열 | 확인된 로컬 근거 | 이 보고서가 말할 수 있는 범위 |
|
||||
|---|---|---|
|
||||
| Superpowers | Codex: `/Users/klaus/.codex/plugins/cache/openai-curated-remote/superpowers/6.4.2/skills`; OpenCode: `/Users/klaus/.cache/opencode/packages/superpowers@git+https:/github.com/obra/superpowers.git/node_modules/superpowers/skills`; manifest `/Users/klaus/.codex/plugins/cache/openai-curated-remote/superpowers/6.4.2/.codex-plugin/plugin.json`은 version `6.4.2`, `skills: ./skills/` 기록 | 양쪽에 아래 15개 동일 정의가 있다. Codex CLI의 설치·활성도 확인했으나 개별 runtime selection은 미검증이다. |
|
||||
| Superpowers OpenCode plugin | `/Users/klaus/.cache/opencode/packages/superpowers@git+https:/github.com/obra/superpowers.git/node_modules/superpowers/.opencode/plugins/superpowers.js` | skills path/registry 추가와 `using-superpowers` bootstrap 주입이 확인됐다. OpenCode 전역 plugin 설정 및 현재 skill 광고는 발견 증거이며 자동 호출 증거는 아니다. |
|
||||
| Matt Pocock | `/Users/klaus/.agents/.skill-lock.json`의 `mattpocock/skills` source 기록, 실제 파일 `/Users/klaus/.agents/skills/{domain-modeling,codebase-design,grilling,improve-codebase-architecture,setup-matt-pocock-skills}/SKILL.md` 및 각 `agents/openai.yaml` | 다섯 파일 확인. `domain-modeling`, `codebase-design`, `grilling`은 interface display/short only; `improve-codebase-architecture`, `setup-matt-pocock-skills`는 `policy.allow_implicit_invocation: false`다. 후자의 두 SKILL frontmatter는 `disable-model-invocation: true`다. 다섯 SKILL 파일에서 OpenCode `opencode/autoinvoke`나 slash key는 발견되지 않았다. |
|
||||
| Addy Osmani | `/Users/klaus/.agents/.skill-lock.json`의 `skills` 객체에서 아래 실제 파일 경로와 같은 여섯 스킬 키의 `source` 값이 `addyosmani/agent-skills`임을 확인했다. 실제 파일 `/Users/klaus/.agents/skills/{api-and-interface-design,security-and-hardening,ci-cd-and-automation,frontend-ui-engineering,observability-and-instrumentation,performance-optimization}/SKILL.md` | 여섯 실제 파일 및 source가 확인됐다. 조사된 frontmatter는 name/description이며 scoped search에서 deny/autoinvoke/policy 메타데이터가 관찰되지 않았다. |
|
||||
| Deep interview | `/Users/klaus/.agents/skills/deep-interview/SKILL.md` | 127행 전문을 읽었다. 해당 디렉터리에는 `SKILL.md`만 있고 yaml sidecar, 종속 파일/실행 요구는 없다. OpenCode 광고와 Codex 문서상 공유 skill 위치는 발견 근거이며 실제 invocation은 미검증이다. |
|
||||
| OpenCode commit wrapper | `/Users/klaus/.config/opencode/skills/commit-with-validation/SKILL.md` | 전역 wrapper가 존재하며 canonical 절차 `/Users/klaus/.agent-commands/commit-with-validation.md`를 먼저 읽으라고 한다. 실제 commit 작업 시 canonical 절차를 사용하고 중복 호출하지 않는다. |
|
||||
|
||||
`/Users/klaus/.agents/.skill-lock.json`은 설치 관리 기록이며 정확한 경로는 `~/.agents/skills/.skill-lock.json`이 아니다. 실제 파일 존재 여부는 각 skill 파일을 확인해 대조했다.
|
||||
|
||||
### 5.2 Superpowers workflow의 알려진 위치
|
||||
|
||||
양쪽 Superpowers skill root를 `SKILL.md` 및 `openai.yaml` 기준으로 대조한 결과 두 곳 모두 아래 동일한 15개 top-level 정의가 확인됐다.
|
||||
|
||||
- `using-superpowers`: 개발 프로세스 기본 진입/분류.
|
||||
- `brainstorming`: 설계·아이디어 탐색.
|
||||
- `writing-plans`: 확정된 사양·요구사항에서 다단계 구현 계획 작성.
|
||||
- `executing-plans`: 승인된 계획의 inline 실행.
|
||||
- `subagent-driven-development`: 독립 task 단위로 승인 계획을 실행.
|
||||
- `dispatching-parallel-agents`: 독립적인 작업을 병렬화.
|
||||
- `using-git-worktrees`: 격리가 요구되는 feature 작업의 worktree 정책.
|
||||
- `test-driven-development`: 기능·버그 수정 시 구현 전 테스트.
|
||||
- `systematic-debugging`: 버그·실패의 가설 기반 조사.
|
||||
- `requesting-code-review`: 완료 변경의 리뷰 요청.
|
||||
- `receiving-code-review`: 피드백을 검증하고 수용 여부 판단.
|
||||
- `verification-before-completion`: 완료 주장 전 증거 확인.
|
||||
- `finishing-a-development-branch`: 검증 완료 후 branch 통합 선택.
|
||||
- `diagnosing-superpowers`: superpowers workflow 자체의 문제 진단.
|
||||
- `writing-skills`: skill 작성·수정·검증.
|
||||
|
||||
양쪽 설치에서 Superpowers metadata를 조사한 범위에 `disable-model-invocation`, `opencode/autoinvoke`, slash key, `allow_implicit_invocation: false`는 없었다. Codex 설치에는 15개의 interface-only `openai.yaml`이 있고 OpenCode sidecar는 관찰되지 않았다. 주 workflow skill의 본문(`brainstorming`, `executing-plans`, `subagent-driven-development`, `requesting-code-review`, 계획 관련)을 검사했고 나머지 보조 skill은 주로 trigger/metadata 수준으로 확인했다. 따라서 모든 skill 본문을 전부 감사했다고 주장하지 않는다. Codex cache의 package manifest와 OpenCode 설정 사실은 유효 활성·실행 증거와 구별한다.
|
||||
|
||||
핵심 배치는 Superpowers를 작업 프로세스의 주 흐름으로 두고, 요청 내용에 직접 맞는 전문 skill을 필요한 단계에서만 보완적으로 연결하는 것이다. 프로세스용 skill 두 개가 같은 단계를 다시 수행하게 하거나 계획·리뷰·요구사항 인터뷰를 재실행하지 않는다. 적합한 Superpowers 절차를 실제 사용하는 것은 자동으로 전문 skill을 추가 호출하는 것과 다르다.
|
||||
|
||||
## 6. deep-interview 전체 분석
|
||||
|
||||
실제 파일: `/Users/klaus/.agents/skills/deep-interview/SKILL.md` (127행, 전부 읽음). 아래 frontmatter는 원문 그대로다.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: deep-interview
|
||||
description: |
|
||||
모호한 요청을 소크라테스식 질문으로 인터뷰해 실행 가능한 요구사항으로 정리한다.
|
||||
사용자가 deep-interview, 심층 인터뷰, 요구사항 명확화, 생각 정리를 요청하거나 목표, 범위, 제약, 완료 기준이 흐릿할 때 사용한다.
|
||||
요청이 이미 구체적이거나 단순 오타, 작은 설정 변경, 테스트 보강처럼 물을 가치가 낮은 작업에는 사용하지 않는다.
|
||||
argument-hint: "<rough request>"
|
||||
---
|
||||
```
|
||||
|
||||
### 6.1 목적과 질문 축
|
||||
|
||||
- 모호한 요청을 실행 전에 명확한 요구사항으로 정리한다. 질문 수를 늘리는 것이 목적이 아니라 가장 큰 불확실성 하나씩 푸는 방식이다.
|
||||
- 순서대로 목표, 범위/제외, 제약, 완료 기준, 기존 맥락/영향 범위 중 가장 불명확한 축을 고른다.
|
||||
- 코드베이스를 조사하면 답할 수 있는 질문은 사용자에게 묻지 않고 직접 확인한다.
|
||||
|
||||
### 6.2 점수와 판단식
|
||||
|
||||
각 사용자 답변 뒤 `Goal`, `Scope`, `Constraints`, `Success`, `Context` 명확성을 `0.0`에서 `1.0`으로 평가한다. Context는 기존 코드베이스 변경에만 포함한다.
|
||||
|
||||
- `0.0`: 알려진 내용이 없거나 서로 충돌.
|
||||
- `0.25`: 일부 단서만 있어 실행 방향을 정하기 어려움.
|
||||
- `0.50`: 대략적 방향은 있으나 여러 해석 가능.
|
||||
- `0.75`: 대부분 명확하나 일부 중요한 판단이 남음.
|
||||
- `1.0`: 중요한 추가 추정 없이 실행·검증 가능.
|
||||
|
||||
신규 프로젝트:
|
||||
|
||||
```text
|
||||
ambiguity = 1 - (goal × 0.35 + scope × 0.25 + constraints × 0.15 + success × 0.25)
|
||||
```
|
||||
|
||||
기존 코드베이스:
|
||||
|
||||
```text
|
||||
ambiguity = 1 - (goal × 0.30 + scope × 0.20 + constraints × 0.15 + success × 0.20 + context × 0.15)
|
||||
```
|
||||
|
||||
점수는 객관적 측정값이 아니라 누락을 일관되게 찾기 위한 판단 보조다. 보통 점수가 가장 낮은 축을 다음 질문 대상으로 삼되, 실행 결과 영향도 고려한다.
|
||||
|
||||
### 6.3 한 턴에 하나의 질문과 선택지
|
||||
|
||||
- 한 번에 질문 하나만 한다. 응답은 다음 질문의 `현재 이해`에 반영하며, 중요 불확실성이 남은 경우에만 계속한다.
|
||||
- 질문 표현은 현재 이해, 전체 모호성, 가장 불명확한 축, 막힌 결정, 질문을 포함한다.
|
||||
- 선택지는 사용자의 판단 기준을 드러내는 데 도움이 될 때만 2~3개 제시하고 마지막은 `- (직접 입력)`으로 둔다. 네 개 이상 필요하면 질문을 더 작게 나눈다.
|
||||
- 저위험 가정만 권장할 수 있고 권장안을 둘 경우 A안에 둔다. 전략, 예산, 보안, 외부 공개, 운영 영향, 되돌리기 어려운 결정은 추천하지 않는다.
|
||||
- `왜 묻는가` 설명은 꼭 필요한 경우 한 문장 이내로 제한한다.
|
||||
|
||||
### 6.4 종료 guard와 최종 요약
|
||||
|
||||
목표·포함/제외 범위·제약·완료 기준·열린 질문을 정리하고, 모호성 점수가 `0.20` 이하여야 종료 조건을 충족한다. 다만 실행 방향을 바꿀 중요한 불확실성이 남으면 점수와 무관하게 계속 묻는다. 어떤 명확성 차원이 `0.50` 이하라면 전체 점수가 낮아도 그 차원이 실행에 중요한지 확인하고 중요하면 계속한다.
|
||||
|
||||
최종 출력은 전체 대화록이 아니라 최종 모호성 점수, 차원별 점수, 결정사항, 열린 질문의 요약이다. 이 요약을 프로젝트 PRD에 기록해 후속 계획에서 재사용할 수 있다. 이는 저장소 통합 방식에 대한 판단이며 원래 skill 파일 작성 의무는 아니다.
|
||||
|
||||
### 6.5 의존성과 경계
|
||||
|
||||
- 확인한 `deep-interview` 전문에는 다른 skill, agent, script를 실행해야 한다는 종속 요구나 파일 쓰기 처방이 없다.
|
||||
- `brainstorming`은 문제/요구사항 인터뷰와 별개로 설계 선택 및 아이디어 탐색을 다룬다. 같은 미해결 요구사항 질문을 되풀이하지 말고 인터뷰 결정 요약을 설계 입력으로 넘긴다.
|
||||
- `grilling`은 사용자가 계획·결정·아이디어를 스트레스 테스트해 달라고 했을 때 적합하다. frontier 설계 질문을 한 라운드에 묻고, 사용자 답을 기다리며, 공유 이해를 사용자가 확인하기 전에는 행동하지 않는다. 기본 요구사항 수집을 대신하지 않는다.
|
||||
- `codebase-design`은 deep module, interface, seam, depth 등의 설계 vocabulary/reference다. 요구사항 인터뷰를 주도하는 skill이 아니며, 실제 모듈 인터페이스를 설계할 때 필요한 용어를 보완한다.
|
||||
- `improve-codebase-architecture`는 사용자가 해당 skill을 직접 선택해 아키텍처 개선 후보 보고를 요청했을 때에 한정된다. 실제 파일 frontmatter는 `disable-model-invocation: true`이며 일반 아키텍처 논의만으로 호출하지 않는다.
|
||||
- `setup-matt-pocock-skills`는 사용자가 직접 선택해 저장소별 이슈/triage/domain 문서 scaffolding을 요청했을 때의 일회성 절차다. 실제 파일도 `disable-model-invocation: true`이며 일반 setup 논의만으로 호출하지 않는다.
|
||||
- Matt Pocock skill을 명시 전용으로 취급하는 경우에도 사용자가 특정 skill을 직접 선택한 것과 일반적인 아키텍처/setup 관련 질문은 다르다. permission allow/ask가 있다고 자동으로 명시 skill 선택이 되는 것은 아니다. native host가 cross-format intent를 보장하지 않으므로 프로젝트 규칙에서 명시 전용 의도를 유지한다.
|
||||
- Addy skill의 출처는 `/Users/klaus/.agents/.skill-lock.json`의 `skills` 객체에 있는 `api-and-interface-design`, `ci-cd-and-automation`, `frontend-ui-engineering`, `observability-and-instrumentation`, `performance-optimization`, `security-and-hardening` 키의 `source: addyosmani/agent-skills` 값과 실제 여섯 파일로 확인했다. 현재 shared `~/.agents/skills`에서 발견되지 않은 Addy skill name은 활성 target로 취급하지 않는다.
|
||||
- Addy reference 누락이 확인됐다: `security-and-hardening/SKILL.md`의 `../../references/security-checklist.md`는 `/Users/klaus/.agents/references/security-checklist.md`로 해석되지만 파일이 없다. 동일한 shared `references/` 아래 `accessibility-checklist.md`, `observability-checklist.md`, `performance-checklist.md`도 없다. 반면 `security-and-hardening/references/hardening-patterns.md`와 `performance-optimization/references/optimization-patterns.md`는 존재한다.
|
||||
- 비설치 Addy skill names `deprecation-and-migration`, `debugging-and-error-recovery`, `shipping-and-launch`를 의존 대상으로 활성화하지 않는다. 이용 가능한 inline 지침과 실제 local pattern은 사용할 수 있으나 checklist 기반 sign-off는 확인하지 못했다.
|
||||
- Addy upstream README는 개별 skill 설치 시 root checklist가 빠질 수 있음을 명시한다: [Addy README, Quick Start](https://raw.githubusercontent.com/addyosmani/agent-skills/main/README.md). reference tree를 수리하거나 복사하는 일은 승인 전 별도 작업이다.
|
||||
|
||||
## 7. 좁은 보완 스킬 라우팅 근거
|
||||
|
||||
아래는 workflow 책임을 혼동하지 않도록 한 선택 기준이다. 이는 런타임 자동 호출 보장이 아니다.
|
||||
|
||||
| 작업 요구 | 좁은 보완 후보 | 하지 않을 일 |
|
||||
|---|---|---|
|
||||
| API·module interface 계약의 설계/안정성 | `api-and-interface-design` | 모든 일반 구현에 무조건 호출하지 않음 |
|
||||
| 보안, 인증, 비밀값, 외부 입력/연동 | `security-and-hardening` | 실제 공격 실험은 현재 PRD 범위가 아님 |
|
||||
| CI/CD 파이프라인 또는 품질 gate 자동화 | `ci-cd-and-automation` | 일반 테스트 실행만으로 호출하지 않음 |
|
||||
| 화면·컴포넌트·접근성 UI 변경 | `frontend-ui-engineering` | Android 레이아웃 속성 테스트 금지 규칙을 우회하지 않음 |
|
||||
| 운영 가시성용 로그·metric·trace | `observability-and-instrumentation` | 근거 없는 계측을 추가하지 않음 |
|
||||
| 측정된 성능 문제 또는 명시 성능 요구 | `performance-optimization` | 측정/요구 없는 최적화 작업을 만들지 않음 |
|
||||
| 모호한 목표·범위·완료 기준을 먼저 정리 | `deep-interview` | 이미 명확한 작은 변경은 인터뷰하지 않음 |
|
||||
| 사용자의 설계/계획 스트레스 테스트 | `grilling` | 일반 요구사항 인터뷰를 grilling으로 대체하지 않음 |
|
||||
| 사용자가 `improve-codebase-architecture`를 직접 선택 | `improve-codebase-architecture` | 일반 아키텍처 논의만으로는 호출하지 않음 |
|
||||
| 사용자가 `setup-matt-pocock-skills`를 직접 선택해 저장소 설정 요청 | `setup-matt-pocock-skills` | 일반 setup 논의나 매 작업마다 자동 실행하지 않음 |
|
||||
|
||||
우선 순서는 요청 유형 분류, 적용할 Superpowers 프로세스 책임자 선택, 필요한 전문 보완 선택이다. 신규 설계의 메인은 `brainstorming`이며 중요한 요구 공백만 `deep-interview` 하위 단계로 넘긴다. 이미 인터뷰나 설계를 끝냈다면 요약을 재사용하고 같은 질문·계획을 다시 실행하지 않는다. 용어 모델 정리 자체는 `domain-modeling`이 맡고 일반 질문·조사는 구현 루프 없이 읽기 전용으로 처리한다.
|
||||
|
||||
프로젝트 규칙에서 고정된 것은 기존 PRD·`plan-task.md` 절차, `docs/YYYYMMDD_.../` 문서 위치, 레거시 보호, 기본 local unit test, 사용자 승인 없는 androidTest/device/UI 실행 금지, 민감정보·Git 안전 규칙이다. skill이 이 범위를 넓히는 근거가 되지 않는다. 현재 문서 작업 범위에서도 전역 설정·설치 파일·코드 수정·커밋은 금지된다.
|
||||
|
||||
## 8. 알려진 공백과 후속 확인
|
||||
|
||||
| 상태 | 확인 결과 또는 남은 항목 | 현재 보고서의 제한 |
|
||||
|---|---|---|
|
||||
| 확인 | Superpowers 양쪽 root에 동일한 15개 top-level definitions 및 지정 metadata scan 결과 반영 | 본문 전체를 읽은 skill은 주요 workflow들로 한정한다. |
|
||||
| 확인 | 다섯 Matt `agents/openai.yaml` 정책 및 Addy 여섯 SKILL frontmatter/scoped metadata 조사 반영 | native runtime에서 자동 호출·권한 통합이 실행되는지는 검증하지 않는다. |
|
||||
| 미검증 | Codex/OpenCode에서 skill을 실제 선택해 발생하는 런타임 동작 | 현재 세션의 광고·파일 존재·CLI 버전은 자동 invocation 증거가 아니다. |
|
||||
| 확인 | Codex Superpowers의 CLI 설치·활성 조회 | `codex plugin list --json`에서 `installed: true`, `enabled: true`; 개별 스킬 자동 선택이나 새 AGENTS 적용 여부와는 별개다. |
|
||||
| 확인 | Addy checklist 참조 네 개의 shared 경로 누락, 사용 가능한 local patterns 두 개 | checklist sign-off가 정상인지 확인되지 않았다. 수리·복사하지 않는다. |
|
||||
| 범위 밖 | 생성물·의존성·별도 worktree 내부의 지침 파일 inventory | 명시된 제외 범위 밖이므로 부재 주장을 하지 않는다. |
|
||||
| 범위 밖 | 모든 환경변수 및 모든 설치 스킬의 완전 목록 | 요청된 경로·변수·스킬에 한정했다. |
|
||||
|
||||
### 전역 범위 후속 제안
|
||||
|
||||
- Codex custom planner `.omo/plans/` 출력/병렬 절차가 실제 사용에서 저장소 PRD·계획 문서와 충돌하는지 검토한 뒤, 전역 조정은 별도 사용자 승인으로만 한다.
|
||||
- Addy reference checklist 네 개의 설치 복구는 별도 승인을 받은 후에만 조사·수정한다. 이번 작업은 `/Users/klaus/.agents/references/` 파일을 생성·복사하지 않았다.
|
||||
- Codex Superpowers의 설치·활성은 읽기 전용으로 확인되어 현재 활성화를 위한 전역 변경 제안은 필요하지 않다. 향후 플러그인·권한 변경이 필요해도 별도 승인 없이 수정하지 않는다.
|
||||
|
||||
## 9. 조사된 로컬 경로
|
||||
|
||||
- 저장소: `/Users/klaus/Develop/sodalive/Android/SodaLive/AGENTS.md`
|
||||
- 작업 요구사항: `/Users/klaus/Develop/sodalive/Android/SodaLive/docs/20261019_스킬_오케스트레이션_우선순위_자동화/prd.md`
|
||||
- 작업 계획: `/Users/klaus/Develop/sodalive/Android/SodaLive/docs/20261019_스킬_오케스트레이션_우선순위_자동화/plan-task.md`
|
||||
- Codex 설정: `/Users/klaus/.codex/config.toml`, `/Users/klaus/.codex/agents/default.toml`, `/Users/klaus/.codex/agents/plan.toml`
|
||||
- OpenCode 설정: `/Users/klaus/.config/opencode/opencode.json`
|
||||
- 사용자 skill inventory 기록: `/Users/klaus/.agents/.skill-lock.json`
|
||||
- Matt/Addy/deep-interview 파일: `/Users/klaus/.agents/skills/<skill>/SKILL.md`
|
||||
- OpenCode commit wrapper: `/Users/klaus/.config/opencode/skills/commit-with-validation/SKILL.md`
|
||||
- Superpowers 경로 및 plugin: §5.1의 Codex/OpenCode 경로, OpenCode cache 내 `.opencode/plugins/superpowers.js`
|
||||
|
||||
### Upstream README 출처
|
||||
|
||||
- Superpowers: <https://raw.githubusercontent.com/obra/superpowers/main/README.md>
|
||||
- Matt Pocock skills: <https://raw.githubusercontent.com/mattpocock/skills/main/README.md>
|
||||
- Addy Osmani skills: <https://raw.githubusercontent.com/addyosmani/agent-skills/main/README.md>
|
||||
|
||||
---
|
||||
|
||||
본 문서는 2026-10-19에 확인된 읽기 전용 근거를 요약한다. 설치·메타데이터·하네스 동작이 바뀔 수 있으므로 이후에는 실제 파일과 공식 문서를 다시 확인한다.
|
||||
Reference in New Issue
Block a user