Favo Yang's Blog

A Two-Layer Project Structure for AI Coding Agents

2026-06-18 orchestrator

Recently, I have been experimenting with a two-layer project structure for working with AI coding agents.

The key idea is simple: 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 is not another source repository. It is an operating layer for 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

This becomes useful once a project 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 kind of 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 improves

  • Project memory has a home. Saved plans, internal notes, and workflow instructions can live above the repos instead of being copied into each one.
  • Private context stays private. For open-source projects, deployment details and internal planning notes do not need to sit inside the public codebase.
  • Cross-repo work becomes natural. A feature may need code, deployment changes, docs, changelog entries, and launch notes. Starting from the workspace keeps those related tasks visible.
  • Prompting becomes higher level. 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> && just 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.

Potential possibilities

A few directions seem possible from here:

  • 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. It would act like a poor man's OpenClaw: one local operating layer for many projects, with enough memory to understand how they relate.

Right now, I find the workspace layer useful enough that I keep using it. It turns the project folder into more than a collection of repositories. It becomes the place where the AI agent can understand the product before choosing where to act.