Managing context in a multi-agent workflow

An LLM’s context window isn’t infinite memory — it’s a sliding window. The longer a session runs, the more the initial instructions lose their influence. That’s context rot , and it’s the central operational problem of agentic workflows in production.

The solution isn’t to wait for models with bigger contexts — it’s to structure work so you never reach degradation. This guide documents the patterns that work on real projects.

Why do long sessions degrade?

LLMs use an attention mechanism that weights tokens by their position in the context. Put simply: recent tokens carry more weight than older ones. The longer the session, the more the early instructions (project conventions, constraints, tone) lose their influence on the agent’s decisions.

In practice, after 20-30 exchanges in a session, you observe:

• The agent starts ignoring constraints stated at the beginning (“use the existing helpers”)
• It produces code in a slightly different style than at the start of the session
• It repeats explanations it already gave
• It makes architecture choices that contradict what had been established

This isn’t a bug — it’s how the model works. The answer is work organization.

How do you structure an effective session?

Fundamental rule: one session = one verifiable deliverable

Before starting a session, define the exit condition. Not “refactor the payment service”, but:

Session: Extract the discount calculation logic from OrderService into DiscountCalculator
Exit condition:
  - Existing tests still pass (phpunit --filter OrderServiceTest)
  - DiscountCalculator has its own unit tests
  - OrderService's public interface is unchanged

When the condition is met, cut the session. Even if the agent still looks sharp. Especially if the agent looks sharp — that’s the time to capitalize, not to continue.

Load the minimum useful context

The context window isn’t a buffer to fill. In OpenCode:

# Load only the files directly related to the task
> /add src/Service/OrderService.php
> /add src/Repository/OrderRepository.php
> /add tests/Service/OrderServiceTest.php

# No need to load all of src/Service/ "just in case"

In Kilo Code, same logic: open in VS Code only the relevant files, not the entire workspace.

The project context file (CLAUDE.md / AGENTS.md)

This file is automatically read by most agents at the start of each session. It replaces inter-session memory — what the agent needs to permanently know about the project:

# Project context

## Stack
- PHP 8.3 + Symfony 7.1 + API Platform 3
- TypeScript 5 + React 18 + Vite
- Tests: PHPUnit 11 (backend), Vitest (frontend)

## Critical conventions
- Repositories inherit from AbstractRepository, never directly from Doctrine
- Unit tests mock via PHPUnit MockObject, never hard-coded `new`
- API Platform endpoints: #[ApiResource] annotation on the Resource class,
  not on the Entity directly

## What the agent does NOT do without asking
- Modify the public interface of an existing service
- Create database migrations
- Modify Symfony configuration files

## Useful commands
- Tests: `php bin/phpunit --filter TestName`
- Dev server: `symfony serve -d`
- TypeScript check: `npx tsc --noEmit`

This file is alive — you enrich it every time you identify a missing convention.

How do you chain multiple sessions on a complex task?

For a task that exceeds one session, the handoff must be explicit. Typical structure with a working file:

Session 1 — Analysis and plan

Instruction: "Analyze PaymentService.php and PaymentRepository.php.
Identify the mixed responsibilities and propose a refactoring plan.
Write the plan in REFACTOR_PAYMENT.md with:
- The identified problems
- The target architecture
- The steps in order (each step must be independently testable)
Don't touch the code."

The REFACTOR_PAYMENT.md file is session 1’s deliverable and the input context for subsequent sessions.

Session 2 — Implementing steps 1 and 2

Instruction: "Read REFACTOR_PAYMENT.md. Implement steps 1 and 2 of the plan.
Exit condition: existing tests pass, each step is in its own commit
with an explicit message."

Session 3 — Continuation and final validation

Instruction: "Read REFACTOR_PAYMENT.md (steps 3 and 4 remaining).
Implement. Once done, verify all tests pass and mark the steps
as Done in the file."

This pattern has several advantages: each session is short (fresh context), the working files are verifiable and committable artifacts, and you can resume at any step if a session is interrupted.

How do you work with multiple agents in parallel?

Parallelization is interesting when two tasks are independent enough not to step on each other. With OpenCode and tmux, it’s immediate:

# Vertical tmux split
# Left pane: agent on the backend
tmux split-window -h
opencode  # backend session

# Right pane: agent on the tests
# (in the right split)
opencode  # test session

No-conflict rule: two parallel agents must not touch the same files. If it’s unavoidable, work in separate branches:

# Agent 1: branch feature/refactor-payment
# Agent 2: branch feature/add-stripe-webhook
# Sequential merge after both are validated

In practice on our project, the time savings from parallel sessions are real on migration or mass test update tasks: while one agent refactors a service, another updates the corresponding tests at the same time.

What are the signs of degrading context?

Watch for:

• The agent calls a function that doesn’t exist in the codebase (context hallucination)
• It uses a pattern it hadn’t used at the start of the session
• It repeats an explanation word for word without adapting it
• It proposes doing something you told it not to do

When one of these signals appears: cut, open a new session, load the minimum context, resume. Don’t try to “correct” the agent in a degraded session — the context is polluted.

Resources

• Guide: agentic workflow — principles
• Guide: prompt engineering for agents
• OpenCode — multi-session architecture