【Claude Code】【Note】: Fundamentals Guide

What is Claude Code? #

Claude Code is an AI-powered coding agent that runs in your terminal. Unlike a chat interface that generates code snippets, it is an agent that plans work, reads your codebase, edits files, runs commands, and verifies results — all autonomously.

Think of it as a developer working alongside you in your terminal, with access to the same files and tools you use.

Installation #

macOS / Linux / WSL (Recommended) #

curl -fsSL https://claude.ai/install.sh | bash

Start in Your Project #

cd your-project
claude

You will be prompted to log in on first use.

How the Agent Loop Works #

You type a task
      ↓
Claude reads CLAUDE.md + your codebase
      ↓
Plans the approach
      ↓
Executes: reads files, edits code, runs commands
      ↓
Verifies the result
      ↓
Reports back to you

Claude Code reads context at the start of every session, acts on your files in real time, and asks for confirmation before risky actions depending on your permission mode.

Directory Structure — Where Things Live #

There are two .claude/ directories in play:

~/.claude/                    ← Global (applies to ALL projects)
├── CLAUDE.md                 ← Your personal instructions
├── settings.json             ← Global settings
├── settings.local.json       ← Local overrides (not synced)
└── commands/                 ← Your personal slash commands

your-project/.claude/         ← Project-level (committed to git)
├── CLAUDE.md                 ← Project instructions
├── settings.json             ← Team-shared settings
├── settings.local.json       ← Your local overrides (gitignored)
└── agents/                   ← Custom subagent definitions

your-project/
└── CLAUDE.md                 ← Main project instructions (most common)

Priority Order #

Project settings.json  →  overrides  →  Global settings.json

Project-level always wins over global. Local always wins over shared.

What to Commit to Git #

CLAUDE.md — The Most Important File #

CLAUDE.md is read by Claude Code at the start of every session. It gives Claude persistent context about your project so you never have to re-explain conventions.

What to Put In It #

# Project Name

## Overview
What this project does and its tech stack.

## Project Structure
- src/ — source code
- content/ — markdown files
- public/ — generated output (never edit)

## Key Commands
- Build: hugo --minify
- Preview: hugo server -D
- Deploy: ./deploy.sh

## Rules
- Never edit files inside themes/
- Always run build before deploying
- Use front matter template for new posts

Best Practices #

• Keep it under 300 lines — Claude wraps it with a reminder it can ignore irrelevant content. The more noise, the more likely important rules get skipped.
• Every line must be universally applicable — if a rule only matters for one feature, it does not belong here.
• Use @filename imports for large reference docs instead of pasting content directly.

Multiple CLAUDE.md Files #

You can have CLAUDE.md at multiple levels — all are merged:

~/.claude/CLAUDE.md              ← Personal rules (all projects)
your-project/CLAUDE.md           ← Project rules (main)
your-project/.claude/CLAUDE.md   ← Project rules (alternate)

Global loads first, then project-level on top.

Session Management #

Start a New Session #

cd your-project
claude

Continue the Most Recent Session #

claude -c

Resume a Specific Past Session #

claude --resume

Useful for picking up exactly where you left off without re-explaining context. Session history is stored in ~/.claude/projects/.

One-Shot Mode (No Interaction) #

claude -p "summarize what this project does"

Use -p (print mode) for scripting, CI pipelines, or quick one-off tasks. Claude runs the task and exits.

Pipe Input Into Claude #

cat error.log | claude -p "what is causing this error?"
git diff main | claude -p "review these changes for issues"

Context Management Inside a Session #

Check Context Usage #

/cost

Shows how much of the context window you have used. A fresh session in a large project can cost 10-20% of context just from reading your codebase.

Compress Context — Keep Working #

/compact

Compresses conversation history while preserving key information. Use when context usage exceeds 80%. You can specify what to keep:

/compact retain the error handling patterns we discussed

Clear and Start Fresh — Switch Tasks #

/clear

Wipes the conversation entirely. Use this when switching to a completely different task.

Rule of thumb:

• Context over 80% → /compact (keep working, stay in session)
• Switching tasks entirely → /clear (fresh start)

Guardrails — Controlling What Claude Can Do #

Permission Modes #

Claude Code has three permission modes:

Switch between them with Shift+Tab during a session.

Setting Permissions in settings.json #

Define allowed and denied actions in .claude/settings.json:

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(hugo:*)",
      "Bash(aws s3 sync:*)",
      "Write(content/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Write(themes/**)"
    ]
  }
}

• allow — Claude can do these without asking
• deny — Claude is blocked from doing these entirely
• Everything else — Claude asks first

Example Guardrails for This Hugo Project #

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read(**)",
      "Write(content/**)",
      "Write(config/**)",
      "Bash(hugo:*)",
      "Bash(aws s3 sync:*)"
    ],
    "deny": [
      "Write(themes/**)",
      "Write(public/**)",
      "Bash(rm -rf:*)"
    ]
  }
}

Claude can freely read everything, write content and config, run Hugo and AWS commands — but cannot touch the theme folder, generated output, or run destructive shell commands.

Plan Mode — Review Before Executing #

Plan mode is the safest way to work on risky tasks. Claude shows you exactly what it plans to do before taking any action.

Enable Plan Mode #

Press Shift+Tab twice (cycles: normal → auto-accept → plan mode).

Or start a session directly in plan mode:

claude --plan

When to Use Plan Mode #

• Before restructuring files or directories
• Before modifying config files
• Before any deployment-related tasks
• When you are unsure what Claude will do

Creating and Using Agents (Subagents) #

What is a Subagent? #

A subagent is a specialized Claude instance that handles a specific task in its own context window. The main session delegates work to it and gets only a summary back — keeping your main session focused and clean.

Main Session (your conversation)
      ↓ delegates
  Subagent (own context, own tools, own permissions)
      ↓ returns summary only
Main Session continues

When to Use a Subagent #

Create a Subagent #

Create a Markdown file in .claude/agents/:

File: .claude/agents/hugo-reviewer.md

---
name: hugo-reviewer
description: Reviews Hugo content files for SEO, front matter completeness, and formatting issues. Use when asked to review or audit content files.
tools: Read, Grep, Glob
model: sonnet
---

You are a Hugo content reviewer. When invoked:
1. Read all markdown files in content/
2. Check front matter for required fields (title, date, description, tags)
3. Flag missing fields or SEO issues
4. Return a concise summary of issues found

Never edit files. Read only.

Key Fields in the Agent Definition #

Writing a Good Description #

Write the description as a triage rule:

Use this agent when [condition]. It returns [output].

Example:

Use when asked to audit or review content files.
Returns a list of issues found per file.

Invoke a Subagent #

Claude Code delegates automatically when your request matches the description. Or invoke explicitly:

Use the hugo-reviewer agent to audit all my content files

Global vs Project Agents #

Frequently Used Commands #

CLI Flags #

Slash Commands Inside a Session #

Keyboard Shortcuts #

Quick Setup Checklist for a New Project #

1. cd your-project
2. claude
3. /init                        ← generates CLAUDE.md
4. Edit CLAUDE.md               ← add your rules and context
5. Create .claude/settings.json ← set permissions and guardrails
6. Create .claude/agents/*.md   ← (optional) custom agents
7. Commit to git:
     CLAUDE.md
     .claude/settings.json
     .claude/agents/
   Add to .gitignore:
     .claude/settings.local.json

How It Was Used in This Project #

In building this Hugo site, Claude Code was used as a site copilot across multiple sessions:

• Read CLAUDE.md at session start to understand project structure and rules
• Created and edited content files in content/
• Modified Hugo config files (params.toml, languages.en.toml, menus.en.toml)
• Diagnosed and fixed Congo theme configuration errors
• Wrote the deploy.sh script with safety checks
• Resumed sessions across days with claude -c

The key to it working well was a well-written CLAUDE.md that clearly defined which files to never touch (themes/, public/), which commands to use, and the overall content structure — so Claude had the right context from the first message of every session.

References #

• Claude Code Official Docs
• Directory Structure Reference
• Subagents Guide
• Memory and CLAUDE.md
• Settings and Permissions