Someone asked me for a practical example of context engineering.

Here is one pattern I use: keep a separate context layer for product memory, and give agents clear rules for maintaining it.

This is different from putting another AGENTS.md into the product codebase. In this pattern, the context layer may live in a separate repository, an Obsidian-like folder, Confluence, or another internal knowledge base. It is not the source code. It is the structured memory around the product: pages, workflows, API behavior, business rules, incidents, and decisions.

The goal is not to give an agent more text. The goal is to give it the right shape of context.

Why Project Context Comes Before Agent Work

Most AI workflows start too late:

Here is the task. Inspect the repo and figure it out.

Sometimes this works. Often it guesses.

The better starting point is the context layer around the product. That context is useful across many kinds of work:

  • developing new features
  • extending existing product behavior
  • refactoring safely
  • debugging production issues
  • handling support requests
  • onboarding engineers
  • sharing knowledge across teams
  • reviewing changes with product and operations stakeholders

Support requests are only one use case, but they are a useful example because they expose the problem clearly: the person reporting the issue often does not provide enough context.

A support request usually starts from a user-facing surface:

  • The dashboard does not load.
  • Export fails for this client.
  • This button works for one account but not another.
  • The page shows a state that should not be possible.

If the intake process only says “dashboard broken”, the agent is already starting from a weak signal. In many teams, the first improvement is not the agent at all. It is the support reporting process.

At minimum, a useful report should identify:

  • affected page, route, or feature
  • visible error message
  • expected behavior
  • actual behavior
  • screenshot or screen recording when relevant
  • reproduction steps if known
  • affected user, account, client, or tenant
  • timestamp or time window
  • Sentry issue, observability report, request ID, or logs link when available

That does not mean every report becomes perfect. It means the workflow has a clear place to attach evidence before the agent starts reasoning.

For production issues, I want the agent or intake system to collect signals from the systems that know what happened:

  • support request details
  • screenshots and reproduction steps
  • Sentry issue or stack trace
  • breadcrumbs, logs, and traces
  • failed API calls
  • recent deploys
  • feature flags
  • affected user, account, client, or tenant
  • the page, route, feature, or workflow involved

Sentry and other observability tools are not just debugging tools in this model. They are context sources. They tell the agent what happened, where it happened, how often it happened, and whether it correlates with a deploy, API failure, frontend route, or customer segment.

But raw observability data should not become permanent context by default. A stack trace is useful evidence. A durable lesson is more valuable.

Bad durable context:

User 123 clicked export on March 3 and got error X after deploy abc123.

Better durable context:

Export failures on the dashboard are often caused by stale client permissions after deployment. Check Sentry tag page:dashboard and API response 403 before changing frontend retry logic.

The second version helps the next agent avoid rediscovering the same pattern.

The same idea applies outside support. For new feature work, the context layer should explain the workflow, business rules, API meaning, and decision history. For refactoring, it should explain which behavior is intentional and which boundaries should not be changed casually. For knowledge sharing, it should give humans and agents the same durable product memory instead of forcing everyone to reverse-engineer intent from code.

Think Like a Frontend Folder Structure

When I talk about context engineering, I often think about frontend project structure.

React, Angular, and Next.js projects already split complexity into useful boundaries:

  • pages
  • routes
  • features
  • shared components
  • API clients
  • state management
  • common utilities
  • domain modules

The context layer can follow a similar shape.

It should not be too broad:

all frontend logic

It should not be too narrow:

one button component with no business meaning

The useful unit is usually the level an experienced engineer or product person would naturally use to explain the system:

  • page
  • route
  • feature
  • workflow
  • API boundary
  • shared state
  • common module
  • recurring incident type

For UI-heavy work, page or route context is often a good starting point. This maps naturally to systems like Next.js routing, where the page is already the user-facing unit of behavior.

Example:

context/
  AGENTS.md
  pages/
    dashboard/
      index.md
      API.md
      incidents.md
  features/
    exports/
      index.md
      API.md
      decisions.md
  common/
    permissions.md
    error-handling.md
  workflows/
    client-onboarding.md
    export-retry.md

In this structure:

  • AGENTS.md explains how agents should maintain the context layer.
  • pages/dashboard/index.md stores business logic and decisions for the dashboard.
  • pages/dashboard/API.md explains which endpoints the page uses and what they mean.
  • pages/dashboard/incidents.md captures recurring production patterns.
  • common/permissions.md stores shared permission rules used across areas.

The important part is that this context is separate from the product codebase. It can reference code, tickets, Sentry issues, PRs, and Confluence pages, but it is not a dumping ground for all of them.

The Role of AGENTS.md

In a product repository, AGENTS.md often tells agents how to work with the codebase.

In a context layer, AGENTS.md has a different job. It tells agents how to interact with context:

  • when to add context
  • when to update context
  • when to remove context
  • how to summarize noisy evidence
  • how to avoid duplicating documentation
  • how to keep context small enough to be useful

Here is a compact example.

# AGENTS.md

## Purpose

This repository is a context layer for AI agents.

It is not the product codebase.

The goal is to maintain clean, useful, human-readable context about product
areas, pages, features, APIs, business rules, incidents, and technical decisions.

Agents use this context to understand the system before acting in another
environment, such as a codebase, ticket system, observability tool, or Confluence.

## Context Storage

Context may live in:

- a separate context repository
- an Obsidian-like folder structure
- Confluence pages
- another internal knowledge base

The storage location is less important than the structure and maintenance rules.

Good units of context:

- product page
- route
- feature
- workflow
- API boundary
- shared module
- business process
- recurring incident type

Avoid context that is either too broad or too narrow.

Too broad:

- the whole dashboard system
- all frontend logic
- all API behavior

Too narrow:

- one button with no business meaning
- one component with no workflow context
- one error message without the surrounding process

## Ingest Rules

When adding new context, do not dump raw information directly into the context layer.

First identify:

1. What product area does this belong to?
2. Is this page-level, feature-level, workflow-level, API-level, or shared context?
3. Is this durable knowledge or temporary noise?
4. Is this already documented somewhere else?
5. What should an agent know next time to avoid rediscovering this?

Sources may include:

- support tickets
- Sentry issues
- logs
- traces
- user reports
- screenshots
- incident reviews
- pull requests
- Slack discussions
- Confluence pages
- product specs
- engineer notes

Always synthesize. Do not paste long raw threads unless explicitly needed.

## What To Add

Add context when it helps future agents or humans understand:

- business rules
- user-facing behavior
- API meaning
- known failure modes
- observability signals
- important tradeoffs
- ownership boundaries
- recurring incidents
- decisions that are easy to forget
- things that look like bugs but are intentional

Good context answers questions like:

- Why does this page behave this way?
- What does this API mean in business terms?
- What usually causes this error?
- Which observability signals should be checked first?
- What should not be changed casually?
- What decision was made and why?

## What Not To Add

Do not add:

- full source files
- huge ticket dumps
- stale implementation details
- temporary debugging notes
- personal opinions without evidence
- duplicated documentation
- vague summaries like "this page handles data"
- information that will be obsolete after one deploy

If the information is useful only for the current task, keep it out of durable context.

## Context Size

Keep each file small enough to be read by an agent in one pass.

Prefer:

- short sections
- explicit bullets
- concrete examples
- links to raw sources when needed

Avoid:

- long narrative history
- repeated explanations
- every implementation detail
- unstructured notes

If a file grows too large, split it by page, feature, workflow, API, or incident type.

## Update Rules

When new information changes existing understanding:

1. Update the relevant context file.
2. Remove or rewrite stale information.
3. Preserve the decision history only if it still helps future reasoning.
4. Add a short note explaining what changed and why.

Do not append endlessly.

Context should become cleaner over time, not larger by default.

## Pruning Rules

Remove or compress context when:

- it duplicates another file
- it describes behavior that no longer exists
- it is too implementation-specific
- it came from a one-off incident with no recurring value
- it makes the agent more confused rather than more informed

When pruning, keep the durable lesson and remove the noise.

## Observability Context

When a request, task, or incident is connected to production behavior, check observability
sources before updating context.

Useful signals:

- Sentry issue
- stack trace
- breadcrumbs
- frontend route
- failed API call
- request ID
- logs
- traces
- feature flags
- recent deploys
- affected user, client, account, or tenant

Observability data should be summarized into durable patterns.

Do not store raw logs unless they are necessary as an example.

## Conflict Handling

If context conflicts with source-of-truth systems:

- code is the source of truth for current implementation
- observability is the source of truth for production behavior
- product/spec documents are the source of truth for intended behavior
- context files are the source of truth for agent-readable synthesis

When conflict is found, update the context file to explain the discrepancy.

## Output Format For Updates

When updating context, write:

```text
Updated context
- File updated:
- Reason:
- Source:
- Durable lesson:
- Removed stale context:
- Open questions:
```

## Core Principle

Context engineering is not about storing more information.

It is about maintaining the right level of product memory:

specific enough to be useful,
general enough to stay durable,
small enough for agents to actually use.

The Hard Part Is Pruning

Most teams understand ingestion. They know how to dump tickets, logs, meeting notes, and documentation into a knowledge base.

The hard part is pruning.

Without pruning, a context layer becomes another stale documentation system. Agents read too much, trust the wrong things, and confuse temporary evidence with durable product knowledge.

That is why I think every context layer needs explicit rules for removal:

  • remove duplicate explanations
  • compress one-off incidents into recurring patterns
  • delete implementation details that no longer match the code
  • rewrite vague notes into concrete business rules
  • split files that are too large to be useful

The goal is not a bigger memory. The goal is a better memory.

What Changes for the Agent

With this structure, an agent no longer starts from:

Search the whole repo and figure out what matters.

For feature work, it can start from:

This change extends the dashboard export workflow. Check the dashboard context, export workflow, API context, and existing decision notes before changing behavior.

For support work, it can start from:

This support request affects the dashboard page. Check the dashboard context, API context, recent incidents, and Sentry signal before deciding whether this is frontend state, permission logic, API failure, or expected behavior.

That is a different operating mode.

The agent still needs access to the codebase when it is time to make a change, review an implementation, or diagnose a bug. But the first pass of reasoning happens against a maintained product memory, not a random scrape of files and tickets.

This is useful in several loops:

  • feature development, where the agent needs the business rules before writing code
  • extension work, where the agent must preserve existing product semantics
  • refactoring, where the agent needs to know which behavior is intentional
  • knowledge sharing, where humans and agents need a common product memory
  • support workflows, where production evidence and product context must be joined

A support workflow is one concrete example:

  1. A user reports a UI issue.
  2. The intake process captures at least the page, visible error, affected account, and time window.
  3. The system matches the report to a page, route, or feature.
  4. Observability sources provide production evidence when available.
  5. The context layer provides product and business meaning.
  6. The agent proposes a diagnosis or fix.
  7. A human reviews the output with the same context available.
  8. Durable lessons are written back into the context layer.

The loop improves over time because the context improves over time.

Closing

Context engineering is not prompt engineering with larger prompts.

It is the design and maintenance of product memory around the way the system actually works.

The right context layer should feel familiar to engineers. It should have boundaries like the product has boundaries: pages, features, workflows, API contracts, shared modules, common rules, and recurring incident patterns.

It should be specific enough to help an agent act, general enough to remain durable, and small enough to be read.

That is how agents stop randomly searching the repo and start operating inside the same mental model as the engineering team.