AI 에이전트를 위한 Postgres 모범 사례 완벽 가이드
관련글
Introducing: Postgres Best Practices
개요
AI 코딩 에이전트는 코드를 작성하는 능력은 뛰어나지만, 시스템을 깊이 이해하지 못한 상태에서 올바른 코드를 작성하는 데는 어려움을 겪습니다. Postgres는 수십 년간 축적된 기능, 엣지 케이스, 그리고 프로덕션 환경에서 중요한 성능 특성을 가진 대표적인 시스템입니다. 에이전트는 동작하는 쿼리를 생성할 수 있지만, 전체 테이블 스캔을 발생시키거나, 쓰기 성능을 저하시키는 인덱스를 제안하거나, Row Level Security를 완전히 간과할 수 있습니다.
Supabase가 공개한 Postgres Best Practices Agent Skills는 이러한 문제를 해결하기 위해 설계되었습니다. 이는 AI 에이전트가 고품질의 올바른 코드를 생성하도록 안내하는 체계적인 규칙 세트입니다.
Agent Skills의 이해
Agent Skills는 에이전트에게 도메인 전문성을 제공하는 오픈 스탠다드 형식입니다. 이는 에이전트가 필요할 때 발견하고 사용할 수 있는 명령어와 예제의 폴더로 구성됩니다. 기계를 위해 작성된 문서라고 생각하면 됩니다. 에이전트가 훈련 데이터에서 올바른 패턴을 학습했기를 바라는 대신, 따라야 할 명시적인 규칙을 제공합니다. 에이전트는 안내가 필요할 때 스킬을 읽고 작업에 규칙을 적용합니다.
이 형식은 Anthropic에서 개발하여 오픈 스탠다드로 공개했으며, 이후 업계 전반에 걸쳐 채택되었습니다. Vercel은 10년간의 React 및 Next.js 최적화 지식을 40개의 규칙으로 패키징한 react-best-practices를 발표했습니다. Cloudflare는 Workers, Pages, D1, R2 및 40개 이상의 서비스에 대한 스킬을 공개했습니다. Supabase는 동일한 접근 방식을 Postgres에 적용하고 있습니다.
이 형식은 Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI 및 기타 도구와 호환됩니다. 에이전트는 쿼리를 작성하거나, 코드를 검토하거나, 스키마 변경을 제안할 때 이러한 규칙을 참조할 수 있습니다. 에이전트는 훈련 데이터에서 조언을 생성하는 대신 규칙을 권위 있는 안내로 취급합니다.
Postgres Best Practices가 필요한 이유
Supabase는 수십만 개의 프로젝트에 대해 Postgres를 실행하며, 반복적으로 발생하는 동일한 실수들을 목격합니다. 외래 키에 누락된 인덱스, 실수로 RLS를 우회하는 쿼리, 프로덕션에서 테이블을 잠그는 마이그레이션, 잘못 관리된 클라이언트로 인한 연결 풀 고갈, ORM 뒤에 숨겨진 전체 테이블 스캔 등이 대표적입니다.
Supabase의 지원팀, 데이터베이스 어드바이저, 문서에는 이미 이러한 지식이 포함되어 있습니다. 이를 에이전트가 직접 사용할 수 있는 형식으로 패키징한 것이 이번 프로젝트입니다.
8가지 카테고리 상세 설명
리포지토리는 영향도에 따라 우선순위가 지정된 8개 카테고리에 걸쳐 30개 이상의 규칙을 포함합니다. 각 규칙은 일관된 형식을 따르며, 제목, 영향도, 태그, 설명, 잘못된 예제와 올바른 예제를 포함합니다.
1. 쿼리 성능 (우선순위: Critical)
쿼리 성능 카테고리는 효율적인 쿼리 작성과 전체 테이블 스캔 방지에 중점을 둡니다. 이는 프로덕션 환경에서 가장 직접적이고 즉각적인 영향을 미치는 영역입니다. 에이전트는 종종 기능적으로는 작동하지만 성능상 치명적인 쿼리를 생성합니다. 예를 들어, 대용량 테이블에서 WHERE 절 없이 SELECT 문을 실행하거나, 인덱스를 활용하지 못하는 방식으로 조건을 작성하는 경우입니다.
올바른 인덱스 전략은 쿼리 성능의 핵심입니다. 외래 키에는 반드시 인덱스가 필요하며, 자주 검색되는 컬럼에도 인덱스를 생성해야 합니다. 그러나 과도한 인덱스는 쓰기 성능을 저하시키므로 균형을 맞춰야 합니다. 복합 인덱스를 사용할 때는 카디널리티가 높은 컬럼을 먼저 배치하는 것이 중요합니다.
EXPLAIN ANALYZE를 활용하여 쿼리 실행 계획을 분석하는 방법도 중요합니다. Seq Scan이 발생하는지, Index Scan을 사용하는지, 조인 순서가 최적인지 확인해야 합니다. 에이전트는 이러한 분석 도구를 사용하여 생성한 쿼리를 검증하도록 안내받습니다.
2. 연결 관리 (우선순위: Critical)
Postgres는 각 클라이언트 연결에 별도의 프로세스를 할당하므로, 연결 관리가 매우 중요합니다. 연결 풀링 없이 매 요청마다 새로운 연결을 생성하면 서버 리소스가 빠르게 고갈됩니다. 에이전트는 pgBouncer, Supavisor 또는 애플리케이션 레벨 풀링 라이브러리를 사용하여 연결을 재사용하도록 코드를 작성해야 합니다.
서버리스 환경에서는 연결 관리가 특히 까다롭습니다. AWS Lambda나 Vercel Functions 같은 환경에서는 각 함수 인스턴스가 독립적인 연결을 생성할 수 있으며, 동시 실행이 증가하면 연결 제한에 도달할 수 있습니다. 이 경우 Supabase의 연결 풀러를 사용하거나, 데이터베이스 프록시를 통해 연결을 중재해야 합니다.
클라이언트 라이프사이클 관리도 중요합니다. 연결을 사용한 후에는 반드시 해제해야 하며, 트랜잭션이 열린 상태로 방치되지 않도록 해야 합니다. 에이전트는 적절한 에러 핸들링과 연결 정리 로직을 포함한 코드를 생성해야 합니다.
3. 보안 및 RLS (우선순위: Critical)
Row Level Security는 데이터베이스 레벨에서 데이터 접근을 강제하는 Postgres의 강력한 기능입니다. 애플리케이션 레벨에서만 필터링에 의존하면, 버그나 우회를 통해 전체 데이터가 노출될 위험이 있습니다. RLS를 활성화하면 사용자는 정책에 의해 허용된 행만 볼 수 있습니다.
멀티 테넌트 애플리케이션에서 RLS는 필수입니다. 각 사용자나 조직이 자신의 데이터만 접근할 수 있도록 정책을 설정해야 합니다. 예를 들어, orders 테이블에서 user_id가 현재 사용자와 일치하는 행만 반환하도록 정책을 생성합니다. FORCE ROW LEVEL SECURITY 옵션을 사용하면 테이블 소유자도 정책의 적용을 받게 되어 더욱 안전합니다.
RLS 정책 작성 시 주의할 점은 성능입니다. 복잡한 정책은 쿼리 성능에 영향을 줄 수 있으므로, 인덱스와 함께 최적화해야 합니다. 또한 정책은 간단하고 명확하게 작성하여 유지보수가 용이하도록 해야 합니다. 에이전트는 RLS가 필요한 시나리오를 식별하고 적절한 정책을 제안하도록 훈련됩니다.
4. 스키마 설계 (우선순위: High)
좋은 스키마 설계는 장기적인 유지보수성과 성능의 기반입니다. 정규화는 데이터 중복을 줄이고 일관성을 유지하는 데 도움이 되지만, 과도한 정규화는 복잡한 조인을 초래할 수 있습니다. 에이전트는 적절한 정규화 수준을 판단하고, 읽기 성능이 중요한 경우 의도적인 비정규화를 제안할 수 있어야 합니다.
데이터 타입 선택도 중요합니다. TEXT vs VARCHAR, INTEGER vs BIGINT, TIMESTAMP vs TIMESTAMPTZ 등의 선택은 저장 공간, 성능, 데이터 정확성에 영향을 미칩니다. 예를 들어, 시간대를 고려해야 하는 경우 TIMESTAMPTZ를 사용해야 하며, 자동 증가 식별자의 경우 향후 확장을 고려하여 BIGSERIAL을 사용하는 것이 좋습니다.
제약 조건은 데이터 무결성을 보장하는 핵심 메커니즘입니다. NOT NULL, UNIQUE, CHECK 제약 조건을 적절히 사용하여 잘못된 데이터가 입력되는 것을 방지해야 합니다. 외래 키 제약 조건은 참조 무결성을 유지하며, ON DELETE CASCADE나 ON DELETE SET NULL 같은 옵션으로 연관 데이터의 처리 방식을 명확히 정의할 수 있습니다.
5. 동시성 및 잠금 (우선순위: Medium-High)
Postgres의 MVCC(Multi-Version Concurrency Control) 시스템은 높은 동시성을 가능하게 하지만, 잘못 사용하면 교착 상태나 성능 저하를 초래할 수 있습니다. 트랜잭션 격리 수준을 이해하고 적절히 선택하는 것이 중요합니다. READ COMMITTED는 기본값이며 대부분의 경우 적합하지만, 더 강한 일관성이 필요한 경우 REPEATABLE READ나 SERIALIZABLE을 사용할 수 있습니다.
데드락을 방지하려면 여러 테이블을 잠글 때 일관된 순서를 유지해야 합니다. 예를 들어, 항상 users 테이블을 먼저 잠그고 orders 테이블을 나중에 잠그는 식입니다. SELECT FOR UPDATE를 사용하여 명시적으로 행을 잠글 때는 필요한 최소 범위만 잠그고, 트랜잭션을 가능한 짧게 유지해야 합니다.
스키마 변경 시 잠금은 특히 주의해야 할 영역입니다. ALTER TABLE 같은 DDL 명령은 테이블에 ACCESS EXCLUSIVE 잠금을 획득하여 모든 읽기와 쓰기를 차단합니다. 프로덕션 환경에서는 짧은 잠금 시간으로 스키마를 변경하는 전략을 사용해야 합니다. 예를 들어, 새 컬럼을 추가할 때 NOT NULL 제약 조건은 나중에 추가하거나, 인덱스를 생성할 때 CONCURRENTLY 옵션을 사용합니다.
6. 데이터 접근 패턴 (우선순위: Medium)
효율적인 데이터 접근 패턴은 애플리케이션 성능에 직접적인 영향을 미칩니다. 페이지네이션을 구현할 때 OFFSET/LIMIT보다 키셋 페이지네이션을 사용하는 것이 대용량 데이터셋에서 훨씬 효율적입니다. OFFSET은 건너뛴 행도 스캔해야 하므로 페이지 번호가 커질수록 성능이 급격히 저하됩니다. 반면 키셋 페이지네이션은 WHERE 절로 직접 시작 지점을 찾으므로 일관된 성능을 유지합니다.
대량 작업에서는 배치 처리가 필수입니다. 개별 INSERT 대신 단일 명령으로 여러 행을 삽입하면 네트워크 왕복과 트랜잭션 오버헤드를 크게 줄일 수 있습니다. UPDATE나 DELETE도 마찬가지로 WHERE IN 절을 사용하여 여러 행을 한 번에 처리해야 합니다. 매우 큰 데이터셋의 경우 COPY 명령을 사용하면 가장 빠른 성능을 얻을 수 있습니다.
N+1 쿼리 문제는 ORM 사용 시 흔히 발생합니다. 부모 레코드를 조회한 후 각 부모에 대해 별도로 자식 레코드를 조회하면 쿼리 수가 폭발적으로 증가합니다. JOIN이나 서브쿼리를 사용하여 단일 쿼리로 필요한 모든 데이터를 가져와야 합니다. 또는 애플리케이션 레벨에서 데이터 로더 패턴을 사용하여 쿼리를 배치 처리할 수 있습니다.
7. 모니터링 및 진단 (우선순위: Low-Medium)
프로덕션 데이터베이스는 지속적인 모니터링이 필요합니다. pg_stat_statements 확장은 실행된 모든 쿼리의 통계를 수집하여, 어떤 쿼리가 가장 많은 시간을 소비하는지, 어떤 쿼리가 가장 자주 실행되는지 파악할 수 있게 해줍니다. 이 정보를 바탕으로 최적화가 필요한 쿼리를 식별할 수 있습니다.
느린 쿼리 로그를 활성화하면 설정한 임계값보다 오래 걸리는 쿼리를 자동으로 기록합니다. log_min_duration_statement 파라미터를 조정하여 문제가 될 만한 쿼리를 캡처하되, 너무 낮게 설정하면 로그가 과도하게 증가할 수 있으므로 주의해야 합니다. 로그 분석 도구를 사용하면 패턴을 식별하고 반복적인 문제를 찾을 수 있습니다.
EXPLAIN과 EXPLAIN ANALYZE는 개별 쿼리를 분석하는 강력한 도구입니다. EXPLAIN은 쿼리 계획을 보여주고, EXPLAIN ANALYZE는 실제로 쿼리를 실행하여 각 단계의 실제 소요 시간을 측정합니다. 예상 비용과 실제 실행 시간을 비교하면 통계 정보가 오래된 경우를 발견할 수 있으며, ANALYZE 명령으로 테이블 통계를 갱신해야 합니다.
8. 고급 기능 (우선순위: Low)
Postgres는 표준 SQL을 넘어서는 많은 고급 기능을 제공합니다. CTE(Common Table Expressions)는 복잡한 쿼리를 읽기 쉽게 분해하며, MATERIALIZED 옵션을 사용하면 중간 결과를 캐싱하여 성능을 향상시킬 수 있습니다. 그러나 CTE는 최적화 펜스 역할을 할 수 있어 경우에 따라 서브쿼리나 조인이 더 나은 성능을 제공할 수 있습니다.
윈도우 함수는 집계 함수와 달리 행을 그룹화하지 않고 각 행에 대해 집계 값을 계산합니다. ROW_NUMBER, RANK, LAG, LEAD 같은 함수는 순위 매기기, 이동 평균 계산, 이전 행과의 비교 등 복잡한 분석 작업을 간결하게 표현할 수 있게 해줍니다. 파티션과 정렬 기준을 올바르게 설정하는 것이 중요합니다.
확장 기능을 통해 Postgres의 기능을 크게 확장할 수 있습니다. PostGIS는 지리 공간 데이터 처리를 가능하게 하고, pg_trgm은 유사 문자열 검색을 지원하며, uuid-ossp는 UUID 생성 함수를 제공합니다. pgvector는 벡터 유사도 검색을 지원하여 AI 애플리케이션에서 임베딩 검색을 구현할 수 있게 합니다. 필요한 확장을 식별하고 올바르게 사용하는 것이 애플리케이션의 기능을 크게 향상시킬 수 있습니다.
Agent Skills의 작동 방식
Agent Skills를 설치하면 에이전트는 30개 이상의 규칙에 접근할 수 있게 됩니다. 쿼리를 작성하거나, 코드를 검토하거나, 스키마 변경을 제안할 때 이러한 규칙을 참조할 수 있습니다. 에이전트는 규칙을 권위 있는 안내로 취급하여 훈련 데이터에서 조언을 생성하는 대신 명시적인 지침을 따릅니다.
예를 들어, 에이전트가 멀티 테넌트 애플리케이션을 위한 데이터베이스 스키마를 생성하라는 요청을 받으면, RLS 규칙을 참조하여 각 테이블에 적절한 정책을 자동으로 포함할 수 있습니다. 또는 대용량 데이터를 조회하는 API를 작성할 때, 페이지네이션 규칙을 참조하여 OFFSET/LIMIT 대신 키셋 페이지네이션을 구현할 수 있습니다.
규칙은 체크리스트가 아니라 컨텍스트입니다. 에이전트는 현재 작업에 관련된 규칙만 고려하며, 규칙을 맹목적으로 적용하지 않습니다. 대신 상황을 이해하고 적절한 규칙을 선택하여 적용합니다. 예를 들어, 읽기 전용 보고서 쿼리를 작성할 때는 RLS 규칙보다 쿼리 성능 규칙이 더 관련이 있을 것입니다.
Supabase MCP 서버와의 시너지
Supabase MCP 서버를 사용한 경험이 있다면, AI 에이전트가 Supabase 프로젝트에 직접 연결할 수 있다는 것을 알고 있을 것입니다. 에이전트는 자연어를 통해 테이블을 생성하고, 쿼리를 실행하고, 스키마를 관리하고, 설정을 구성할 수 있습니다.
MCP 서버는 에이전트에게 데이터베이스 작업 능력을 제공합니다. 이 모범 사례는 에이전트가 올바르게 작업을 수행하도록 가르칩니다. MCP 서버를 운전대라고 한다면, 모범 사례는 운전 교습입니다. MCP 접근 권한을 가진 에이전트는 요청한 모든 쿼리를 실행할 수 있습니다. MCP 접근 권한과 이러한 규칙을 모두 가진 에이전트는 테이블을 잠그는 인덱스를 생성하기 전에 경고하고, 안전하지 않은 코드를 배포하기 전에 RLS 정책을 제안하며, 성능 문제를 피하도록 쿼리를 구조화할 것입니다.
두 도구는 함께 잘 작동합니다. MCP 서버는 연결과 실행을 처리합니다. 모범 사례는 판단을 처리합니다. 예를 들어, 에이전트가 MCP를 통해 새 테이블을 생성하라는 요청을 받으면, 모범 사례 규칙을 참조하여 적절한 인덱스, 제약 조건, RLS 정책을 포함하는 완전한 스키마를 생성할 수 있습니다. 또는 기존 테이블을 수정할 때, 프로덕션 환경에서 안전한 마이그레이션 전략을 제안할 수 있습니다.
설치 및 사용 방법
기본 설치
Vercel의 skills npm 패키지를 사용하여 대화형으로 스킬을 설치할 수 있습니다.
1
npx skills add supabase/agent-skills
이 명령은 사용 가능한 스킬 목록을 표시하고 설치할 스킬을 선택할 수 있게 합니다. Postgres Best Practices를 선택하면 에이전트의 구성에 자동으로 추가됩니다.
Claude Code에서의 설치
Claude Code를 사용하는 경우 플러그인으로 이 스킬을 설치할 수 있습니다.
1
2
/plugin marketplace add supabase/agent-skills
/plugin install postgres-best-practices@supabase-agent-skills
첫 번째 명령은 Supabase의 에이전트 스킬 마켓플레이스를 추가하고, 두 번째 명령은 Postgres Best Practices 스킬을 설치합니다.
다른 도구와의 통합
Agent Skills 형식은 Cursor, GitHub Copilot, VS Code 확장, Gemini CLI 등 다양한 도구와 호환됩니다. 각 도구는 스킬을 로드하고 사용하는 고유한 방법을 가지고 있으므로 해당 도구의 문서를 참조하여 설정하시기 바랍니다.
일반적으로 프로젝트의 .skills 디렉토리나 유사한 구성 위치에 스킬을 배치하면 에이전트가 자동으로 발견하고 로드합니다. 일부 도구는 전역 스킬 디렉토리를 지원하여 모든 프로젝트에서 스킬을 사용할 수 있게 합니다.
설치 후 확인
설치 후 에이전트에게 Postgres 관련 작업을 요청하여 스킬이 올바르게 작동하는지 확인할 수 있습니다. 예를 들어:
- “멀티 테넌트 애플리케이션을 위한 users와 posts 테이블을 생성해줘”
- “이 쿼리를 최적화해줘” (비효율적인 쿼리 제공)
- “대용량 products 테이블을 위한 페이지네이션 API를 작성해줘”
에이전트가 적절한 RLS 정책, 인덱스, 효율적인 쿼리 패턴을 제안하면 스킬이 올바르게 작동하는 것입니다.
프로젝트 기여 방법
이 리포지토리의 규칙은 Supabase의 내부 지식 베이스에서 가져왔지만, 커뮤니티가 놓친 인사이트가 있다는 것을 알고 있습니다. 에이전트가 알아야 할 Postgres의 함정을 발견했다면 PR을 열어주시기 바랍니다.
규칙 작성 가이드
각 규칙에는 다음이 필요합니다:
명확한 제목: 규칙이 다루는 내용을 간결하게 설명합니다. “Enable Row Level Security for Multi-Tenant Data”처럼 구체적이어야 합니다.
우선순위 수준: Critical, High, Medium, Low 중 하나를 선택합니다. 프로덕션 환경에서 즉각적인 문제를 일으킬 수 있는 사항은 Critical로 분류합니다.
중요한 이유 설명: 이 규칙을 따르지 않으면 어떤 문제가 발생하는지 설명합니다. 구체적인 시나리오와 영향을 포함하면 좋습니다.
좋은 코드와 나쁜 코드 예제: 잘못된 접근 방식과 올바른 접근 방식을 모두 보여줍니다. 예제는 실제로 실행 가능하고 현실적이어야 합니다. 주석을 사용하여 각 부분이 왜 좋거나 나쁜지 설명합니다.
태그: 규칙을 분류하는 키워드를 추가합니다. 예: rls, performance, indexing, security
기여 프로세스
- 리포지토리를 포크합니다.
- 적절한 카테고리 폴더에 새 규칙 파일을 생성합니다.
- CONTRIBUTING.md의 템플릿을 따라 규칙을 작성합니다.
- 규칙이 명확하고 예제가 정확한지 확인합니다.
- PR을 생성하고 규칙이 필요한 이유를 설명합니다.
Supabase 팀은 PR을 검토하고 피드백을 제공합니다. 규칙이 승인되면 다음 릴리스에 포함됩니다.
좋은 규칙의 예
좋은 규칙은 다음 특징을 가집니다:
- 실용적: 에이전트가 실제로 적용할 수 있는 구체적인 조언을 제공합니다.
- 명확한 예제: 코드 예제가 자체적으로 설명되며, 복잡한 설정 없이 이해할 수 있습니다.
- 컨텍스트 제공: 규칙이 언제, 왜 적용되는지 설명합니다.
- 균형 잡힌 관점: 트레이드오프가 있다면 명시합니다.
- 참조 링크: 추가 정보를 위한 공식 문서나 신뢰할 수 있는 소스를 제공합니다.
실전 활용 시나리오
시나리오 1: 새 프로젝트 시작
새로운 SaaS 애플리케이션을 시작한다고 가정해봅시다. 에이전트에게 “멀티 테넌트 블로그 플랫폼을 위한 데이터베이스 스키마를 생성해줘”라고 요청하면, Postgres Best Practices 스킬을 참조하여 다음을 포함하는 스키마를 생성합니다:
- 적절한 데이터 타입과 제약 조건이 있는 테이블
- 외래 키와 그에 대한 인덱스
- 각 테이블에 대한 RLS 정책
- 자주 조회되는 컬럼에 대한 추가 인덱스
- 타임스탬프 컬럼 (created_at, updated_at)
에이전트는 또한 연결 풀링 설정과 마이그레이션 전략에 대한 조언을 제공할 수 있습니다.
시나리오 2: 성능 문제 해결
프로덕션 환경에서 특정 API 엔드포인트가 느리다는 보고를 받았습니다. 에이전트에게 문제의 쿼리를 제공하고 “이 쿼리를 최적화해줘”라고 요청하면, 다음을 수행할 수 있습니다:
- EXPLAIN ANALYZE를 실행하여 현재 실행 계획 분석
- 전체 테이블 스캔이나 비효율적인 조인 식별
- 필요한 인덱스 제안
- 쿼리를 재구성하여 더 효율적으로 만들기
- 결과 캐싱이나 구체화된 뷰 사용 고려
에이전트는 변경 전후의 성능 차이를 보여주고, 제안된 인덱스가 쓰기 성능에 미치는 영향도 설명할 수 있습니다.
시나리오 3: 보안 강화
기존 애플리케이션에 RLS를 추가하고 싶습니다. 에이전트에게 “users, posts, comments 테이블에 Row Level Security를 추가해줘”라고 요청하면:
- 각 테이블의 소유권 모델 분석
- 적절한 RLS 정책 생성
- FORCE ROW LEVEL SECURITY 활성화
- 정책이 인덱스와 잘 작동하도록 보장
- 기존 애플리케이션 코드 수정 제안 (필요한 경우)
- 정책 테스트 방법 안내
에이전트는 단계별 마이그레이션 계획도 제공하여 프로덕션에서 안전하게 RLS를 롤아웃할 수 있습니다.
시나리오 4: 대규모 데이터 마이그레이션
수백만 행이 있는 테이블에 새 컬럼을 추가해야 합니다. 에이전트에게 “users 테이블에 email_verified 컬럼을 추가하는 안전한 마이그레이션을 작성해줘”라고 요청하면:
- 잠금을 최소화하는 단계별 마이그레이션 생성
- 먼저 NULL을 허용하는 컬럼 추가
- 백그라운드에서 데이터 채우기
- 데이터 검증
- NOT NULL 제약 조건 추가 (선택적)
- 롤백 계획 제공
에이전트는 각 단계의 예상 소요 시간과 영향을 설명하여 다운타임 없이 마이그레이션을 계획할 수 있게 합니다.
시나리오 5: API 개발
REST API의 페이지네이션 엔드포인트를 구현해야 합니다. 에이전트에게 “products 테이블을 위한 페이지네이션 API를 작성해줘”라고 요청하면:
- OFFSET/LIMIT 대신 키셋 페이지네이션 구현
- 적절한 인덱스 제안 (정렬 컬럼에 대한)
- 첫 페이지, 다음 페이지, 이전 페이지 로직
- 에지 케이스 처리 (빈 결과, 마지막 페이지 등)
- 클라이언트를 위한 메타데이터 (hasNext, 등)
에이전트는 Node.js, Python, Go 등 선호하는 언어로 완전한 예제를 제공할 수 있습니다.
지속적인 학습과 개선
Postgres Best Practices Agent Skills는 살아있는 문서입니다. Postgres 자체가 계속 발전하고, 새로운 모범 사례가 등장하며, 커뮤니티가 새로운 패턴을 발견함에 따라 이 스킬도 업데이트됩니다. 정기적으로 리포지토리를 확인하여 새로운 규칙과 개선 사항을 받아보시기 바랍니다.
에이전트 사용 중 스킬이 제안한 패턴이 특정 상황에서 최적이 아닌 것을 발견하면, 이슈를 열거나 개선 사항을 제안해주세요. 커뮤니티의 피드백은 스킬을 더욱 정확하고 유용하게 만드는 데 필수적입니다.
또한 자신의 프로젝트에서 에이전트가 범한 실수나 놓친 최적화를 추적하는 것도 좋은 습관입니다. 이러한 사례는 새로운 규칙의 좋은 후보가 될 수 있으며, 전체 커뮤니티에 도움이 됩니다.
결론
AI 에이전트는 개발 워크플로우를 크게 가속화할 수 있지만, 복잡한 시스템에 대한 깊은 지식 없이는 미묘한 문제를 만들 수 있습니다. Postgres Best Practices Agent Skills는 에이전트에게 수십 년간 축적된 데이터베이스 전문 지식을 제공하여, 단순히 작동하는 코드가 아니라 프로덕션 환경에서 안전하고 효율적으로 작동하는 코드를 생성하도록 안내합니다.
8개 카테고리에 걸친 30개 이상의 규칙은 쿼리 성능, 연결 관리, 보안, 스키마 설계, 동시성, 데이터 접근 패턴, 모니터링, 고급 기능을 포괄합니다. 각 규칙은 실제 경험에서 나온 것이며, Supabase가 수십만 개의 프로젝트를 실행하면서 반복적으로 목격한 문제를 해결합니다.
Supabase MCP 서버와 결합하면 에이전트는 데이터베이스에 연결하고 작업을 수행할 수 있는 능력뿐만 아니라, 올바르게 수행할 수 있는 판단력도 갖추게 됩니다. 이는 개발 속도를 늦추지 않으면서도 코드 품질과 안전성을 유지하는 강력한 조합입니다.
리포지토리는 github.com/supabase/agent-skills에서 확인할 수 있으며, 다음 Postgres 프로젝트에서 시도해보시고 어떤 규칙이 누락되었는지 알려주시기 바랍니다. 커뮤니티의 기여를 통해 이 스킬은 계속 성장하고 개선될 것입니다.
작성 일자: 2026-01-28