Skip to main content
최종 업데이트: 2026-04-08
Genie Code를 처음 열면 프롬프트 입력만 보이지만, 설정을 제대로 구성하면 동일한 프롬프트에서도 완전히 다른 수준의 결과 를 얻을 수 있습니다. 이 가이드는 Genie Code의 모든 설정 항목을 체계적으로 설명하고, 역할별 최적 구성과 실전 운영 모범사례를 다룹니다.

​
1. 설정 화면 구성 요소

Genie Code 패널 상단의 톱니바퀴(Settings) 아이콘을 클릭하면 다섯 가지 설정 영역이 나타납니다. 각 영역이 Genie Code의 동작에 미치는 영향을 이해하는 것이 효과적 활용의 출발점입니다.
설정 항목역할영향 범위누가 설정하는가
MCP 서버외부 도구 연동 (Slack, JIRA, GitHub 등)해당 사용자의 Agent 모드 세션개인 사용자
패널 뷰Docked(하단 고정) / Side(우측 패널) 전환UI 레이아웃만 변경개인 사용자
User Instructions개인용 지속적 지침 — 모든 대화에 자동 적용해당 사용자의 모든 Genie Code 세션개인 사용자
Workspace Instructions조직 전체 지침 — 모든 사용자에게 적용워크스페이스 전체워크스페이스 관리자
Skills재사용 가능한 작업 템플릿 (Agent 모드 전용)User 스킬은 개인, Workspace 스킬은 전체개인 또는 관리자
이 다섯 가지 중 User Instructions, Workspace Instructions, Skills 가 Genie Code의 응답 품질에 직접적인 영향을 미칩니다. MCP 서버는 Agent 모드의 활용 범위를 결정하고, 패널 뷰는 순수하게 UI 편의 설정입니다.
참고 Genie Code는 응답 생성 시 Workspace Instructions를 User Instructions보다 우선 적용합니다. 두 지침이 충돌하면 Workspace Instructions가 이깁니다. 이는 조직의 보안 정책이 개인 선호보다 항상 우선하도록 설계된 것입니다.

​
2. User Instructions 작성법

​
2.1 User Instructions란?

User Instructions는 Genie Code에게 “나는 이런 사람이고, 이렇게 일해줬으면 좋겠어” 라고 지속적으로 알려주는 개인화 지침입니다. 한 번 설정하면 새 대화를 열 때마다 자동으로 적용되므로, 매번 같은 요구사항을 반복할 필요가 없어집니다.

​
2.2 생성 방법

User Instructions를 설정하는 두 가지 방법이 있습니다. 방법 1: UI에서 직접 설정
  1. Genie Code 패널 상단의 톱니바퀴(Settings) 아이콘 클릭
  2. User instructions 섹션 찾기
  3. “지침 파일 추가(Add instruction file)” 클릭
  4. 마크다운 에디터에 지침 작성 후 저장
방법 2: 파일 직접 생성 사용자 디렉토리에 .assistant_instructions.md 파일을 생성합니다: 
/Workspace/Users/{your-email}/.assistant_instructions.md
주의 User Instructions의 최대 길이는 20,000자 입니다. 이 안에서 가장 중요한 지침을 상위에 배치하세요. LLM은 지침의 앞부분에 더 높은 가중치를 부여하는 경향이 있습니다.

​
2.3 효과적인 User Instructions 구조

좋은 User Instructions는 구조화된 마크다운 으로 작성됩니다. 헤딩(##)으로 카테고리를 나누고, 불릿(-)으로 구체적 규칙을 나열하면 Genie Code가 각 규칙을 명확하게 구분하여 적용합니다.

​
2.4 좋은 User Instructions 예시

다음은 데이터 엔지니어를 위한 실전 User Instructions 예시입니다: 
## 내 역할과 컨텍스트
- 나는 데이터 엔지니어이며, 주로 Delta Lake 파이프라인과 SQL 분석 작업을 합니다
- 우리 팀의 프로덕션 카탈로그는 `main_catalog`이고, 개발용은 `dev_catalog`입니다
- 사용하는 클라우드: AWS (S3, Glue, Redshift 연동)

## 코딩 스타일
- Python 코드는 PEP 8을 따르세요
- SQL은 대문자 키워드를 사용하세요 (SELECT, FROM, WHERE)
- 변수명은 snake_case를 사용하세요
- 함수에는 반드시 docstring을 포함하세요
- 타입 힌트를 사용하세요 (Python 3.10+ 스타일)

## 선호 라이브러리 & 프레임워크
- 데이터 처리: PySpark (pandas 대신)
- 시각화: Plotly (matplotlib 대신)
- ML: MLflow + scikit-learn
- 테스트: pytest + Great Expectations

## 보안 규칙 (절대 위반 금지)
- 프로덕션 테이블(main_catalog.prod.*)은 절대 수정하지 마세요
- DROP TABLE, DELETE, UPDATE 문은 생성하지 마세요
- 임시 결과는 dev_catalog.sandbox.simyung 스키마에 저장하세요
- 민감 컬럼(ssn, email, phone)은 마스킹 처리하세요
- 자격 증명(password, token, key)을 코드에 하드코딩하지 마세요

## 응답 스타일
- 코드 블록 앞에 간단한 설명을 붙여주세요
- 복잡한 쿼리에는 인라인 주석을 추가하세요
- 한국어로 응답하세요
이 예시가 효과적인 이유는 다음과 같습니다:
  1. 역할과 도메인을 명시 해서 Genie Code가 적절한 수준과 맥락으로 응답합니다
  2. 구체적 카탈로그/스키마 이름을 포함 해서 생성되는 코드가 실제 환경에 맞습니다
  3. 금지 사항을 명확히 구분 해서 위험한 작업을 사전에 차단합니다
  4. 선호 라이브러리를 지정 해서 일관된 기술 스택으로 코드를 생성합니다

​
2.5 나쁜 User Instructions와 개선 방향

다음은 흔히 저지르는 실수와 왜 비효과적인지를 보여줍니다. 나쁜 예시 1: 너무 모호한 지침 
좋은 코드를 작성해주세요.
버그 없이 짜주세요.
빠른 코드를 만들어주세요.
“좋은”, “빠른” 같은 추상적 형용사는 LLM에게 구체적 행동 변화를 유도하지 못합니다. 무엇이 “좋은” 것인지 구체적으로 정의 해야 합니다. 나쁜 예시 2: 상충되는 지침 
- 코드를 최대한 간결하게 작성하세요
- 모든 에러 케이스를 처리하세요
- 모든 함수에 상세한 docstring을 추가하세요
- 한 줄이라도 줄여주세요
간결함과 상세한 에러 처리/문서화는 본질적으로 상충합니다. 우선순위를 정하거나 상황별로 구분해야 합니다. 나쁜 예시 3: 역할과 무관한 과잉 지침 
## JavaScript 규칙
- React 18을 사용하세요
- TypeScript strict 모드를 적용하세요

## CSS 규칙
- Tailwind CSS를 사용하세요
- BEM 네이밍을 따르세요

## DevOps 규칙
- Docker multi-stage build를 사용하세요
Genie Code는 Databricks 환경의 데이터 작업 에 특화되어 있습니다. JavaScript, CSS, DevOps 관련 지침은 의미가 없을 뿐 아니라, 20,000자 제한 내에서 실제로 필요한 지침의 자리를 차지합니다.
팁 User Instructions는 자주 반복하게 되는 지침 만 포함하세요. 일회성 요구사항은 프롬프트에서 직접 지시하는 것이 더 효과적입니다. 지침이 너무 많으면 오히려 핵심 규칙이 희석됩니다.

​
3. Workspace Instructions 설정

​
3.1 왜 Workspace Instructions가 필요한가?

User Instructions는 개인 선호이므로 사람마다 다릅니다. 하지만 조직에는 모든 사람이 반드시 따라야 하는 규칙 이 있습니다. 보안 정책, 네이밍 컨벤션, 데이터 접근 규칙 등이 그것입니다. Workspace Instructions는 이러한 조직 수준의 규칙을 한 곳에서 관리하고, 모든 사용자의 Genie Code 세션에 자동으로 강제 적용 합니다. User Instructions가 “나는 이렇게 해줘”라면, Workspace Instructions는 “우리 조직에서는 반드시 이렇게 해야 해” 입니다.

​
3.2 생성 방법

워크스페이스 관리자가 다음 경로에 파일을 생성합니다: 
/Workspace/.assistant_workspace_instructions.md
주의 Workspace Instructions는 워크스페이스 관리자만 생성하고 수정 할 수 있습니다. 일반 사용자는 이 파일을 읽을 수 있지만 변경할 수 없습니다. 이는 보안 정책이 개인에 의해 우회되는 것을 방지하기 위한 설계입니다.

​
3.3 효과적인 Workspace Instructions 예시

다음은 데이터 팀을 위한 실전 Workspace Instructions입니다: 
## 조직 코딩 표준
- 모든 테이블 참조는 Unity Catalog 3-level 네이밍을 사용하세요 (catalog.schema.table)
- 2-level 네이밍(schema.table)이나 1-level 네이밍(table)은 사용하지 마세요
- 파이프라인 코드에는 반드시 try-except 에러 핸들링을 포함하세요
- 로깅은 Python logging 모듈을 사용하고, print()로 디버깅하지 마세요

## 데이터 레이어 네이밍 컨벤션
- Bronze 테이블: raw_{소스시스템}_{엔티티} (예: raw_sap_orders)
- Silver 테이블: clean_{도메인}_{엔티티} (예: clean_sales_orders)
- Gold 테이블: agg_{비즈니스영역}_{메트릭} (예: agg_revenue_daily)
- 임시 테이블: tmp_{작성자}_{목적} (예: tmp_simyung_test_join)

## 데이터 접근 정책
- PII 테이블 목록: hr.employees, crm.contacts, crm.customers
- 위 테이블 접근 시 반드시 마스킹 함수 적용: mask_pii(column_name)
- 프로덕션 카탈로그(prod_catalog)에 대해 DDL/DML 문 생성 금지
- 개발 작업은 반드시 dev_catalog 내에서 수행

## SQL 스타일 가이드
- 키워드는 대문자: SELECT, FROM, WHERE, JOIN, GROUP BY
- 테이블 alias는 의미 있는 약어 사용 (o for orders, c for customers)
- 서브쿼리 대신 CTE(WITH 절)를 우선 사용
- 쿼리에는 반드시 LIMIT 절을 포함 (개발 단계에서는 기본 1000)

## 보안 필수 규칙
- 자격 증명, 비밀번호, API 키를 코드에 절대 포함하지 마세요
- Databricks Secrets를 사용하세요: dbutils.secrets.get(scope, key)
- 외부 API 호출 시 반드시 타임아웃을 설정하세요 (기본 30초)
이 Workspace Instructions가 효과적인 이유는 조직의 핵심 규칙을 구조화된 카테고리 로 분류하고, 각 규칙에 구체적 예시 를 포함하여 해석의 모호함을 제거했기 때문입니다. 특히 네이밍 컨벤션에 실제 패턴과 예시를 함께 제공하면, Genie Code가 새 테이블이나 파이프라인을 생성할 때 자동으로 이 패턴을 따릅니다.

​
3.4 User Instructions와 Workspace Instructions의 역할 분리

두 지침의 목적이 다르므로, 내용도 명확히 구분해야 합니다.
구분User Instructions에 적합Workspace Instructions에 적합
코딩 스타일개인 선호 (들여쓰기 스타일, 주석 언어)조직 표준 (네이밍 컨벤션, 필수 에러 처리)
라이브러리선호 라이브러리 (Plotly vs matplotlib)금지 라이브러리 (보안 취약 패키지)
데이터 접근자주 쓰는 스키마/테이블PII 정책, 프로덕션 접근 제한
응답 형식언어 선호, 상세도로깅/문서화 의무 사항
보안개인 sandbox 스키마조직 전체 보안 규칙
개인 선호와 조직 규칙이 같은 곳에 섞이면 관리가 어렵고, 규칙 충돌 시 어떤 것이 우선인지 혼란이 생깁니다. 조직이 강제해야 할 규칙은 Workspace Instructions에, 개인이 선택할 수 있는 선호는 User Instructions에 분리하는 것이 원칙입니다.

​
4. Skills 생성 및 활용

​
4.1 Skills란?

Skills는 재사용 가능한 작업 템플릿 입니다. User Instructions가 “이렇게 해줘”라는 규칙 이라면, Skills는 “이 작업을 할 때는 이 절차를 따라라”라는 레시피 입니다. Agent 모드에서만 동작하며, Genie Code가 사용자의 요청을 분석하여 관련 스킬을 자동으로 로드하거나, 사용자가 @스킬명 으로 직접 호출할 수 있습니다. Skills가 필요한 상황의 핵심 판단 기준은 다음과 같습니다: 같은 유형의 작업을 여러 번 반복하면서 매번 동일한 절차와 규칙을 프롬프트에 작성하고 있다면, 그것은 스킬로 만들어야 합니다.

​
4.2 폴더 구조

Skills는 정해진 디렉토리 구조를 따릅니다: Workspace 스킬 (모든 사용자 공유): 
/Workspace/.assistant/skills/{skill-name}/
├── SKILL.md           # 스킬 정의 (필수)
├── template.py        # 관련 스크립트 (선택)
└── examples/          # 참고 파일 (선택)
    └── sample.sql
User 스킬 (개인 전용): 
/Workspace/Users/{email}/.assistant/skills/{skill-name}/
├── SKILL.md           # 스킬 정의 (필수)
└── ...

​
4.3 SKILL.md 작성법

모든 스킬은 SKILL.md 파일로 정의됩니다. YAML frontmatter에 메타데이터를 넣고, 본문에 상세 지침을 작성합니다: 
---
name: data-quality-check
description: 테이블의 데이터 품질을 검증하고 리포트를 생성합니다
---

# 데이터 품질 검증 스킬

## 이 스킬을 사용하는 경우
- 사용자가 테이블의 데이터 품질을 확인하고 싶을 때
- 새로운 데이터 소스를 수집한 후 품질 검증이 필요할 때
- 정기적인 데이터 품질 리포트를 생성할 때

## 실행 절차

### 1단계: 테이블 프로파일링
대상 테이블에 대해 다음 항목을 분석하세요:
- 전체 행 수, 컬럼 수
- 각 컬럼의 null 비율
- 각 컬럼의 고유값(distinct) 수
- 숫자 컬럼의 min/max/mean/std
- 문자 컬럼의 최소/최대 길이

### 2단계: 품질 규칙 점검
다음 규칙을 점검하고 위반 건수를 집계하세요:
- PK 컬럼의 중복 여부
- NOT NULL이어야 하는 컬럼의 null 존재 여부
- 날짜 컬럼이 합리적 범위 내인지 (미래 날짜 없음)
- 숫자 컬럼이 비정상 범위가 아닌지 (음수 매출 등)

### 3단계: 리포트 생성
분석 결과를 다음 형식으로 정리하세요:
- 요약: 전체 점수 (통과율 %)
- 상세: 각 규칙별 통과/실패 건수
- 권장 조치: 실패한 항목에 대한 조치 방안

​
4.4 실전 스킬 예시

​
예시 1: 파이프라인 템플릿 생성 스킬

---
name: pipeline-template
description: Bronze/Silver/Gold 레이어별 DLT 파이프라인 코드를 생성합니다
---

# 파이프라인 템플릿 생성

## 이 스킬을 사용하는 경우
- 새로운 데이터 소스를 위한 파이프라인을 구축할 때
- 기존 배치 파이프라인을 DLT로 마이그레이션할 때

## 필수 입력
사용자에게 다음 정보를 확인하세요:
1. 소스 시스템 (S3, JDBC, Kafka 등)
2. 대상 카탈로그와 스키마
3. 증분 처리 여부 (전체 로드 vs CDC)
4. 스케줄 주기

## 생성 규칙
- Bronze: 소스를 있는 그대로 수집. 컬럼 추가: _ingested_at, _source_file
- Silver: 타입 캐스팅, null 처리, 중복 제거. 컬럼 추가: _processed_at
- Gold: 비즈니스 로직 적용, 집계 테이블 생성
- 모든 테이블은 DLT @dlt.table() 데코레이터 사용
- Expectations 정의 포함 (null 검사, 범위 검사)
- 네이밍: Workspace Instructions의 컨벤션을 반드시 따를 것

​
예시 2: 대시보드 생성 스킬

---
name: dashboard-builder
description: 분석 결과를 AI/BI 대시보드로 구성합니다
---

# 대시보드 생성

## 이 스킬을 사용하는 경우
- 분석 결과를 시각화하여 공유할 때
- 정기 리포트용 대시보드를 만들 때

## 실행 절차

### 1단계: 데이터 확인
- 대시보드에 표시할 테이블/뷰의 스키마를 확인하세요
- 시간 축이 될 날짜 컬럼을 식별하세요
- 주요 차원(dimension)과 측정값(measure)을 구분하세요

### 2단계: 시각화 구성
다음 순서로 위젯을 구성하세요:
1. 상단: KPI 카드 (핵심 지표 3~5개)
2. 중단: 트렌드 차트 (시계열 라인/바 차트)
3. 하단: 상세 테이블 (드릴다운용)

### 3단계: SQL 쿼리 작성 규칙
- 각 위젯별 독립 SQL 쿼리 작성
- 파라미터 위젯으로 날짜 범위 필터 추가
- 쿼리에 반드시 주석으로 위젯 목적 설명 포함

### 4단계: 발행
- Databricks AI/BI 대시보드 형식으로 생성
- 권한 설정: 팀 그룹에 VIEW 권한 부여

​
예시 3: 데이터 품질 모니터링 스킬

---
name: quality-monitor
description: Unity Catalog 모니터를 설정하고 알림 규칙을 구성합니다
---

# 데이터 품질 모니터링 설정

## 이 스킬을 사용하는 경우
- 프로덕션 테이블에 지속적 품질 모니터링을 설정할 때
- 데이터 드리프트 감지가 필요할 때

## 실행 절차

### 1단계: 모니터 대상 분석
- 대상 테이블의 스키마와 데이터 특성 파악
- 시간 기준 컬럼(timestamp column) 식별
- 모니터링할 핵심 컬럼 선정

### 2단계: Lakehouse Monitor 생성
```python
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()

# 스냅샷 모니터 또는 시계열 모니터 생성
monitor = w.quality_monitors.create(
    table_name="catalog.schema.table",
    assets_dir="/Workspace/Users/\{email\}/monitors",
    output_schema_name="catalog.monitoring",
    schedule=\{"quartz_cron_expression": "0 0 8 * * ?"\}  # 매일 08시
)

​
3단계: 커스텀 메트릭 추가

  • 비즈니스 규칙에 맞는 커스텀 메트릭 정의
  • 예: null 비율, 범위 이탈 비율, 고유값 변화율

​
4단계: 알림 규칙 설정

  • 임계값 위반 시 Slack/이메일 알림 구성
  • 심각도별 분류: WARNING (>5% 이탈), CRITICAL (>20% 이탈)

### 4.5 Workspace 스킬 vs User 스킬 선택 기준

스킬을 어디에 배치할지는 **누가 사용하는가** 와 **표준화가 필요한가** 로 결정합니다.

| 판단 기준 | Workspace 스킬 | User 스킬 |
|-----------|---------------|-----------|
| **사용 범위** | 팀 전체가 동일한 절차를 따라야 할 때 | 개인 업무에 특화된 반복 작업 |
| **표준화 필요성** | 파이프라인 템플릿, 배포 절차 등 일관성이 중요한 작업 | 개인 분석 패턴, 실험 워크플로 |
| **관리 권한** | 관리자가 버전 관리하며 업데이트 | 개인이 자유롭게 수정 |
| **예시** | 데이터 품질 검증, DLT 파이프라인 생성, 대시보드 표준 | 개인 리포트 자동화, 실험 결과 정리 |

> **팁**
처음에는 User 스킬로 만들어서 개인적으로 검증한 뒤, 팀에 유용하다고 판단되면 Workspace 스킬로 승격시키는 것이 안전한 접근법입니다. Workspace 스킬은 모든 사용자에게 영향을 미치므로, 충분히 검증된 절차만 올려야 합니다.


---

> MCP 서버 연동, Agent 모드 실전 팁, 역할별 추천 설정은 [MCP 서버 연동과 Agent 모드 실전 팁](settings-mcp-agent) 페이지에서 이어집니다.