.claude.json at the Project Level: Use the Right File

At the project level, .claude.json usually means project-specific entries inside the home-directory ~/.claude.json file, not a .claude.json file you should add to the repository. Use the documented project settings and instruction files for configuration you want teammates to share.

For changing project decisions and progress, tools like fenbs keep a shared work record outside local configuration. Separating those jobs helps you fix the right file without copying personal machine state into everyone else’s setup.

How do you choose the right file first?

1. Identify the outcome: change tool behavior, give written instructions, connect an outside service, or preserve work progress.
2. Choose the scope: only you, everyone using this repository, or an organization-managed environment.
3. Match that outcome and scope to the documented file below. Check its location before editing anything.
4. Make one small change and verify it in a new session. Do not copy the whole home-directory configuration into the project.

Say you want every assistant session to know that a billing redesign is waiting for approval. That is project progress. Adding it to a JSON setting does not turn it into a shared, current work record. Conversely, a written note about preferred tool access is not a substitute for configuring the tool’s actual permissions.

Anthropic’s settings documentation↗ (opens in a new tab) identifies these configuration locations and distinguishes files you maintain from state Claude Code manages. Keep that reference available when deciding where a change belongs.

Why does a home-directory file mention my project?

A setting can apply to one project while being stored outside that project. Think of an editor remembering which folders you trust: the folder is the subject of the setting, but the preference belongs to your local application state.

Claude Code’s MCP scope documentation↗ (opens in a new tab) describes local-scoped server entries stored under a project path in ~/.claude.json. MCP is a standard way for an AI app to use an outside tool. In that terminology, local and project scopes have different sharing behavior.

This distinction matters when a colleague cannot see your connection. The presence of a project path in your home file does not mean the configuration traveled with the repository. Compare the intended scope with the actual configuration before assuming a service is broken.

For the separate task of sharing server configuration, see project-level MCP. This article focuses on choosing the correct home for project information.

What belongs in written instructions instead?

Put durable guidance in the instruction mechanism your installed Claude Code supports: how to navigate the repository, which checks matter, and which changes require a person’s approval. Anthropic’s project memory guide↗ (opens in a new tab) explains instruction files and their loading behavior.

Keep each instruction specific enough to act on. “Follow our conventions” leaves the assistant guessing. “Read the package’s own instructions before editing it” names an observable first step. Include a pointer to the authoritative source when the details are too long to repeat.

Temporary investigation notes need a different home. Yesterday’s suspected cause should not become tomorrow’s standing instruction just because it was pasted into a file that loads automatically. Our guide to organizing Claude projects covers the broader organization problem.

How can you check whether a change actually applied?

Start from the working directory you intended to configure. Check the exact path and filename in your editor, then compare the key with the vendor reference. A valid JSON document can still be the wrong configuration file or contain a key that does not apply at that scope.

• Separate observation from expectation: record what changed and what behavior you expected.
• Check applicable organization settings before assuming your project file wins.
• Use the documented configuration or status view to inspect loaded settings.
• Test a harmless, narrow behavior change before granting broader tool access.
• If a change fails, preserve the error and undo only the change you made.

Avoid deleting an entire local state file as an opening troubleshooting step. You may remove unrelated preferences or connection state and make the original problem harder to isolate. Redact personal paths and authentication material before sharing diagnostic output.

Where should the team keep rules and current decisions?

A useful rule has an owner, a scope, and a reason. A useful progress note says what happened, what was checked, and what comes next. Neither requires teammates to copy one person’s machine configuration.

For example, keep “production changes need owner approval” as an agreed rule. Keep “the new checkout screen is built but still needs keyboard testing” with the task. Leave a proposed change clearly open until a person decides it. This keeps a technical preference from silently becoming project authority.

fenbs puts Decisions and rules alongside tasks and Where we left off, so connected assistants can read the current record; see how it works. The distinction also helps when Claude project memory and local instructions contain overlapping information.

How to do this with fenbs

1. Create a free account, free for one person with no credit card, and add the project whose configuration you are organizing.
2. Record the person-approved working rules in Decisions and rules, including where each rule applies.
3. Add a task for the configuration change. Keep the problem, planned change, and verification result with that task.
4. Connect a supported assistant using Integrations, then ask it to read the project context before changing settings.
5. Save Where we left off with the file changed, the check performed, and the remaining question. Keep secrets and personal configuration out of the record.

fenbs is not the right fit for enforcing Claude Code permissions or distributing machine settings. Use the application’s configuration and your organization’s controls for those jobs. For broader planning across sessions, Claude for project management covers the work record itself.

What should you keep after the setup works?

Leave behind a short explanation of which file owns which concern and how you verified it. Record the intended behavior rather than a large dump of generated state. A teammate should be able to reproduce the setup without borrowing your personal trust choices or authentication.

Review that explanation when the project moves or the team changes its tools. Paths and local state may change; the approved requirement should remain understandable. More guides in the context engineering hub explain how to keep instructions and active work useful without loading everything into every session.