architecture

Context Engineering Mastery

The discipline of shaping what the model sees. CLAUDE.md hierarchy, retrieval patterns, memory tiers, and the prompts that compound.

14 min read·2026-05-16

The Shift

Prompt Engineering Is Dead

The difference: a prompt is what you say. Context is everything the model knows before you say anything. Most people optimize the tip of the iceberg while ignoring the 90 % below the surface.

“Prompt engineering is dead. Context engineering is the skill.”

A prompt is a single message. Context is the entire environment: your identity, your rules, your tools, your history, your constraints. Shaping that environment is where real leverage lives.

The Hierarchy

Context Pyramid

Bottom layers are fixed. Top layers are what you control. The further down you build, the more leverage you get per session.

06Your Messagejust the tip

05Memorypersistent knowledge

04Hooksautomatic injection + safety

03Skills.claude/skills/, structured tasks

02System ContextCLAUDE.md, your instructions

01Model Capabilitiesbase, you cannot change this

Weapon 1

CLAUDE.md Architecture

The most underused and most powerful weapon. Not just “be helpful” but a full operating system for your Claude, read at the start of every session.

CLAUDE.md defines who you are, how Claude should behave, what systems exist, what you are building, and how to handle edge cases. It is the difference between a blank-slate assistant and a deeply-informed collaborator.

Hierarchy: Global → Project → Subfolder

~/.claude/CLAUDE.mdGlobal: applies to every project. Your identity, communication style, universal rules.

project/CLAUDE.mdProject-level: specific tech stack, team, project context. Inherits from global.

project/src/CLAUDE.mdSubfolder-level: narrow overrides for specific areas. Inherits project + global.

Each level inherits from the one above and can override, like CSS specificity for AI context.

CLAUDE.md Template

# Your Name - Context File

## Identity & Business
[who you are, what you are building]

## How to Work With Me
[communication preferences, debugging style]

## Current Projects
[active work, priorities]

## Tools & Stack
[MCP servers, CLI tools, APIs available]

## Team Context
[engineers, clients, stakeholders]

## Rules & Constraints
[what not to do, when to ask, when to act]

Weapon 2

Memory Tiers

Auto-memory system lives at ~/.claude/projects/[project]/memory/. Every session adds to memory. The next session starts smarter, without you repeating yourself.

The Compound Effect

Every session adds facts, preferences, patterns, and corrections to memory files. Over weeks and months, Claude builds a deep understanding of your project, your style, your team, and your constraints, without you repeating yourself.

Memory Types

User memory: your preferences and identity
Project memory: project-specific facts and state
Feedback memory: corrections and improvements
Reference memory: bookmarks and external resources

Storage Location

~/.claude/projects/[hash]/memory/MEMORY.md

One file per project. Automatically loaded at session start. Claude writes to it when it learns something new about your project.

Weapon 3

Retrieval Patterns: Skills Architecture

Skills are reusable, named workflows stored in .claude/skills/. Each skill is a folder with a SKILL.md with instructions for a specific task triggered by name or keywords.

What Skills Are

Stored in .claude/skills/. Each is a folder with a SKILL.md containing instructions. Think of them as saved procedures Claude executes on demand.

Skills vs CLAUDE.md

CLAUDE.md = always active (loaded every session)
Skills = on-demand (loaded when triggered)
Skills can be composable: skill A can call skill B.

# Skill folder structure
.claude/skills/
  meeting-processor/
    SKILL.md           # instructions
    template.md        # output template
  client-report/
    SKILL.md
    report-template.md
  proposal/
    SKILL.md
    pricing-model.json

Weapon 4

Hooks: Prompts That Compound

Hooks run at specific points in the Claude Code lifecycle. They do not just protect. They inject context and transform what Claude sees, compounding with every action.

Three Hook Types That Matter

PreToolUseFires BEFORE a tool runs. Add context: "this file is critical, be careful." Block dangerous commands. Inject warnings.

PostToolUseFires AFTER a tool runs. Add context: "this ran, here is what to check next." Log changes. Validate outputs.

UserPromptSubmitTransforms the user's message BEFORE Claude sees it. Auto-append current year, expand shorthand, inject memory context.

Example: auto-append year to web searches

#!/bin/bash
query="$1"
year=$(date +%Y)

# If query does not contain a year, append current year
if ! echo "$query" | grep -qE '20[0-9]{2}'; then
  echo "${query} ${year}"
else
  echo "$query"
fi

The System

All 4 Weapons Working Together

What happens in every Claude Code session. Each weapon activates at the right moment.

Session Starts

CLAUDE.md loaded, always active context

Memory Files Loaded

Project context, user preferences, feedback history

User Types Message

Your prompt, the actual request

UserPromptSubmit Hook Fires

Enriches the message: appends year, injects memory, expands shorthand

Claude Processes With Full Context

CLAUDE.md + memory + enriched prompt = deeply informed response

PreToolUse Hook Fires

If a tool is called: safety checks, context injection, warnings

Tool Executes

File read, bash command, web search, etc.

PostToolUse Hook Fires

Log changes, validate output, add follow-up context

Response Generated

Informed by every layer of context

Stop Hook Fires

Save new learnings to memory for next session

Worked Examples

Context in Practice

Three scenarios showing how each layer compounds.

01Bootstrapping a New Project

Instead of writing CLAUDE.md from scratch, say: “I have a new project. Interview me.”Claude asks 10 targeted questions. You answer. Claude generates a complete CLAUDE.md. Five minutes of answers produces a context file that would take an hour to write manually.

User:   I have a new project. Interview me to build
        a CLAUDE.md for it.

Claude: I will ask 10 questions. Answer each one.

        1. What is this project?
        2. Who is the target user?
        3. What is the tech stack?
        4. What are the current priorities?
        5. What tools/MCP servers are available?
        6. What are the hard constraints?
        7. Who else is on the team?
        8. What should I never do?
        9. What is your communication style?
        10. What does success look like?

User:   [answers each question]

Claude: [generates complete CLAUDE.md]

02Persistent Code Review Style

Add a project/src/CLAUDE.md with specific rules for a module, e.g. “this directory uses Result types, never throw.” Claude applies these constraints automatically on every edit without you repeating them. Subfolder CLAUDE.md overrides project-level only where you need it.

# src/payments/CLAUDE.md
## Payment Module Rules
- Never throw; return Result<T, PaymentError>
- All amounts in smallest currency unit (cents)
- Log every state transition
- No external HTTP calls except Stripe SDK

03Memory-Driven Personalization

After a session where Claude learns you prefer concise PR descriptions, a Stop hook writes that preference to MEMORY.md. In the next session, Claude drafts shorter PRs without being told. The context compounds: week 1 feels different from week 8.

# MEMORY.md (auto-generated by Stop hook)
## Preferences
- PR descriptions: 2-3 bullet points max, no fluff
- Commit messages: imperative mood, ≤72 chars
- Code reviews: flag security issues first

## Project Facts (learned 2026-05-10)
- Stripe webhook secret rotated monthly
- Staging DB is read-only on weekends

The Cost of Skipping This

Anti-Patterns: Context Debt

What happens when you skip context engineering. The tax compounds daily.

Without Context Engineering

20 min/day re-explaining who you are
Inconsistent behavior across sessions
No compound improvement
Skills forgotten, patterns lost
Every session starts from zero

With Context Engineering

0 min re-explaining
Consistent, predictable behavior
Compound improvement over weeks
Skills and patterns persist
Every session starts smarter than the last

2-4h

Setup Time

20-30m/day

Time Saved

Week 1

Break-Even

Common anti-patterns to avoid:

One giant CLAUDE.md

Break it into global / project / subfolder layers. Specificity beats size.

Treating skills as prompts

Skills are persistent procedures. Write them once, trigger them forever.

Ignoring PostToolUse hooks

The best context injection happens after Claude acts, not before you ask.

Never writing to memory

If you correct Claude and don't log it, you'll correct it again next week.

Quick Reference

Context Engineering Mastery: Key Takeaways

→

Context is the entire environment Claude operates in, not just your current message.

→

CLAUDE.md hierarchy: global → project → subfolder, each inheriting and overriding.

→

Memory tiers accumulate across sessions; corrections compound into preferences.

→

Skills are on-demand retrieval: stored procedures for repeated workflows.

→

Hooks inject context at four lifecycle points: UserPromptSubmit, PreToolUse, PostToolUse, Stop.

→

Prompts compound when each session ends by writing learnings back to memory.

→

Context debt: every skipped layer costs ~20 min/day in re-explanation.

→

The Interview Pattern bootstraps CLAUDE.md in 5 minutes via structured Q&A.

To go deeper on hooks specifically, see Advanced Hooks. For how context engineering applies to agent teams, see Agent Swarms Architecture. Want help building this system for your team? Book a consultation.

Want this running in your stack?

AY Automate builds agent systems, RAG pipelines, and Claude Code setups for production teams.

Book a free architecture call See what we build