{"slug": "the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive", "title": "The One Weird Git Trick That Makes Coding Agents More Effect-Ive", "summary": "The Effect team recommends vendoring the Effect source code into a project using git subtrees to improve coding agent performance, as agents learn more effectively from real library code than from documentation or compiled node_modules. Git subtrees avoid the initialization and indirection issues of git submodules, making external code seamlessly explorable by AI agents.", "body_md": "One of the most common questions we get on the Effect team in the era of AI-assisted coding is how to get coding agents to write good, idiomatic Effect code.\n\nOur answer is always the same: give your agent real library code to learn from. More specifically, give the agent access to the Effect source code.\n\n## Stop Making Agents Guess\n\nIf you follow us on social media, you’ve probably heard us recommend cloning the Effect repository directly into your project. The advice sounds strange until you remember what coding agents are actually good at: reading and exploring *code* (crazy, I know).\n\nThey’re substantially *less* effective when working from documentation written for humans. When source code is available, an agent can explore it the way it was designed to: by following usage patterns, tracing abstractions, and learning from existing patterns. More importantly, this approach isn’t specific to Effect - it works for any external software your application depends on.\n\nThe most practical method for making external software explorable by your coding agent is to simply vendor the project’s Git repository directly into your application’s codebase.\n\nIn this post we will explain why this works, why `git subtrees`\n\nare a good fit for it, and how to set it up without making your project harder to manage.\n\n## Why Having the Source Code Available Matters\n\nA common approach when utilizing coding agents is to rely on web search / web fetch to allow the agent to retrieve information about external dependencies when required. In practice, however, the agent will only have access to isolated code snippets without the surrounding structure, often requiring it to repeatedly fetch code it has already seen or until it has enough information to proceed. This is token inefficient and leads to highly fragmented context.\n\nDocumentation has a different limitation - it usually explains what an API or library *does* but not how it is actually *used* across a codebase. Coding agents rely on patterns and examples, not descriptions.\n\nHaving source code available locally allows us to remedy both issues at once. When the agent is unsure about how to use a particular API or library, it can explore the actual implementation of that codebase just like any other part of your project.\n\nThis is also why relying on code in `node_modules`\n\nusually isn’t enough. The code is often compiled or flattened, which removes the structure that makes it useful to read. Even if a particular library does publish their uncompiled source, most coding agents are deoptimized from exploring `node_modules`\n\nor other gitignore directories in the first place.\n\n## Why Git Subtrees Instead of Git Submodules?\n\nIt might seem intuitive to simply use `git submodule`\n\nto vendor external software into a project. Submodules are (unfortunately) a familiar feature of `git`\n\nfor most developers, keep the repositories cleanly separated, and allow pinning external codebases to a specific commit.\n\nAnd to be honest, submodules are *fine* - they accomplish the end goal which is allowing the agent direct access to external source code. But in our opinion there are features of `git submodule`\n\nthat make them quite annoying for this specific purpose.\n\n- They require explicit initialization when cloning a project, which (if you are like me) can be really easy to forget to do\n- They also introduce a layer of indirection (your repo now “points” to another repo instead of just containing the source code)\n- They require additional metadata to be tracked in git (i.e. the\n`.gitmodules`\n\nfile)\n\nInstead, `git subtree`\n\nallows you to directly nest one repository inside another as a subdirectory. Once a subtree is created, it behaves like any other directory in your project. That means both the engineers and coding agents working on a project can ignore the fact that a subtree is even in use.\n\n## Adding a Git Subtree\n\nYou can add an external dependency to your project under a dedicated directory (such as `repos/effect`\n\n) with a single command:\n\nThe `--prefix`\n\nflag controls where the repository will live inside your project. We recommend keeping all vendored projects under a single directory (i.e. `repos/`\n\n). This makes it much easier to, for example, add a one-liner to your `AGENTS.md`\n\nto explore `repos/effect`\n\nwhen writing Effect code.\n\nIt’s also worth calling out the `--squash`\n\nflag - without it, you will clone the **entire history** of the external repository into your own project’s git history. For larger projects this can mean thousands of commits. Including `--squash`\n\nin the command ensures that everything is collapsed into a single commit.\n\n## Updating a Git Subtree\n\nWhen you want to pull in changes from an external project, you can simply run:\n\nEach update shows up as a single commit, which keeps things predictable and easy to review.\n\n## Configuring Your Editor\n\nOk, now you’ve got a few external repositories sitting in your `repos/`\n\ndirectory and you’re ready to let your agents `--dangerously-skip-permissions`\n\n.\n\nThe problem is that you (the human-in-the-loop) probably still want to be able to use your code editor from time to time. On those rare occasions where you are hands-on in a code editor instead of a prompt box, you probably do **not** want your editor suggesting search results and/or auto-imports from these external repositories.\n\nIn VSCode, you can exclude your `repos/`\n\ndirectory from search, file watching, and auto-import suggestions with a few small tweaks to your project’s `.vscode/settings.json`\n\n:\n\nOther editors can be configured similarly, but your mileage may vary.\n\n## Configuring the Agent\n\nNow that you’ve got one or more subtrees vendored into your project, you will need to make the agent aware that they are there, and how to use them. This is usually done through the `AGENTS.md`\n\nfile (or whichever file your coding agent uses).\n\nThe important thing is to be explicit about both the location and the intended usage. You do not want the agent treating vendored repositories as part of your application codebase. You want it to read them as reference material. For example:\n\nYou can also make this more specific for the libraries you vendor, for example:\n\nIf you’ve created a subtree for Effect v4, you can also explicitly tell the agent to always read @repos/effect/LLMS.md before writing any Effect code.\n\n### Creating Pattern Files\n\nAnother useful pattern is to ask the agent to create a small reference file for a particular data type or module from the vendored codebase. This gives the agent a project-local artifact it can come back to later instead of rediscovering the same patterns repeatedly.\n\nFor example, you might ask:\n\nThe resulting file does not need to be exhaustive. It should be a practical reference that captures the idioms the agent is most likely to need when working in your application code.\n\n## The Trade-Off\n\nVendoring repositories does increase the size of your project, and you take on a bit of responsibility for keeping them up to date. It’s not free.\n\nBut the payoff in terms of improved output quality from your coding agents when using external dependencies is, in our opinion, well worth it. Especially in an era where humans are doing less and less of the actual hands-on coding ourselves.", "url": "https://wpnews.pro/news/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive", "canonical_source": "https://www.effect.website/blog/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive", "published_at": "2026-07-25 18:55:19+00:00", "updated_at": "2026-07-25 19:22:21.830718+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models"], "entities": ["Effect team", "Effect", "git subtrees", "git submodules"], "alternates": {"html": "https://wpnews.pro/news/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive", "markdown": "https://wpnews.pro/news/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive.md", "text": "https://wpnews.pro/news/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive.txt", "jsonld": "https://wpnews.pro/news/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive.jsonld"}}