Here's what I tried and where each approach broke down:
Running log in a single .txt file: everything ended up in a monolithic timeline. Context was buried. The agent would still hallucinate task order.Relying on the agent's built-in memory features: tool-specific memory (likeClaudeProjects or custom instructions) helped for global preferences but couldn't handle per-task context with interdependent subtasks.Spawning a separate shell per task: worked for a few tasks, then you lose track of which shell had which state; also easy to accidentally kill the wrong session.
The solution came down to a single rule:
every task gets its own file in a dedicated project directory. I added a
/ai/tasks/
folder at the repo root, with one Markdown file per task. Each file uses a simple front-matter block followed by a checklist and a context section.
---
status: active
priority: high
task: "Decrease inference latency in batch processing module"
module: analysis/batch/inference.py
last_active: 2025-03-20
---
## Progress
- [x] Profile current pipeline to identify bottlenecks (noted top 3 functions)
- [ ] Implement caching in the embedding step (blocked: waiting on DB schema change)
- [ ] Test with production-scale data
## Context Dump
Related models: ModelA, ModelB. Key vector columns are in table `embeddings_v2`.
Branch is `latency-fix`, base commit `abc1234`. The last error was a `RuntimeError` about tensor shape mismatch in the attention layer — discussed with team, identified as an index-off-by-one. Fix needs to wrap around to batch boundaries.
Every session starts by the relevant task file into the agent's context window. I use a simple shell helper that prepends the markdown content as a system message. This gives the agent a clear status snapshot so it never has to guess where we left off.
The biggest improvement isn't technical — it's discipline. The agent works best when the human structures the input. Writing a clean context dump before closing a session saves 10x that time on the next start.
This approach also makes it trivial to hand a task off to another team member (or to an agent running on a CI machine). Just point them at the .md
file and the branch name.
If you're fighting context loss with coding agents, this file-per-task model will probably save you a lot of repeated work. The
Next OpenAI’s new throttling hit my agent – here’s how I traced the →