Best Practice contribution: No Symlinks when using Google Drive

Hi All!

I was going to combine this post with a CoWork question I have, but they're different enough that I'm splitting them into two posts.

First (hopefully) helping, then asking for help:

If you keep your ICM in Google Drive, don't use symlinks. I learned this the hard way: the Drive process ballooned to ~30GB of RAM trying to resolve them and my machine was crawling for a couple of hours before I connected the two.

The setup that caused it: CLAUDE.md was my folder map, and AGENTS.md was a symlink pointing at it so Codex/Cursor (or any other AI agent) could read the same context. Worked fine until Drive got involved in some folders.

Flipped it. Now:

AGENTS.md is the real file in every folder. All the actual context lives there.
CLAUDE.md is a one-line stub containing exactly @AGENTS.md.

Claude Code inlines that import at load time, so Claude always sees the full context. Codex, Cursor, Windsurf and Aider read AGENTS.md natively. One source of truth, zero duplication, and critically, zero symlinks, so Drive and OneDrive stay happy.

Creating a new folder is two steps, and I have both written into my root AGENTS.md so Claude does it automatically: write the context into AGENTS.md, then create the stub. The stub is literally one line, @AGENTS.md, nothing else.

I have a PostToolUse hook that enforces it inside Claude Code: write a new AGENTS.md and it auto-creates the stub; write a CLAUDE.md with real content and it moves the content into AGENTS.md and leaves the stub behind. But the convention works fine without the hook.

One caveat worth knowing: the @import is a Claude Code feature. Other agents read AGENTS.md directly, so they never need it. If anyone has a cleaner way to keep folder context tool-agnostic, I'm interested. This is just what survived contact with Drive.

0 comments

Best Practice contribution: No Symlinks when using Google Drive