Lesson 7: Safety, Guardrails & Settings

What this lesson is about

Claude Code is designed to be helpful, but helpfulness without boundaries can cause real problems — especially on projects where certain files must never be touched or certain actions must never run automatically. This lesson shows you how to use the settings file to build your own customised set of guardrails, so that Claude Code behaves exactly the way you need it to on every project you work on.

---

Core concept: The house alarm control panel

Think about a modern house alarm system. Out of the box, it comes with some basic protection already built in. But the real power is in the control panel: you decide which zones trigger an alert, which entry points are monitored, which actions are completely blocked (like disabling the system without a code), and which activities are allowed freely (like a family member walking through the front door).

The control panel does not replace the alarm’s built-in intelligence — it works alongside it. Your specific rules layer on top of the system’s defaults to create a combined set of protections tailored exactly to your home.

Claude Code’s .claude/settings.json file is your control panel. Claude arrives with sensible built-in safety limits already in place. Your settings file lets you add your own rules on top: which tools Claude may use, which files it must never touch, and which actions are completely off limits regardless of what anyone asks.

---

Where to find the settings file

The settings file lives inside a hidden folder called .claude at the root of your project — that is, inside the main folder for whichever project you are currently working on. The full path looks like this:

your-project-folder/
└── .claude/
    └── settings.json

The dot at the beginning of .claude makes it a hidden folder. On most computers, hidden folders are invisible by default. To reveal them:

• Mac: Press Command + Shift + . (full stop) while in Finder
• Windows: Open File Explorer, click “View” in the top menu, and tick “Hidden items”
• Terminal: Type ls -a instead of ls to list all files including hidden ones

If the .claude folder and settings.json file do not exist yet in your project, you can create them manually. In your terminal, navigate into your project folder and run:

mkdir -p .claude
touch .claude/settings.json

The mkdir -p command creates the .claude folder (the -p part means “create any missing parent folders too, and do not complain if it already exists”). The touch command creates an empty file at the path you specify.

---

Understanding the settings file

Before you look at the code, here is a plain English explanation of what a typical settings file contains and what each part does:

• allowedTools — A list of tools Claude is permitted to use in this project. Only tools on this list are available. Think of it as a whitelist: anything not mentioned here is off by default.
• blockedTools — A list of tools Claude is explicitly forbidden from using, regardless of what you or anyone else asks. This overrides everything, including the allowedTools list.
• ignorePatterns — A list of file name patterns that Claude must never read, edit, or delete. This is where you protect sensitive files like passwords, private keys, and confidential documents.
• bash — Settings that control whether and how Claude can run direct commands on your computer’s operating system.

Here is a simple, annotated example that shows all of these working together:

{
  "allowedTools": [
    "read_file",
    "write_file",
    "web_search"
  ],
  "blockedTools": [
    "delete_file"
  ],
  "ignorePatterns": [
    ".env",
    ".env.*",
    "**/*.key",
    "**/secrets/**",
    "**/private/**"
  ],
  "bash": {
    "enabled": false
  }
}

Reading this file line by line in plain English:

• "allowedTools" — Claude may read files, write files, and search the web. Nothing else.
• "blockedTools" — Claude may never delete a file, even if explicitly asked to.
• "ignorePatterns" — Claude must never touch files named .env, any file whose name starts with .env., any file ending in .key anywhere in the project, or anything inside a folder named secrets or private.
• "bash" — Direct command-line access is switched off entirely.

---

The key settings explained

allowedTools — your permitted list

The allowedTools setting is a whitelist (a list of things explicitly allowed). If a tool is not on the list, Claude cannot use it in this project, even if it would normally have access.

Common tools you might want to include or exclude:

Tool name	What it does	Include for
read_file	Reads the contents of a file	Almost all projects
write_file	Creates or overwrites a file	Projects where Claude should produce output
delete_file	Deletes a file permanently	Rarely — omit this unless you are certain
web_search	Searches the internet	Research and writing projects
run_bash_command	Runs a terminal command directly	Developer projects only — avoid for beginners

blockedTools — your forbidden list

The blockedTools setting is a blacklist (a list of things explicitly forbidden). Items here are blocked regardless of what is in allowedTools or what anyone asks Claude to do. This is your absolute floor — the line Claude cannot cross.

"blockedTools": [
  "delete_file",
  "run_bash_command"
]

Use this for any action that could cause irreversible damage if used accidentally or maliciously. Blocking delete_file across all your projects is a sensible default for anyone who is not yet fully confident with Claude Code.

ignorePatterns — protecting sensitive files

This setting tells Claude which files and folders it must never look at, modify, or even acknowledge. It uses a simple pattern language:

Pattern	What it matches	Protects
.env	A file named exactly .env	Environment variables (passwords, API keys)
.env.*	Any file starting with .env.	.env.production, .env.local, etc.
**/*.key	Any .key file, anywhere in the project	Private encryption keys
**/secrets/**	Anything inside any folder named secrets	Your designated secrets folder
**/*.pem	Any .pem file, anywhere	Certificate files used for secure connections
**/private/**	Anything inside any folder named private	Your designated private folder

The ** pattern means “in any folder, at any depth.” The * pattern means “any characters in a filename.” Together, they let you write rules that catch sensitive files no matter where they happen to be stored in your project.

---

Restricting bash command execution

Bash is the language of direct terminal commands — the instructions that talk to your computer’s operating system rather than to Claude. Allowing Claude to run bash commands is powerful but carries real risk: a bash command can delete folders, modify system files, install software, or connect to the internet in ways that bypass other safeguards.

For non-developers and anyone working with sensitive projects, the safest setting is to disable bash entirely:

"bash": {
  "enabled": false
}

If you are working on a project where some bash access is genuinely needed, you can allow it but restrict which commands are permitted:

"bash": {
  "enabled": true,
  "allowedCommands": [
    "ls",
    "pwd",
    "cat"
  ]
}

This allows Claude to list files (ls), show the current folder location (pwd), and display file contents (cat) — all read-only operations — while blocking everything else.

---

Why sharing settings.json with your team matters

Version control is a system that tracks every change ever made to a project’s files, like a detailed change history for every document. The most widely used version control system is called Git, and when a project is stored on a platform like GitHub, the entire team can access the same files and see the same history.

When you add your .claude/settings.json file to version control, every person who works on the project automatically receives the same guardrails the moment they download the project. There is no manual setup, no individual configuration, no risk that one team member has restrictions turned off while another has them on.

This is particularly valuable for teams where:

• Some members are more experienced with Claude Code than others
• The project contains sensitive client data that must be protected by everyone
• You want consistent, auditable behaviour across all contributors

To include your settings file in version control, simply make sure it is not listed in your project’s .gitignore file (a file that tells Git which files to ignore). If your .gitignore contains .claude/, remove that line so the settings file is tracked alongside your other project files.

---

How Claude’s built-in safety limits work with your settings

Your settings.json file does not replace Claude’s built-in safety limits — it adds to them. Think of it as two layers of protection:

Layer	What it covers	Who controls it
Claude’s built-in limits	Actions that are always off limits regardless of any settings: producing harmful content, bypassing core ethical guidelines, certain destructive system operations	Anthropic — cannot be changed
Your custom settings	Project-specific restrictions: which files to protect, which tools to allow, whether bash is available	You — fully configurable

Even if you accidentally wrote a settings.json that tried to grant Claude unlimited permissions, Claude’s built-in limits would still apply. Your settings can only restrict Claude further — they cannot grant it access to things it is fundamentally not permitted to do.

---

A ready-to-use settings template for non-developers

Copy this template into your .claude/settings.json to get a sensible, safe starting point for any non-technical project. The plain English explanation of each section follows below the code block.

{
  "allowedTools": [
    "read_file",
    "write_file",
    "web_search",
    "list_directory"
  ],
  "blockedTools": [
    "delete_file",
    "run_bash_command"
  ],
  "ignorePatterns": [
    ".env",
    ".env.*",
    "**/*.key",
    "**/*.pem",
    "**/*.p12",
    "**/secrets/**",
    "**/private/**",
    "**/passwords/**",
    "**/*password*",
    "**/*credential*"
  ],
  "bash": {
    "enabled": false
  },
  "costLimit": {
    "monthly": 25.00,
    "currency": "USD"
  }
}

What each section does:

allowedTools — Claude may read files, create or update files, search the web, and list what is in a folder. These four tools cover the vast majority of useful non-technical tasks.

blockedTools — Claude may never delete a file and may never run direct terminal commands. This prevents the two most common sources of accidental damage.

ignorePatterns — All standard sensitive file types are protected: environment files (where passwords and API keys are often stored), encryption keys, security certificates, and any folder or file with “secrets,” “private,” “passwords,” “password,” or “credential” in the name. This is a deliberately broad net.

bash — Direct terminal access is switched off entirely, which is the right default for anyone who is not a developer.

costLimit — A $25 monthly safety cap prevents any runaway spending. Adjust this to suit your budget.

---

Practical Exercise

a. Open your terminal and navigate to your claude-practice folder by typing cd claude-practice and pressing Enter. Create the .claude folder and an empty settings.json file by running these two commands:

mkdir -p .claude
touch .claude/settings.json

Open settings.json in a text editor — on a Mac you can type open -e .claude/settings.json, on Windows you can type notepad .claude/settings.json. Paste in the ready-to-use template from the section above. Save and close the file.

b. Create a sensitive-looking test file to verify that ignorePatterns is working:

touch .env
echo "SECRET_KEY=abc123" > .env

Start a Claude Code session by typing claude and pressing Enter. Ask Claude: “Please read the contents of the .env file in this folder.” Claude should refuse or report that the file is not accessible to it, confirming that your ignorePatterns rule is working correctly.

c. Now test the blockedTools setting. While still in your Claude Code session, ask: “Please delete the file called test-file.txt.” (If test-file.txt does not exist, ask Claude to delete any file in the folder.) Claude should decline, explaining that the delete tool is not available. This confirms your blockedTools rule is in force. Type /exit to close the session, then run /cost one final time before you close — take note of how inexpensive this short, well-configured session was.

---

Common problems and how to fix them

Claude is ignoring my ignorePatterns — it still reads the .env file

What is happening: The most common cause is a syntax error in the JSON. JSON is strict: a missing comma, an extra bracket, or a misplaced quotation mark will cause the entire file to fail silently, meaning Claude falls back to its defaults as if no settings file existed.

How to fix it: Copy the entire contents of your settings.json and paste it into a free online JSON validator (search for “JSON validator” in any browser). The validator will highlight exactly which line contains the error. Fix that line, save the file, and restart your Claude Code session.

The .claude folder does not appear even after I created it

What is happening: Hidden folders (those starting with a dot) are not visible in most file browsers by default.

How to fix it: On a Mac, press Command + Shift + . to toggle hidden file visibility in Finder. On Windows, enable “Hidden items” in File Explorer’s View menu. Alternatively, confirm the folder exists by typing ls -a in your terminal — you should see .claude in the list.

My team member has different settings to me on the same project

What is happening: Either the settings.json file is listed in the project’s .gitignore file (which tells the version control system to ignore it), or your team member has a newer version of the file that has not been shared yet.

How to fix it: Open the .gitignore file in your project (it is in the root folder of the project) and check whether it contains .claude/ or settings.json. If it does, remove that line and save the file. Then commit and push the settings file to your version control system so everyone receives it automatically. If you are not familiar with committing and pushing files, ask a developer on your team to do this once — they will know exactly what to do.

I want to allow bash for one specific command but nothing else

What is happening: You need bash enabled but want to prevent anything destructive from running.

How to fix it: Use the allowedCommands approach shown earlier in this lesson. List only the specific commands you need:

"bash": {
  "enabled": true,
  "allowedCommands": ["ls", "pwd", "cat", "echo"]
}

Start with the smallest possible list and add to it only when you have a specific, understood need for each additional command.

---

What you have learned in this lesson

• The .claude/settings.json file is your personal control panel for Claude Code — like a house alarm system that you configure to match your specific needs
• The file lives in a hidden .claude folder inside your project folder and can be created manually if it does not exist yet
• allowedTools is a whitelist of the tools Claude may use; anything not listed is unavailable
• blockedTools is a blacklist of tools Claude can never use, overriding everything else
• ignorePatterns protects sensitive files — passwords, keys, private folders — from ever being read or touched by Claude
• Disabling bash with "bash": { "enabled": false } is the safest default for non-developers and sensitive projects
• Sharing your settings.json via version control ensures every team member automatically has the same guardrails with no manual setup required
• Claude’s built-in safety limits always apply beneath your custom settings — your configuration can only add restrictions, never remove fundamental protections
• The ready-to-use template in this lesson gives you a safe, sensible starting point for any non-technical project