The CLAUDE.md That Travels With Me, and the One That Doesn't

Two files set the rules for how Claude Code behaves in this project, and they are not the same kind of file even though they share a name. One lives at the person’s home directory and applies to every project they ever open, on every machine. The other lives inside this one repository, checked into git alongside the code it describes, and says nothing about anywhere else.

Confusing which rule belongs in which file is not a hypothetical risk. The global file I read at the start of this project includes an entire section devoted to exactly that mistake.

What belongs in the personal file

The global file governs things that are true about the person, not about any one codebase: which operating system they are on today, where their repositories live on disk, and — the largest section by far — a hard rule against ever writing an absolute path into a committed file. Not /Users/name/..., not C:/Users/name/..., not even a tilde-shortcut that only resolves correctly on one operating system.

The reason that rule lives in the personal file rather than any project’s own file is that it is not really about any one project. It is about a working style: the same repositories get opened from a Windows desktop, a Mac laptop, and occasionally a cloud environment, and a path hardcoded for one of those silently breaks every script that runs on the others. The fix prescribed is a fallback chain — try several likely locations in order, use whichever exists — given as copy-paste-ready code in both Bash and Python, so the rule is not just stated but made easy to actually follow.

What belongs in the project file

The file inside this repository is a different register entirely. It describes this one pipeline: which directories hold which kind of content, the naming convention for a content-calendar entry, which seven brand names are valid, and the exact sequence a blog post travels through from topic selection to publication. None of that means anything outside this repository. A different project’s file describes a completely different pipeline, because it is describing different work.

This is the file that answers “how does this specific thing work,” and it is deliberately silent on anything the personal file already covers. It does not repeat the cross-platform path rule — it references it, because restating a rule in two places is how the two places eventually disagree.

The synchronisation detail that makes this interesting

The project file does not only describe this repository. It names a separate repository — a shared library of skills and conventions — as the upstream source for parts of its own configuration, with a version number and a sync command. Pull from that shared source, and defined pieces of this project’s own setup update to match it.

That is a real dependency between two things that look, from the outside, like they should be independent: the project’s own rules, and a shared library neither this project nor any other one project owns. Getting the layering right — personal file for cross-machine identity, shared library for conventions common to many projects, project file for what is actually specific to this one repository — is what lets all three update independently without the other two needing to change every time one of them does.

Why getting this wrong is a quiet failure, not a loud one

None of this produces an error message when it goes wrong. A path hardcoded into a project file that should have used the personal file’s fallback chain will work perfectly on the machine it was written on, for as long as nobody else, and no future version of the same machine, ever looks at it differently. The failure shows up later, somewhere else, as a script that silently finds nothing and reports nothing — exactly the shape of failure this series keeps returning to, because a rule that only sometimes applies is a rule that is already broken, waiting for the day someone runs it from the wrong place.

The practical test, when adding anything to either file: would this line make sense on a different machine, in a different project, read by someone else entirely? If yes, it belongs in the file that travels. If the honest answer is “only here, only for this,” it belongs in the one that does not.

---

Ash Ganda is the founder of Ganda Tech Services. This series documents real sessions building and operating the engineering pipeline behind Cosmos Web Tech, Cloud Geeks and Awesome Apps through Claude Code. Part 5: The Skill File Is the New System Prompt.