context-engineering

Context Engineering

Overview

Feed agents the right information at the right time. Context is the single biggest lever for agent output quality — too little and the agent hallucinates, too much and it loses focus. Context engineering is the practice of deliberately curating what the agent sees, when it sees it, and how it's structured.

When to Use

• Starting a new coding session
• Agent output quality is declining (wrong patterns, hallucinated APIs, ignoring conventions)
• Switching between different parts of a codebase (Avalonia host vs ASP.NET Core API vs shared Core)
• Setting up a new project for AI-assisted development
• The agent is not following project conventions

The Context Hierarchy

Structure context from most persistent to most transient:

┌─────────────────────────────────────┐
│  1. Rules Files (CLAUDE.md, etc.)   │ ← Always loaded, project-wide
├─────────────────────────────────────┤
│  2. Spec / Architecture Docs        │ ← Loaded per feature/session
├─────────────────────────────────────┤
│  3. Relevant Source Files            │ ← Loaded per task
├─────────────────────────────────────┤
│  4. Error Output / Test Results      │ ← Loaded per iteration
├─────────────────────────────────────┤
│  5. Conversation History             │ ← Accumulates, compacts
└─────────────────────────────────────┘

Level 1: Rules Files

Create a rules file that persists across sessions. This is the highest-leverage context you can provide.

CLAUDE.md (for Claude Code) — example for a .NET/Avalonia project:

# Project: [Name]

## Tech Stack
- .NET 8 (LTS), C# 12
- Avalonia 11 for desktop UI (CommunityToolkit.Mvvm for view models)
- ASP.NET Core 8 for the HTTP API
- EF Core 8 against PostgreSQL (Npgsql); SQLite for integration tests
- xUnit v3 + native `Xunit.Assert` for unit tests; WebApplicationFactory for integration tests
- `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`, `<Nullable>enable</Nullable>`

## Solution layout
- src/MyApp               → Avalonia host, composition root
- src/MyApp.Core          → Domain types, use cases, pure logic (no framework references)
- src/MyApp.Infrastructure → EF Core DbContext, external integrations
- src/MyApp.Contracts     → DTOs shared by server + clients
- tests/MyApp.Core.Tests
- tests/MyApp.Infrastructure.Tests

## Commands
- Restore:  `dotnet restore`
- Build:    `dotnet build -warnaserror`
- Test:     `dotnet test --collect:"XPlat Code Coverage"`
- Format:   `dotnet format --verify-no-changes`
- Run host: `dotnet run --project src/MyApp`
- Migrate:  `dotnet ef migrations add <Name> -p src/MyApp.Infrastructure -s src/MyApp`

## Code Conventions
- Nullable reference types on (`<Nullable>enable</Nullable>`); public APIs have honest nullability
- `_camelCase` for private fields; `PascalCase` for properties and methods
- Prefer `record` / `record struct` for value-typed data with value equality
- Expression-bodied methods only when the body is one short line
- File-scoped namespaces; one top-level type per file
- `async` methods always accept `CancellationToken` on I/O paths; no sync-over-async (`.Result`, `.Wait()`)
- `using` directives sorted alphabetically with `System.*` first

## Boundaries
- Never commit secrets; use `dotnet user-secrets` for dev and Key Vault / env for prod
- Never add a NuGet package without updating `Directory.Packages.props`
- Ask before modifying EF Core migrations or `DbContext` shape
- Ask before adding project references (we intentionally avoid `Core → Infrastructure`)
- Always run `dotnet test` and `dotnet build -warnaserror` before committing

## Patterns
[Paste one short, well-written view model or service from the codebase — e.g. a CommunityToolkit.Mvvm partial class with observable properties and a RelayCommand, or an ASP.NET Core Minimal API endpoint with ProblemDetails error handling]