CLAUDE.md or a company brain: what goes where

CLAUDE.md is the first place most teams put what they want Claude Code to know. It is also where most of them end up with a file too long to be useful and half out of date. The fix is not a better CLAUDE.md. It is putting each kind of knowledge where it belongs.

What CLAUDE.md is for

Claude Code reads CLAUDE.md when a session starts: the one in your repository, your own in your home folder, and the ones in subfolders when it works there. Everything in it is in the conversation from the first message.

That makes it the right place for what every task in this repository needs:

• how to build, test and run it
• the conventions you follow, and the commands that check them
• rules that must never be broken here ("never push to main")
• where things are, when it isn't obvious from the files

Other agents have the same idea under other names: Codex reads AGENTS.md, and Cursor reads its project rules.

What doesn't belong in it

Anything that isn't about this repository, or that changes somewhere else:

• Company knowledge: pricing, customers, policies, how the product works for users.
• Decisions and why they were made. The reasons live in docs and threads, and they change.
• Procedures shared across repositories: releases, incident response, onboarding.
• Long documents. Everything in CLAUDE.md is read every session, whether the task needs it or not.

Each of these, copied into CLAUDE.md, is a second copy that nobody updates.

What goes where

The last row is the important one: CLAUDE.md should tell the agent where the rest of the knowledge is, not contain it.

How we do it at Noetix

Our own repository's CLAUDE.md holds what every task there needs: the commands, the architecture in brief, and the rules that keep production safe. It does not hold why things are the way they are. That lives in our own Noetix brain, which our docs folder is loaded into, and which Claude Code reaches over MCP.

The part of our CLAUDE.md that connects the two is short. In substance:

• Before guessing why something is the way it is, recall it from the brain: the code records what was built, the brain records what was decided, what was tried and dropped, and who wrote it.
• For a task with a house procedure (shipping, a migration, recording a decision), search the skills, use the matching one, and follow it.
• If the brain has nothing, flag the gap once, so it gets written down.
• When the brain and the docs folder disagree, the file in the docs folder is newer.

That last line matters for anyone doing the same: if a brain is loaded from files, say which one wins.

A section to copy

Add this to your CLAUDE.md (or AGENTS.md) after you connect Noetix to your agent:

## Company knowledge

Our company's knowledge is in Noetix, connected as the `noetix` MCP server.

- Before guessing why something is the way it is, `recall` it.
- For a task with a house procedure (a release, a migration), use `search_skills`,
  then `use_skill`, and follow it.
- If the brain has nothing on a question, `flag_gap` once with the question.

Moving knowledge out of a long CLAUDE.md

If your CLAUDE.md has grown, sort it in three passes:

1. Keep what every task in this repository needs.
2. Move company knowledge, decisions and long explanations into the brain: write them as pages, or point Noetix at the docs where they already live.
3. Turn procedures into skills, so every agent and every repository follows the same steps.

What is left is a short file that is right every session, and a brain that stays current for the rest.