I wouldn't even think that CLAUDE.md would make it into source control, let alone into the product. I don't AI-code for a living, so I don't know what is considered best practices, but I would think that CLAUDE.md, AGENTS.md, REQUIREMETNS.md, MY_PLAN.md, THIS_STUFF.md, THAT_THING.md, all the instruction/feeder files that drive the AI should not go into source control. Only the actual code that gets compiled.

I look at all those files the same way as IDE configuration cruft--it's workstation-specific configuration that shouldn't even go into source control. I would .gitignore all of those files. Is this not what is done in industry?

EDIT: Wow, thanks for all the replies. Very eye-opening to see what's happening outside of my hobby-experimentation with the technology. I was coming at it with the assumption that 1-2 out of 20 people on the team were using CLAUDE.md, so why have it in source control. But if all 20 people are using it, I can see the benefits. This reply chain has really opened my eyes, thank you HN.

I think it makes sense to include in source control, just as it’s pretty typical to include documentation (such as a readme file) in source control. CLAUDE.md is really just project documentation.

Our Team Claude file is the same. It has our team conventions in it etc.

Its critical that its part of the source code.

They shouldn’t make it into the product/build, but if you think about them as documentation, it makes sense to version control them.

They often describe:

- Overall architecture

- Repository layout

- Processes to use

- Things not to do: code styles to avoid, libraries to not use, etc.

While they’re primarily documenting these things for an agent, the information is similarly useful to a human.

It is super valuable to have your agent files in version control, both because it is useful to be able to revert to previous state and have your AI know where you are, and because being able to freshly clone a repo and have your AI know everything is very helpful.

In my personal and professional experience CLAUDE.md will be set up with workspace/project specific info that any agent on anyone's computer needs to know: * what the repo actually is ("this is a rust application that does XYZ", "this is a internal tooling platform") * how it's structured so the agent knows where to look * code and review standards * rules ("don't automatically run formatters/linters", "don't touch dependencies")

I can see it happening. It's very easy to drag and drop a file into an Xcode project and when the dialog pops up asking if you want it to be added to the target app bundle you just hit OK, not realizing what you just did. I've done it before with a document file but caught it before I shipped by inspecting the app bundle output.

IntelliJ's .idea/ folder has its own .gitignore and Copilot expects to find things committed under a .github/ folder.

I used to be a purist about IDE configurations, but if everyone isn't on the same page about formatting and stuff like that you see a lot of file churn as things move around.

I would have said the same thing about the .github/ folder, but I've had to add things to it to prevent Copilot from thinking bad patterns in existing code are actually good patterns that should be repeated.

It makes more sense when your communication between teammates is constrained to the repository, because your other communication channels are already saturated. They're meta concerns that really have nowhere to go outside the repository without getting lost.

To be fair, most IDEs will usually try to commit their own workspace configurations to a git repo unless you tell them off with a .gitignore. They tend to also exclude themselves from gitignore presets for much the same reason.

VS Code is one notorious offender in that realm; it will try to commit settings.json, even if their gitignore's are set up to ignore all other cruft.

In general, the question of what should go in the source folder is a bit of a mess. Source code, README and License make enough sense, but what about files describing project governance or CI configuration logic? Or what about files that are used to make the forge you're using render the repository in a certain way (for example: bug tracker templates). Those are all cruft insofar that they have nothing to do with code, but it's generally agreed on that you're supposed to commit those, maybe in a dot-folder if necessary.

No.

Version control everything (inputs)

If your coworker needs to make a change, those md files can capture a lot of elements of design intent and known gotchas that are otherwise latent or implicit. That’s kind of what comments are for, to say nothing of blindingly obvious design, but …if everyone else using the same tool, sharing a tool native file makes sense in the same way that checking an IDE workspace file can.

I personally don't have strong experience here , but I would treat them similar to BUILD files and the like - probably in the root directory of a repo but nowhere near the bin/ or build/ directories.

Also it looks like there's a compilation step to these files, which is interesting. The raw file was included, not the environment specific file.

> Only the actual code that gets compiled.

And tests, linter configuration, doc...

You're describing project-level shared resources, there are local versions of that like CLAUDE.local.md which should be gitignored

How will you understand the garbage out without keeping track of the garbage in?

Nah. That’s not how it looks once you start working with it. Its code-equivalent for sure. You probably would not keep your plan files or the working chats though.

Agent instruction files are code, though. And none of this is really workstation-specific, it is codebase-specific. Should each developer keep a nearly identical copy of CLAUDE.md? The instructions really aren't for a developer, they are for an LLM agent. In most cases (I'd imagine, anyway) the agentic instruction files must be in source control for them to even provide much value.

I think it’s more like project-wide code style rules or build instructions.