---
title: 로컬 데이터를 다루는 AI 에이전트용 SQL | DuckLocal CLI
description: AI 에이전트가 스키마를 확인하고 로컬 파일을 단일 문 DuckDB SQL로 쿼리해 상한이 적용된 JSON 출력을 얻습니다.
image: https://ducklocal.app/og-image.jpg?v=2
language: ko
---

# AI 에이전트가 SQL로 로컬 데이터를 쿼리하도록 하십시오

**스키마 먼저. 문은 하나. 출력은 구조화.**

DuckLocal은 Claude Code, Codex, Cursor 및 기타 코딩 에이전트에 CSV, Parquet, JSON, DuckDB 데이터를 다루는 헤드리스 DuckDB 워크플로를 제공합니다. GUI 자동화도, 데이터베이스 서버도, 사용자 지정 API도 필요 없습니다.

## 먼저 파악하고, 그다음에 쿼리하십시오

1. **스키마를 파악하십시오.** `ducklocal schema ./data/`는 릴레이션, 바로 쿼리에 쓸 수 있는 `FROM` 식, 열과 타입을 반환합니다. 카탈로그가 크면 더 깊이 파고들 힌트와 함께 요약을 반환합니다.
2. **범위 안에서 미리보십시오.** 작은 제한을 붙여 SQL 문 하나를 실행합니다. 종료 상태와 JSON `truncated` 필드를 확인하십시오.
3. **SQL에서 계산하십시오.** 일부 미리보기를 에이전트 컨텍스트에서 합산하지 말고 필터, 조인, 집계를 DuckDB에서 수행합니다.

```bash
ducklocal schema ./data/
ducklocal schema sales.csv --stats
ducklocal query --sql "SELECT channel, sum(revenue) FROM 'sales.csv' GROUP BY channel"
```

`query` 호출마다 전용 연결을 만들고, SQL 문이 정확히 하나인지 검증한 뒤 기계가 읽을 수 있는 결과를 stdout에 씁니다. 오류는 JSON으로 stderr에 기록되고 0이 아닌 종료 코드가 반환됩니다.

## Claude Code, Codex, Cursor에서 설정하기

모든 에이전트에는 두 가지가 필요합니다. `PATH`에 있는 `ducklocal` 명령과 그 사용법에 대한 지침입니다. 둘 다 앱의 **Command line & AI…**(제목 표시줄의 로봇 버튼 또는 DuckLocal 메뉴)에서 준비할 수 있습니다.

### Claude Code: 스킬 설치

**Install command**를 클릭한 다음 **Add to Claude Code**를 클릭하세요. 스킬이 `~/.claude/skills/ducklocal`에 저장되고, Claude Code는 모든 프로젝트에서 이를 찾습니다. 요청이 스킬과 맞으면 Claude Code가 스킬을 불러와 시키지 않아도 스키마부터 확인하는 워크플로를 따릅니다.

```text

# In any project, ask in plain language:
Which channel brought in the most revenue in data/sales.csv?
Use DuckLocal and show me the query.
```

한 프로젝트에서만 스킬을 쓰려면 [`skills/ducklocal`](https://github.com/JetSquirrel/DuckLocal/tree/main/skills/ducklocal)을 그 프로젝트의 `.claude/skills/`에 복사하세요.

### Codex: 지침을 AGENTS.md에 붙여넣기

**Install command**를 클릭한 다음 **Copy brief**를 클릭하고, 지침을 프로젝트 루트의 `AGENTS.md`에 붙여넣으세요. Codex는 세션을 시작할 때 이 파일을 읽습니다. 지침 내용(일부):

```text
DuckLocal is installed on this machine. Its command, ducklocal,
runs DuckDB SQL over local CSV, TSV, Parquet, JSON and Excel files
and databases, and prints JSON.

- Start with `ducklocal --help` for the options.
- See what there is to query, with columns, before writing SQL:
  `ducklocal schema ./data/` (or `--database file.duckdb`).
- Profile what you will chart or summarize:
  `ducklocal schema data.csv --stats`.
- Compute totals in SQL, not from sample rows;
  check `truncated` in the output.
- It opens data read-only by default. Answer from the values
  it returns, and say which query produced them.
```

사용하는 Codex 버전이 스킬을 지원한다면 같은 `SKILL.md`와 `references/cli.md`를 그 스킬 디렉터리에 복사해도 됩니다.

### Cursor: 지침을 프로젝트 규칙으로 저장

**Install command**를 클릭한 다음 **Copy brief**를 클릭하고, 지침을 프로젝트 규칙(예: `.cursor/rules/ducklocal.mdc`)으로 저장하세요. 그러면 Cursor 에이전트는 그 프로젝트에서 작업할 때마다 이 명령을 압니다. 터미널 도구에는 `ducklocal`을 실행할 권한이 필요합니다. `schema`와 `query`는 허용하고, 파일에 쓰는 작업은 계속 하나씩 승인하세요.

```text

# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.
```

지침의 정확한 문구는 설치된 앱에서 가져오며, `ducklocal`이 아직 `PATH`에 없으면 명령의 전체 경로가 들어갑니다. [스킬 설치하고 살펴보기 →](https://ducklocal.app/docs/ko/cli#install-the-official-skill)

## 에이전트가 미리보기를 직접 합산하면 안 되는 이유

행을 읽어 자기 컨텍스트에서 더하는 에이전트는 보여 준 만큼만으로 답합니다. 120만 행짜리 파일과 기본 1,000행 한도라면, 보이는 것은 데이터의 0.1%도 안 됩니다. 보고하는 합계가 그럴듯해 보여도 자릿수가 틀릴 수 있습니다.

DuckLocal은 그 공백을 조용히 숨기지 않고 드러냅니다. 미리보기는 `"truncated": true`를 반환하고, `total_rows`는 결과가 실제로 몇 행이었는지 보여 줍니다. 세기가 일찍 멈추면 `total_rows_exact`가 `false`이고 그 합계는 하한일 뿐입니다. 스킬은 에이전트가 이를 표본으로 다루고 계산을 모든 행을 읽는 DuckDB에 맡기도록 알려 줍니다.

[한도, 예산, 출력 형식](https://ducklocal.app/docs/ko/cli#query-options)

```bash
ducklocal query --sql \
  "SELECT * FROM 'events.csv'"
{..., "row_count":1000,
 "truncated":true,
 "total_rows":101000,
 "total_rows_exact":false}

ducklocal query --sql \
  "SELECT count(*) AS n, sum(amount) AS total
   FROM 'events.csv'"
{..., "rows":[[1204381,8812094.5]],
 "truncated":false}
```

## 상한이 있고 명시적인 출력

기본 한도는 1,000행이며 2,000,000셀 예산이 적용됩니다. DuckLocal은 한 행을 더 읽어 결과가 잘렸는지 판단합니다.

JSON 봉투에는 다음이 포함됩니다.

- 타입이 지정된 열과 행
- `row_count`
- `truncated`
- `elapsed_ms`

종료 코드 2는 잘못된 인수, 종료 코드 1은 실행 실패를 뜻합니다. `--format md`는 같은 결과를 사람이 읽을 수 있는 Markdown 표로 그립니다.

## 공식 에이전트 스킬

오픈 소스 스킬은 에이전트에게 스키마를 확인하고, 상한이 적용된 샘플을 미리보고, SQL로 집계하고, 잘림 여부를 검증하고, 반환된 값으로 답하는 방법을 가르칩니다. 앱에서 Claude Code용으로 설치하거나 다른 에이전트를 위한 설명서로 사용할 수 있습니다.

에이전트는 `ducklocal open`으로 작업을 실행 중인 데스크톱 앱에 넘기고, `ducklocal open --state`로 표시 중인 탭과 결과 미리보기를 읽을 수 있습니다.

## 보안 경계

DuckLocal은 로컬 파일을 DuckLocal 서비스에 업로드하지 않지만 보안 샌드박스도 아닙니다. 읽기 전용 데이터베이스 모드가 SQL의 다른 파일 쓰기나 네트워크 액세스를 막아 주지는 않습니다.

실행 전에 출력 경로, 덮어쓰기, 데이터베이스 변경, 확장 기능 설치, 외부 액세스를 승인하십시오.

## 링크

- [DuckLocal 다운로드](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [CLI 전체 레퍼런스](https://ducklocal.app/docs/ko/cli)
- [공식 스킬 설치](https://ducklocal.app/docs/ko/cli#install-the-official-skill)
- [로컬 데이터 분석](https://ducklocal.app/ko/use-cases/local-data-analysis/)
- [Claude Dashboards에서 DuckLocal에 대해 배운 것](https://ducklocal.app/ko/blog/claude-dashboards-ducklocal/)
- [DuckDB GUI](https://ducklocal.app/ko/use-cases/duckdb-gui/)
- [Parquet 뷰어](https://ducklocal.app/ko/use-cases/parquet-viewer/)
- [SQL로 CSV 쿼리](https://ducklocal.app/ko/use-cases/query-csv-with-sql/)
- [SQL 대시보드](https://ducklocal.app/ko/use-cases/sql-dashboards/)
- [DuckLocal vs DBeaver](https://ducklocal.app/ko/compare/ducklocal-vs-dbeaver/)

Source: https://ducklocal.app/ko/use-cases/ai-agent-sql/
