범람시키지 말고 경로를 지정하세요: Oracle 인식 어시스턴트를 안내하기 위한 db/SKILL.md 활용법

만약 당신이 어시스턴트를 "Oracle 인식(Oracle-aware)" 상태로 만들려고 시도해 보았다면, 아마도 동일한 벽에 부딪혔을 것입니다. 링크를 한 더미씩 붙여넣으면, 모델은 특정 벤더에 중립적인 습관과 오래된 Oracle 가이드를 뒤섞어 버리고, 정밀함이 필요한 순간에 답변은 모호해집니다. 해결책은 더 많은 컨텍스트(Context)를 제공하는 것이 아니라, 더 나은 라우팅(Routing)입니다. 한 번에 하나의 Oracle 기술을, 올바른 순서에 따라 제공하여 다음 모든 단계가 Oracle 자체의 시퀀스(Sequence)를 따르도록 하는 것입니다. Article 1에서 우리는 Oracle Database 상의 AI를 위한 운영 모델인 '라우팅(route) → 실행(act) → 신뢰(trust)'를 개괄했습니다. 이 글은 첫 번째 동사인 '라우팅'에 대해 깊이 있게 다룹니다. 공개된 Oracle Database Skills 저장소의 db/SKILL.md를 어떻게 입구로 사용할 수 있는지, 페르소나(Persona)나 작업(Task)별로 어떻게 라우팅하는지, 그리고 어시스턴트가 한 번에 정확히 하나의 파일만 로드하도록 점진적 발견(Progressive discovery)을 어떻게 강제하는지를 보여줍니다. 이 글은 실행(Execution)을 다루지 않습니다. 우리는 라우팅 차선에 머물 것이며, 도구에 관한 내용은 Article 3(SQLcl MCP)로 넘깁니다. 전제 조건: 웹 브라우저에서 https://github.com/oracle/skills 를 탐색할 수 있기만 하면 됩니다.

라우팅이 컨텍스트 덤핑(Context dumping)보다 나은 이유
프롬프트에 링크 더미를 쏟아붓는 것은 철저해 보이지만, 버전 경계를 흐리고 일반적인 "SQL" 패턴이 Oracle 특화 가이드를 압도하게 만듭니다. 또한 다음 의사결정을 개선하지 못한 채 토큰 예산(Token budgets)만 낭비합니다. db/SKILL.md는 유지 관리되는 Oracle Database 기술 지도를 제공하고, 일반적인 작업에 적합한 시작 파일을 안내하며, 다단계 워크플로(Workflows)를 위한 짧고 주관적인 시퀀스를 인코딩함으로써 이 문제를 해결합니다. 목표는 모든 것을 읽는 것이 아닙니다. 다음 파일을 선택하고, 그것을 소화한 뒤, 파일이 하나 더 필요한지 결정하는 것입니다. 실제로 명령을 실행할 준비가 되면, 당신은 라우팅을 떠나 "실행(act)" 단계로 진입한 것입니다(Article 3에서 SQLcl MCP를 다룹니다).

db/SKILL.md를 입구로 취급하세요
db/SKILL.md는 Database 도메인을 위한 라우터입니다. 이는 라우팅 테이블(Routing table)과 컨텍스트를 타이트하게 유지하기 위한 가이드로 시작합니다. 테이블에서 시작하여, 필요한 특정 파일이나 카테고리만 읽으십시오.

또한 다음과 같은 디렉토리를 포함하여 Database skills (데이터베이스 기술)의 형태를 보여줍니다: db/agent, db/features, db/frameworks, db/performance, db/security, db/devops, db/migrations, db/sqlcl. 첫 번째 검토 시 가장 중요한 두 가지 부분이 있습니다. 첫째, 이 파일은 실제 작업에 대한 구체적인 진입점(entry points)을 강조합니다. 즉, 성능 분류(performance triage)가 어디서 시작되는지, SQLcl 기초 및 MCP 서버 진입점(설정은 Article 3로 미룸)이 어디에 있는지, 스키마 마이그레이션(schema migrations)에 어떻게 접근해야 하는지, 그리고 코드를 작성하기 전에 반드시 이해해야 하는 에이전트 동작(스키마 검색(schema discovery) 등)이 무엇인지 알려줍니다. 둘째, 가드레일(guardrails) 역할을 하는 일반적인 시퀀스(sequences)를 개괄합니다. 예시로는 RAG (db/features 하위 기술: ai‑profiles → vector‑search → dbms‑vector), 느린 쿼리 진단 (db/performance 하위 기술: explain‑plan → wait‑events → optimizer‑stats → awr‑reports), 그리고 에이전트 안전 스키마 변경 (db/agent 및 db/migrations 하위 기술: schema‑discovery → destructive‑op‑guards → idempotency‑patterns → schema‑migrations) 등이 있습니다. 또한 라우팅(routing)에서 액션(action)으로 넘어갈 때 나중에 사용하게 될 MCP 설정 경로도 있습니다: sqlcl‑basics → db/security 내의 최소 권한/권한 관리(least‑privilege/privilege‑management) 기술 → sqlcl‑mcp‑server. 여기서부터 시작하면 어시스턴트의 동작 방식이 바뀝니다. 인터넷에서 관련 있어 보이는 것을 무작정 가져오는 대신, "다음 Oracle 작성 파일은 무엇인가요?"라고 묻게 됩니다. 그 결과 잘못된 방향으로 가는 일이 줄어들고, 더 짧고 검토 가능한 프롬프트(prompts)를 얻을 수 있습니다.

프로젝트 범위를 정할 때는 페르소나(persona)에 따라 경로를 지정하세요
티켓에 응답하는 것이 아니라 범위를 정의할 때는, 자신의 역할에 맞춰 파일 하나를 로드하십시오. 저장소 전체를 먼저 훑어보지 마십시오. 경로를 지정하고, 읽고, 결정하십시오.

앱 개발자 (App developer)
서비스를 Oracle에 연결하는 경우, 프레임워크(frameworks)부터 시작하여 애플리케이션 특정 기술을 계층적으로 쌓아 올리십시오. db/frameworks 디렉토리는 Spring, Django, SQLAlchemy와 같은 스택에 대한 가이드를 제공합니다: 연결 구성(connection configuration), 드라이버/방언(driver/dialect) 선택, 데이터 타입 매핑(data type mapping), 그리고 권장되는 연결 패턴(connection patterns) 등이 포함됩니다.

프레임워크가 설정되면, 실제로 필요한 JSON, Spatial, Text 또는 풀링(pooling)의 미세한 차이를 다루는 app-dev 기술로 깊이 들어갑니다. 이 순서대로 진행하면 불필요한 시행착오를 피할 수 있습니다. 즉, 커스텀(customize)을 하기 전에 Oracle에서 검증된 경로를 채택하게 됩니다. AI 엔지니어(AI engineer)는 db/agent와 db/features에서 시작하십시오. agent 기술은 모델이 데이터베이스에 접근할 때 중요한 동작들을 다룹니다: DML 수행 전 스키마(schema) 탐색, 파괴적인 작업(destructive operations) 방지, 재시도 시 중복 적용되지 않도록 단계의 멱등성(idempotent) 확보, 그리고 추적 가능성(traceability)을 위한 클라이언트 식별 등이 포함됩니다. features 기술은 Oracle의 AI 네이티브 빌딩 블록(building blocks)을 소개합니다: 거버넌스가 적용된 NL2SQL을 위한 Select AI 및 AI Profiles, 그리고 검색 및 RAG를 위한 AI Vector Search/DBMS_VECTOR가 이에 해당합니다. 버전 제한(Version gate): 각 기능의 문서를 확인하십시오. DBMS_VECTOR와 많은 Select AI/AI Profiles 예제는 26ai를 기준으로 문서화되어 있으며, 여러 AI 기능은 Autonomous Database에서도 사용할 수 있습니다. 기술이나 문서에 명시적으로 기재되어 있지 않는 한 19c에서 사용 가능하다고 가정하지 마십시오. DBA는 어시스턴트로부터 Oracle 네이티브 결과물을 얻는 가장 빠른 방법으로, db/performance를 거쳐 db/security로 경로를 지정하는 것입니다. Performance 기술은 어시스턴트가 실제로 실행된 실행 계획(plan)을 획득하고 읽는 법(예: DBMS_XPLAN.DISPLAY_CURSOR(NULL, NULL, 'ALLSTATS LAST')를 통해), 로우 소스(row sources)와 카디널리티(cardinality)를 해석하는 법, 그리고 적절한 시점에 실행 계획 읽기에서 대기 이벤트(wait events)로, 필요하다면 AWR로 전환하는 법을 가르칩니다. Security 기술은 권한 설계, 감사(auditing), 암호화(encryption)를 Oracle의 용어로 정립하여, "최소 권한(least privilege)"이 단순한 슬로건이 아닌 실행 가능한 설계가 되도록 합니다. 마이그레이션 리드(Migration lead)는 db/migrations와 db/devops를 하나의 작업의 두 부분으로 취급하십시오. Migration 기술은 평가 및 변환을 돕고, devops 기술은 스키마 변경 워크플로, 온라인 작업(online operations), Edition-Based Redefinition, 테스트와 같은 전달 메커니즘(delivery mechanics)을 처리합니다. 파일을 한 번에 하나씩 로드함으로써 이기종 환경(heterogeneous estates)이 일반적이고 최저 공통 분모 수준의 조언으로 무너지는 것을 방지합니다.

업무 시간이 촉박할 때는 작업별로 경로를 지정하세요. 단일 작업이 포함된 티켓이 도착하면 리포지토리(repository)에 정의된 순차적 시퀀스를 따르십시오. Oracle의 진단(diagnostics)과 기본값(defaults)에는 그만한 이유가 있는 주관(opinionated)이 담겨 있습니다. 이 순서를 무시하는 것은 대개 시간 낭비로 이어집니다.

Oracle Database에서의 RAG (Retrieval-Augmented Generation)
AI Profiles부터 시작하십시오. 그곳에서 제공자(provider)와 모델(model)을 선택하고, 결정적으로 모델이 볼 수 있는 데이터베이스 객체(database objects)를 정의하기 때문입니다. 범위(scope)와 거버넌스(governance)가 설정된 후에야 벡터 검색(vector-search)의 검색 패턴(retrieval patterns)을 학습하고, 그 다음 DBMS_VECTOR를 사용하여 파이프라인을 오케스트레이션(orchestrate)해야 합니다. 그 결과는 데이터베이스에 임베딩(embeddings) 뭉치를 대충 붙여놓은 것이 아니라, 검사(SHOW SQL)가 가능하고(OBJECT_LIST 및 데이터 액세스 제어로) 강화할 수 있는 거버넌스가 적용된 RAG 흐름입니다.

경로 (db/features 하위의 기술들): ai-profiles → vector-search → dbms-vector
참조: Select AI 예시 (SHOW SQL, OBJECT_LIST 및 데이터 액세스 제어): https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/examples-using-select-ai.html
버전 참고: 기능 문서를 따르십시오. DBMS_VECTOR와 많은 Select AI/AI Profiles 예시는 26ai를 기준으로 문서화되어 있습니다. 여러 AI 기능은 Autonomous Database에서도 사용할 수 있습니다. 기술이나 문서에 명시적으로 기재되어 있지 않는 한 19c에서 사용 가능하다고 가정하지 마십시오.

느린 쿼리 진단 (Slow-query diagnosis)
실제로 실행된 실행 계획(plan)을 읽는 것부터 시작하십시오. Oracle에서 이는 EXPLAIN PLAN 추정치에만 의존하는 것이 아니라, 커서(cursor)로부터 실행된 계획을 캡처하는 것을 의미합니다 (예: DBMS_XPLAN.DISPLAY_CURSOR(NULL, NULL, 'ALLSTATS LAST')). 실행 계획이 정상적으로 보임에도 런타임(runtime)에서 정체된다면, 대기 이벤트(wait events)로 전환하십시오. 행(rows)과 조인(joins)이 잘못 추정되었다면, AWR로 분석 범위를 넓히기 전에 통계 정보(statistics)와 카디널리티(cardinality)를 먼저 수정하십시오.

경로 (db/performance 하위의 기술들): explain-plan → wait-events → optimizer-stats → awr-reports
가용성 참고: AWR/ASH 액세스는 환경 및 라이선스에 따라 달라집니다.

에이전트 안전형 스키마 변경 (Agent-safe schema change)
변경을 제안하기 전에 무엇이 존재하는지 먼저 파악하고, 단 하나의 잘못된 술어 (predicate)가 테이블을 손상시키지 않도록 손실 방지 (loss-prevention) 기능을 추가하며, 재시도 시 중복 적용되지 않도록 각 단계를 멱등적 (idempotent)으로 만드세요. 오직 그 후에야 감사 가능한 마이그레이션 워크플로우 (audited migration workflow)로 진입해야 합니다. 경로 지정 (db/agent 및 db/migrations 하위의 skills): 스키마 발견 (schema-discovery) → 파괴적 작업 방어 (destructive-op-guards) → 멱등성 패턴 (idempotency-patterns) → 스키마 마이그레이션 (schema-migrations)

점진적 발견을 강제하는 컴팩트한 프롬프트
작은 프롬프트 하나가 경로 지정, 파일 하나 읽기, 요약, 결정의 루프를 강제함으로써 에이전트가 임의로 행동하는 것 (freelancing)을 방지할 수 있습니다. 이러한 규율은 컨텍스트 (context)를 정확하고 비용 효율적으로 유지합니다.

프롬프트
db/SKILL.md를 여세요. 나는 [페르소나 또는 작업]입니다. 다음에 로드해야 할 단일 스킬 파일은 무엇이며, 그 이유는 무엇입니까? 해당 파일을 5개의 불렛 포인트로 요약한 다음, 다음 결정(다른 파일 읽기 또는 중단)을 제안하세요. 어떤 작업도 실행하지 마세요.

점진적 라우팅 루프 (Progressive routing loop)
미니 데모 (DB 액세스 없음, 실행 없음)
이 프롬프트들은 도구를 연결하기 전에 라우팅 동작을 검증합니다. 이들은 의도적으로 "읽고 결정하기"로 제한되어 있습니다.

데모 A: Spring 앱 개발자를 위한 페르소나 우선 경로
프롬프트
db/SKILL.md를 여세요. 나는 Spring Boot 서비스를 Oracle에 연결하고 있습니다. 다음에 로드해야 할 단일 frameworks/appdev 스킬은 무엇이며, 그 이유는 무엇입니까? 해당 파일을 5개의 불렛 포인트로 요약한 다음, 다음 결정을 제안하세요. 어떤 작업도 실행하지 마세요.

어시스턴트 응답 예시
다음 파일: db/frameworks/ 하위의 A Spring Data JPA with Oracle 스킬. 이유: Oracle 전용 연결 설정, 드라이버/방언 (dialect) 선택, 풀링 (pooling) 및 타입 매핑을 다룹니다. 요약:

• Spring Boot를 위한 권장 Oracle JDBC URL 형식 및 서비스 명명법
• 방언/드라이버 선택 및 일반적인 DataSource 함정
• Oracle에 최적화된 트랜잭션, 배치 (batching) 및 페치 크기 (fetch-size) 옵션
• LOB, DATE/TIMESTAMP 및 NUMBER 매핑 고려 사항
• 스타터 체크 및 후속 appdev 스킬로의 링크

다음 결정:

• 풀링/재시도/서킷 브레이커의 세부 사항이 필요한 경우, 다음에 연결/풀링 스킬을 읽으세요.
• 그렇지 않다면, 중단하고 다음 단계로 진행하기 전에 이러한 구성 단계들을 적용하세요.

데모 B: 느린 쿼리 (slow query) 진단을 위한 작업 우선 경로 (Task‑first route)

프롬프트
db/SKILL.md에서 시작하여, 느린 쿼리 분류 (triage)를 위한 순차적인 스킬 파일 목록을 나열하세요. 첫 번째 파일만 로드하고, 이를 5개의 불렛 포인트로 요약한 다음, 다음 파일을 읽을지 아니면 중단할지를 권장하세요. 어떠한 작업도 실행하지 마세요.

어시스턴트 응답 예시
정렬된 파일:

1. db/performance/ 내의 explain-plan 스킬
2. db/performance/ 내의 wait-events 스킬
3. db/performance/ 내의 optimizer-stats 스킬
4. db/performance/ 내의 awr-reports 스킬

로드됨: explain-plan

요약:

• 커서(cursor)로부터 실행된 플랜(executed plan)을 확보하는 방법(EXPLAIN PLAN 추정치와 비교) 및 해당 위치 확인
• 로우 소스(row sources) 및 카디널리티(cardinality) 읽기; 잘못된 추정 및 조인 순서(join-order) 문제 식별
• 안티 패턴(anti-patterns) 인식 (강제 전체 스캔, 왜곡된 히스토그램, 암시적 형변환)
• 적응형 기능(adaptive features) 및 병렬 결정(parallel decisions)을 위한 플랜 노트(plan notes) 해석
• 플랜 분석에서 대기 이벤트(wait-event) 조사로 전환할 시점 결정

권장 사항:

• 플랜이 합리적으로 보이지만 런타임(runtime)에서 정체된다면 다음으로 wait-events를 읽으세요.
• 플랜이 명백히 잘못되었다면, 중단하고 다음 단계로 진행하기 전에 플랜 문제를 수정하세요.

참고 사항:
이 경로의 “explain‑plan” 스킬은 단순히 EXPLAIN PLAN 추정치를 보는 것이 아니라, 실제 커서 플랜(actual cursor plan)을 캡처하고 읽는 법을 가르칩니다. AWR/ASH는 모든 환경에서 사용 가능하지 않을 수 있으며 라이선스(licensing)가 필요할 수 있습니다.

버전 범위 및 컨텍스트 예산 규율 (Version scope and context‑budget discipline)
스킬에서 더 높은 요구 사항을 명시하지 않는 한, Oracle Database 19c를 기준으로 가정합니다. AI 기능의 경우, 기능별 문서를 확인하세요: DBMS_VECTOR와 많은 Select AI/AI Profiles 예제들은 26ai를 위해 문서화되어 있습니다; 여러 AI 기능들은 Autonomous Database에서도 사용할 수 있습니다. 스킬이나 문서에서 명시적으로 언급하지 않는 한 19c에서 사용 가능하다고 가정하지 마세요. 경로를 지정할 때 해당 단계들을 명확하게 표시하세요.

어시스턴트를 정확하고 비용 효율적으로 유지하는 두 가지 습관:

1. 한 번에 하나의 파일 또는 짧은 인덱스만 로드한 다음, 5개의 불렛 포인트로 요약하세요.
2. 중단할지, 하나를 더 읽을지, 아니면 작업(Article 3의 SQLcl MCP)으로 넘길지를 결정하세요. 경로 지정(routing)과 실행(execution)을 혼동하지 마세요.

왜 “범람시키지 말고 경로를 지정하세요”가 압박 속에서도 유효한가

팀들은 마감 기한이 다가오면 컨텍스트 (Context)를 대량으로 로드 (bulk-load) 하는 경향이 있습니다. 역설적이게도, 점진적 발견 (progressive discovery)은 시간이 촉박할 때 가장 큰 효과를 발휘합니다. db/SKILL.md는 Oracle의 경험을 신뢰할 수 있는 짧은 경로로 압축합니다. 대기 시간을 찾아 헤매기 전에 실행된 계획 (executed plan)을 먼저 읽고, 검색 (retrieval)을 실험하기 전에 AI 프로필 (AI Profile)의 범위를 정하며, 어떠한 스키마 (schema) 변경을 수용하기 전에 발견 (discovery)과 가드레일 (guards)을 증명하십시오. 이러한 차선 (lanes)을 유지하는 것은 속도를 늦추는 것이 아니라, 며칠을 허비하게 만드는 우회로를 제거하는 것입니다.

정문(front door)에 쉽게 도달하게 만드세요. 가장 간단한 방법은 웹 브라우저에서 리포지토리 (repository)를 탐색하고 db/SKILL.md를 여는 것입니다. 로컬 복사본을 선호한다면, Database 도메인을 직접 설치하십시오: npx skills add oracle/skills/db. 이렇게 하면 도메인 파일들이 작업 디렉토리 (working directory)에 배치되어 즉시 db/SKILL.md를 열 수 있습니다. 그런 다음 어시스턴트 (assistant)의 “Oracle Database” 시스템 프롬프트 (system prompt)를 “Open db/SKILL.md”로 시작하도록 설정하고, 다음 결정이 진정으로 실행 (act)하는 단계가 될 때까지 점진적 발견 (progressive-discovery) 루프를 유지하십시오.

결론
Oracle Database Skills는 PDF d