Claude Code Guide

Purpose

Fetch the latest Claude Code documentation from code.claude.com and help update your configuration files based on current best practices.

Usage

/claude-code-guide

Topics

Embedded Best Practices

Memory (CLAUDE.md)

File Locations & Precedence (highest to lowest):

1. Managed policy: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) - org-wide
2. Project memory: ./CLAUDE.md or ./.claude/CLAUDE.md - team-shared
3. Project rules: ./.claude/rules/*.md - modular topic-specific rules
4. User memory: ~/.claude/CLAUDE.md - personal across all projects
5. Project local: ./CLAUDE.local.md - personal project-specific (gitignored)

Best Practices:

• Be specific: "Use 2-space indentation" beats "Format code properly"
• Use structure: Format memories as bullet points under descriptive markdown headings
• Review periodically: Update as project evolves
• Use imports: @path/to/file syntax to include other files
• Path-specific rules: Use YAML frontmatter with paths field for conditional rules

Example CLAUDE.md:

# Project Standards

- Use TypeScript strict mode
- Follow ESLint airbnb config
- Write tests for all new functions

# Commands

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

# Architecture

- React components in src/components/
- API routes in src/api/
- Shared utilities in src/utils/

Modular Rules (.claude/rules/):

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All endpoints must include input validation
- Use standard error response format
- Include OpenAPI documentation comments

Skills

Location: .claude/skills/<skill-name>/SKILL.md

Frontmatter Fields:

Example Skill:

---
name: code-review
description: Reviews code for quality and best practices. Use after code changes.
allowed-tools: Read, Grep, Glob
---

When reviewing code:
1. Check for code clarity and readability
2. Look for potential bugs
3. Verify error handling
4. Check test coverage
5. Note security concerns

Provide feedback organized by priority:
- Critical (must fix)
- Warnings (should fix)
- Suggestions (consider)

Supporting Files: Skills can include additional files (templates, scripts, examples) referenced from SKILL.md.

String Substitutions:

• $ARGUMENTS - User-provided arguments
• ${CLAUDE_SESSION_ID} - Current session ID

Hooks

Configuration Location: settings.json under hooks key

Available Hook Events:

Hook Configuration Structure:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Exit Codes:

• 0: Success (stdout shown in verbose mode)
• 2: Blocking error (stderr fed back to Claude)
• Other: Non-blocking error

Environment Variables:

• CLAUDE_PROJECT_DIR: Project root path
• CLAUDE_ENV_FILE: (SessionStart only) File for persisting env vars

Agents (Subagents)

Location: .claude/agents/<agent-name>.md or ~/.claude/agents/

Built-in Agents:

• Explore: Fast, read-only, uses Haiku
• Plan: Research for plan mode, inherits model
• general-purpose: Full tools, complex tasks

Frontmatter Fields:

Example Agent:

---
name: code-reviewer
description: Expert code review. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards.

When invoked:
1. Run git diff to see changes
2. Focus on modified files
3. Review for quality, security, performance

Provide feedback by priority:
- Critical (must fix)
- Warnings (should fix)
- Suggestions (consider)

Settings

File Locations (precedence highest to lowest):

1. Managed: System-level managed-settings.json
2. CLI arguments: Session overrides
3. Local project: .claude/settings.local.json
4. Project: .claude/settings.json
5. User: ~/.claude/settings.json

Key Settings:

Permissions Example:

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test:*)"],
    "deny": ["Bash(curl:*)", "Read(./.env)"],
    "additionalDirectories": ["../docs/"]
  }
}

MCP Servers

Adding Servers:

# HTTP transport (recommended for remote)
claude mcp add --transport http <name> <url>

# SSE transport (deprecated)
claude mcp add --transport sse <name> <url>

# Stdio transport (local)
claude mcp add --transport stdio <name> -- <command> [args...]

Scopes:

• local (default): Current project, private
• project: Shared via .mcp.json
• user: All your projects

Example .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_URL}"]
    }
  }
}

Commands:

• claude mcp list - List servers
• claude mcp get <name> - Get details
• claude mcp remove <name> - Remove server
• /mcp - Check status (in Claude Code)

Plugins

Plugin Structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # Required manifest
├── skills/              # Skills with SKILL.md
├── agents/              # Agent definitions
├── hooks/
│   └── hooks.json       # Hook configs
└── .mcp.json            # MCP servers

plugin.json Manifest:

{
  "name": "my-plugin",
  "description": "Plugin description",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

Testing Plugins:

claude --plugin-dir ./my-plugin

Installing from Marketplace:

/plugin install <plugin-name>@<marketplace>

Workflow

Step 1: Fetch Fresh Documentation

For the requested topic, fetch from https://code.claude.com/docs/en/:

For memory:

• WebFetch https://code.claude.com/docs/en/memory
• WebFetch https://code.claude.com/docs/en/best-practices

For skills:

• WebFetch https://code.claude.com/docs/en/skills

For hooks:

• WebFetch https://code.claude.com/docs/en/hooks
• WebFetch https://code.claude.com/docs/en/hooks-guide

For agents:

• WebFetch https://code.claude.com/docs/en/sub-agents

For settings:

• WebFetch https://code.claude.com/docs/en/settings

For mcp:

• WebFetch https://code.claude.com/docs/en/mcp

For plugins:

• WebFetch https://code.claude.com/docs/en/plugins
• WebFetch https://code.claude.com/docs/en/plugin-marketplaces

For cli:

• WebFetch https://code.claude.com/docs/en/cli-reference

For overview:

• WebFetch https://code.claude.com/docs/en/features-overview

Step 2: Read Current Configuration

For memory:

• Read ~/.claude/CLAUDE.md
• Read ./CLAUDE.md
• Read ./CLAUDE.local.md
• Glob .claude/rules/*.md

For skills:

• Glob .claude/skills/*/SKILL.md
• Read each skill file

For hooks:

• Read ~/.claude/settings.json (hooks section)
• Read .claude/settings.json
• Read .claude/settings.local.json

For agents:

• Glob ~/.claude/agents/*.md
• Glob .claude/agents/*.md

For settings:

• Read ~/.claude/settings.json
• Read .claude/settings.json
• Read .claude/settings.local.json

For mcp:

• Read settings.json mcpServers section
• Read .mcp.json

For plugins:

• Read .claude/plugins/ directory

Step 3: Compare & Recommend

• Identify differences from documentation best practices
• Note deprecated patterns
• Suggest improvements
• Highlight missing recommended configurations

Step 4: Apply Updates

Ask user which recommendations to apply, then:

• Edit existing config files
• Create new config files if needed
• Validate changes

Notes

• Documentation is fetched fresh each time for up-to-date guidance
• No changes made without user approval
• Respects existing patterns while suggesting improvements