Core Configuration

Reasonable configuration helps Claude Code better fit your project and team. This section explains configuration role, priority, and optimization for different usage scenarios.

Configuration File Locations and Priority

Claude Code uses layered configuration strategy. Different levels have different scope and priority. Understanding this lets you manage settings flexibly.

Configuration priority (high to low):

Merge rules:

• Higher-priority config overrides same key in lower priority
• Non-conflicting keys are merged
• Project config overrides global config
• Local personal config overrides shared project config

Practical scenarios:

Scenario 1: team project

~/.claude/settings.json          # your personal default editor settings
.claude/settings.json            # team coding standards and permission config
.claude/settings.local.json      # your debug preferences and theme settings

Scenario 2: personal project

~/.claude/settings.json          # global default config
.claude/settings.json            # project-specific config (e.g. special permission rules)

CLAUDE.md - Project Memory

CLAUDE.md is the most important file for Claude Code configuration. It acts like a project "manual." Every time Claude Code starts, it reads CLAUDE.md under current directory, understanding background, stack, and conventions.

Why CLAUDE.md is so important:

Imagine joining a new project: you need to learn stack, coding conventions, and common commands. Normally this takes hours of docs/code review and teammate questions. With CLAUDE.md, Claude knows this at startup and you can immediately collaborate effectively.

Minimum viable template:

# [Project Name]

## Tech Stack
- Framework: React 18 + TypeScript
- State: Zustand
- Styling: Tailwind CSS
- Build tool: Vite

## Common Commands

\`\`\`bash
npm run dev      # start development server (port 5173)
npm run test     # run unit tests
npm run build    # production build
npm run lint     # lint checks
\`\`\`

## Code Conventions
- Components use function components + Hooks
- Naming: PascalCase (components), camelCase (utility funcs)
- Git commits use Conventional Commits
- All API calls must go through unified request wrapper

Full template (recommended):

# [Project Name]

## Project Overview
One-sentence description of main functionality and target users.

## Tech Stack
### Frontend
- Framework: React 18 + TypeScript
- Router: React Router v6
- State: Zustand + React Query
- Styling: Tailwind CSS + Headless UI
- Build: Vite

### Backend (if applicable)
- Runtime: Node.js + Express
- Database: PostgreSQL + Prisma
- Auth: JWT + bcrypt

## Project Structure

\`\`\`
src/
├── components/      # reusable components
├── pages/           # page components
├── hooks/           # custom Hooks
├── lib/             # utility functions
├── types/           # TypeScript types
└── api/             # API calls
\`\`\`

## Common Commands

\`\`\`bash
# development
npm run dev              # start dev server
npm run dev:mock         # use mock data in development

# testing
npm run test             # run all tests
npm run test:watch       # watch mode
npm run test:coverage    # generate coverage report

# code quality
npm run lint             # ESLint check
npm run lint:fix         # auto-fix ESLint issues
npm run format           # Prettier format
npm run typecheck        # TypeScript type check

# build
npm run build            # production build
npm run preview          # preview production build
\`\`\`

## Development Rules
### Code style
- Use function components, avoid class components
- Prefer custom Hooks for logic abstraction
- Component props must define TypeScript interfaces

### Git workflow
- Branch prefix: `feature/`, `fix/`, `refactor/`
- Commit messages follow Conventional Commits
- PR must pass CI and code review

### Performance requirements
- Component lazy loading to reduce first-screen load time
- Use WebP images and enable lazy loading
- Keep API response time under 200ms

## Environment Variables

\`\`\`bash
# .env.local
VITE_API_BASE_URL=http://localhost:3000
VITE_APP_NAME=MyApp
\`\`\`

## Common Issues

### Dev server failed to start?

Check whether port 5173 is occupied, or try `npm run dev -- --port 3000`

### Type errors?

Run `npm run typecheck` to see detailed errors

Fast generation of CLAUDE.md:

If your project exists but has no CLAUDE.md, run /init:

claude
# inside Claude Code
/init

Claude analyzes project structure, package.json, and current code, then generates a practical CLAUDE.md. After generation, manually review and adjust.

.claudeignore - Save Tokens

.claudeignore tells Claude Code which files should not be read into context. Correct configuration can significantly reduce token usage (often 40-60%) and improve response speed.

Why .claudeignore is needed:

When Claude Code tries to understand project, it reads related files. Some files do not help understanding and can:

• consume many tokens (for example type definition files in node_modules)
• introduce noise (logs, build outputs)
• include sensitive info (.env files)

Recommended config:

# ===== dependencies =====
# huge third-party code, usually unnecessary for Claude context
node_modules/
.pnp/
.pnp.js

# ===== build outputs =====
# generated artifacts, not source logic
dist/
build/
.next/
out/
*.tsbuildinfo

# ===== logs =====
# runtime logs, no value for understanding architecture
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

# ===== testing outputs =====
coverage/
.nyc_output/

# ===== editor / IDE =====
.vscode/*
!.vscode/extensions.json
.idea/
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

# ===== system files =====
.DS_Store
Thumbs.db

# ===== env files =====
.env
.env.local
.env.*.local

# ===== large binary assets =====
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.ico
*.mp4
*.webm

# ===== lock files (optional) =====
# If you do not need Claude to analyze dependency versions, ignore these
# package-lock.json
# yarn.lock
# pnpm-lock.yaml

Config tips:

1. Start minimal: ignore node_modules and build outputs first, then observe token usage
2. Tune per project: image-heavy project -> ignore image formats; docs project -> keep Markdown
3. Optimize regularly: use /context to see top token-consuming files and decide whether to ignore

Permission Configuration

By default, Claude Code asks confirmation before sensitive operations. Through permissions in settings.json, you can control which actions are auto-allowed, require confirmation, or fully denied.

Permission config structure:

{
  "permissions": {
    "allow": [
      // auto-allow without asking
    ],
    "ask": [
      // ask before execution
    ],
    "deny": [
      // fully deny
    ]
  }
}

Rule syntax:

Permission rules use ActionType(pattern) format:

Wildcard support:

• * matches arbitrary characters (excluding /)
• ** matches arbitrary paths
• ? matches one character

Real config example:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Edit(src/**/*.{ts,tsx})",
      "Edit(tests/**/*.test.ts)",
      "Read(src/**/*.ts)",
      "Write(src/components/*.tsx)"
    ],
    "ask": [
      "Bash(git commit:*)",
      "Bash(git push:*)",
      "Bash(git pull:*)",
      "Bash(npm install:*)",
      "Bash(npm run build)",
      "Edit(package.json)",
      "Edit(tsconfig.json)",
      "Read(.env)",
      "Read(config/secrets.*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl * | sh)",
      "Bash(wget * | sh)",
      "Edit(.git/*)",
      "Write(/etc/*)",
      "Read(/etc/passwd)"
    ]
  }
}

Configuration suggestions:

1. Development stage: relatively relaxed permissions for faster iteration
2. Production stage: stricter permissions, especially deployment and sensitive data operations
3. Team collaboration: place baseline rules in shared settings.json, personal tweaks in settings.local.json

Rules Directory

For large projects, a single CLAUDE.md can become bloated and hard to maintain. Claude Code supports modular management through Rules directory, splitting conventions by topic into separate files.

Directory structure:

.claude/
├── settings.json          # main config file
├── CLAUDE.md              # project overview (still needed)
└── rules/                 # rules directory
    ├── 00-security.md     # security rules (global)
    ├── 01-coding-style.md # coding style rules (global)
    ├── 10-api.md          # API dev rules
    ├── 11-frontend.md     # frontend dev rules
    ├── 12-backend.md      # backend dev rules
    └── 20-testing.md      # testing rules

Filename suggestion:

Use numeric prefixes (00-, 01-) to control load order: base rules first, specific rules later.

Rule file format:

Rule files support YAML frontmatter to define applicability:

---
# Optional: paths where this rule applies
globs:
  - "src/api/**/*.ts"
  - "src/services/**/*.ts"

# Optional: commands where this rule applies
commands:
  - "generate api"
  - "create endpoint"

# Optional: rule priority (smaller number = higher priority)
priority: 10
---

# API Development Rules

## Route design
- RESTful style, use plural nouns
- Versioning: /api/v1/users
- Nested resources: /api/v1/users/123/orders

## Request/response format
- Use JSON consistently
- Error response must include code and message
- Pagination response uses { data, pagination } structure

## Security requirements
- All endpoints must verify authentication (except public endpoints)
- Sensitive operations require secondary confirmation
- Implement rate limiting to prevent abuse

Rule inheritance and override:

• Global rules (no frontmatter or globs: *) apply to all files
• Path-specific rules apply only to matched files
• If rules conflict, higher-priority rule wins
• Specific rules can override global rules

Usage scenario examples:

Scenario 1: frontend-backend separated project

.claude/rules/
├── 00-general.md          # general standards (commit message, naming)
├── 10-backend.md          # backend standards (NestJS-specific)
├── 11-frontend.md         # frontend standards (React-specific)
└── 20-database.md         # database standards (Prisma-specific)

Scenario 2: microservice architecture

.claude/rules/
├── 00-global/             # global rules
│   ├── security.md
│   └── logging.md
├── 10-services/           # service-specific rules
│   ├── user-service.md
│   ├── order-service.md
│   └── payment-service.md
└── 20-shared/             # shared component rules
    ├── shared-lib.md
    └── common-utils.md

Migration recommendation:

If you already have a very large CLAUDE.md, migrate to Rules directory like this:

1. Create .claude/rules/
2. Split CLAUDE.md by topic
3. Add suitable frontmatter per rule file
4. Keep CLAUDE.md as project overview and move detailed standards out
5. Test and ensure rule loading works correctly