ACE (Agentic Context Engineering): A Detailed Playbook Instead of a Short Prompt

STEP 1 (Generator): Solve the task → reasoning trajectory + code/actions

STEP 2 (Reflector): Analyze the attempt → a list of concrete insights:
  - What worked (strategies to repeat)
  - Where it went wrong (common problems)
  - Root cause analysis (why it happened)

STEP 3 (Curator): Update the playbook → add new bullet points:
  - Format: ID + type + content + helpful/harmful counters
  - Operations: add new items, update existing ones, remove duplicates
  - Result: an expanded playbook for the next task

The key difference from other methods: Step 3 is not an LLM rewriting the whole context, but lightweight logic that merges small deltas. That makes it possible to process many tasks in parallel and accumulate knowledge without the risk of context collapse.

Task: You're a project manager at a tech company in Chicago. After 3 months of working with various contractors, you've piled up cases: some blew deadlines, some didn't understand the spec, some did a great job. Instead of keeping all this in your head, you want to build a detailed "Working with Contractors" playbook for yourself and your colleagues.

You apply the ACE principle: not a short summary like "be stricter", but a structured reference of concrete strategies.

Prompt:

I'm a project manager working with external contractors (designers, developers, SEO).
I want to build up a detailed playbook — a base of proven strategies and common problems.

PLAYBOOK STRUCTURE:
- Each item is a specific tactic/mistake/rule
- Format: [Type: strategy/mistake/red_flag] — [description]
- Detail beats brevity — you're an LLM, you can handle it; I need completeness

CURRENT PLAYBOOK:
[empty at the start, or paste what you've accumulated]

I'll tell you about a case from work. Your job:
1. Extract SPECIFIC strategies/mistakes/patterns from this case
2. Propose new playbook items (detailed, not generic)
3. Check for duplicates with existing items
4. Output the updated PLAYBOOK

CASE: We worked with Jake, a designer from the studio "Pixel".
On the first call I asked for "a modern website for a startup".
Jake delivered a mockup, but it had a dark theme (we're B2B, we need trust, light colors).
The redo took a week. Next time, with a different designer, I showed
3 competitor references + a moodboard in Figma right away — nailed it on the first try.

Result:

The model analyzes the case and adds concrete items to the playbook, like:

• [Strategy] When briefing a designer — skip words like "modern" and send 3-5 reference screenshots
• [Mistake] Describing the style abstractly ("stylish," "minimalist") → the designer will interpret it their own way
• [Red flag] If the designer asks no clarifying questions during the brief → they'll probably deliver the wrong thing
• [Tactic] A moodboard in Figma/Pinterest before kickoff → cuts redos by 70%

With the next case (say, a developer didn't clarify the API requirements), the model extends the playbook with new items but keeps the old ones. After 10-20 cases you end up with a detailed knowledge base for working with contractors.

LLMs do better with long, detailed contexts than with short generalizations. The study shows that when a model gets a comprehensive playbook (even 10-20k tokens), it picks out what's relevant on its own at inference time. Humans need brevity to remember things; LLMs don't. Quite the opposite: the more specific edge cases, API quirks and proven tactics in the context, the more accurate the result. A short prompt like "be more careful" gives the model no concrete levers — what exactly to check, which mistakes are common, how to handle typical problems.

Incremental updates prevent context collapse. When you ask an LLM to "rewrite the whole prompt," it tends to compress — dropping details, generalizing, losing nuance. That's natural for a language model: it's optimized to generate coherent text, not to preserve every detail. ACE doesn't rewrite, it adds small deltas. The Curator doesn't get "reword the context," it gets "here are 3 new insights — add them as bullet points." The old stays, the new extends it. Deduplication removes repeats, but the details remain.

Splitting the roles raises the quality of each stage. When one model does everything (solves the task AND analyzes AND updates the context), you get a conflict of interest — it's hard to generate and critique yourself at the same time. ACE splits it up: the Generator focuses on solving, the Reflector on analysis (it can run several times to dig deeper), the Curator on structuring. It's like a team: the developer writes the code, the reviewer finds the bugs, the tech writer documents it — everyone does their own job well.

Control knobs for adapting it:

• Number of Reflector rounds (1-5) → more rounds = deeper analysis, but pricier. For simple tasks, 1-2 is enough.
• Batch size (how many tasks to analyze at once) → 1 in the study, but you can use 5-10 to speed things up.
• Deduplication threshold → how similar items have to be to count as duplicates. Stricter = a more compact playbook, looser = more detail.
• Warmup → you can start with an empty playbook (online learning) or warm it up on training examples (offline warmup).

Basic template for accumulating knowledge

I'm working on {area/project}. I want to build a detailed playbook —
a base of proven strategies, common mistakes and edge cases.

PLAYBOOK PRINCIPLES:
- Detail > brevity (you're an LLM, long context is your strength)
- Concrete tactics, not abstract advice
- Format: [Type] — [description]
  Types: strategy | mistake | red_flag | edge_case | API_quirk

CURRENT PLAYBOOK:
{paste existing items or leave empty}

---

NEW CASE/TASK:
{describe what happened, what worked/didn't work}

---

TASKS:
1. REFLECTOR MODE: Analyze the case
   - What can be extracted? (strategies, mistakes, patterns)
   - Why did it happen? (root cause)
   - What to do in the future? (concrete actions)

2. CURATOR MODE: Update the playbook
   - Propose new items (detailed, with examples)
   - Check for duplicates with existing items
   - If an item resembles an existing one — clarify the difference or merge them

3. Output the updated PLAYBOOK (all old items + the new ones)

What to fill in:

• {area/project} — your specialty (marketing, sales, code, hiring, design)
• {existing items} — copy the playbook from the previous response
• {case} — describe a specific situation: what you did, what happened, where it failed

Multi-turn workflow (simulating ACE in a regular chat)

I want to improve {my prompt/approach to a task} through iterative learning.

Current approach:
{describe your method or paste the prompt}

Let's run a 3-stage loop:

STAGE 1 — GENERATOR:
Try solving this task with the current approach:
{task}

STAGE 2 — REFLECTOR:
Analyze your attempt:
- What worked?
- Where's the mistake/shortcoming?
- Root cause (why did it turn out that way?)
- What concrete strategies can be extracted?

STAGE 3 — CURATOR:
Based on the reflection, propose an updated approach:
- Add new rules/strategies
- Keep what worked
- Remove duplicates

Output the final improved approach for the next iteration.

🚀 Quick start — paste into the chat:

Here's the ACE template for accumulating knowledge. Adapt it to my task: {your task}.
Ask me questions to fill in the fields.

[paste the "Basic template for accumulating knowledge" above]

The LLM will ask about your field, your first case and what playbook format you need — because structuring knowledge requires understanding the context and the level of detail you want. It'll take the Reflector→Curator pattern from the template and adapt it to your specific task.

⚠️ Depends on Reflector quality: If the model can't extract useful insights from a case (a weak model or a very niche domain), the playbook fills up with noise. The study used DeepSeek-V3 — with weaker models, it's better to add examples of good reflection to the prompt.

⚠️ Needs a feedback signal: ACE works well when there's clear feedback — execution success/failure for code, ground truth for tasks. In tasks where the "right answer" is subjective (creative work, writing style), the effect is smaller. On financial tasks without ground truth, ACE and the other methods degraded.

⚠️ Not for every task: Simple tasks (HotPotQA — find a fact in a document, Game of 24 — a fixed strategy) don't need long playbooks. ACE is built for complex domains with lots of edge cases and strategies (agents, specialized analysis, code).

⚠️ Warm-up overhead: The playbook needs several iterations to "warm up." In offline mode, run it on 50-100 training examples. In online mode, the first 10-20 tasks may be worse than the baseline until the context builds up.

The team tested ACE on two kinds of tasks: agents (AppWorld — interacting with APIs, code, an environment) and domain-specific ones (financial analysis with FiNER and Formula). They took 7 models of different sizes and compared against strong baselines: ICL (many-shot with demonstrations), MIPROv2 (Bayesian prompt optimization), GEPA (genetic prompt search via reflection), and Dynamic Cheatsheet (adaptive agent memory).

They tested in two modes: offline (optimize on train, evaluate on test) and online (update the context on every test example and use it right away).

How they reached their conclusions: ACE beat everyone by 10.6% (agents) and 8.6% (finance) on average. A surprising finding — on the AppWorld benchmark, ACE with a small open-source model, DeepSeek-V3, matched the top production agent IBM CUGA (GPT-4.1) on average and beat it on the harder test-challenge split (+8.4% TGC). This shows that comprehensive context makes up for a smaller model.

The second big insight — ACE works without labeled data. On agent tasks with execution feedback (the code ran or crashed), ACE improved on the baseline by 14.8% without ever seeing ground truth. That means the method suits self-improving agents that learn from their own mistakes.

The third — cost and speed. ACE cut adaptation latency by 82-92% compared to GEPA and Dynamic Cheatsheet, needing 75% fewer rollouts and 84% fewer dollars on tokens. The reason: incremental delta updates are cheaper than rewriting the whole context.

Ablation studies showed: the Reflector adds +5-7% to accuracy (vs. without it), multi-epoch adaptation (running over the training data several times) adds another +3-4%, and offline warmup before online learning gives a fast start.

Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models (2025)
Qizheng Zhang, Changran Hu, Shubhangi Upasani, Boyuan Ma, Fenglu Hong, Vamsidhar Kamanuru, Jay Rainton, Chen Wu, Mengmeng Ji, Hanchen Li, Urmish Thakker, James Zou, Kunle Olukotun
Stanford University, SambaNova Systems, UC Berkeley

AppWorld Leaderboard — the agent benchmark where ACE posted its results
Dynamic Cheatsheet paper — ACE's predecessor, adaptive agent memory