Settings & Configuration

To get the most out of Claude Code, you can configure its behavior, constraints, and automated workflows through a dedicated configuration directory. By defining rules, skills, and hooks, you transform Claude from a general-purpose assistant into a specialized teammate that understands your specific codebase patterns.

The .claude Directory

All project-specific configuration resides in the .claude/ directory at your root. This ensures that your team shares the same environment settings and quality standards.

| Component | Purpose | | :--- | :--- | | settings.json | Project-level behavior toggles and automation hooks. | | settings.md | High-level rules and constraints (e.g., "Do not edit main branch"). | | skills/ | Markdown-based domain knowledge for specific libraries or patterns. | | agents/ | Specialized prompts for recurring tasks like code reviews. | | hooks/ | Executable scripts triggered by Claude’s actions. |

Core Configuration (settings.json)

The settings.json file is the primary interface for managing how Claude interacts with your code and which automation gates it must pass.

{
  "hooks": {
    "pre-commit": "npm run lint",
    "post-edit": "node .claude/hooks/skill-eval.js",
    "test": "npm test"
  },
  "automation": {
    "autoFormat": true,
    "runTestsOnChanges": true,
    "blockMainBranchEdits": true
  }
}

Automation Toggles

• autoFormat: Automatically runs your configured formatter (e.g., Prettier) after Claude generates or modifies code.
• runTestsOnChanges: Triggers relevant test suites when Claude modifies files associated with those tests.
• blockMainBranchEdits: A safety guard that prevents Claude from making direct changes to protected branches, forcing it to work on feature branches instead.

Intelligent Skill Activation

Claude Code uses a "Skill Evaluation Engine" to determine which domain-specific knowledge to load based on your intent. This prevents "context window bloat" by only providing Claude with the information it needs for the task at hand.

Skill Evaluation Hook

The skill-eval.js script (located in .claude/hooks/) analyzes your prompt and the files you are touching to suggest or activate relevant skills.

How it works:

1. Keyword Matching: Detects specific technologies (e.g., "GraphQL", "TypeScript").
2. Path Detection: Identifies if you are working in specific directories (e.g., src/components/ triggers the UI skill).
3. Intent Detection: Scans for verbs like "review", "test", or "fix" to suggest the appropriate agent or skill.

To customize these triggers, modify .claude/hooks/skill-rules.json:

{
  "skills": {
    "ui-components": {
      "triggers": {
        "keywords": ["button", "theme", "css", "component"],
        "paths": ["src/components/**"]
      },
      "priority": 10
    }
  }
}

External Integrations (MCP)

Claude Code integrates with external platforms (like JIRA, Linear, or Slack) via the Model Context Protocol (MCP). These are configured in .mcp.json.

Connecting these servers allows Claude to perform cross-platform actions:

• Reading tickets: Automatically pull acceptance criteria from a JIRA ID.
• Status updates: Move a ticket to "In Review" once a PR is generated.
• New tasks: Create "Todo" items if Claude identifies tech debt during a refactor.

Example .mcp.json structure:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/mcp-server"],
      "env": {
        "LINEAR_API_KEY": "your_key_here"
      }
    }
  }
}

Custom Commands

You can extend Claude's CLI with custom slash commands by adding Markdown files to .claude/commands/.

For example, a /ticket command defines the workflow for:

1. Fetching requirements from your ticket system.
2. Creating a feature branch.
3. Implementing the changes.
4. Linking the final PR back to the original ticket.

This turns complex, multi-step engineering workflows into a single, repeatable command.