# Skill: Understand and tune the agent harness -- context, tokens, and memory management

> Use this skill to diagnose why an AI agent is performing poorly and to structure any agentic session so the agent stays focused, cheap, and accurate across long tasks.

Source: sodigi-learn -- vibecoding/kak-dumaet-agent - https://sodigi.io/learn/vibecoding/kak-dumaet-agent

## When to use
- The agent is losing the thread, repeating itself, or "forgetting" earlier decisions mid-session.
- A rule or instruction given once in chat has disappeared after a restart.
- Token costs are unexpectedly high or the agent is slow.
- You are setting up a new agentic workflow and want to avoid context overflow from the start.

## Core rules
- The model is the brain; the harness (tools, rules, memory files, context structure) is what you tune -- not the model itself.
- Context = a desk with limited space. Clutter it with logs and old messages and the agent gets dumber.
- Every instruction that must survive a restart must live in a file on disk, not only in the chat.
- Long-term memory = files. Short-term memory = context window. Close the session and short-term is gone.
- Do a compact (context cleanup) only at task BOUNDARIES -- never mid-debugging, never before an important decision.
- Pass the agent only the file or snippet it needs, not the entire project at once.
- A good harness tool has one narrow job and tells the agent what happened and what to do next. A mega-tool that does everything confuses the agent.
- Nine out of ten AI "stupidities" are a cluttered desk, a missing tool, or lost context -- not an unintelligent model.

## Procedure
1. Before starting a complex session, write key requirements and decisions into a file (e.g., DECISIONS.md).
2. Break the work into checkable 15-minute chunks; have the agent show results and wait for approval between chunks.
3. Instruct the agent not to rewrite already-approved sections without explicit permission.
4. When the session feels cluttered: check whether context is overloaded, whether a compact erased something critical, whether the rule is actually in a file.
5. Allow a compact only after a finished chunk -- never in the middle of active debugging.
6. After a compact, give the agent a one-line hint about the next task so it starts oriented.

### Quick diagnosis checklist (when the agent acts "dumb")
1. Is the context overloaded? -- Start fresh or compact at a safe boundary.
2. Did a compact wipe something? -- Repeat the key requirements and save them to a file.
3. Is the rule in a file? -- Saying it once in chat is not enough.
4. Is a tool failing silently? -- Look for commands the agent keeps retrying with no explanation.
5. Is the task too big? -- Slice it into ~15-minute chunks.

## Ready-to-use prompt
```
Build [describe the task]. Before writing any code:

1. Write the key requirements into a file called DECISIONS.md:
   [list the decisions -- font, palette, constraints, non-negotiables].
   Check against it as you work.
2. Work one block at a time: [block 1], [block 2], [block 3].
   After each block show me the result and wait for my "ok."
3. Do not rewrite already-approved blocks without my permission.
4. If the history overflows, do a compact ONLY after a finished block,
   never in the middle of one.
```

## Pitfalls
- Pasting the whole project into the chat -- expensive and buries the desk; hand over only the needed chunk.
- Keeping rules only in the conversation -- they vanish after a restart; put them in a file.
- Giving one giant task -- the agent chokes; break it into chunks.
- Compacting mid-debugging -- you erase exactly the details you were chasing.
- Ignoring token costs -- a "free" long chat eventually surfaces a surprising bill.
- Arguing with a confused agent instead of starting a fresh session with a clean context.