Claude Code Project Setup: CLAUDE.md, Memory Files, Rules, and Team Conventions for Reliable Repository Workflows

Claude Code project setup works best when teams treat project memory as a shared onboarding layer that helps Claude understand how the repository works, how the team writes code, and which conventions should guide future changes.

This setup matters because Claude Code is not only answering questions about code.

It can read files, edit projects, run commands, follow repository context, and participate in multi-step development workflows where consistency depends on the instructions it receives before work begins.

A well-designed setup gives Claude stable project context without turning memory files into bloated manuals or treating them as substitutes for tests, code review, permissions, and CI enforcement.

·····

CLAUDE.md should function as concise project onboarding for Claude Code.

CLAUDE.md is best understood as the repository’s onboarding document for Claude.

It should contain the durable project information that a senior developer would give a new teammate before asking them to modify the codebase.

That includes what the project does, how it is organized, how to install dependencies, how to run tests, which package manager to use, what architecture patterns matter, and which mistakes should be avoided.

The best CLAUDE.md files are concise, operational, and specific.

They do not try to describe every file in the repository.

They describe the rules and context that Claude needs repeatedly across tasks.

When the file is too vague, Claude has little to apply.

When the file is too long, important instructions can be buried under noise.

........

What a Strong CLAUDE.md Should Include

Section	Purpose
Project overview	Explains what the repository does
Setup commands	Tells Claude how dependencies and local setup work
Test commands	Defines how changes should be validated
Architecture notes	Highlights important project structure and design choices
Coding conventions	Describes the patterns Claude should follow when editing

·····

Memory files guide behavior, but they should not be treated as hard enforcement.

Claude Code memory files provide context, not absolute enforcement.

That distinction is important because teams sometimes expect CLAUDE.md to behave like a policy engine.

It does not.

Claude can use the file to understand team preferences, workflows, commands, and repository rules, but critical requirements still need technical enforcement through tests, linters, type checks, branch protections, hooks, permissions, and code review.

This means memory files should be written as guidance that improves Claude’s behavior rather than as the only protection against bad changes.

For example, a memory file can say that database migrations require tests and review.

The repository should still enforce migration checks through CI or review rules.

A memory file can say not to edit generated files.

The project should still mark generated files clearly and validate outputs through tooling.

........

Why Memory Is Guidance Rather Than Enforcement

Project Rule Type	Better Enforcement Layer
Formatting standards	Formatter and lint checks
Type safety	Type checker and CI
Test requirements	Automated test pipeline
Security-sensitive changes	Review rules and permissions
Generated files	Build scripts and repository conventions

·····

Shared team memory and personal memory should be kept separate.

A clean Claude Code setup separates shared repository instructions from personal developer preferences.

Team-wide instructions belong in committed project files so everyone using Claude Code in the repository gets the same baseline context.

Personal preferences belong outside the repository, such as in local or user-level memory, because they reflect one developer’s workflow rather than the team’s standard.

This prevents shared memory from becoming cluttered with local paths, private habits, one person’s editor setup, or machine-specific notes.

It also prevents accidental exposure of private information.

A team CLAUDE.md should describe the repository.

A personal memory file can describe how one developer prefers explanations, which local aliases they use, or how they like tasks summarized.

Keeping those layers separate makes Claude’s behavior more consistent across the team.

........

How to Separate Shared and Personal Memory

Memory Type	What Belongs There
Shared project memory	Team conventions, setup commands, test commands, architecture notes
Local project memory	Machine-specific paths or local development notes
User memory	Personal preferences that apply across projects
Rules files	Scoped instructions for a package, feature area, or directory
Skills	Reusable procedures that are too detailed for memory

·····

Rules files help large repositories avoid one overloaded instruction file.

In larger repositories, one root CLAUDE.md can become too broad to be useful.

Rules files help solve this by allowing instructions to be scoped to specific directories, packages, domains, or workflows.

This makes project setup easier to maintain because frontend conventions, backend conventions, infrastructure rules, database practices, and documentation style do not all need to live in one giant file.

A frontend rule file can describe component patterns, accessibility expectations, styling conventions, and test locations.

A backend rule file can describe API structure, error handling, database access, and service boundaries.

An infrastructure rule file can describe deployment, secrets, Terraform, or environment rules.

Scoped rules keep Claude’s context more relevant to the files being edited.

They also make it easier for teams to update conventions without rewriting the entire project memory layer.

........

How Rules Files Improve Repository Setup

Repository Area	Useful Scoped Rule
Frontend	Component style, accessibility, test patterns, design-system usage
Backend	API conventions, service boundaries, database access rules
Infrastructure	Deployment rules, environment settings, secrets handling
Documentation	Tone, structure, terminology, and update expectations
Tests	Naming conventions, fixtures, mocks, and required validation paths

·····

Directory-scoped instructions should be designed with loading behavior in mind.

Nested project instructions are useful, but teams should understand that not every subdirectory instruction may be loaded at the start of a session.

If a rule must apply globally, it should live in the root project memory or another reliably loaded location.

If a rule applies only to a specific package or directory, it can live closer to that code, but the team should expect it to become relevant when Claude reads or works in that area.

This matters when troubleshooting.

If Claude ignores a rule, the issue may be that the rule was not loaded yet, or the rule may be written too vaguely for Claude to apply.

Teams should use memory inspection tools to confirm what has been loaded before assuming Claude is deliberately ignoring project conventions.

Good setup requires both good file placement and clear instruction writing.

........

How to Decide Where Instructions Belong

Instruction Scope	Best Location
Applies across the whole repository	Root project memory
Applies to one package	Package-level rules or memory
Applies to one developer	Local or user memory
Applies to one repeated workflow	Skill file
Applies as a hard requirement	CI, hook, setting, or permission rule

·····

Auto memory is useful for learned context, but curated team rules should remain intentional.

Auto memory can help Claude remember useful project patterns, repeated preferences, or information discovered during work.

That makes it valuable for evolving context.

However, teams should not rely on auto memory as the primary home for important project rules.

Important conventions should be written intentionally, reviewed by the team, and committed where appropriate.

Auto memory is better for convenience and adaptation.

Curated memory is better for shared standards.

This distinction matters because accidental or outdated memories can create confusion if they are treated as authoritative.

A repository should not depend on the model silently learning a critical workflow through repeated use.

The team should write the workflow down clearly in the right project file.

........

How Auto Memory and Curated Memory Differ

Memory Layer	Best Use
Auto memory	Learned preferences and recurring patterns
Root CLAUDE.md	Stable shared project context
Local memory	Developer-specific or machine-specific details
Rules files	Scoped conventions for parts of the repository
Skills	Repeatable procedures and checklists

·····

The /memory command helps teams inspect and troubleshoot loaded context.

The /memory command is important because it gives users visibility into what Claude has actually loaded.

This helps troubleshoot situations where Claude appears to miss a convention or behave inconsistently.

A team can inspect loaded memory files, open them for editing, and confirm whether the expected project instructions are present.

This is useful during setup and maintenance.

If Claude does not follow a rule, the first question should be whether the rule is loaded.

The second question should be whether the rule is specific enough.

A vague instruction such as “write clean code” is much less useful than a direct instruction such as “use pnpm for all package commands and run pnpm test before summarizing code changes.”

Memory inspection turns project setup into something observable rather than mysterious.

........

Why /memory Is Useful During Project Setup

Troubleshooting Need	How /memory Helps
Confirm loaded instructions	Shows which memory files are active
Edit project memory	Opens memory files for updates
Find missing rules	Helps identify instructions that were not loaded
Review memory clutter	Reveals whether context has become too noisy
Improve instruction quality	Helps teams refine vague or outdated guidance

·····

Good team conventions should be short, specific, and testable.

The best team conventions are written in a way that Claude can actually apply.

Vague principles may sound reasonable, but they are hard to follow consistently.

A good convention names the tool, command, directory, pattern, or forbidden action.

Instead of saying “use best practices,” a project memory file should say which framework pattern to use, which folder owns business logic, which generated files should not be edited, and which tests should run after changes.

Specific conventions are also easier for humans to review.

If Claude makes a change, the developer can compare the result against the written rule.

This makes CLAUDE.md more useful as a shared engineering contract.

It also reduces disagreements about what the model was supposed to do.

........

How to Write Better Team Conventions

Weak Convention	Better Convention
Write clean code	Keep business logic in the service layer and avoid adding logic to route handlers
Run tests	Run pnpm test for code changes and pnpm lint for formatting-sensitive changes
Follow the style guide	Use existing component patterns from src/components before creating new patterns
Avoid risky changes	Do not modify migrations, auth logic, or billing code unless explicitly requested
Be concise	Summarize changed files, validation steps, and unresolved risks at the end

·····

Skills are better than CLAUDE.md for long procedures and repeatable workflows.

A common mistake is turning CLAUDE.md into a long procedure manual.

When a section becomes a detailed checklist or multi-step workflow, it may belong in a skill instead.

Skills are better suited for repeatable procedures such as release preparation, migration review, security auditing, component creation, documentation updates, or incident-summary generation.

This keeps project memory shorter and makes procedural instructions easier to invoke when needed.

The separation is useful.

Memory tells Claude what the project is and how the team works.

Rules tell Claude which conventions apply in a scope.

Skills tell Claude how to perform a repeatable process.

This keeps the setup modular and easier to maintain.

........

When to Move Instructions From CLAUDE.md to a Skill

Instruction Type	Better Home
Stable project fact	CLAUDE.md
Directory-specific convention	Rules file
Long release checklist	Skill
Security review process	Skill
Local developer preference	User or local memory

·····

Hooks and CI turn conventions into operational safeguards.

Memory can guide Claude, but hooks and CI can enforce rules more reliably.

Hooks can help connect Claude Code activity to project-specific automation.

CI can ensure that tests, linters, type checks, build steps, and security scans run before changes are accepted.

This matters because some conventions are too important to rely on instruction following alone.

If the project must never commit generated files, that rule should be checked.

If every API change needs tests, CI should verify it.

If formatting must follow a standard, the formatter should enforce it.

Claude can be told these rules in memory, but tooling should still protect the repository.

The best setup pairs memory guidance with technical enforcement.

........

How Enforcement Complements Memory

Convention	Operational Safeguard
Formatting rules	Formatter or linter
Type correctness	Type checker
Test requirements	CI test pipeline
Security-sensitive paths	Code owners or protected reviews
Build integrity	Required build checks

·····

Large repositories need memory hygiene to prevent instruction clutter.

As repositories grow, project memory can become cluttered with outdated commands, duplicate rules, temporary notes, and instructions that no longer match the codebase.

This reduces reliability because Claude may receive conflicting or irrelevant guidance.

Memory hygiene should therefore be part of project maintenance.

Teams should periodically review CLAUDE.md, local rules, and skills to remove stale information and keep instructions current.

They should also avoid putting every preference into the root file.

Large repositories benefit from a layered setup where root memory stays concise, scoped rules handle local conventions, and skills carry repeatable workflows.

The goal is not to maximize the amount of memory.

The goal is to maximize the relevance of memory.

........

How to Maintain Memory Hygiene

Maintenance Step	Why It Helps
Remove outdated commands	Prevents Claude from running obsolete workflows
Delete duplicate rules	Reduces conflicting guidance
Move procedures into skills	Keeps root memory concise
Scope local conventions	Prevents unrelated rules from polluting context
Review after major refactors	Keeps memory aligned with the current architecture

·····

Team setup should include examples of the expected development workflow.

Claude performs better when the project setup explains not only static rules but also the normal development workflow.

A useful CLAUDE.md can describe how the team expects a task to proceed.

For example, Claude should inspect relevant files first, propose a brief plan for large changes, make focused edits, run the appropriate tests, review the diff, and summarize what changed.

This helps align the agent’s behavior with the team’s working style.

It also makes outputs easier for developers to review.

The workflow should be specific enough to guide behavior but not so rigid that it prevents Claude from adapting to the task.

Good project setup describes the default path while allowing explicit user instructions to override it when needed.

........

A Practical Claude Code Workflow Convention

Workflow Step	Team Expectation
Inspect	Read relevant files before editing
Plan	Outline approach for multi-file or risky changes
Edit	Make focused changes within the requested scope
Validate	Run the smallest relevant test command when practical
Summarize	Report changed files, validation results, and remaining risks

·····

Claude Code project setup matters most when teams treat memory as shared engineering infrastructure.

The strongest way to understand Claude Code project setup is to treat memory, rules, skills, hooks, and CI as parts of one repository workflow.

CLAUDE.md gives Claude shared project context.

Rules files scope conventions to the right part of the codebase.

Local and user memory keep personal preferences separate from team standards.

Skills hold repeatable procedures that are too detailed for the root memory file.

Hooks, tests, linters, branch protections, and code review enforce the conventions that cannot be left to guidance alone.

This layered setup makes Claude Code more predictable, easier to troubleshoot, and safer to use across a team.

The goal is not to write the longest possible instruction file.

The goal is to give Claude the right context at the right level, then back critical rules with real engineering safeguards.

·····

FOLLOW US FOR MORE.

·····

DATA STUDIOS

·····

[datastudios.org]

·····