Context Management

Modern LLMs can hold far more context than they used to, but a larger context window does not mean the agent can use all of that context equally well.

As a session grows, the hard problem shifts from “will this fit?” to “can the agent still find the right signal?” Long, noisy context makes it easier for agents to lose focus, over-weight stale assumptions, copy irrelevant patterns, or miss requirements that were technically present but buried. In practice, agents do best when they get exactly what they need for the task at hand - and as little else as possible.

The real context problem

When a session gets too large, too noisy, or too mixed, quality drops. You may see agents:

Forget important requirements mid-implementation
Drift from the plan
Copy inconsistent patterns from earlier discussion
Anchor on old assumptions that are no longer true
Miss edge cases that were already discussed

This can happen even with very large context windows. Bigger windows reduce the hard limit, but they do not fix low-quality context.

What actually bloats context

Context bloat is not only about token count. It is often caused by stale, ambiguous, or irrelevant information lingering in the conversation for too long.

Common examples:

A CLAUDE.md file becomes a dumping ground for rules that do not matter for the current task
A long debugging session accumulates several failed hypotheses that keep biasing the model
Large logs, stack traces, generated files, and broad file reads get pulled in “just in case”
Research sessions include too many raw docs, web search results, or pasted references
Planning, implementation, debugging, and review all happen in one long thread
Requirements change mid-session, but the old requirements are still sitting in context
Multiple designs are explored without clearly choosing one
You discover an unrelated bug while building a feature and try to solve both in the same session

The result is that the model can no longer tell which constraints are current, central, and authoritative.

The key principle

Context quality matters more than context size.

The goal: give the agent the minimum high-signal context needed to solve the problem well.

How ACT solves this

ACT is designed around a simple idea: turn one long, messy conversation into a sequence of shorter, focused sessions connected by files.

Instead of keeping interview, requirements, task breakdown, implementation, and review inside one ever-growing chat, ACT turns resolved context into durable artifacts - Specs, Interview Ledgers, and Work Items - that become the input to the next step.

/new

/act-interview "add user authentication"
↓ Asks targeted questions and records important Q&A decisions

/act-create-spec
↓ Creates a Spec with requirements, user flows, constraints, and acceptance criteria

/new

/act-create-issues ai_specs/0001-auth/spec.md
↓ Creates bounded Work Items with dependencies and verification expectations

/new

/act-implement ai_specs/0001-auth/work-items/01-registration.md
↓ Implements first Work Item and reports verification results

→ Repeat /new and /act-implement for all remaining Work Items

That workflow gives you the best of both worlds:

Each stage starts with a clear context
The important knowledge is preserved in files
The noisy conversation that produced those files can be discarded
The agent stays focused on one mode of work at a time

This is exactly why some tools now offer explicit context-reset features. Claude, for example, has a way to clear context and continue working once a task brief is ready. That works well because the valuable output is the artifact itself, not the full exploratory path that led to it.

ACT patterns that keep context clean

1. Specs as persistent context

The Spec is the source of truth for requirements. During /act-implement, the agent reads the relevant Work Item and its parent Spec, so requirements do not depend on chat history.

2. Bounded Work Items

ACT breaks implementation into Work Items. Each Work Item has a focused goal, acceptance criteria, dependency information, and verification expectations before work starts.

This avoids the slow context drift that happens when a feature grows inside one endless session.

3. Loading the right knowledge automatically

Use the plain workflow skills for general work. Use the -flutter workflow skills for Flutter/Dart tasks so Flutter patterns, testing expectations, and implementation guidance are carried through the workflow.

This way, the sessions stay focused and the agent gets the guidance it needs for the task without forcing you to paste in lots of docs, rules, or reference material by hand.

If deeper research is needed, the best approach is usually to do that in a separate session and write the distilled findings to a file that can be referenced later as needed. Today that is still a manual workflow, but ACT will support this pattern better over time.

Best practices

Scope specs tightly

A Spec that tries to cover too much will produce Work Items that are too large and too diffuse.

Instead of “add user management”, split it into smaller specs like registration, profile editing, and permissions
Aim for Work Items that can be implemented and verified independently

Separate research from execution

If you need lots of web research or docs review, do that in a dedicated session. Capture the distilled findings in a file, then start a fresh implementation session from that summary.

Do not mix unrelated work

If you uncover a bug halfway through a feature, do not automatically fold it into the same thread. Often the better move is to handle it separately, or even in another branch or worktree, so the agent is not trying to solve two problems at once.

Reset between major stages

Once the Spec is done, start fresh for refinement or Work Item creation. Once a Work Item is ready, start fresh for implementation. Keep the artifact, not the whole conversation.

Next steps

See the Choosing the Right Model guide