I have been using a two-layer project structure for AI coding agents.
The pattern is straightforward: keep the source code in focused repositories, but run the agent from a higher-level workspace that understands how those repositories fit together. That top-level folder operates above the source repositories and holds the work around the code: saved plans, internal notes, private instructions, and cross-repo context.
project-workspace/
repo # main repo, open source
repo-devops # server deployment stuff, closed source
related-repo1
related-repo2
related-repo3
...
AGENTS.md # knowledge about how each sub-repo works
plans/ # agent plans
Each sub-repo can still have its own AGENTS.md. But in practice, I rarely enter the individual repo folder to prompt the agent. Most of the time, I work from the workspace root and use it as the starting point.
Why the workspace exists
A project quickly grows beyond one codebase. A real product often has the main app, deployment scripts, infrastructure configuration, documentation, marketing material, support tools, experiments, and private operational notes. These pieces are connected, but they should not always live in the same public repository.
From the workspace, I can ask the agent something like:
/goal implement this feature, then write a blog post, and schedule a tweet about it
That request does not belong cleanly inside a single repo. The implementation may happen in the app repo, the deployment change in the DevOps repo, the product explanation in docs or a blog draft, and the launch message in a publishing plan.
From the workspace level, the agent can plan the sequence before dropping into any one folder.
What gets better
Project memory gets one place to live. Saved plans, internal notes, and workflow instructions can sit above the repos instead of being copied into each one.
Private context also stays private. For open-source projects, deployment details and internal planning notes do not need to sit inside the public codebase.
Cross-repo work feels more natural from this level. A feature may need code, deployment changes, docs, changelog entries, and launch notes. Starting from the workspace keeps those related tasks visible.
The prompt can start at the project level too. Instead of asking, "What file should I edit in this repo?", I can ask, "What needs to happen across the project?"
Tradeoff
The risk is that the agent can see too much. It may search across too many folders, pull in unrelated context, or treat every task as a whole-project problem.
That makes the workspace-level AGENTS.md important. It should describe what each sub-folder is for, which repos are public or private, where plans belong, and when the agent should stay inside a single repo instead of searching the whole workspace.
For example, a workspace-level AGENTS.md might look like this:
# Project Workspace Agent Notes
This directory is an operator workspace that groups multiple independent Git
repositories. Treat each child directory with its own `.git/` as a separate
repository, not as source owned by this root workspace repository.
## Workspace Shape
Known child repositories:
- `<app-repo>`: application codebase. Read `<app-repo>/AGENTS.md` before
changing application, docs, package, job, or shared library code.
- `<deploy-repo>`: deployment and operations. Read `<deploy-repo>/AGENTS.md`
before changing deployment, infrastructure, service, or production
verification behavior.
- `<pipeline-repo>`: build and publish pipelines. Read
`<pipeline-repo>/AGENTS.md` before changing pipeline scripts or YAML.
- Other child directories with their own `.git/`: independent repositories.
Check for repo-local guidance before editing.
- `plans/`: workspace planning notes and cross-repo coordination material.
## Working Rules
- Do not add child repositories, their contents, or embedded repo gitlinks to
the root workspace Git repository.
- Make source changes inside the owning child repository and use that
repository's Git history for commits and branches.
- Use this root only for workspace-level guidance, notes, and coordination
files.
- Before cross-repo changes, inspect the relevant child repo status with
`git -C <repo> status --short` so unrelated local work is not disturbed.
- Never revert or overwrite changes in a child repository unless the user
explicitly asks for that exact repo and change.
- Prefer repo-local commands from the repo root, for example
`cd <repo> && npm test` or `cd <deploy-repo> && npm run verify`.
The exact names do not matter. What matters is that the agent understands the boundary between the root workspace and the child repositories: where instructions live, where plans belong, which Git history owns a change, and which local or secret state must not leak into public work.
Where this can go
A few directions are worth testing:
- A workspace-level agent could act as an orchestrator instead of doing everything itself. It could pass a goal to a sub-agent running inside the relevant repo folder, then let that sub-agent handle the focused implementation.
- The same structure could become a personal vault for loosely connected knowledge: notes, relationships, blog drafts, high-level projects, and other information that does not fit cleanly into one repo.
- At the extreme, the workspace could become a project root for all projects: one local operating layer for many projects, with enough memory to understand how they relate.
The workspace layer turns the project folder into more than a collection of repositories. It gives the agent one place to understand the product before choosing where to act.
To comment and continue discussing this article, please comment on the X Article.