Why You Must Never Skip CLAUDE.md, Permissions, and Verification When Using Claude Code

Introduction

After a popular Vibe Coding tips post, many readers asked about Claude Code. The author shares a year‑plus of hands‑on experience, focusing on practical configuration rather than re‑explaining the official docs.

CLAUDE.md Is Essential

Treat CLAUDE.md as a project‑specific memo, not a second README. It should contain rules Claude cannot infer from code, common commands, team conventions, and version constraints. Keep each file under 200 lines; when it grows, split into .claude/rules/ and Skills directories.

Loading order (global → user → project → local) determines precedence. Global files live in /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL), or C:\Program Files\ClaudeCode\CLAUDE.md (Windows) and are rarely edited per project. User‑level files go in ~/.claude/CLAUDE.md. Project‑level files reside at ./CLAUDE.md or ./.claude/CLAUDE.md and should be committed to Git. Local overrides use ./CLAUDE.local.md and must be listed in .gitignore.

my-project/
├── CLAUDE.md
├── backend/
│   └── CLAUDE.md
├── frontend/
│   └── CLAUDE.md
└── .claude/
    ├── rules/
    ├── skills/
    └── agents/

Claude reads a subdirectory’s CLAUDE.md only when it accesses that path, making the approach friendly to monorepos.

Permission Management

Claude Code prompts for confirmation on sensitive actions (file writes, Bash commands). Start with a permissive allow list for safe read‑only commands ( git diff, rg, etc.) and a deny list for destructive operations ( rm -rf, git push --force, .env, secrets/, etc.).

{
  "permissions": {
    "allow": ["Bash(git status*)", "Bash(git diff*)", "Bash(rg *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", "Bash(rm -rf *)"]
  }
}

Only deny rules are enforced; a plain prompt like “don’t read .env” is merely advisory.

Auto Mode

Shift+Tab toggles permission mode. When the account, model, provider, and organization settings allow it, auto appears in the mode cycle. Enterprise admins can enable or lock it. Auto Mode automatically approves low‑risk actions but still blocks high‑risk tasks such as downloading unknown code, pushing to main, or executing curl | bash. It does not provide sandboxing; high‑risk operations still require containers, temporary credentials, or explicit deny rules.

Do not set "defaultMode": "auto" in a project‑level .claude/settings.json because newer versions (v2.1.142+) ignore it. Instead configure the user‑level settings ( ~/.claude/settings.json) or organization‑managed settings.

Security Boundaries

Avoid exposing production credentials, database passwords, or cloud tokens to Claude. Keep secrets out of the AI’s readable scope and never let it push directly to main without review. Treat files like .env, ~/.aws/, ~/.kube/, and any credential dumps as off‑limits unless explicitly needed and isolated.

Claude Code Components

The ecosystem includes:

CLAUDE.md : background rules and project conventions.

Rules : path‑scoped constraints (frontend, backend, security).

Skills : reusable task scripts (TDD, code review, article writing).

MCP : Model Context Protocol for connecting external services (GitHub, Notion, Sentry, databases).

Sub‑Agent : isolated sub‑sessions for focused research or code modification.

Hooks : lifecycle callbacks (pre‑tool use, post‑edit, session end).

Plugins : packaged bundles of Skills, MCP servers, Hooks, and scripts.

For example, a rule that “every edit must run a formatter” belongs in a Hook, while a multi‑step workflow like “TDD → code review → deploy” belongs in a Skill.

Code Intelligence

When available, enable language‑server‑backed Code Intelligence so Claude can jump to definitions, find references, and catch type errors without exhaustive full‑text searches. Install the appropriate server binary (e.g., jdtls for Java, typescript-language-server for TypeScript). Missing binaries surface as “Executable not found in $PATH”.

MCP (Model Context Protocol)

MCP lets Claude call external tools. Example to add a Notion server:

claude mcp add --transport http notion https://mcp.notion.com/mcp \
  --header "Authorization: Bearer your-token"

Store shared MCP configs in .mcp.json and commit non‑secret parts to the repo. Secrets should remain in user‑level config, environment variables, or a secret manager.

Sub‑Agent Usage

Built‑in sub‑agents include:

Explore (Haiku, read‑only) – file discovery and code search.

Plan (inherits main model, read‑only) – planning and analysis.

general‑purpose (inherits tools, can write) – complex research or code changes.

Custom sub‑agents are defined under .claude/agents/ (project‑wide) or ~/.claude/agents/ (user‑wide) with their own model, tools, and trigger conditions.

---
name: security-reviewer
description: Reviews Java and Spring Boot code for security risks.
tools: Read, Grep, Glob, Bash
model: opus
---

Review the target diff for:
- SQL injection and unsafe dynamic queries.
- Authentication and authorization bypass.
- Secrets or credentials committed to code.
- Unsafe deserialization or command execution.

Return concrete file and line references. Do not rewrite code unless explicitly asked.

Hooks

Hooks run at specific lifecycle points. Example: a PreToolUse hook intercepts a dangerous rm -rf /tmp/build and returns deny, preventing execution.

PreToolUse Hook receives the Bash command, evaluates it against rules, and can return "deny" to cancel the operation.

Hooks are ideal for mandatory actions (auto‑format after edit, run tests before session end) while background rules belong in CLAUDE.md.

Typical Workflow

For complex tasks, follow Explore → Plan → Execute → Verify :

# Exploration (read‑only)
Enter plan mode. Read src/auth and related tests, report the current flow and possible change points.

# Planning
I need to fix user‑session token refresh failures. List files to modify, test strategy, and risks.

# Execution
Implement the plan: first add a failing test, then fix the implementation.

# Verification
Run the relevant tests and paste the command and results.

Small edits can skip planning and go straight to execution.

TDD (Test‑Driven Development)

Prompt Claude with explicit test cases before asking for implementation. Example:

Write an email validation function. Test cases:
- [email protected] should pass
- hello@ should fail
- @domain.com should fail
- [email protected] should pass
Run the tests and show the command and output.

This anchors Claude’s output to concrete verification.

Codebase Q&A

When onboarding a new project, ask high‑level questions without permitting modifications:

What is the complete login flow from HTTP request to session write? List relevant classes and methods. Do not modify files.

Always double‑check the AI’s summary against the actual code.

Bug Fixing

Provide full error logs, reproduction steps, and request a root‑cause analysis before any code change.

Below is the production error log, reproduction steps, and request parameters. First locate the cause, then add a reproducible test, and finally fix it.

Worktree Isolation

Use Git worktrees to run parallel Claude sessions without stepping on each other’s changes:

claude --worktree feature-auth
claude --worktree bugfix-payment

Worktrees are stored under .claude/worktrees/<name>/. You can also create them manually with Git and launch Claude in the new directory.

Commit & PR Practices

Prefer small, focused commits. Before each commit, ask Claude to summarize the diff ( git diff --stat) and list verification commands. Review the diff yourself; Claude’s summary is not a substitute.

Prompt Engineering Tips

Use English for technical terms and commands, Chinese for business context. Clearly state scope, goals, and prohibited actions. Provide concrete examples or “gold‑standard” snippets to guide Claude’s output.

# Scoped investigation
Only investigate src/payment and src/order. Goal: confirm where inventory deduction happens after successful payment. Do not modify files, just list the call chain.

Give Claude a reference implementation to mimic project style instead of vague “make it look good”.

Read UserController.java, UserService.java, UserDTO.java. Follow their layering, constructor injection, Result<T> return format, and exception handling. Add an OrderController without introducing a new response structure.

Common Failure Modes

Overly noisy sessions – use /clear and handoff files.

Infinite correction loops – abort after a few attempts and rewrite the prompt.

Rule bloat – prune outdated rules instead of adding more.

Unbounded investigation – limit directories or delegate to Sub‑Agent.

All‑green tests but incorrect behavior – require manual verification.

Over‑permissive permissions – layer allow/deny, use Auto Mode cautiously, and isolate high‑risk tasks.

Conclusion

The key to reliable Claude Code usage is disciplined configuration: maintain a concise CLAUDE.md, plan before you code, verify after changes, isolate parallel work with worktrees, and keep permissions tight. Start with a single module and a verifiable task, then gradually expand as Claude proves stable.