Ask HN: What agentic directory structure do you use?
10 comments
I break this up into two parts: assets and workflow state. All assets go in the repo, this is the context that all agents read to be able to understand what we're doing and how we do it.
The workflow state is the release train with all the tasks and dependencies. I use a personal MCP I wrote to store all this in a DB, out of band. I previously had .md files that did this, but I needed 1) a guaranteed structure and 2) hard enforcement of the structure when the agents change things.
My general approach is to have a conversation with Claude Code about what I want and how to do it, in the context of the repo. I typically start with a context-priming exercise where I ask it how something works now. Then we talk about the approach and I have it describe what it is going to do. I iterate until I agree and think it properly captures it correctly.
Then I have it build out the release train to do what we agreed in my tool. The tool itself has structured docs that it cannot change that describe the workflow, so I have it read that first. I review the releases, then have it burn down the tasks.
Once it finishes with a release, I use this prompt to keep everything up to date in the repo: "Please review all the relevant .md files and compare them to what you know now. If you can improve them please do so. Use modular documentation, with concise CLAUDE.md files at the appropriate places in the dirtree that point to full docs in .md files which you can read as needed."
This works for me: the immutable stuff is in the tool as docs, critical state is also in the tool with an enforced interface, and the repo has all the living context.
The workflow state is the release train with all the tasks and dependencies. I use a personal MCP I wrote to store all this in a DB, out of band. I previously had .md files that did this, but I needed 1) a guaranteed structure and 2) hard enforcement of the structure when the agents change things.
My general approach is to have a conversation with Claude Code about what I want and how to do it, in the context of the repo. I typically start with a context-priming exercise where I ask it how something works now. Then we talk about the approach and I have it describe what it is going to do. I iterate until I agree and think it properly captures it correctly.
Then I have it build out the release train to do what we agreed in my tool. The tool itself has structured docs that it cannot change that describe the workflow, so I have it read that first. I review the releases, then have it burn down the tasks.
Once it finishes with a release, I use this prompt to keep everything up to date in the repo: "Please review all the relevant .md files and compare them to what you know now. If you can improve them please do so. Use modular documentation, with concise CLAUDE.md files at the appropriate places in the dirtree that point to full docs in .md files which you can read as needed."
This works for me: the immutable stuff is in the tool as docs, critical state is also in the tool with an enforced interface, and the repo has all the living context.
The missing primitive in most setups I've seen: per-task scope contracts. A CLAUDE.md covers what the codebase is, but a per-task declaration of what must not change and where the agent stops is a separate thing. I've started putting those as a header in the task description itself, separate from persistent context.
Agents drift when they have full project context with no explicit stopping condition. What does the boundary spec look like in your setup?
The first bit that really annoyed me was the lack of tracking prompts. There are lot's of little inputs that inform the what the system should do and it seems to be very ephemeral. I've since started tracking the prompts in the codebase.
Another observation is that if you want to have good agentic output, you need to provide lot's of signal into the context window. It seems that being disciplined about what goes into the context window is key. Using AI to generate input files can be dangerous because it adds entropy/noise to the human signal.
One practice I have started to do is organize my projects in a certain way:
- /specs - Pure human signal such as product vision, requirements, designs, etc. - /prompts - Agentic recipes such as skills, jobs, AI patterns. - /references - References that can be used in the context window (brand assets, documents, figma exports, data sets, etc.) - /plans - The agentic plans for a project. Ususually there are iterations on these plans. - /build - The codebases and traditional mono repos that are built from plans and prompt interactions.
(I have the above with an AGENTS.md as a public GH repo at rekallai/craft)
I'm not fully satisfied yet with this structure. I think /plans is a bit of a misnomer the more I use it (e.g. I often have reports that I want to generate on top of the codebase or other data sets).
I am really curious how other developers (that embrace agentic coding) here organize their projects. My goal is to standardize this in my teams.