> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# 설정 & 모범사례

> **최종 업데이트**: 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 예시입니다:

```markdown theme={null}
## 내 역할과 컨텍스트
- 나는 데이터 엔지니어이며, 주로 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: 너무 모호한 지침**

```markdown theme={null}
좋은 코드를 작성해주세요.
버그 없이 짜주세요.
빠른 코드를 만들어주세요.
```

"좋은", "빠른" 같은 추상적 형용사는 LLM에게 구체적 행동 변화를 유도하지 못합니다. **무엇이 "좋은" 것인지 구체적으로 정의** 해야 합니다.

**나쁜 예시 2: 상충되는 지침**

```markdown theme={null}
- 코드를 최대한 간결하게 작성하세요
- 모든 에러 케이스를 처리하세요
- 모든 함수에 상세한 docstring을 추가하세요
- 한 줄이라도 줄여주세요
```

간결함과 상세한 에러 처리/문서화는 본질적으로 상충합니다. 우선순위를 정하거나 상황별로 구분해야 합니다.

**나쁜 예시 3: 역할과 무관한 과잉 지침**

```markdown theme={null}
## 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입니다:

```markdown theme={null}
## 조직 코딩 표준
- 모든 테이블 참조는 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에 메타데이터를 넣고, 본문에 상세 지침을 작성합니다:

```markdown theme={null}
---
name: data-quality-check
description: 테이블의 데이터 품질을 검증하고 리포트를 생성합니다
---

# 데이터 품질 검증 스킬

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

## 실행 절차

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

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

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

### 4.4 실전 스킬 예시

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

```markdown theme={null}
---
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: 대시보드 생성 스킬

```markdown theme={null}
---
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: 데이터 품질 모니터링 스킬

````markdown theme={null}
---
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) 페이지에서 이어집니다.
```