Beyond the Basics with Claude Code

1. CLAUDE.md: The Discipline of What Not to Write

CLAUDE.md is the file Claude reads at the start of every session. It is your opportunity to give Claude persistent context it cannot infer from code alone — build commands, architectural quirks, naming conventions, “don’t touch this” warnings. But the most common mistake is writing too much, not too little.

Every line in CLAUDE.md is a recurring token cost. Worse, a bloated file causes Claude to ignore important rules because they get lost in the noise. The goal is not a comprehensive project wiki; it is a short, precise prompt that prevents mistakes.

The filter to apply to every line: “Would removing this cause Claude to make a mistake?” If the answer is no — because Claude can infer it from the code, because it describes something obvious, or because it hasn’t actually mattered in practice — cut it. A clean CLAUDE.md of twenty lines outperforms a sprawling one of two hundred.

What belongs in CLAUDE.md

The content that earns its place falls into a few clear categories:

Auto-memory and the # shortcut

You don’t have to write CLAUDE.md manually. Run /init in any project and Claude generates a starter file by exploring the codebase — it picks up your build system, test runner, and code patterns. Use it as a foundation, then prune ruthlessly.

During any session, start a message with # and Claude appends that note to CLAUDE.md automatically. Type # always use pnpm, not npm once and it sticks. Claude also builds auto-memory as it works, saving observations like build commands and debugging insights without you writing anything.

Finally, CLAUDE.md can import other files using @path/to/file syntax — useful for referencing a shared README.md or linking to architecture docs without duplicating them.

2. MCP: Giving Claude Tools Beyond the Filesystem

By default, Claude Code can read and write files and run shell commands. That covers most coding work, but not all of it. To review a Figma design, query a production database, update a Jira ticket, or fetch error context from Sentry, Claude needs tools that don’t exist in the filesystem.

Model Context Protocol (MCP) is the standard that bridges this gap. An MCP server exposes a set of tools — function signatures that Claude can call during the agentic loop, just like it calls shell commands. When you connect an MCP server, Claude gains access to everything that server exposes: database queries, API calls, browser automation, note-taking apps, whatever the server implements.

How MCP fits into the agentic loop

MCP doesn’t change the loop itself (gather context → act → verify → repeat). It expands what Claude can do in the “act” step. Instead of being limited to Read, Edit, and Bash, Claude can call github__create_pull_request, postgres__query, or sentry__get_latest_errors as naturally as any other tool.

Connecting and configuring MCP servers

Add a server with a single command:

claude mcp add github -- npx @modelcontextprotocol/server-github

Claude Code stores the configuration and starts the server when you launch a session. Team-shared MCP servers go in .mcp.json at the project root (committed to git). Personal servers go in ~/.claude.json.

// .mcp.json — checked into the repo, shared with the team
{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

The context cost of MCP

MCP server tool schemas load into the context window at session start — before you type your first message. A server with forty tools loads forty tool schemas upfront. If you are doing a pure Python refactoring task and have a browser-automation MCP server connected, you are paying that cost for nothing.

The rule: only connect servers you need for the current work. Disconnect servers you are not using with claude mcp remove <server-name>. Skills (covered next) are a better fit for reusable knowledge that doesn’t need to be available every session.

3. Skills: Packaging Team Knowledge

Every team accumulates repeatable workflows. The way to create a pull request, the release checklist, the process for fixing a GitHub issue, the conventions for writing API endpoints. These live in wikis, Notion docs, or engineers’ heads — and Claude has no access to any of them unless you paste them in every time.

Skills are the answer. A skill is a markdown file in .claude/skills/<name>/SKILL.md that creates a slash command (e.g., /fix-issue, /deploy-staging, /review-pr). Claude loads skill descriptions at session start — just enough to know what’s available, roughly 100 tokens per skill — and only loads the full content when you or Claude invoke the skill. This is the key advantage over CLAUDE.md: procedures that live in CLAUDE.md cost context on every message; skills cost almost nothing until they’re needed.

Anatomy of a skill

---
name: fix-issue
description: Fix a GitHub issue end to end
disable-model-invocation: true
allowed-tools: Bash(gh *) Bash(git *) Edit Read Grep
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Run `gh issue view $ARGUMENTS` to get the issue details
2. Search the codebase for relevant files
3. Implement the fix, respecting the patterns in CLAUDE.md
4. Write and run tests to verify the fix
5. Ensure code passes linting and type checking
6. Create a descriptive commit message
7. Push and open a PR with `gh pr create`

Run /fix-issue 1234 and Claude receives the rendered prompt with $ARGUMENTS replaced by 1234. The whole workflow runs without you guiding each step.

Two types of skills

Reference skills add domain knowledge that Claude applies automatically. A skill called api-conventions with a description like “REST API design conventions for our services” makes Claude aware of your team’s patterns whenever you’re working on an endpoint — no invocation needed.

Task skills are step-by-step workflows you trigger intentionally. Add disable-model-invocation: true to prevent Claude from running them automatically — you don’t want Claude deciding to deploy because the code looks ready.

---
name: deploy-staging
description: Deploy the current branch to the staging environment
disable-model-invocation: true
---

Deploy $ARGUMENTS to staging:
1. Run `npm test` and abort if any tests fail
2. Run `npm run build`
3. Run `./scripts/deploy.sh staging`
4. Verify the deployment at https://staging.example.com/health

Where skills live

Commit .claude/skills/ to your repo and every team member gets the same workflows automatically. No documentation to maintain separately — the skill is the documentation.

Dynamic context injection

Skills can embed live data using the !`command` syntax. Commands run before Claude sees the skill, and their output is inlined:

---
name: summarize-changes
description: Summarize uncommitted changes and flag risks
---

## Current diff
!`git diff HEAD`

## Task
Summarize the changes above in 2-3 bullet points.
Flag any missing error handling, hardcoded values, or untested paths.

When you run /summarize-changes, Claude receives the actual diff, not a placeholder — no file reads needed.

4. Auto Mode: Removing Permission Prompts Safely

By default, Claude Code asks permission before running commands or editing files. That is safe, but after you have approved the same npm test command for the tenth time, you are no longer reviewing — you are clicking through. The accumulated interruptions break flow and defeat the purpose of an autonomous agent.

Auto mode solves this. Instead of asking you, Claude Code routes each action through a separate classifier model that evaluates whether the action is safe to proceed without human review. Routine operations pass silently. Actions that look risky — scope escalation, operations outside your environment, hostile patterns in content — are blocked and surfaced for your decision.

What auto mode approves and blocks

The classifier makes decisions in four tiers:

By default, the classifier trusts your working directory and the current repo’s configured remotes. Pushing to your company’s GitHub org or writing to a cloud bucket is blocked until you tell the classifier about your infrastructure.

Enabling auto mode

# Start a session in auto mode
claude --permission-mode auto

# Toggle during a session
Shift+Tab  # cycles through permission modes

For unattended non-interactive runs:

claude --permission-mode auto -p "fix all lint errors across the codebase"

Configuring auto mode for your team

The most important configuration is telling the classifier about your infrastructure. Out of the box, pushing to your company’s GitHub org looks like scope escalation. Add it to the autoMode.environment section in ~/.claude/settings.json (personal) or your managed settings (organization-wide):

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Organization: Acme Corp. Primary use: software development",
      "Source control: github.com/acme-corp and all repos under it",
      "Trusted cloud buckets: s3://acme-build-artifacts",
      "Trusted internal domains: *.corp.acme.com, api.internal.acme.com",
      "Key internal services: Jenkins at ci.acme.com"
    ]
  }
}

The "$defaults" string keeps the built-in rules intact while adding your own. Never omit it unless you intend to replace the entire rule list — dropping it silently discards all built-in protections including the data exfiltration rules.

Use the CLI subcommands to inspect your configuration:

claude auto-mode defaults  # print built-in rules
claude auto-mode config    # print effective rules with your settings applied
claude auto-mode critique  # get AI feedback on your custom rules

The CLAUDE.md connection

The classifier reads the same CLAUDE.md that Claude reads. An instruction like "never force-push to main" in your project’s CLAUDE.md steers both Claude’s behavior and the classifier’s decisions simultaneously. One source of truth for both human and machine.

5. Putting It Together: The Layered Configuration Model

These four systems — CLAUDE.md, MCP, skills, and auto mode — are independent but designed to compose. Understanding the configuration hierarchy they share makes the whole system predictable.

Settings in Claude Code resolve in a strict precedence order (top wins):

1. CLI flags (--permission-mode, --settings)
2. Enterprise managed settings (cannot be bypassed by users)
3. .claude/settings.local.json (personal, gitignored)
4. .claude/settings.json (team, version-controlled)
5. ~/.claude/settings.json (user defaults)

This means your team can enforce security policies via managed settings, individual developers can override team defaults for their own machine, and the whole configuration is auditable and version-controlled.

A minimal but complete .claude/settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run build)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(gh pr create *)"
    ]
  },
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.com/your-org"
    ]
  }
}

Pair this with:

• A crisp CLAUDE.md covering commands, style, and gotchas
• An MCP server for GitHub (so Claude can read issues and create PRs)
• A /fix-issue skill that orchestrates the full workflow
• Auto mode enabled for unattended runs

Together, these let you hand Claude a GitHub issue number and walk away. Claude reads the issue, explores the codebase, writes a fix, runs tests, and opens a pull request — all without a single permission prompt, and with the classifier standing guard over anything irreversible.

git add CLAUDE.md
git commit -m "chore: tighten CLAUDE.md to high-signal rules only"

claude mcp add github -- npx @modelcontextprotocol/server-github

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

mkdir -p .claude/skills/fix-issue

---
name: fix-issue
description: Fix a GitHub issue end to end — reads the issue, implements a fix, runs tests, opens a PR
disable-model-invocation: true
allowed-tools: Bash(gh *) Bash(git *) Bash(npm run test:*) Bash(npm run build) Read Edit Grep Glob
---

Analyze and fix GitHub issue $ARGUMENTS.

1. Run `gh issue view $ARGUMENTS` to read the issue details
2. Search the codebase for relevant files using Grep and Glob
3. Implement the fix, following the conventions in CLAUDE.md
4. Run `npm run test` and fix any failures before proceeding
5. Run `npm run build` to confirm the build passes
6. Commit with a descriptive message referencing the issue number
7. Run `gh pr create --title "Fix #$ARGUMENTS: <summary>" --body "Closes #$ARGUMENTS"`

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Organization: <your-org-name>. Primary use: software development",
      "Source control: github.com/<your-github-org> and all repos under it"
    ]
  }
}

claude auto-mode config

claude --permission-mode auto

/fix-issue 42

git add .claude/ .mcp.json
git commit -m "chore: add fix-issue skill and team MCP + auto mode config"