Why CLAUDE.md, Permissions, and Verification Are Essential When Using Claude Code

CLI Workflow Overview

Start a Claude Code session by explicitly stating the project directory, goals, and acceptance criteria. Let Claude read the code and run commands, then review the /diff and test results.

CLAUDE.md – Project Memo

Use CLAUDE.md as a concise (<200 lines) project memo for rules that are not obvious from the code, frequently mis‑guessed commands, directory conventions, required tests, and version constraints. Split large files into .claude/rules/ (path‑scoped rules) and .claude/skills/ (low‑frequency references) when the file grows.

Placement and Loading Order

Organization‑level: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows).

User‑level: ~/.claude/CLAUDE.md.

Project‑level: ./CLAUDE.md or ./.claude/CLAUDE.md (commit to Git).

Local‑level: ./CLAUDE.local.md (add to .gitignore).

Later files override earlier ones; a project‑level rule such as "use Tab for indentation" wins over a user‑level "use spaces" rule.

For monorepos, place a CLAUDE.md in each subdirectory (e.g., backend/CLAUDE.md, frontend/CLAUDE.md) and keep global conventions in the root.

Permission Management

Layered Authorization

Claude Code prompts for confirmation on sensitive actions (file writes, Bash, MCP tools). Begin with a restrictive set and gradually allow low‑risk read‑only commands.

{
  "permissions": {
    "allow": [
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(rg *)",
      "Bash(mvn test*)",
      "Bash(pnpm test*)",
      "Bash(npm run lint*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)",
      "Bash(git push --force*)"
    ]
  }
}

Only deny rules are enforced; advisory prompts such as "do not read .env" are ignored unless expressed as a deny rule.

Auto Mode

Toggle Auto Mode with Shift+Tab. Low‑risk operations (e.g., git diff, rg) are auto‑approved; high‑risk actions (downloading code, external network calls, production deploys, force pushes) remain blocked or require manual review. Do not set "defaultMode": "auto" in a project‑level .claude/settings.json because versions v2.1.142+ ignore it; instead configure the user‑level settings or organization‑managed policies.

Do not use --dangerously-skip-permissions in regular projects; it bypasses all safety checks.

Security Boundaries

Never expose production credentials, database passwords, cloud provider tokens, or private keys to Claude. Keep files such as .env, secrets/, ~/.aws/, ~/.kube/, and SSH keys out of the context or protect them with deny rules. When high‑privilege automation is required, run it inside isolated containers or with temporary, minimal‑privilege accounts.

Extensibility Mechanisms

CLAUDE.md : Persistent project‑wide background knowledge.

Rules : Path‑scoped constraints (e.g., frontend vs. backend policies).

Skills : Reusable task definitions (TDD, code review, article generation). Store user‑level skills in ~/.claude/skills/ and project‑level skills in .claude/skills/.

MCP (Model Context Protocol): Connect external services (GitHub, Notion, Sentry, databases). Example addition:

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

Shared MCP configs belong in .mcp.json (committed) but never include raw tokens.

Sub‑Agents : Isolated sub‑sessions for focused tasks. Built‑in agents:

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

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

general‑purpose (full tool set) – multi‑step operations and code modification.

Custom agents are defined under .claude/agents/ (project) or ~/.claude/agents/ (user). Example security‑review agent:

---
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/authorization bypass.
- Secrets committed to code.
- Unsafe deserialization or command execution.
Return concrete file and line references. Do not rewrite code unless explicitly asked.

Hooks : Lifecycle callbacks (e.g., PreToolUse to block rm -rf /tmp/build). HTTP hooks must return a 2xx response with decision: "block" or permissionDecision: "deny" to be effective.

Plugins : Bundled packages that combine skills, MCP servers, hooks, and scripts. Install from the official marketplace with:

/plugin install <em><name></em>@claude-plugins-official

Inspect permissions and source before installing; remove unused plugins.

Code Intelligence

When available, enable language‑server‑based Code Intelligence (e.g., jdtls for Java, typescript-language-server for TypeScript). This allows Claude to jump to definitions and view references without exhaustive rg searches, keeping the context cleaner.

Common Workflows

Explore → Plan → Execute → Verify

For complex changes, first let Claude read the repository (no file writes), then ask for a concrete plan, confirm it, and finally execute with explicit commands, always reviewing /diff and running tests.

Test‑Driven Development (TDD)

Write a failing test that captures the desired behavior, let Claude see the failure, then iterate until the test passes. This prevents Claude from guessing implementations without evidence.

Codebase Q&A

When onboarding, ask Claude to describe call chains or locate definitions without modifying code, then manually verify the answers.

Bug Fixes

Provide full context: logs, stack traces, reproduction steps, and request parameters. Ask Claude to diagnose first, then to add a reproducible test before fixing.

Git Worktree Isolation

Run parallel tasks in isolated worktrees:

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

Worktrees are stored under .claude/worktrees/<name>/. Control background isolation with worktree.bgIsolation in .claude/settings.json (e.g., "none" to share the same worktree).

Command Cheat Sheet

/help

– list available commands. /diff – show file changes. /context / /compact – manage context size. /permissions – view current permission rules. /memory – inspect loaded files and rules. /mcp – manage MCP connections. /code-review (with --comment or --fix) – static analysis; supports effort levels (e.g., /code-review high). /simplify – cleanup‑only review (not a full correctness review). /batch, /loop, /run, /verify – orchestrate larger or repeated workflows.

Common Failure Modes

Context overload: mixing many topics in one session. Use /clear or start a fresh HANDOFF.md.

Dead‑end corrections: after three failed attempts, restart with a clearer prompt.

Over‑grown CLAUDE.md: prune rules that are already obvious from the code.

Unbounded investigations: limit directories and goals, or delegate to a Sub‑Agent.

All‑green test suites are not proof of correctness; request additional evidence or manual checks.

Overly permissive permissions are the biggest risk; prefer deny‑by‑default and layer allow rules.

Conclusion

Reliable Claude Code usage hinges on disciplined engineering habits: keep CLAUDE.md concise, plan before coding, verify after changes, isolate long investigations with Sub‑Agents, separate concurrent work with Worktrees, and enforce tight permission boundaries.