슈파베이스 AI 에이전트 스킬 | 30개 규칙으로 안전한 PostgresSQL DB 코드 생성

AI 코딩 에이전트는 코드를 빠르게 작성하는 데 탁월하지만, 올바른 코드를 작성하는 데는 한계가 있습니다. 특히 PostgreSQL 같은 복잡한 시스템에서 이 문제는 심각합니다. AI 에이전트가 생성한 쿼리는 작동하지만 전체 테이블 스캔(Full Table Scan)을 유발할 수 있습니다. 제안한 인덱스는 쓰기 성능을 오히려 저하시킬 수 있습니다. 가장 위험한 것은 Row Level Security(RLS)를 완전히 누락하여 데이터 유출 위험을 만드는 경우입니다.

PostgreSQL은 30년 이상의 역사를 가진 데이터베이스로, 프로덕션 환경에서 중요한 수많은 기능, 엣지 케이스, 성능 특성이 존재합니다. AI 에이전트의 학습 데이터만으로는 이 모든 것을 완벽하게 커버할 수 없습니다. 작동하는 코드와 프로덕션에 배포해도 안전한 코드 사이에는 큰 차이가 있습니다.

2026년 1월 21일, Supabase는 이 문제를 해결하기 위해 Postgres Best Practices Agent Skills를 공개했습니다. 이는 AI 코딩 에이전트가 고품질의 정확한 PostgreSQL 코드를 작성하도록 가르치는 30개의 규칙 모음입니다. Query Performance, Connection Management, Security and RLS, Schema Design, Concurrency and Locking, Data Access Patterns, Monitoring and Diagnostics, Advanced Features 등 8개 카테고리로 체계화되어 있으며, 각 규칙은 영향도에 따라 Critical부터 Low까지 우선순위가 부여되어 있습니다.

이 Agent Skills는 Anthropic이 개발하고 오픈 표준으로 공개한 Agent Skills 포맷을 따릅니다. Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI 등 주요 AI 코딩 도구들이 모두 지원하며, Vercel은 React 모범 사례 40개 규칙을, Cloudflare는 Workers와 D1 등 40개 서비스의 규칙을 이 포맷으로 공개했습니다. Supabase는 이 접근 방식을 PostgreSQL에 적용하여, 수십만 개 프로젝트를 운영하며 축적한 데이터베이스 전문 지식을 AI 에이전트가 직접 활용할 수 있도록 만들었습니다.

이 글에서는 Supabase Agent Skills의 구조와 핵심 규칙을 상세히 분석하고, Supabase MCP 서버와의 시너지, 실전 적용 방법, 그리고 커뮤니티 기여 방법까지 완벽하게 다룹니다. AI 에이전트를 활용해 데이터베이스 작업을 자동화하면서도 프로덕션 수준의 안전성과 성능을 보장하고 싶다면, 이 가이드가 필수적인 출발점이 될 것입니다.

* 핵심 사이트
1) https://github.com/supabase/agent-skills
2) https://supabase.com/blog/postgres-best-practices-for-ai-agents

Agent Skills는 AI 에이전트에게 도메인 전문성을 부여하는 오픈 표준입니다. 기존 방식은 AI 에이전트가 학습 데이터에서 패턴을 추론하기를 기대했습니다. 하지만 이는 불확실하고 일관성이 없었습니다. 에이전트가 올바른 PostgreSQL 패턴을 학습했는지, 오래된 안티패턴을 학습했는지 알 수 없었습니다. Agent Skills는 이를 명시적으로 해결합니다. 학습 데이터에 의존하는 대신, 에이전트에게 명확한 규칙을 제공합니다.

Agent Skills는 기계를 위해 작성된 문서입니다. 인간을 위한 문서는 예제와 설명을 섞어 자연어로 작성하지만, Agent Skills는 구조화된 포맷으로 "이렇게 하세요(DO)", "이렇게 하지 마세요(DON'T)"를 명확히 구분합니다. 에이전트는 필요할 때 해당 Skill을 읽고 작업에 규칙을 적용합니다. 예를 들어 SQL 쿼리를 작성할 때 Query Performance 규칙을 참조하고, 스키마를 변경할 때 Schema Design 규칙을 확인합니다.

Skill은 폴더 단위로 구성됩니다. 각 폴더에는 SKILL.md 파일과 선택적 지원 파일(예제 코드, 다이어그램)이 포함됩니다. SKILL.md는 두 부분으로 나뉩니다. 첫째, YAML frontmatter는 메타데이터를 정의합니다. 제목(title), 영향도(impact), 설명(impactDescription), 태그(tags) 등이 포함되며, 에이전트는 이 정보를 보고 언제 이 Skill을 활성화할지 판단합니다. 둘째, Markdown 본문은 에이전트가 따라야 할 구체적인 지침입니다. 잘못된 코드 예제와 올바른 코드 예제를 비교하여 보여주고, 공식 문서 링크를 참조로 제공합니다.

AnthropicAdvisor은 2025년 Agent Skills 포맷을 개발하고 오픈 표준으로 공개했습니다. 이후 업계 전반에서 채택되며 사실상 표준이 되었습니다. Vercel은 React와 Next.js의 10년 최적화 노하우를 40개 규칙으로 패키징한 react-best-practices를 공개했습니다. Cloudflare는 Workers, Pages, D1, R2 등 40개 이상의 서비스에 대한 Agent Skills를 릴리스했습니다. Supabase는 PostgreSQL에 동일한 접근 방식을 적용했습니다.

Agent Skills는 온디맨드 방식으로 작동합니다. 에이전트가 모든 규칙을 항상 메모리에 로드하는 것이 아니라, 필요한 시점에만 관련 Skill을 검색하고 적용합니다. 예를 들어 개발자가 "users 테이블에 email 컬럼을 추가해줘"라고 요청하면, 에이전트는 Schema Design 카테고리의 규칙을 참조하여 데이터 타입 선택, 제약 조건 추가, 인덱스 고려 사항 등을 적용합니다. "orders 테이블에서 user별 주문 조회 쿼리를 작성해줘"라고 요청하면, Security and RLS 규칙을 참조하여 Row Level Security 정책이 누락되지 않았는지 확인합니다.

지원 도구는 광범위합니다. Claude Code는 Anthropic의 공식 AI 코딩 도구로, Agent Skills를 네이티브로 지원합니다. /plugin marketplace add supabase/agent-skills 명령으로 Skill을 설치하고, /plugin install postgres-best-practices@supabase-agent-skills로 활성화합니다. Cursor는 최근 업데이트에서 Agent Skills를 통합했으며, Agents는 도메인별 지식이 관련될 때 자동으로 Skill을 발견하고 적용합니다. GitHub Copilot과 VS Code도 Agent Skills 표준을 지원하며, Vercel의 skills npm 패키지를 통해 인터랙티브 설치가 가능합니다. npx skills add supabase/agent-skills 명령 하나로 에이전트에 PostgreSQL 전문성이 추가됩니다.

또한 Agent Skills는 크로스 플랫폼 호환성을 보장합니다. 한 번 작성한 Skill은 Claude.ai, Claude Code, API 등 모든 환경에서 동일하게 작동합니다. Skill에 의존성이 필요한 경우에만 환경이 이를 지원하는지 확인하면 됩니다. 예를 들어 특정 PostgreSQL 확장 기능을 사용하는 Skill은 해당 확장이 설치된 환경에서만 활성화됩니다. 이런 유연성 덕분에 개발자는 도구를 바꾸더라도 동일한 모범 사례를 유지할 수 있습니다.

Supabase Agent Skills 저장소는 PostgreSQL 모범 사례를 8개 카테고리, 30개 규칙으로 체계화했습니다. 각 카테고리는 데이터베이스 개발의 핵심 영역을 다루며, 규칙은 프로덕션 환경에서의 영향도(impact)에 따라 우선순위가 부여되었습니다. 이는 Supabase가 수십만 개 프로젝트를 운영하며 반복적으로 발견한 실수 패턴을 반영한 것입니다.

Query Performance (Critical): 효율적인 쿼리 작성과 전체 테이블 스캔 방지에 관한 규칙입니다. 외래 키(Foreign Key)에 인덱스가 누락되는 문제, JOIN 시 불필요한 데이터 로드, N+1 쿼리 패턴 등 프로덕션 성능에 직접 영향을 미치는 이슈를 다룹니다. 예를 들어 orders 테이블의 user_id 컬럼이 외래 키인데 인덱스가 없으면, 사용자별 주문 조회 시 전체 테이블을 스캔하게 됩니다. 규칙은 "외래 키에는 항상 인덱스를 추가하라"고 명시하며, CREATE INDEX idx_orders_user_id ON orders(user_id); 같은 올바른 코드를 제시합니다.

Connection Management (Critical): 커넥션 풀링, 클라이언트 생명주기, 리소스 한계 설정입니다. 이는 프로덕션 장애의 가장 흔한 원인 중 하나입니다. 애플리케이션이 데이터베이스 커넥션을 제대로 관리하지 않으면, 커넥션 풀이 고갈되어 새로운 요청이 대기하거나 실패합니다. 규칙은 PgBouncer 같은 커넥션 풀러 사용을 권장하고, 클라이언트가 커넥션을 사용 후 반드시 해제하도록 강제합니다. Serverless 환경에서는 각 요청마다 새 커넥션을 생성하지 말고, 글로벌 변수로 재사용하라고 안내합니다.

Security and RLS (Critical): Row Level Security 정책과 접근 제어 패턴입니다. 이는 데이터 유출을 막는 마지막 방어선입니다. 애플리케이션 레벨에서만 필터링하면 버그나 우회로 인해 모든 데이터가 노출될 수 있습니다. 규칙은 멀티테넌트 데이터에 RLS를 활성화하고, ALTER TABLE orders ENABLE ROW LEVEL SECURITY;로 테이블을 보호하며, CREATE POLICY orders_user_policy ON orders FOR ALL USING (user_id = auth.uid()); 같은 정책으로 데이터베이스 레벨에서 격리를 강제합니다.

Schema Design (High): 테이블 구조, 데이터 타입, 정규화 결정입니다. 잘못된 스키마 설계는 나중에 수정하기 매우 어렵습니다. 규칙은 적절한 데이터 타입 선택(예: 금액은 NUMERIC 사용), 기본 키 전략(UUID vs SERIAL), 외래 키 제약 조건, 정규화와 역정규화의 트레이드오프 등을 다룹니다. 특히 JSON 컬럼 남용을 경고하고, 구조화된 데이터는 별도 테이블로 분리하라고 권장합니다.

Supabase는 규칙을 4단계 우선순위로 분류했습니다. 이는 개발자가 어떤 규칙에 먼저 집중해야 할지 명확히 알려줍니다.

Critical (치명적): Query Performance, Connection Management, Security and RLS 카테고리의 대부분이 여기 속합니다. 이 규칙을 위반하면 프로덕션 장애, 데이터 유출, 성능 붕괴가 발생할 수 있습니다. AI 에이전트는 이 규칙을 최우선으로 적용하며, 위반 시 경고를 표시합니다. 예를 들어 "외래 키 인덱스 누락"은 Critical이므로, 에이전트가 외래 키를 생성할 때 자동으로 인덱스도 추가합니다.

High (높음): Schema Design의 핵심 규칙들이 포함됩니다. 잘못된 데이터 타입 선택이나 정규화 실수는 즉각적인 장애를 일으키지 않지만, 시간이 지나면서 유지보수 비용과 성능 문제를 누적시킵니다. 에이전트는 High 우선순위 규칙도 적극 적용하지만, Critical보다는 유연하게 대응합니다.

Medium-High / Medium: Concurrency and Locking, Data Access Patterns 카테고리입니다. 트랜잭션 격리 수준, 데드락 방지, 페이지네이션 패턴 등이 포함됩니다. 이는 중급 이상 개발자가 마주치는 문제로, 초기에는 크게 신경 쓰지 않아도 되지만 트래픽이 증가하면 중요해집니다. 에이전트는 컨텍스트에 따라 선택적으로 적용합니다.

Low-Medium / Low: Monitoring and Diagnostics, Advanced Features 카테고리입니다. 쿼리 분석, 성능 추적, CTE(Common Table Expressions), Window Functions, 확장 기능 활용 등 고급 최적화 기법이 포함됩니다. 이는 이미 잘 작동하는 시스템을 더 개선하기 위한 규칙입니다. 에이전트는 개발자가 명시적으로 요청하거나, 성능 이슈가 감지될 때 이 규칙을 제안합니다.

Supabase Agent Skills의 30개 규칙 중 프로덕션 환경에서 가장 빈번하게 마주치고 영향이 큰 규칙들을 상세히 분석합니다. 각 규칙은 왜 중요한지(Why), 어떻게 적용하는지(How), 실무 예제(Example)로 구성됩니다.

멀티테넌트 데이터에 Row Level Security 활성화하기는 Critical 우선순위의 보안 규칙입니다. 이는 데이터베이스 레벨에서 사용자별 데이터 격리를 강제하여, 애플리케이션 버그나 권한 우회 시도로부터 데이터를 보호합니다.

잘못된 방식 (애플리케이션 레벨 필터링만 사용):

-- 애플리케이션 코드에서 필터링
SELECT * FROM orders WHERE user_id = $current_user_id;

-- 문제: 버그나 우회 시 모든 데이터 노출
SELECT * FROM orders; -- 모든 주문 반환!

애플리케이션에서만 필터링하면 개발자 실수로 WHERE 절을 빼먹거나, SQL Injection 공격, 권한 상승 취약점 등으로 인해 전체 데이터가 노출될 위험이 있습니다. 특히 ORM을 사용할 때 쿼리를 자동 생성하다 보면 필터 조건이 누락되기 쉽습니다.

올바른 방식 (데이터베이스 RLS 강제):

-- 1. 테이블에 RLS 활성화
ALTER TABLE orders
ENABLE ROW LEVEL SECURITY;

-- 2. 사용자별 정책 생성
CREATE POLICY orders_user_policy ON orders
FOR ALL
USING (
  user_id = current_setting('app.current_user_id')::bigint
);

-- 3. 테이블 소유자도 RLS 적용 (선택적, 더 강력한 보안)
ALTER TABLE orders
FORCE ROW LEVEL SECURITY;

-- 4. 사용자 컨텍스트 설정 후 쿼리
SET app.current_user_id = '123';
SELECT * FROM orders; -- user 123의 주문만 반환

RLS를 활성화하면 PostgreSQL이 모든 쿼리에 자동으로 정책을 적용합니다. 개발자가 WHERE 절을 빼먹어도 데이터베이스가 보호합니다. FORCE ROW LEVEL SECURITY는 테이블 소유자(보통 슈퍼유저)도 정책을 우회할 수 없게 만들어 더 강력한 보안을 제공합니다.

Supabase 인증 시스템 사용 시:

CREATE POLICY orders_user_policy ON orders
FOR ALL
TO authenticated
USING (user_id = auth.uid());

Supabase는 auth.uid() 함수를 제공하여 현재 인증된 사용자 ID를 자동으로 가져옵니다. TO authenticated는 인증되지 않은 요청은 아예 차단합니다. 이는 Supabase 프로젝트에서 가장 간결하고 안전한 패턴입니다.

외래 키에 인덱스 추가하기는 Query Performance 카테고리의 Critical 규칙입니다. PostgreSQL은 외래 키를 생성할 때 자동으로 인덱스를 추가하지 않습니다. 이는 의도된 설계 결정이지만, 대부분의 경우 외래 키 컬럼에 인덱스가 필요합니다.

문제 상황:

-- orders 테이블에 외래 키만 있고 인덱스 없음
CREATE TABLE orders (
  id BIGINT PRIMARY KEY,
  user_id BIGINT REFERENCES users(id),
  created_at TIMESTAMP
);

-- 사용자별 주문 조회 시 전체 테이블 스캔 발생
SELECT * FROM orders WHERE user_id = 123;
-- Seq Scan on orders (cost=0.00..1000000)

user_id에 인덱스가 없으면 PostgreSQL은 100만 개 주문을 모두 읽어 user_id가 123인 행을 찾습니다. 이는 테이블이 커질수록 기하급수적으로 느려집니다.

해결책:

-- 외래 키 컬럼에 인덱스 추가
CREATE INDEX idx_orders_user_id ON orders(user_id);

-- 이제 빠른 인덱스 스캔 사용
SELECT * FROM orders WHERE user_id = 123;
-- Index Scan using idx_orders_user_id (cost=0.00..8.27)

인덱스를 추가하면 쿼리 비용이 100만에서 8로 줄어듭니다. 특히 JOIN 시에도 성능이 극적으로 개선됩니다.

복합 인덱스 고려:

-- user_id와 created_at를 함께 자주 조회하는 경우
CREATE INDEX idx_orders_user_created 
ON orders(user_id, created_at DESC);

-- 사용자의 최근 주문 10개 조회 최적화
SELECT * FROM orders 
WHERE user_id = 123 
ORDER BY created_at DESC 
LIMIT 10;

복합 인덱스는 여러 컬럼을 함께 필터링하거나 정렬할 때 유용합니다. 단, 인덱스가 많아지면 INSERT/UPDATE 성능이 저하되므로, 실제 쿼리 패턴을 분석하여 필요한 인덱스만 추가해야 합니다.

Connection Pooling 필수 설정:

// 잘못된 방식: 매 요청마다 새 커넥션 생성
app.get('/orders', async (req, res) => {
  const client = new Client({ connectionString: DATABASE_URL });
  await client.connect(); // 새 커넥션!
  const result = await client.query('SELECT * FROM orders');
  await client.end();
  res.json(result.rows);
});

// 올바른 방식: 커넥션 풀 재사용
const pool = new Pool({ 
  connectionString: DATABASE_URL,
  max: 20, // 최대 20개 커넥션
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000
});

app.get('/orders', async (req, res) => {
  const client = await pool.connect(); // 풀에서 가져옴
  try {
    const result = await client.query('SELECT * FROM orders');
    res.json(result.rows);
  } finally {
    client.release(); // 풀에 반환
  }
});

커넥션 풀은 데이터베이스 커넥션을 재사용하여 매번 새로 생성하는 오버헤드를 제거합니다. Serverless 환경에서는 글로벌 변수로 풀을 선언하여 여러 요청 간 재사용하는 것이 핵심입니다.

Supabase Agent Skills의 진정한 가치는 Supabase MCP(Model Context Protocol) 서버와 결합될 때 극대화됩니다. MCP 서버는 AI 에이전트가 Supabase 프로젝트에 직접 연결하여 테이블 생성, 쿼리 실행, 스키마 관리, 설정 변경 등을 자연어로 수행할 수 있게 합니다. 하지만 MCP 서버만으로는 무엇을 실행할 수 있는지(What)만 제공할 뿐, 어떻게 올바르게 실행해야 하는지(How)는 보장하지 않습니다.

MCP 서버의 역할: 실행 능력

MCP 서버는 AI 에이전트에게 운전대(Steering Wheel)를 제공합니다. 개발자가 "users 테이블을 만들어줘"라고 요청하면, 에이전트는 MCP 서버를 통해 Supabase API를 호출하고 실제로 테이블을 생성합니다. "지난주 가입한 사용자 수를 알려줘"라고 물으면, MCP 서버가 SQL 쿼리를 실행하고 결과를 반환합니다. 이는 강력한 능력이지만 위험도 큽니다. 에이전트가 잘못된 쿼리를 실행하면 프로덕션 데이터베이스에 즉시 영향을 미칩니다.

Agent Skills의 역할: 판단 능력

Agent Skills는 운전 교습(Driving Lessons)을 제공합니다. MCP 서버로 테이블을 생성하기 전에, Agent Skills는 "외래 키에 인덱스를 추가했나요?", "Row Level Security를 활성화했나요?", "적절한 데이터 타입을 선택했나요?"를 확인합니다. 개발자가 마이그레이션을 요청하면, "이 작업은 테이블을 잠글 수 있습니다. lock_timeout을 설정하세요"라고 경고합니다. 쿼리를 작성할 때는 "LIMIT 절이 없으면 메모리 초과가 발생할 수 있습니다"라고 제안합니다.

시너지 효과:

개발자: "orders 테이블을 만들고 users와 연결해줘"

[MCP 서버만 있는 경우]
에이전트: CREATE TABLE orders (id BIGINT, user_id BIGINT REFERENCES users(id));
→ 작동은 하지만 user_id 인덱스 누락, RLS 미설정

[MCP + Agent Skills]
에이전트: 
1. CREATE TABLE orders (id BIGINT PRIMARY KEY, user_id BIGINT REFERENCES users(id));
2. CREATE INDEX idx_orders_user_id ON orders(user_id); -- Query Performance 규칙 적용
3. ALTER TABLE orders ENABLE ROW LEVEL SECURITY; -- Security 규칙 적용
4. CREATE POLICY orders_user_policy ON orders FOR ALL TO authenticated USING (user_id = auth.uid());
→ 프로덕션 안전한 코드 생성

실전 사례:

개발자: "지난 30일 주문 데이터를 분석해줘"

[Agent Skills 없음]
SELECT * FROM orders WHERE created_at > NOW() - INTERVAL '30 days';
-- LIMIT 없음 → 메모리 초과 위험

[Agent Skills 적용]
SELECT 
  DATE_TRUNC('day', created_at) AS order_date,
  COUNT(*) AS order_count,
  SUM(total_amount) AS daily_revenue
FROM orders 
WHERE created_at > NOW() - INTERVAL '30 days'
GROUP BY order_date
ORDER BY order_date DESC;
-- 집계 쿼리로 변환 → 효율적

Agent Skills는 대량 데이터를 다룰 때 자동으로 집계나 샘플링을 제안합니다. Data Access Patterns 규칙이 "전체 행을 가져오지 말고 필요한 통계만 계산하라"고 안내하기 때문입니다.

Supabase Agent Skills를 프로젝트에 적용하는 구체적인 단계와 도구별 설정 방법을 안내합니다.

Vercel Skills 패키지로 설치:

npx skills add supabase/agent-skills

이 명령은 인터랙티브 프롬프트를 제공하여 어떤 Skill을 설치할지 선택할 수 있습니다. postgres-best-practices를 선택하면 로컬 .skills/ 디렉토리에 30개 규칙이 다운로드됩니다. AI 에이전트는 이 디렉토리를 자동으로 스캔하고 규칙을 컨텍스트에 로드합니다.

Claude Code 플러그인 설치:

/plugin marketplace add supabase/agent-skills
/plugin install postgres-best-practices@supabase-agent-skills

Claude Code는 마켓플레이스에서 공식 플러그인을 제공합니다. 설치 후 Claude가 SQL 쿼리를 작성하거나 스키마를 변경할 때 자동으로 규칙을 참조합니다. /skills list 명령으로 활성화된 Skill 목록을 확인할 수 있습니다.

Cursor 통합:

Cursor는 2026년 1월 업데이트에서 Agent Skills를 네이티브 지원하기 시작했습니다. 프로젝트 루트에 .skills/ 폴더를 만들고 GitHub에서 규칙을 복사하면, Cursor Agent가 자동으로 발견합니다.

git clone [https://github.com/supabase/agent-skills.git](https://github.com/supabase/agent-skills.git)
cp -r agent-skills/postgres-best-practices .skills/

Cursor는 에이전트 모드(Cmd+K)에서 관련 Skill을 자동으로 활성화하며, 슬래시 명령(/)으로 수동 호출도 가능합니다.

VS Code + GitHub Copilot:

VS Code에서는 .github/copilot-instructions.md 파일에 Skill 내용을 포함시켜 Copilot에게 컨텍스트를 제공할 수 있습니다.

# Copilot Instructions

## PostgreSQL Best Practices
- Always add indexes on foreign keys
- Enable Row Level Security on multi-tenant tables
- Use connection pooling in production
...

실전 워크플로우:

• 개발 단계: Claude Code나 Cursor로 데이터베이스 스키마와 쿼리 작성 시 Agent Skills가 실시간 제안
• 코드 리뷰: Pull Request에서 /review 명령으로 Agent Skills 규칙 위반 체크
• 배포 전 검증: CI/CD 파이프라인에 규칙 검증 스크립트 추가
• 프로덕션 모니터링: pg_stat_statements로 실제 쿼리 성능 추적, 규칙 위반 패턴 발견

Supabase Agent Skills는 오픈소스 프로젝트로, 커뮤니티 기여를 적극 환영합니다. Supabase 팀의 내부 지식만으로는 모든 PostgreSQL 함정을 커버할 수 없습니다. 실무에서 마주친 문제와 해결책을 공유하면 전 세계 개발자들이 혜택을 받습니다.

기여 가능한 규칙 유형:

• PostgreSQL 특정 버전에서만 발생하는 버그나 회귀
• 특정 ORM(Prisma, Drizzle, TypeORM)과 함께 사용 시 주의사항
• 클라우드 제공자별 차이점(AWS RDS vs Google Cloud SQL vs Supabase)
• 대용량 데이터 마이그레이션 전략
• 백업과 복구 모범 사례
• 확장 기능(PostGIS, pg_vector, TimescaleDB) 사용 패턴

Pull Request 제출 프로세스:

• GitHub 저장소 Fork: github.com/supabase/agent-skills를 자신의 계정으로 Fork
• 새 규칙 파일 생성: postgres-best-practices/ 디렉토리에 .md 파일 추가
• 규칙 템플릿 따르기: CONTRIBUTING.md의 템플릿 사용
• 코드 예제 작성: 잘못된 방식(DON'T)과 올바른 방식(DO) 비교
• 우선순위 설정: Critical, High, Medium, Low 중 선택
• 참조 링크 추가: 공식 PostgreSQL 문서나 Supabase Docs 링크

규칙 템플릿:

---
title: [간결하고 명확한 제목]
impact: [CRITICAL | HIGH | MEDIUM | LOW]
impactDescription: [왜 이 규칙이 중요한지 한 문장으로]
tags: [관련, 키워드, 쉼표, 구분]
---

## [제목 반복]

[규칙에 대한 2-3문장 설명. 왜 이것이 문제인지, 어떤 상황에서 발생하는지]

**Incorrect (잘못된 방식):**

sql
-- 안티패턴 코드
-- 주석으로 문제점 설명

**Correct (올바른 방식):**

sql
-- 권장 패턴 코드
-- 주석으로 이유 설명

**Additional context (선택사항):**
- 성능 벤치마크 결과
- 엣지 케이스 주의사항
- 대안적 접근법

Reference: [관련 문서 링크]

실제 기여 예시:

Supabase 커뮤니티의 한 개발자가 "프로덕션 마이그레이션 시 테이블 잠금 방지" 규칙을 기여했습니다:

---
title: Use CONCURRENTLY for Index Creation in Production
impact: CRITICAL
impactDescription: Prevent table locks during index creation on live databases
tags: index, migration, locking, production, concurrency
---

## Use CONCURRENTLY for Index Creation in Production

인덱스 생성 시 기본적으로 테이블 전체에 잠금이 걸려 쓰기가 차단됩니다. 프로덕션에서는 CONCURRENTLY 옵션을 사용해야 합니다.

**Incorrect:**

sql
CREATE INDEX idx_orders_user_id ON orders(user_id);
-- 테이블 잠금 발생! 서비스 중단

**Correct:**

sql
CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders(user_id);
-- 잠금 없이 인덱스 생성

**주의사항:**
- CONCURRENTLY는 일반 생성보다 2-3배 느림
- 트랜잭션 내에서 사용 불가
- 실패 시 INVALID 인덱스가 남음 → 수동 삭제 필요

Reference: [https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY](https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY)

이런 실무 노하우가 Agent Skills에 추가되면, 전 세계 AI 에이전트가 동일한 실수를 방지할 수 있습니다.

Supabase Postgres Best Practices Agent Skills는 AI 코딩 에이전트와 프로덕션 데이터베이스 사이의 안전장치입니다. 2026년 현재 AI 에이전트는 코드 작성 속도를 10배 빠르게 만들었지만, 품질과 안전성은 여전히 인간 개발자의 검토가 필요했습니다. Agent Skills는 이 격차를 메웁니다. 30개 규칙이 수십만 개 Supabase 프로젝트에서 발견된 반복적 실수를 체계화하여, AI 에이전트가 처음부터 올바른 코드를 생성하도록 안내합니다.

8개 카테고리는 데이터베이스 개발의 전체 라이프사이클을 커버합니다. Query Performance는 느린 쿼리와 전체 테이블 스캔을 방지합니다. Connection Management는 커넥션 풀 고갈로 인한 서비스 장애를 예방합니다. Security and RLS는 데이터 유출의 마지막 방어선입니다. Schema Design은 유지보수 가능한 구조를 보장합니다. 나머지 카테고리들은 동시성, 데이터 접근 패턴, 모니터링, 고급 기능까지 다루어 초보자부터 전문가까지 모두에게 가치를 제공합니다.

Supabase MCP 서버와의 결합은 게임 체인저입니다. MCP 서버가 실행 능력을, Agent Skills가 판단 능력을 제공하여 AI 에이전트는 이제 "테이블을 만들어줘"라는 간단한 요청에도 외래 키 인덱스, RLS 정책, 적절한 데이터 타입까지 자동으로 적용합니다. 개발자는 비즈니스 로직에 집중하고, 데이터베이스 모범 사례는 에이전트가 알아서 처리합니다.

오픈소스 커뮤니티 기여는 이 프로젝트의 핵심입니다. Supabase 팀만으로는 모든 PostgreSQL 엣지 케이스를 발견할 수 없습니다. 전 세계 개발자들이 실무에서 마주친 함정과 해결책을 공유하면, Agent Skills는 점점 더 완성도 높은 지식 베이스로 성장합니다. 한 개발자의 실수가 수만 명의 학습 자료가 되는 선순환이 만들어집니다.

지금 바로 npx skills add supabase/agent-skills 명령으로 프로젝트에 PostgreSQL 전문성을 추가하세요. Claude Code, Cursor, VS Code 어느 도구를 사용하든 즉시 적용 가능합니다. 다음 데이터베이스 마이그레이션에서 AI 에이전트가 "이 작업은 테이블을 잠급니다. CONCURRENTLY 옵션을 사용하세요"라고 경고하는 순간, Agent Skills의 가치를 체감하게 될 것입니다. AI 에이전트 시대에도 안전하고 빠른 데이터베이스 개발은 가능합니다. 올바른 도구와 지식만 있다면.