Claude Code: Five Project Setup Mechanisms
Instructions, minimal permissions, skills, hooks and MCP. What to configure, how to verify it and where the limits are.
Five mechanisms help adapt Claude Code to a project: instructions, permissions, skills, hooks and MCP. You do not need all of them at once. Start with one task and add what helps complete it safely.
This is Claude Code configuration, not a universal setup for every Claude product. Interfaces and features depend on version and environment. Checked against official documentation on November 7, 2026; check claude --version before setup.
1. CLAUDE.md: instructions, not guaranteed memory
Use CLAUDE.md for the project purpose, verified test commands, change boundaries and acceptance criteria. Keep keys and client data out. Instructions provide context, not technical enforcement. A session does not necessarily start from zero without this file: other context sources may exist.
Check instructions loaded at startup in /context all under Memory files. Use /memory to view locations and edit instructions. Subdirectory instructions may load later. Reading AGENTS.md depends on version and settings; it is no longer a file exclusively for other agents. When you need an explicit compatible import, use @AGENTS.md from CLAUDE.md without duplicating conflicting rules.
Draft CLAUDE.md for [project folder]. Read only agreed files without secrets. Preserve existing instructions and propose a diff covering purpose, check commands, change boundaries and acceptance criteria. Mark untested commands. Do not change permissions or publish anything. Ask before applying the draft.
Source: instructions and memory.
2. .claude/settings.json: minimum permissions
This file provides some Claude Code rules. Other configuration levels and organization-managed policies may also apply. Check effective rules with /permissions, not just the existence of one file.
Allow specific operations for necessary paths and commands. Do not grant blanket Bash, all-command patterns or bypassPermissions for convenience. Settings do not replace filesystem, network and external-service restrictions.
Prompt for Claude Code
Prepare minimum permissions for [task] in [project folder].
1. Read effective permission settings without secret values. Agree on the contents and protected location of a backup; do not copy authentication or credentials files. Keep secrets out of the diff. Preserve existing rules and account for managed policies.
2. Propose exact paths, commands and operations that are necessary. Do not add blanket Bash, broad patterns or bypassPermissions.
3. Keep deletion, external network access, sending, publishing and access changes subject to separate approval.
4. Show a diff and explain every permission. Apply only after my approval.
5. In an isolated test directory, check one allowed safe operation and denial of a synthetic canary file. Use only dummy data. Record the blocked status, not real secret contents.
If a permission prompt remains, identify the rule and settings level behind it. It does not prove settings.json is misplaced. Do not disable confirmation globally.
Source: Claude Code permissions. Checked November 7, 2026.
3. Skills: a repeatable procedure
For a new skill, use .claude/skills/review-check/SKILL.md. The older .claude/commands/review-check.md format remains supported: commands have merged into skills, not disappeared. Pass arguments through $ARGUMENTS.
Example of a review-only skill:
---
name: review-check
description: Review an agreed file without changing it
disable-model-invocation: true
---
Review $ARGUMENTS against the project rules.
Do not edit files, send messages or publish anything.
Return: issue, location, evidence and proposed correction.
Ask first if a check needs a command to run or external access.
Invoke it in Claude Code with /review-check src/example.ts. disable-model-invocation: true leaves invocation to the user. It controls skill invocation, not tool permissions. Do not add automatic publication to a release-preparation skill.
Source: skills and command compatibility.
4. Hooks: a specific event and a verifiable action
A hook responds to a configured Claude Code event. For example, PostToolUse with an appropriate matcher can run a local check after Edit or Write; this does not mean every save in every editor triggers it. PostToolUse happens after the action and cannot undo it. An asynchronous hook is not a blocking gate.
PreToolUse supports blocking before a tool call. The outcome depends on the event, matcher, exit code, timeout and loading policy. Test success, failure and a nonmatching case in a test folder. Hooks run commands with the process's access: do not paste an unreviewed script into them.
Design a local-check hook for [file types]. Do not install or run it yet. Specify the event, matcher, exact command, working directory, timeout and failure behavior. Preserve existing hooks. Show a diff and a test plan using fake files, including a failed check and a nonmatching path. No network transmission, package installation or publication without approval.
Source: hook events and limitations.
5. MCP: external tools with chosen permissions
MCP connects additional tools and data. It is not the only way to work beyond files: Claude Code also has built-in tools whose availability depends on environment and permissions. An MCP server is not automatically official, safe or read-only.
Claude Code has three MCP configuration scopes:
project:.mcp.jsonin the project root, shared with the team; never add secrets.local: a current-project entry in~/.claude.json, private to you.user: an entry in~/.claude.jsonavailable across your projects.
Normally add servers with claude mcp add and the appropriate --scope project, --scope local or --scope user. .claude/settings.json contains settings and policies, including MCP-related controls; it is not the normal server-registration location for mcpServers.
Source: MCP installation scopes, checked November 7, 2026.
Prompt for Claude Code
Show the official setup for the selected search MCP server.
Check its source, supported transport and required permissions. Propose local
scope for a private project setup, project for shared .mcp.json, or user.
Show the plan first and ask before installation, access or data sharing.
Never put keys in the repository. After approved setup, check claude mcp list,
claude mcp get <name> or /mcp and one safe request.
Setup acceptance checks
/context all→ Memory files: startup instructions loaded without contradictions. Check nested instructions when working with the relevant files./permissions: permissions are minimal; a denial is not bypassed with another tool.- Skill: returns a verifiable report on a practice file without changing anything.
- Hook: allowed action, failure and matching boundaries have been tested.
/mcp: the server is connected and the agreed test completed. Diagnose the exact error, transport, scopes, network and compatibility, not just the key or URL.
Moving to another project requires checking paths, commands, dependencies and permissions again. This is not a permanent one-time setup.
Sources: built-in tools, MCP.
Frequently asked questions
What is CLAUDE.md and where should it live?
It holds project instructions, not guaranteed memory or an action blocker. Common locations are CLAUDE.md at the project root or .claude/CLAUDE.md. Check startup loading with /context all → Memory files; /memory lists locations and supports editing. Other instructions, history and auto memory may remain without the file.
How does CLAUDE.md differ from AGENTS.md?
Both can hold project instructions. Direct AGENTS.md loading is supported from v2.1.277, depending on version, session and Project instructions. By default, a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above loads instead of AGENTS.md; user-level and managed instructions do not count for this check. Check the AGENTS.md path in /memory (it may not appear before v2.1.280). Use an @AGENTS.md import from CLAUDE.md when needed.
Do I need all five files? Where should I start?
No. These are five mechanisms, not five mandatory files. Start with instructions and minimal permissions. Add skills, hooks and MCP for a specific task. MCP project configuration lives in .mcp.json; local and user configuration lives in ~/.claude.json. Check the connection with /mcp.
What should I write in CLAUDE.md so Claude follows it?
Use short, testable rules: test commands, change boundaries, project structure and acceptance criteria. Neither vague nor specific wording guarantees compliance. Back important boundaries with permissions, checks and approval, and verify the result.