Hacker News Reader

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.

I’ve always struggled with what should be in Claude.md that doesn’t belong in readme.md or a similar supporting file.

I tend to include a well documented justfile, so between the readme and that common commands are covered. If there’s a style guide it should be its own file, or summarized in the readme.

If Claude is making errors I tend to just update my global Claude file, but I haven’t updated it in 6 months — only to disable Claude signatures on generated commit messages.

README.md should be for humans CLAUDE.md for machines.

Most agents use README as a storage for EVERYTHING related to the project by default, which is annoying for humans who just want to figure out a) what the thing does b) how to install it. Then you start reading and there's some intricate documentation on how data flows through the application etc.

If you're only working on your personal projects with no collaborators, just a global claude file is just fine. Per-project files are more for things that are specific to that project.

methinks if you really want to have it versioned it should be AGENTS.md in VCS and your globally gitignored CLAUDE.md just @AGENTS.md

otherwise it's like leaving vim dotfiles in the repo or something

If you're committed to Anthropic at an organizational level, there's no point to have a 'standard' AGENTS.md with a CLAUDE.md layer on top. Just commit the CLAUDE.md.

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.

That's like 10% of the reason why people would commit CLAUDE.md…

The number one reason is, you are on a 10-dev tea and it just doesn't make sense for everyone to waste their token budget creating separate instances of this file, which an also requires ingesting the othe whole repo... That is 50, 60%.

The other bit is that you have a review pipeline hooked into CI/CD, and it is the easiest way to tell the bot how to review your code.

Yeah, having one that's consistent across team members is 100% better than everyone having their own each with their own quirks

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 addition, it ensures the team's AI agents are using the same instructions.

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")

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.

.idea was designed to be added to source control. It doesnt have to be, but everyone on the team using the same project configuration has its advantages. Code style can be checked in too, reducing or preventing the churn you speak of.

> 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.

IMO that is what automated static analysis jobs are for. Let me configure my IDE how I want.

Other GitHub metadata goes into the .github folder as well. And that is expected to be commuted. Like action workflows/actions and CodeOwners Pull and issue templates etc.

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.

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)

I agree. The intent is sacred. This should be the default and CLIs should make use of the available history (while preserving inputs you need to preserve outputs too because context matters).

The idea of having to repeat something to your computer is ridiculous.

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.

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.

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

CLAUDE.md is project-specific. It's intended to be there so that anyone working on the project with agentic tools gets the best possible experience.

If you want private stuff you use CLAUDE.local.md

> Only the actual code that gets compiled.

And tests, linter configuration, doc...

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.

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

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