AI-Assisted SQL Development with Claude Code — Rules, Skills and Agents That Enforce Conventions

Published Jun 6, 2026
by

A stored procedure, a migration script, a complex report — Claude Code writes them in seconds. That’s the easy part. The hard part starts afterwards: generated SQL that belongs to no one drifts apart just like hand-written code — only faster, because the AI produces hundreds of lines on demand. AI-assisted SQL development only pays off when the generated code follows the same conventions as the hand-written kind — and when a human still understands what was produced.

This article is the entry point to a series on how AI-assisted SQL development with Claude Code works in practice — not as autocomplete, but as three concrete levers: rules files that enforce conventions, skills for recurring tasks, and agents for multi-step data workflows. The common thread stays the data work: SQL Server, Postgres, ETL — not AI for its own sake.

What you’ll take away:

  • why SQL and ETL work in particular benefits from machine-enforced conventions;
  • the three levers of Claude Code — rules, skills, agents — and what each is good for;
  • how a .claude/rules/ file turns a style guide into a default at generation time;
  • why generated code needs conventions and human understanding — not one without the other.

Prerequisite: a basic grasp of SQL/ETL. Claude Code (Anthropic’s AI coding agent) is introduced here, not assumed.

Contents

Why AI coding, and why for SQL work?

SQL and ETL work is full of recurring patterns: the same naming convention across hundreds of objects, the same procedure layout, the same log inserts in every load step, the same formatting across every statement. Patterns like these are the ideal ground for machine enforcement — regular enough that an AI can reproduce them reliably, and numerous enough that human discipline eventually tires.

At the same time, SQL lets missing understanding slip through silently: a statement can be syntactically correct, run fast, and still answer the wrong question. An AI that generates SQL sharpens both sides — it produces patterns faster, but it also produces wrong answers faster. AI-assisted SQL development is therefore only worth it with two guardrails: enforced conventions, so the generated code stays readable and reviewable, and a human who understands the business question.

The three levers: rules, skills, agents

Claude Code offers three mechanisms that go beyond plain autocomplete — each solves a different problem:

  • Rules files (.claude/rules/) — enforce conventions. Project instructions the agent receives automatically on every request. They answer: “What should generated code look like?”
  • Skills / slash commands — encapsulate recurring tasks. Named, parameterizable routines for things you do the same way over and over. They answer: “How do I trigger a known task reproducibly?”
  • Agents — orchestrate multi-step workflows. Routines that go beyond a single prompt — several steps, tools, checks. They answer: “How do I run a whole chain of steps reliably?”

The following sections take each lever in turn — through the SQL lens.

Rules files: conventions the agent enforces

The most direct lever. A .claude/rules/ file sits in the repository and is handed to Claude Code as a project instruction on every request. Whatever it says becomes the default at generation time: prescribe sp_<verb>_<entity> and you get sp_upd_project instead of update_project — without anyone having to remember it in review.

The difference from a classic style guide is fundamental. A style guide in a wiki depends on human discipline and gets forgotten; a rules file is handed to the agent on every generation. “Please stick to it” becomes “this is how it’s generated”. For that to hold, the rules file must be built differently for an agent than for a human: explicit code examples instead of prose, explicit anti-patterns (Don'ts), and — most importantly — a reason per rule, so the agent can transfer it to new cases.

What that looks like in detail — from the name prefix through the collapsible block structure to tabular alignment — is shown by the sister article on PL/pgSQL conventions using a complete, battle-tested sql.md. It’s the case study for this section.

The “what” behind the rules files — the concrete conventions for formatting and structure — is described at length on this blog anyway: in the articles on Formatting SQL Statements (Part 1) and Part 2, and on Structuring SQL Statements. A rules file turns that knowledge into a machine-enforced rule.

Skills and slash commands: recurring SQL tasks

Some tasks you do the same way every time: create a new table with its standard procedures, drop a logging pattern into an ETL step, format a statement by the house rules, generate a data-quality check. A skill (invoked as a slash command in Claude Code) encapsulates such a routine under a name — including the necessary steps and conventions.

The gain is reproducibility: instead of rephrasing every prompt (and forgetting this or that along the way), you invoke the same reviewed routine every time. For SQL work that means, for instance: a skill that creates a table by the surrogate-PK rule and generates the sp_ins_/sp_upd_ procedures in the house style right alongside — identically structured every time.

Agents: multi-step data workflows

The biggest lever — and the one that demands the most care. An agent runs a routine that goes beyond a single prompt: several steps, intermediate results, tool calls, checks. In the ETL context this is a natural fit, because ETL itself is multi-step — extract, check, transform, load, log.

An agent could, say, analyze a source table, propose a suitable data-quality check, generate the load script and wire in the logging — all in the conventions the rules file prescribes. The decisive point: the more steps an agent takes on its own, the more important the two guardrails from the start become. Enforced conventions keep the generated code reviewable; a human who understands the business question catches the plausible-but-wrong results that an agent produces just as fluently as the right ones.

The common thread: generated code needs understanding

The same thesis runs through all three levers: the tool takes the typing off your hands, not the understanding. Formatting and structuring SQL was never just cosmetics — it’s the act in which you read the statement in full and build the relationships between the tables mentally. When the AI takes over that act, a gap opens up: technically correct SQL that still doesn’t answer the business question.

Conventions don’t close that gap by themselves — but they make it visible. Generated code that follows house rules is readable enough for a human to review in seconds instead of having to decipher it first. That’s exactly why rules, skills and agents are not a replacement for domain knowledge but an amplifier: they handle the reproducible part reliably and free the human’s mind for what no model can do safely — asking the right question.

FAQ

Do I need Claude Code, or does this work with any AI tool?

The three levers — enforced conventions, encapsulated tasks, multi-step routines — are tool-agnostic as a concept. The concrete implementation differs: Claude Code loads .claude/rules/ files automatically as a project instruction, other tools have their own mechanisms (project settings, system prompts, custom instructions). The principle “conventions as a machine-loaded rule” transfers; the file paths don’t, 1:1.

Is generated SQL safe enough for production?

Only with review. An AI produces plausible code — including where it’s wrong. Enforced conventions lower the risk because generated code stays readable and therefore reviewable; they don’t replace the review. Security-relevant logic (permission checks, mutations) deserves especially careful reading.

How do I keep the AI from ignoring my conventions?

By keeping the conventions in a rules file in the repo instead of in your head. Three things help: explicit code examples instead of prose descriptions, explicit Don'ts (anti-patterns), and a reason per rule, so the agent transfers it to cases it hasn’t been shown.

Is this worth it for solo developers or only in a team?

Both — for different reasons. In a team, conventions prevent drift across several hands. Solo, the gain is the “second developer” that never forgets the rules: even working alone, you benefit from generated code staying consistent and still being readable in 18 months.

SQL conventions & structure (the “what” the AI enforces):

ETL practice (the ground for skills and agents):