Favo Yang's Blog Writing about AI-native building, games, open source, and trade. 2026-06-18T00:00:00Z https://favoyang.com/ Favo Yang A Two-Layer Project Structure for AI Coding Agents 2026-06-18T00:00:00Z https://favoyang.com/a-two-layer-project-structure-for-ai-coding-agents/ <p>Recently, I have been experimenting with a two-layer project structure for working with AI coding agents.</p> <p>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.</p> <pre><code class="language-text">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 </code></pre> <p>Each sub-repo can still have its own <code>AGENTS.md</code>. 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.</p> <h2>Why the workspace exists</h2> <p>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.</p> <p>From the workspace, I can ask the agent something like:</p> <pre><code class="language-text">/goal implement this feature, then write a blog post, and schedule a tweet about it </code></pre> <p>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.</p> <p>From the workspace level, the agent can plan the sequence before dropping into any one folder.</p> <h2>What improves</h2> <ul> <li><strong>Project memory has a home.</strong> Saved plans, internal notes, and workflow instructions can live above the repos instead of being copied into each one.</li> <li><strong>Private context stays private.</strong> For open-source projects, deployment details and internal planning notes do not need to sit inside the public codebase.</li> <li><strong>Cross-repo work becomes natural.</strong> A feature may need code, deployment changes, docs, changelog entries, and launch notes. Starting from the workspace keeps those related tasks visible.</li> <li><strong>Prompting becomes higher level.</strong> Instead of asking, &quot;What file should I edit in this repo?&quot;, I can ask, &quot;What needs to happen across the project?&quot;</li> </ul> <h2>Tradeoff</h2> <p>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.</p> <p>That makes the workspace-level <code>AGENTS.md</code> 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.</p> <p>For example, a workspace-level <code>AGENTS.md</code> might look like this:</p> <pre><code class="language-markdown"># 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: - `&lt;app-repo&gt;`: application codebase. Read `&lt;app-repo&gt;/AGENTS.md` before changing application, docs, package, job, or shared library code. - `&lt;deploy-repo&gt;`: deployment and operations. Read `&lt;deploy-repo&gt;/AGENTS.md` before changing deployment, infrastructure, service, or production verification behavior. - `&lt;pipeline-repo&gt;`: build and publish pipelines. Read `&lt;pipeline-repo&gt;/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 &lt;repo&gt; 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 &lt;repo&gt; &amp;&amp; npm test` or `cd &lt;deploy-repo&gt; &amp;&amp; just verify`. </code></pre> <p>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.</p> <h2>Potential possibilities</h2> <p>A few directions seem possible from here:</p> <ul> <li>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.</li> <li>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.</li> <li>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.</li> </ul> <p>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.</p>