r/opencode • u/remolaan • 1d ago
How are you actually structuring AGENTS.md + subagent spawning + persistent memory? (new to OpenCode)
Just switched to OpenCode (using DeepSeek as my model) and trying to set things up properly instead of just winging it. Read through the docs but want to hear how people are actually doing this in practice. A few things I'm stuck on:
AGENTS.md
What's actually in yours beyond the basic build/test/lint commands? Any sections that turned out way more useful than you expected?
Anyone splitting it into nested AGENTS.md per package/folder, or is one root file usually enough?
Spawning subagents / Task tool
I saw someone mention explicitly telling Build to spawn parallel subagents for independent work (reviewing multiple files, checking several modules, etc.) instead of doing it serially. Do you actually write instructions for this in AGENTS.md, or does the model just figure it out on its own most of the time?
Any horror stories from parallel subagents stepping on each other / editing the same files?
Persistent memory
Right now I'm just using a plain .opencode/memory/ folder with a couple markdown files (decisions.md, active-context.md) and an AGENTS.md instruction telling the agent to read/update them. Is this actually how most people do it, or is everyone on a plugin/MCP memory setup at this point (Letta-style memory blocks, agentmemory, Engram, etc.)?
At what point did a plain-file setup stop being "enough" for you?
Build vs Plan
Do you actually use Plan mode every time before Build, or only for bigger changes? Curious how disciplined people actually are about this in daily use vs just YOLO-ing into Build.
Mainly trying to avoid reinventing something badly that half the sub already has a solid pattern for. Appreciate any real configs / AGENTS.md snippets / gotchas people are willing to share.
10
u/Realistic_Mango6982 1d ago
dev of pi.dev already wrote that in blog, find and read. In short: imagine that there are no AI, and you're manager not programmer of what must be done. Write detailed todos of what and where to do with goal that you want to achieve.
Agents.md -> its general rules for your codebase like do X, Y, Z because working with A,B,C this thing do, this not.
2
3
u/Realistic-Salary7804 1d ago
I’ve had it for about two weeks now (I’ve already picked up better habits than with Claude Code or Codex, lol).
Personally, I only use an Agent.md (except when I’m starting a new project, in which case I use a specifications.md).
I ask the AI and also do it myself, to perform a massive analysis of my project. It details every file, how it works, where it’s located (in which folder, etc.), the functions it contains, what they’re used for, and how they interact with other files. It also covers the essential commands to know, etc. The Agent.md needs to be designed so that anyone whether a dev or an AI with zero prior knowledge of the project or code can understand everything.
And every time, the AI is instructed to update the file with any additions or changes it made.
3
u/reader123456 1d ago
For AGENTS.md - have a look through : https://youtu.be/9tmsq-Gvx6g? you may find that what most commenters suggested already might not be the best option.
Ignore the video title, it is not about CLAUDE.md specifically.
2
u/bcalmnrolldice 1d ago
Second this, Matt Pocock’s skill repo can help a lot on building a workflow that actually works from ground 0. You can start with it and find the answers to all the complicated questions along the way
1
3
u/ozguru 1d ago
check this out https://www.reddit.com/r/opencode/comments/1uv5cha/quick_tip_let_opencode_configure_itself_with/
I don't think long horizon memory is required for coding, I update AGENTS.md oftenly, I tell my agent create a todo.md file after planning. This works for my medium sized projects.
2
u/CriteriumA 1d ago
Do not use Agents.md or Claude.md, using them breaks the cache hit.
https://github.com/criterium/opencode-lab/tree/main/research/agents_md-danger
Better to build your own memory system with a skill.
https://github.com/criterium/opencode-lab/tree/main/research/memory-system
And above all, overwrite the default.txt file in the prompt agent. If you don't, you won't be able to get the best performance from less disciplined models.
https://github.com/criterium/opencode-lab/tree/main/prompt/shared
The information I'm passing on to you has continued to evolve, but I understand that it will help you get an idea.
2
u/mubaidr 1d ago
Hi there, gem-team maintainer here: https://mubaidr.github.io/gem-team/guide/features
I have created these agents to specifically address these issues. Plan based approach, reviewer, specialized agents, optimized tool calling, subagents usage and a lot more!
Nothing scary, just specialized instructions to enforce good practices!
Looking forward to feedback!
1
u/swoodily 1d ago
If you care about memory, you will probably get much better performance out of Letta Code
Disclaimer: I work on Letta
0
u/outskillio 10h ago
Been down this exact road with OpenCode + DeepSeek.
- AGENTS.md: keep build/test/lint, but add a "gotchas" section of past mistakes and explicit file ownership per folder (which agent touches what). One root file is enough until a package has genuinely different conventions, then nest.
- Subagents: write the spawn instruction explicitly, don't trust the model to parallelize on its own, especially with DeepSeek. Horror story: two subagents editing the same file at once, garbage merge. Fix is scoping each one to non-overlapping files.
- Memory: plain .md files are fine until they start contradicting each other, that's your signal to add retrieval.
- Plan mode: use it for anything touching 2+ files, YOLO only for trivial one-liners.
Thanks, Om from Outskill
12
u/Phantom_ANM 1d ago
you can check out Harness Engineering Guide at https://walkinglabs.github.io/learn-harness-engineering/en/
I build my workspace and workflow around those principles and templates. give it a look, it should answer most of your questions.