Skip to content
Agentic Coding Toolkit

Context Management

AI agents have a limited context window. How you manage that context directly affects the quality of their output. ACT provides tools and patterns to keep agents focused and productive.

The context problem

Section titled “The context problem”

AI coding agents have a fixed context window. As conversations grow, earlier context gets compressed or lost. This leads to:

  • Forgetting requirements mid-implementation
  • Drifting from the plan
  • Inconsistent patterns across files
  • Missed edge cases that were discussed earlier

How ACT manages context

Section titled “How ACT manages context”

1. Specs as persistent context

Section titled “1. Specs as persistent context”

The spec file is the source of truth for requirements. During /act:workflow:work, the AI reads the spec alongside the plan. This means requirements don’t get lost in conversation history — they’re always available in the file.

2. Priming with knowledge

Section titled “2. Priming with knowledge”

ACT loads Flutter knowledge into context at the start of implementation:

CommandWhat it loadsContext size
/act:prime-official-rulesOfficial Flutter team guidelinesSmall
/act:prime-patterns-liteEssential patterns and principlesMedium
/act:prime-patterns-fullAll patterns, principles, and breaking changesLarge

/act:workflow:work loads lite by default. Use full for complex features that need deeper pattern guidance:

Terminal window
/act:workflow:work ai_specs/feature-plan.md full

3. Phased execution

Section titled “3. Phased execution”

Breaking work into phases naturally manages context. Each phase:

  • Has a focused goal (not the entire feature)
  • References specific files to read
  • Ends with verification and a commit

This prevents the “boiling frog” problem where context gradually fills with irrelevant information.

4. Research agents

Section titled “4. Research agents”

The /act:workflow:plan --use-subagents flag launches background agents that research your codebase in parallel:

  • act:codebase-researcher — maps project structure and conventions
  • act:flutter-patterns-researcher — finds relevant patterns and principles
  • act:flutter-docs-researcher — gathers SDK documentation and migration guides

These agents run in separate context windows, so their research doesn’t consume the main agent’s context. Only the synthesized findings are brought back.

Best practices

Section titled “Best practices”

Scope specs tightly

Section titled “Scope specs tightly”

A spec that tries to cover too much will produce a plan that’s too large for one context window. Break large features into smaller specs:

  • Instead of “add user management” → “add user registration flow” + “add user profile editing” + “add user role permissions”
  • Each spec should produce a plan that fits in 3-5 phases

Use the right model

Section titled “Use the right model”

Larger models have more context and better reasoning. For complex features:

  • Use Opus for spec creation and plan review
  • Use Sonnet for straightforward implementation
  • Match model capability to task complexity

Start fresh for new features

Section titled “Start fresh for new features”

Don’t continue a conversation that already has a lot of context when starting a new feature. Start a new session to give the AI a clean context window.

Let ACT handle file reading

Section titled “Let ACT handle file reading”

ACT’s workflow commands strategically read only the files needed for each phase. Avoid manually reading large numbers of files into context — let the plan guide which files the AI needs.

Next steps

Section titled “Next steps”