Project memory and rules

The first piece of setting AI up is giving it your project's memory and rules, the conventions, context and standards it should already know before it starts. Claude reads these from CLAUDE.md files and rules, so getting their structure right is how it builds the way your project already does.

Say it another way

Project memory is a plain file, called CLAUDE.md, where you write your project's conventions and decisions. The AI reads it before every task, so it starts already knowing the house rules, like handing a new hire the team handbook on day one rather than letting them guess.

The CLAUDE.md layers you will usually use, broad to specific: personal at the user level, shared at the project level, granular in a subfolder. Each layer adds detail for a narrower scope, and you keep each one modular with @import or a .claude/rules/ folder rather than one giant file.

What one actually looks like

This is the CLAUDE.md from the vibe2value base, the repo every project here starts from. You can take it from vibe2value/vibe2value on GitHub. Three things are worth noticing: it is short, it points at where the detail lives rather than holding the detail itself, and the last rule is about how to write rather than what to build.

# CLAUDE.md

Guidance for AI assistants working in the PROJECT_NAME repo. Keep it short.
The detail lives in the knowledge base.

## Read these first

- `knowledge-base/product/` what PROJECT_NAME is and is not.
- `knowledge-base/system/ways-of-working/` how we branch, commit and ship.
  Follow this.
- `knowledge-base/system/architecture/` the stack and how the pieces fit.

Ground every change in the knowledge base. If a decision is not written down
there, that is a gap to close, not a detail to invent.

## Working rules

- Every change starts from an issue and a branch off `develop` named
  `<type>/<topic>/<what>`. See
  `knowledge-base/system/ways-of-working/branching-strategy.md`.
- Commit with Conventional Commits, ending every commit with the issue number
  `(#n)` and no body. See
  `knowledge-base/system/ways-of-working/commit-conventions.md`.
- Write docs with no emdashes and no Oxford comma, plain enough for a person
  or an AI to read.

The "read these first" section is doing the heavy lifting. It keeps the file small while still pointing Claude at everything it needs, so the file does not have to grow every time the project does.

Doing this with Claude Code: Project memory and rules

Give Claude its instructions through CLAUDE.md files and rules, laid out so the right guidance is already in place before it starts a task, and so each session is consistent.

It earns its keep in four ways: layer by scope, keep it modular, scope rules to where they apply, and check what actually loaded.

Layer it by scope. User-level for your personal preferences across every project, project-level for the shared conventions that travel in the repo, directory-level for a specific part. Each layer down is narrower and adds detail. Because user-level config lives with you and not in the repo, it has no automatic backup, so keeping it safe is on you.

Keep it modular, not one giant file. Split it into focused topic files, either pulled in with @import or kept as a .claude/rules/ folder, so each concern lives in its own file.

Scope a rule to where it applies. Give a rule a path so it only loads when Claude is working on matching files, so its context is not filled with rules that are not relevant.

Check what actually loaded. /memory shows which files are in play this session, so when behaviour is off you can tell a wrong instruction from one that simply never loaded. And if something works for you but not a teammate, the instruction is usually in your personal user file rather than the shared project one, so move it down a layer.

Common questions

What belongs in the user file rather than the project file?
Your personal details and the way you like to work, the things that are yours across every project rather than about this one. A conventional-commit preference lives there and follows you to every project you touch.
Why does something work for me but not for a teammate?
Because a teammate only gets an instruction if it is also in the project file. The diagnosis is right instruction, wrong layer, and the fix is to move it down to the project level so it travels with the repo.
How do I tell a wrong instruction from one that never loaded?
Running /memory shows which instruction files are in play this session. If the file you expected is not listed then nothing is wrong with the instruction, it simply was not seen, which is a different fix.
Does splitting one big file into imports save context?
No. An imported file still loads at launch and enters the context just the same, so importing helps organisation and sharing rather than saving room. The conditional, context-saving load is a path-scoped rule.
Is my user-level config backed up anywhere?
No. It sits in your home directory rather than in any repo, so there is no automatic backup and keeping it safe is on you. Shared config in a repo gets that safety for free.

Back to For developers. The craft around it is Working with AI.