Context Engineering

Where Your
AI Looks

Five layers that turn a wandering agent into a focused one. The infrastructure that makes Copilot, Claude, and any other coding AI stop guessing and start delivering.

The Problem

Even with instructions, your AI still wanders

An instructions file is a real upgrade. After a few weeks, the cracks show. One file is loaded into every conversation, so it has to be short. Some rules belong everywhere; some rules belong on one file type; some rules are procedures, not standards. When everything goes in the same place, none of it lands consistently.

RULE: Be concise
Honored in chat. Forgotten during a long query review.
A single rule that should apply everywhere does not, because the model rereads the instructions file as a wall of text each turn and skips parts when context fills up.
RULE: lowercase_with_underscores in T-SQL
Applied to Power Query M by accident.
Dialect-specific rules in a global file leak into the wrong files. The AI cannot tell which rules apply to the file open in front of you, so it follows them everywhere or nowhere.
RULE: Run validation queries before publishing
Skipped because you forgot to remind it.
A multi-step procedure buried in a paragraph of identity copy. The model treats it as background flavor, not a checklist to execute.
The Idea

Context is a layered budget

Every token your AI reads is a token it cannot spend on your problem. The fix is not to write more rules, it is to put each rule on the right layer so it loads only when it actually applies. Three questions decide the layer.

When should it apply?
→
Always, only when a matching file is touched, only on a keyword, or only on a specific event.
Who pays the cost?
→
Every turn for always-on, just-in-time for path-scoped, near zero for dormant skills, separate context for delegated subagents.
How is it enforced?
→
Advisory (the model reads and tries to follow) or deterministic (a script runs and the rule cannot be skipped).
The Stack

Five layers, each with a different cost

Stacked from highest cost to lowest. The right rule on the right layer is the entire game. Every layer below the first is essentially free unless the model needs it.

01
Identity (always-on)
Standards, voice, what the project is. CLAUDE.md or .github/copilot-instructions.md.
Non-Technical Definition:Like a job description for the AI, loaded before every conversation. Same lens, every time.
Pays every turn
02
Path-scoped rules (auto-load)
File-type or folder rules that load only when a matching file is open or edited.
Non-Technical Definition:Rules tied to specific file types. T-SQL rules only show up when you are working in a .sql file, Power Query rules only when you open a .pq file.
Pays when relevant
03
Skills (keyword-triggered)
Multi-step procedures that stay dormant until a trigger phrase wakes them.
Non-Technical Definition:Pre-written recipes for tasks you do over and over. The AI ignores them until you say the magic words.
Pays when invoked
04
Subagents (delegated context)
A separate, tool-restricted helper for a single task. Its context never touches the main thread.
Non-Technical Definition:A side-assistant sent to do one focused job, like reviewing a query for performance issues or auditing a report's row counts. Reports back when done. Your main chat stays clean.
Separate window
05
Hooks (deterministic enforcement)
A shell command that runs on a fixed event (pre-edit, post-save, on-stop). Cannot be skipped.
Non-Technical Definition:A small automatic check that runs at a fixed moment (when you save a query, when you publish a report). The AI cannot turn it off or forget.
Runs as a script
Deep Dive

Layers 1 to 3: what the model reads

The first three layers shape what your AI sees before it starts thinking. Identity is the lens. Path rules are the page-margins. Skills are the recipes it can pull off the shelf when asked.

Layer 1 - Identity
What the project is, who it is for, how it should sound
Always loaded into every conversation. Best for standards, voice, project facts. Worst for procedures and language-specific rules. Keep it short, every word costs.
CLAUDE.md .github/copilot-instructions.md AGENTS.md
Cost: every token, every turn.
Layer 2 - Path rules
Rules that auto-load when a matching file is touched
A glob in the file's frontmatter decides when it loads. T-SQL rules load on .sql, Power Query rules load on .pq, report rules load on files inside the reports folder. Free until they apply.
.claude/rules/sql.md globs: "**/*.sql" .github/instructions/ reports.instructions.md globs: "reports/**"
Cost: zero unless a matching file is in scope.
Layer 3 - Skills
Multi-step procedures dormant until a keyword fires
A folder per skill with a SKILL.md describing trigger keywords. The model stays unaware of the procedure until you say one of the magic phrases, then it loads the steps and runs them.
.claude/skills/monthly-variance/ SKILL.md description: triggered by "monthly variance", "run the variance pack"
Cost: zero until invoked.
Deep Dive

Layers 4 and 5: what the model cannot skip

The last two layers solve different problems. Subagents protect the main conversation from doing too much at once. Hooks remove the model from the loop entirely for rules that must always fire.

Layer 4 - Subagents
A delegate with its own context and a restricted toolset
Spawn a separate helper for one task: a query review for performance issues, a row-count audit on a refreshed table, an open-ended search across the reports folder. Its context is fresh, its tools are limited to what the role needs, and the main conversation stays clean. When it finishes, only its summary returns.
.claude/agents/query-reviewer.md tools: [Read, Grep, Glob] description: review query for joins, indexes, and snake_case column names
Cost: separate context window. Main thread untouched.
Layer 5 - Hooks
A shell command that runs on a fixed event, no model in the loop
Configured in settings.json. Examples: a pre-save hook that strips em dashes from generated copy, a post-save hook that runs EXPLAIN against a query to catch missing indexes, an on-stop hook that blocks the AI from claiming work is done if a validation query has not been run. The model cannot decide to skip it.
.claude/settings.json { "hooks": { "PostToolUse": [...], "Stop": [...] } }
Cost: a shell command. Runs deterministically.
Routing

First-match wins. Walk down the list.

For any new rule, walk these five questions top to bottom. Stop at the first one that fits. The same rule placed on the wrong layer either burns context every turn or never fires when it should.

  1. Is this a universal rule or identity fact the AI must always know?
    CLAUDE.md
  2. Is this a file-type or folder-scoped rule that only applies sometimes?
    .claude/rules/*.md
  3. Is this a multi-step procedure or workflow a user kicks off by name?
    .claude/skills/*/SKILL.md
  4. Is this a restricted role with a limited toolset for one job?
    .claude/agents/*.md
  5. Must this fire deterministically, with no chance of being skipped?
    settings.json hook
The principle: every layer below identity is essentially free. Always-on context is the most expensive shelf in the system. If a rule does not need to live there, push it down.
Pitfalls

Three traps that quietly waste context

Every project that uses AI long enough drifts into one of these. They are easy to fix once you see them, hard to spot from inside.

TRAP 01
A workflow buried in CLAUDE.md
A 200-line "how we refresh and publish the monthly variance pack" lives in your always-on file. Every conversation pays for it, even a one-off question. The model skips most of it anyway. Everything is fighting for attention.
Move it to .claude/skills/monthly-variance/SKILL.md, triggered by "monthly variance". CLAUDE.md keeps a pointer.
TRAP 02
A dialect constraint in CLAUDE.md
"Always use T-SQL date helpers, never Oracle-style TRUNC" lives in your always-on file. You pay for it editing Excel formulas, writing markdown, answering chat questions. None of those need it.
Move it to .claude/rules/sql.md with globs: "**/*.sql". Free unless a SQL file is in play.
TRAP 03
A skill with no trigger keywords
You wrote a skill. Its description says "this is for handling the monthly variance pack" but never names a trigger keyword. The model cannot recognize when to load it, so the skill is dead weight. The work feels like it should fire and never does.
Put the exact phrases in the description: "triggered by 'monthly variance', 'variance pack', 'run the variance'." Specificity is the activation key.
Get Started

Audit your project in 15 minutes

  • 1
    Open your CLAUDE.md or copilot-instructions.md. Read it top to bottom. Note anything longer than three lines.
  • 2
    Walk each rule through the routing questions. Universal, file-scoped, procedure, restricted role, or deterministic? Mark every rule with the layer it actually belongs on.
  • 3
    Move file-type rules to .claude/rules/. One file per dialect or path: a sql.md for T-SQL conventions, a pq.md for Power Query, a reports.md for everything inside the reports folder. Add a globs: line to the frontmatter so it auto-loads only when relevant.
  • 4
    Move multi-step procedures to .claude/skills/. One folder per skill (monthly variance, week-over-week refresh, ad-hoc audit), each with a SKILL.md. Put exact trigger phrases in the description so the model knows when to load it.
  • 5
    For rules the AI must never skip, write a hook. Add it to .claude/settings.json under hooks. Hooks run as shell commands on fixed events (when a file is saved, when the AI tries to stop), with the model out of the loop.

The first audit is the longest. After that, every new rule has a home before it is written. Your CLAUDE.md gets shorter, your AI gets faster, and rules stop quietly disappearing under context pressure.

Sources

Where this comes from

Each layer in this module maps to a documented surface in either the Claude Code or VS Code Copilot ecosystem. The five-layer framing is original synthesis, but every layer is a real, documented configuration mechanism. Verify anything you want to.

  1. [1]
    Anthropic Docs Claude Code overview

    Umbrella reference for the Claude Code CLI. Backs the framing that CLAUDE.md, path-scoped rules, skills, subagents, and hooks are all first-class configuration surfaces, not just convention.

    docs.claude.com/en/docs/claude-code/overview
  2. [2]
    Anthropic Docs Subagents in Claude Code

    Documents how subagents are defined in .claude/agents/, how the tools list restricts their capabilities, and how their context is isolated from the main thread. Backs Layer 4 (scene 6).

    docs.claude.com/en/docs/claude-code/sub-agents
  3. [3]
    Anthropic Docs Hooks in Claude Code

    Reference for the hook system: hook events (PreToolUse, PostToolUse, Stop, etc.), how they are configured in settings.json, and the fact that they run as deterministic shell commands. Backs Layer 5 (scene 6) and the enforcement framing in scene 3.

    docs.claude.com/en/docs/claude-code/hooks
  4. [4]
    VS Code Docs Use custom instructions in VS Code

    Documents .github/copilot-instructions.md as the always-on identity surface plus the .github/instructions/ folder for path-scoped instructions. Backs Layers 1 and 2 in the Copilot ecosystem.

    code.visualstudio.com/docs/copilot/customization/custom-instructions
  5. [5]
    VS Code Docs Customize AI in Visual Studio Code

    Umbrella reference for every Copilot customization surface, including chat modes and reusable prompts (Copilot's analog to skills). Backs the cross-ecosystem framing in scenes 4 through 6.

    code.visualstudio.com/docs/copilot/customization/overview