저장 프로시저(Stored procedure), 마이그레이션 스크립트(Migration script), 복잡한 보고서(Complex report) — _Claude Code_는 이를 몇 초 만에 작성합니다. 그것은 쉬운 부분입니다. 진짜 어려운 부분은 그 이후에 시작됩니다. 누구의 소유도 아닌 생성된 SQL은 수작업으로 작성된 코드와 마찬가지로 점차 따로 놀게 됩니다. 다만 AI가 요청에 따라 수백 줄을 즉시 생성하기 때문에 그 속도가 훨씬 더 빠를 뿐입니다. AI 지원 SQL 개발은 생성된 코드가 수작업으로 작성된 코드와 동일한 컨벤션(Conventions)을 따를 때, 그리고 인간이 생성된 내용을 여전히 이해할 수 있을 때에만 가치가 있습니다.

이 글은 Claude Code를 활용한 AI 지원 SQL 개발이 실무에서 어떻게 작동하는지에 대한 시리즈의 입문서입니다. 단순한 자동 완성(Autocomplete)이 아니라, 세 가지 구체적인 레버(Levers)로서 작동합니다: 컨벤션을 강제하는 규칙 파일(Rules files), 반복적인 작업을 위한 기술(Skills), 그리고 다단계 데이터 워크플로우를 위한 **에이전트(Agents)**입니다. 관통하는 핵심 주제는 AI 그 자체가 아니라 SQL Server, Postgres, ETL과 같은 데이터 작업입니다.

학습 내용:

• 왜 SQL 및 ETL 작업이 특히 기계에 의해 강제되는 컨벤션의 이점을 얻는지;
• Claude Code의 세 가지 레버인 규칙(Rules), 기술(Skills), **에이전트(Agents)**와 각각의 용도;
• .claude/rules/ 파일이 어떻게 스타일 가이드(Style guide)를 생성 시점의 기본값으로 전환하는지;
• 왜 생성된 코드에는 컨벤션과 인간의 이해가 모두 필요한지 — 어느 하나만으로는 부족한 이유.

전제 조건: SQL/ETL에 대한 기본적인 이해. Claude Code (Anthropic의 AI 코딩 에이전트)는 여기서 소개될 예정이며, 이미 알고 있다고 가정하지 않습니다.

왜 AI 코딩인가, 그리고 왜 SQL 작업인가?

SQL 및 ETL 작업은 반복되는 패턴으로 가득 차 있습니다: 수백 개의 객체에 걸친 동일한 명명 규칙(Naming convention), 동일한 프로시저 레이아웃, 모든 로드 단계에서의 동일한 로그 삽입, 모든 문장에 걸친 동일한 포맷팅 등입니다. 이러한 패턴은 기계적 강제(Machine enforcement)를 위한 이상적인 토대입니다. AI가 신뢰성 있게 재현할 수 있을 만큼 규칙적이며, 인간의 규율이 결국 지칠 만큼 빈번하기 때문입니다.

동시에, SQL은 놓치기 쉬운 이해를 조용히 빠뜨리게 합니다: 구문적으로는 정확하지만, 빠르게 실행되고도 여전히 잘못된 질문에 답할 수 있는 문장이 있을 수 있습니다. SQL을 생성하는 AI는 양쪽 면 모두를 날카롭게 만듭니다 — 패턴을 더 빨리 생성하지만, 또한 오답도 더 빨리 생성합니다. 따라서 AI 지원 SQL 개발은 두 가지 안전장치와 함께 할 때만 가치가 있습니다: 코드가 읽기 쉽고 검토 가능하도록 강제되는 컨벤션(conventions)과 비즈니스 질문을 이해하는 사람입니다.

세 가지 레버리지: 규칙, 기술, 에이전트

Claude Code는 단순한 자동 완성 기능을 넘어선 세 가지 메커니즘을 제공하며 — 각각 다른 문제를 해결합니다:

• 규칙 파일(Rules files) (.claude/rules/) — 컨벤션 강제. 프로젝트가 요청 시마다 에이전트에게 자동으로 받는 지침입니다.

전통적인 스타일 가이드 (Style guide)와의 차이점은 근본적입니다. 위키(Wiki)에 있는 스타일 가이드는 인간의 규율에 의존하며 잊히기 쉽지만, 규칙 파일 (Rules file)은 에이전트가 생성할 때마다 매번 전달됩니다. "이를 준수해 주세요"가 "이것이 생성되는 방식입니다"로 바뀌는 것입니다. 이를 유지하기 위해서는 규칙 파일을 인간이 아닌 에이전트용으로 다르게 구축해야 합니다. 즉, 산문(Prose) 대신 명시적인 코드 예시를 사용하고, 명시적인 안티 패턴 (Anti-patterns, Don'ts)을 포함하며, — 가장 중요한 점은 — 에이전트가 이를 새로운 사례에 적용할 수 있도록 규칙마다 이유를 명시해야 합니다.

이름 접두사(Name prefix)부터 접이식 블록 구조(Collapsible block structure), 표 형식 정렬(Tabular alignment)에 이르기까지 상세한 모습은, 완성되고 검증된 sql.md를 사용하는 PL/pgSQL 컨벤션 (PL/pgSQL conventions) 관련 자매 기사에서 확인할 수 있습니다. 이 섹션의 사례 연구(Case study)에 해당합니다. 그리고 이러한 규칙 파일이 애초에 어떻게 만들어지는지 — 즉, _Claude Code_가 수동 수정 사항을 규칙으로 변환하는 과정 — 는 **Claude Code를 활용한 SQL 컨벤션 도출 (Deriving SQL Conventions with Claude Code)**에서 단계별로 보여줍니다.

규칙 파일의 이면에 있는 "무엇(What)", 즉 포맷팅과 구조에 대한 구체적인 컨벤션은 이 블로그의 SQL 문 포맷팅 (Formatting SQL Statements) (Part 1) 및 Part 2 기사와 SQL 문 구조화 (Structuring SQL Statements) 기사에서 상세히 설명되어 있습니다. 규칙 파일은 그러한 지식을 기계가 강제하는 규칙으로 변환합니다.

기술 (Skills) 및 슬래시 명령어 (Slash commands): 반복되는 SQL 작업

매번 같은 방식으로 수행하는 몇 가지 작업들이 있습니다: 표준 절차에 따라 새 테이블을 생성하거나, ETL 단계에 로깅 패턴을 삽입하거나, 사내 규칙에 따라 문장을 포맷팅하거나, 데이터 품질 검사 (data-quality check)를 생성하는 작업 등입니다. 기술 (Skill) (Claude Code에서 슬래시 명령어 (slash command)로 호출됨)은 필요한 단계와 컨벤션 (convention)을 포함하여 이러한 루틴을 하나의 이름 아래 캡슐화합니다.

이를 통해 얻는 이점은 재현성 (reproducibility)입니다. 매번 프롬프트 (prompt)를 다시 작성하는 대신 (그 과정에서 이것저것 잊어버리는 대신), 검토된 동일한 루틴을 매번 호출할 수 있습니다. SQL 작업의 경우, 예를 들어 대리 키 (surrogate-PK) 규칙에 따라 테이블을 생성하고, 사내 스타일로 sp_ins_/sp_upd_ 프로시저를 바로 옆에 생성하는 기술을 만든다면, 매번 동일한 구조로 작업이 수행됩니다.

에이전트 (Agents): 다단계 데이터 워크플로 (multi-step data workflows)

가장 강력한 지렛대이자, 동시에 가장 세심한 주의를 요구하는 요소입니다. **에이전트 (Agent)**는 단일 프롬프트를 넘어선 루틴을 실행합니다. 즉, 여러 단계, 중간 결과, 도구 호출 (tool calls), 검사 등을 수행합니다. ETL 자체가 추출 (extract), 검사 (check), 변환 (transform), 로드 (load), 로깅 (log)과 같은 다단계 과정이므로, ETL 컨텍스트 (context)에서 에이전트는 매우 자연스럽게 어울립니다.

예를 들어, 에이전트는 소스 테이블을 분석하고, 적절한 데이터 품질 검사를 제안하며, 로드 스크립트를 생성하고 로깅을 연결할 수 있습니다. 이 모든 과정은 규칙 (rules) 파일이 규정한 컨벤션에 따라 이루어집니다. 결정적인 지점은 다음과 같습니다. 에이전트가 스스로 수행하는 단계가 많아질수록, 처음부터 설정한 두 가지 가드레일 (guardrails)이 더욱 중요해집니다. 강제된 컨벤션은 생성된 코드를 검토 가능한 상태로 유지해 줍니다. 비즈니스 질문을 이해하고 있는 사람이 에이전트가 생성한 결과물 중, 그럴듯해 보이지만 틀린 결과를 올바른 결과만큼이나 능숙하게 잡아낼 수 있게 합니다.

공통 분모: 생성된 코드에는 이해가 필요하다

이 세 가지 레버(levers)를 관통하는 동일한 논지는 다음과 같습니다. 도구는 타이핑(typing)의 수고를 덜어줄 뿐, 이해(understanding)를 대신해주지는 않는다는 점입니다. SQL을 포맷팅하고 구조화하는 것은 단순히 미적인 작업이 아니었습니다. 그것은 문장 전체를 읽고 테이블 간의 관계를 머릿속으로 구축하는 행위입니다. AI가 이 행위를 대신하게 되면 격차가 발생합니다. 기술적으로는 정확하지만, 여전히 비즈니스 질문에는 답하지 못하는 SQL이 만들어지는 것입니다.

컨벤션(Conventions) 그 자체가 이 격차를 메워주지는 않지만, 격차를 가시화해 줍니다. 사내 규칙(house rules)을 따르는 생성된 코드는 사람이 먼저 해독할 필요 없이 몇 초 만에 검토할 수 있을 만큼 가독성이 높습니다. 이것이 바로 규칙(rules), 기술(skills), 에이전트(agents)가 도메인 지식(domain knowledge)의 대체재가 아니라 증폭기(amplifier)인 정확한 이유입니다. 이들은 재현 가능한 부분을 안정적으로 처리하며, 어떤 모델도 안전하게 수행할 수 없는 일, 즉 '올바른 질문을 던지는 일'에 인간의 정신을 집중할 수 있도록 해줍니다.

FAQ

Claude Code가 반드시 필요한가요, 아니면 다른 AI 도구에서도 작동하나요?

강제된 컨벤션(enforced conventions), 캡슐화된 작업(encapsulated tasks), 다단계 루틴(multi-step routines)이라는 세 가지 레버는 개념적으로 도구에 구애받지 않습니다(tool-agnostic). 구체적인 구현 방식은 다릅니다. Claude Code는 .claude/rules/ 파일을 프로젝트 지침으로 자동 로드하지만, 다른 도구들은 각자의 메커니즘(프로젝트 설정, 시스템 프롬프트, 커스텀 인스트럭션)을 가지고 있습니다. "기계가 로드하는 규칙으로서의 컨벤션"이라는 원칙은 전이되지만, 파일 경로가 1:1로 일치하지는 않습니다.

생성된 SQL이 프로덕션(production) 환경에서 사용하기에 충분히 안전한가요?

검토(review)가 동반될 때만 그렇습니다. AI는 그릇된 부분이 포함된, 그럴듯해 보이는 코드를 생성합니다. 강제된 컨벤션은 생성된 코드가 가독성을 유지하고 따라서 검토 가능하게 만듦으로써 리스크를 낮춰주지만, 검토 자체를 대체하지는 않습니다. 보안 관련 로직(권한 확인, 데이터 변형(mutations))은 특히 주의 깊은 읽기가 필요합니다.

AI가 제 컨벤션을 무시하지 않게 하려면 어떻게 해야 하나요?

머릿속에 담아두는 대신, 저장소(repo) 내의 규칙(rules) 파일에 컨벤션(conventions)을 기록해 두는 것입니다. 다음 세 가지가 도움이 됩니다: 산문 형태의 설명 대신 명시적인 코드 예시(code examples)를 제공하는 것, 명시적인 '하지 말아야 할 것(Don'ts, 안티 패턴(anti-patterns))'을 정의하는 것, 그리고 각 규칙마다 이유를 명시하여 에이전트(agent)가 학습하지 않은 사례에도 이를 적용할 수 있도록 하는 것입니다.

이것이 개인 개발자에게도 가치가 있을까요, 아니면 팀 단위에서만 유용할까요?

둘 다 해당하며, 이유는 서로 다릅니다. 팀의 경우, 컨벤션은 여러 명의 작업자 사이에서 스타일이 어긋나는 것(drift)을 방지합니다. 개인 개발자의 경우, 규칙을 절대 잊지 않는 '두 번째 개발자'를 얻는 효과가 있습니다. 혼자 작업하더라도 생성된 코드가 일관성을 유지하고, 18개월 뒤에도 읽기 쉬운 상태로 남는 이점을 누릴 수 있습니다.

AI 워크플로우 (AI workflow) (규칙 이면의 "방법"):

• Claude Code를 활용한 SQL 컨벤션 도출 — Generate-Refine-Derive 루프

SQL 컨벤션 및 구조 (SQL conventions & structure) (AI가 강제하는 "대상"):

• SQL 컨벤션 // 2년 뒤에도 읽을 수 있는 PL/pgSQL 프로시저(Procedures)
• Postgres 테이블 컨벤션 — 일관된 스키마(Schema)를 위한 명명 규칙, 키(Keys) 및 감사 컬럼(Audit Columns)
• PL/pgSQL 함수 컨벤션 — 휘발성(Volatility), RETURNS 및 프로시저와의 경계
• PL/pgSQL 테이블 반환 함수 (Table-Returning Functions) — RETURNS TABLE, SETOF 및 뷰(View)가 더 나은 경우
• SQL 문 포맷팅 (Part 1) — 식별자(Identifiers), 구분자(Delimiters), 쉼표(Commas), 별칭(Aliases)
• SQL 문 포맷팅 (Part 2) — 문장 구조: SELECT, WHERE, FROM, JOIN
• SQL 문 구조화 및 포맷팅 (Structuring and Formatting SQL Statements)

ETL 실무 (ETL practice) (기술(skills)과 에이전트(agents)의 토대):

• 디자인 패턴 // ETL 프로세스의 아키텍처
• ETL 프로세스에서의 데이터 품질 관리
• 디자인 패턴 // T-SQL을 사용한 ETL 프로세스 로깅