Claude Code as a DBA assistant: CLAUDE.md, rules, skills, agents, hooks and permissions
How the Claude Code configuration layers (CLAUDE.md, path-scoped rules, skills, sub-agents, hooks, permissions, MCP) fit together in a DBA scripts repository.
I use Claude Code every day on a repository full of PowerShell modules, T-SQL scripts and pipeline YAML. Out of the box it is a clever generalist. What turns it into a useful DBA assistant is the configuration around it: a handful of small files, each with one job. This article explains the layers and how they fit together.
The layers
flowchart TD
U["DBA request"] --> S["Claude Code session"]
S --> C["CLAUDE.md : always loaded"]
S --> R["Rules : loaded by file path"]
S --> K["Skills : loaded on demand"]
S --> A["Sub-agents : delegated work"]
S --> H["Hooks : run on events"]
S --> P["Settings : permissions"]
S --> M["MCP servers : external tools"]
P -->|allow ask deny| M
H -->|feedback or block| S
A --> R
K --> A
| Layer | File | Loaded | Job |
|---|---|---|---|
| Project memory | CLAUDE.md |
every session | what is true everywhere: architecture, how to build and test, safety rules, working style |
| Rules | .claude/rules/*.md |
when a matching file is opened | one convention per kind of file |
| Skills | .claude/skills/<name>/SKILL.md |
on demand | a workflow or a body of knowledge |
| Sub-agents | .claude/agents/*.md |
when delegated to | a specialist with its own context and tools |
| Hooks | settings.json |
on an event | deterministic checks and notifications |
| Settings | .claude/settings.json |
always | permissions, hooks, environment |
| MCP | .mcp.json or user scope |
at start | access to Grafana, Jira, docs, Azure |
CLAUDE.md: what holds everywhere
The repository CLAUDE.md is read at the start of every session, so every line costs context in every conversation. I keep in it only what must be true even when no specific file is open:
- the architecture in a few lines (the repo is a parent with modules and applications as submodules);
- the validation commands (lint, import the module, run the tests);
- an index of the other layers ("T-SQL conventions: rule X"), so Claude knows where to look;
- the safety section: which scripts are never run by the AI, what needs an explicit approval;
- the working style: state assumptions, minimal changes, verify before declaring done.
The personal file in the home directory holds generic behaviour; when the project file says something different, the project wins.
Path-scoped rules: one convention per kind of file
Application facts used to live in CLAUDE.md, loaded for nothing. I moved them into rules. A rule is a Markdown file with a paths list in its frontmatter; Claude loads it when it opens a matching file.
---
paths:
- "**/*.sql"
---
# T-SQL scripts
- Header comment: purpose, parameters, an example call.
- `SET NOCOUNT ON` and `TRY...CATCH` with `THROW` in procedures.
- Scripts that create or drop objects are idempotent.
I have one rule per language convention (PowerShell functions, SQL, pipelines, docs) and one per application, whose decisions and open points are only relevant when its folder is touched.
Skills, agents, hooks, permissions
- Skills carry a workflow ("diagnose a failed run", "write a KQL query") or knowledge (a map of the server estate). Only the short description is always visible; the body loads when the task matches or when I type the slash command.
- Sub-agents are specialists (SQL, PowerShell, Azure, documentation review). They work in their own context and return a summary, which keeps the main conversation small. See the dedicated article.
- Hooks run commands on events: lint every edited PowerShell file, play a sound when Claude is done. They are code, so they always run, unlike an instruction that a model may forget.
- Permissions in
settings.jsonhave three lists:allow(no prompt),ask,deny. Reads are allowed, destructive scripts are denied.
How a request flows
I ask for a change to a SQL template. Claude opens a .sql file, so the SQL rule loads. CLAUDE.md says SQL work goes to the SQL agent, which receives a short brief and the name of the rule. When a file is written, the lint hook runs. Anything that touches production hits the permission list first.
Lessons learned
- Put each fact in one place. Duplicated conventions drift. Agents and skills point to the rule, they do not copy it.
- Start the session at the repository root. Rules, hooks and deny lists live in the root
.claudefolder; a session started in a sub-folder does not get the root settings and runs without the deny rules. - Shared versus local. The committed settings hold read-only approvals; personal approvals go in the local settings file that is never committed.
- Instructions are not enforcement. If something must never happen, use a deny rule or a hook, not a sentence in
CLAUDE.md. - Prune. A long
CLAUDE.mdis read less carefully. When a paragraph only matters for one folder, it is a rule.