Claude Code: Practical Tutorial & Power-User Guide

This guide explains how Claude Code works as a coding assistant, how it differs from a plain LLM, and how to extend it using tools, MCPs, GitHub hooks, and workflows.

1. Claude Code vs a Plain LLM

Before diving into configuration, it’s important to understand what makes Claude Code different.

1.1 Coding Assistant vs LLM

A coding assistant is not just a language model that generates text.

Claude Code: - Understands how to use tools - Knows when to invoke them - Can sequence multiple steps to accomplish a task

A plain LLM, by contrast: - May generate correct-looking code - Does not reliably decide which tools to use - Struggles with multi-step or operational workflows

1.2 Tool Usage Quality Matters

Not all LLMs use tools with the same finesse.

Claude Code is particularly strong at: - Choosing the right tool - Using tools at the right time - Recovering gracefully when tool calls fail

This makes it well suited for: - Debugging - Refactoring - CI / PR workflows - Repo-wide reasoning

1.3 Extensibility via MCPs and Hooks

Claude Code can be extended using: - Custom MCP servers - GitHub hooks - Custom commands

Examples include: - PR reviews - Issue triage - Security scans - Repo-specific workflows

This turns Claude Code into a programmable teammate, not just a chatbot.

2. Understanding claude.md Files

Claude uses claude.md files to persist preferences and rules.

2.1 Project-Level Configuration (Shared)

claude.md

• Lives in the project root
• Committed to Git
• Shared across the team
• Best for:
• Coding standards
• Architectural constraints
• Repo-wide conventions

2.2 Personal Project Overrides (Not Shared)

claude.local.md

• Local to your machine
• Not committed
• Used for personal preferences such as:
• Verbosity
• Formatting style
• Personal shortcuts

2.3 Machine-Level Preferences

~/.claude/claude.md

• Applies to all projects on your machine
• Ideal for global defaults and habits

3. Modifying Claude Behavior Inline

You can update Claude’s behavior while working.

How it works

• Start a message with #
• Claude automatically updates the relevant claude.md

Example

# Reduce the amount of comments in generated code

This change persists, so you don’t need to repeat it later.

4. Guiding Claude to Files Explicitly

You can explicitly point Claude to files using @file.

Example

@file src/api/auth.ts

This works: - In chat messages - Inside claude.md

It ensures Claude reads real code instead of guessing.

5. Thinking Modes: Breadth vs Depth

Claude supports multiple reasoning modes.

Plan Mode

Use Plan Mode when: - The problem is broad - You want an outline or strategy - You’re exploring trade-offs

Think Modes

• think → shallow reasoning
• think more → deeper analysis
• ultrathink → maximum depth

Use deeper modes for: - Complex debugging - System design - Edge-case reasoning

6. Claude as a Git Power Tool

Claude Code is an excellent Git assistant.

It can: - Review pull requests - Address GitHub issues - Explain diffs - Suggest refactors

You can also provide runtime context:

Server runs on localhost:3000  
Logs are stored in ./logs/app.log

This improves debugging accuracy.

7. Controlling Context Explicitly

Context control is critical for long sessions.

Useful Commands

• ESC + ESC
  Go back while preserving task context (useful if debugging gets stuck)

• /compact
  Compress learned context and move to a related task

• /clear
  Start a completely new task

8. Custom Commands

You can define reusable commands for repeatable workflows.

Examples: - Running a security scanner - Enforcing a specific code-review process

After defining them and restarting Claude: - Commands become available via / - Commands can accept arguments

9. MCP Servers (Model Context Protocol)

MCPs allow Claude to interact with external systems.

Adding an MCP

claude mcp add playwright

Handling Permissions

By default, MCPs may request permission on each run.

To allow permanently:

// .claude/settings.json
{
  "allow": ["mcp__playwright"]
}

⚠️ Note the double underscore (mcp__<name>).

10. GitHub Actions Integration

Claude can: - Review pull requests - Address issues - Participate in CI workflows

You can define repo-specific context such as: - Server locations - Log paths - Test commands

This makes Claude CI-aware.

11. Hooks: Pre- and Post-Tool Automation

Hooks run automatically before or after tool usage.

Simple Hooks

• Block reading .env files using a READ | GREP matcher

Advanced Hooks

• Detect duplicated code (PostToolUse)
• Run vulnerability scanners
• Enforce architectural constraints

Hooks can be lightweight or deeply sophisticated.

Final Mental Model

Think of Claude Code as:

An LLM + tools + memory + workflows

Configured well, it becomes: - A coding assistant - A Git reviewer - A CI helper - A programmable teammate