Claude Code の高性能エージェント構築入門

**

# Introduction

Most people's Claude Code** setup never gets past day one. They run the installer, log in, type a prompt, get something useful back, and never touch a config file again. Weeks later, sessions start losing track of earlier decisions, the same permission prompt shows up fifty times a day, and every long task ends the same way: a wall of context warnings and a conversation that has to be abandoned and restarted from scratch.

None of that is a limitation of the model. It's a limitation of the setup. Claude Code ships with sensible defaults, but sensible defaults and high performance are different bars, and the gap between them is almost entirely made up of a handful of files most beginners never open. This guide closes that gap. It walks through the actual configuration, permissions, hooks, and command habits that separate a fresh install from a setup that holds up under real, sustained agentic work, verified against Anthropic's current documentation rather than assumed from an older version of the tool.

# Installing Claude Code the Right Way

**

Claude Code installs as a standalone command-line interface (CLI), and the current recommended path** is the native installer rather than npm, though npm still works as a fallback:

# macOS, Linux, or WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Or, via npm, if you'd rather manage it with your existing Node toolchain
npm install -g @anthropic-ai/claude-code

Once installed, cd into an actual project directory before running claude for the first time. This matters more than it sounds like it should: Claude Code scopes its project memory and settings to the directory you launch it from, so starting it from your home folder or your desktop means it never picks up the right context for anything you're working on.

cd your-project-directory
claude

The first run walks you through authentication — either OAuth login with a Claude subscription (Pro, Max, or Team) or an application programming interface (API) key tied to a Console account. Beyond the terminal, Claude Code is also available through a VS Code extension, a JetBrains plugin, a desktop app, and a web-based version at claude.ai for sessions you want to pick up from a browser rather than a terminal. All of them read from the same underlying settings and project files, so nothing you set up in the terminal is wasted if you later switch to an integrated development environment (IDE) panel.

With that done, the install itself is the easy part. What actually determines whether Claude Code performs well from here is the set of three files most tutorials skip past.

# The Three Files That Actually Run the Show

**

Claude Code reads configuration from two places: your project's .claude/ directory (and a CLAUDE.md at the project root), and a global ~/.claude/ directory that applies across every project on your machine. Understanding what lives where is the single biggest lever on whether the tool performs well or drifts, according to Anthropic's own documentation on the .claude directory structure**.

• CLAUDE.md is project memory — instructions Claude reads at the start of every session in that repository: architecture notes, build and test commands, code style rules, and anything else that would otherwise need re-explaining every single time. Run /init in a fresh project, and Claude Code will scan the codebase and generate a starting CLAUDE.md for you, which you then refine with /memory. Keep it lean. Anthropic's guidance is to treat it as a living reference under roughly 2,500 tokens, and to push anything long or path-specific into .claude/rules/*.md files instead, which can be scoped to load only when Claude touches matching files.

• settings.json, living at .claude/settings.json for project-level config or ~/.claude/settings.json for personal defaults, is where permissions, hooks, environment variables, and model defaults actually live. This is the file most beginners never open, and it's directly responsible for two of the most common complaints about the tool: constant permission interruptions and Claude reaching for a more expensive model than a task actually needs.

• Auto memory is the newer, quieter layer: Claude can write and read its own working notes across a session without you managing a file directly, toggled with the autoMemoryEnabled setting or the CLAUDE_CODE_DISABLE_AUTO_MEMORY environment variable if you'd rather keep memory fully manual and auditable through CLAUDE.md alone.

The practical rule that ties these together, echoed across Anthropic's documentation and independent breakdowns of the config system alike, is this: stable rules belong in CLAUDE.md, because instructions buried only in conversation history get lost the moment a long session triggers automatic compaction. If a rule needs to survive past today's session, write it down.

# Setting Up Permissions and Hooks Before Needed

**

Claude Code runs in one of three permission modes, cycled with Shift+Tab**:

• Default, which asks before every potentially risky tool call.

• Auto-Accept Edits, which lets file edits through without prompting while still gating other tools.

• Plan Mode, which is read-only — no edits, no shell commands — until you approve a plan. Plan Mode is worth defaulting to for your first sessions in an unfamiliar codebase, since it forces Claude to propose before it acts.

Beyond the interactive modes, settings.json lets you write actual permission rules, so you're not manually approving the same safe command fifty times a session:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  }
}

What this does: anything matching allow runs without a prompt, anything matching deny is blocked outright regardless of what else matches, and anything left unlisted falls back to asking you directly. That deny-first ordering matters: a deny rule always wins even if a broader allow rule would otherwise cover it, which is what makes it safe to grant fairly broad read and test-running access without also opening the door to destructive commands.

Hooks go a step further than permission rules, since a rule can only allow or block a call, while a hook can actually run something in response to one. A PostToolUse hook that auto-formats every file Claude edits is one of the most commonly recommended starting points:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

What this does: every time Claude writes or edits a file, this hook fires afterward and runs Prettier against exactly the file that changed, using the path Claude Code passes in through the $CLAUDE_TOOL_INPUT_FILE_PATH environment variable. You stop manually reformatting after every edit, and your style rules apply consistently whether Claude wrote the file or you did.

A PreToolUse hook can go further and actually block a dangerous command before it runs, which is a stronger guarantee than a permission rule alone since it can inspect the exact command text rather than just matching a pattern:

#!/usr/bin/env python3
# .claude/hooks/block-dangerous-bash.py
import json, re, sys

DANGEROUS_PATTERNS = [
    r'\brm\s+.*-[a-z]*r[a-z]*f',
    r'sudo\s+rm',
    r'chmod\s+777',
    r'git\s+push\s+--force.*main',
]

input_data = json.load(sys.stdin)
if input_data.get('tool_name') == 'Bash':
    command = input_data.get('tool_input', {}).get('command', '')
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print("BLOCKED: matches a dangerous command pattern", file=sys.stderr)
            sys.exit(2)
sys.exit(0)

What this does: Claude Code pipes the tool call's details to this script as JSON on stdin before the command runs. If the bash tool is about to execute something matching a recursive force-delete, a sudo rm, a world-writable chmod, or a forced push to main, the script prints a reason and exits with code 2, which Claude Code's hook system treats as a hard block — stopping the command before it ever runs. Register it in settings.json under PreToolUse with a Bash matcher, and this becomes a permanent safety net rather than something you have to remember to check for manually.

# The Commands Worth Learning First

**

Claude Code ships with more than sixty built-in commands as of this writing, and trying to memorize all of them on day one is a waste of time. The table below covers the ones that actually change how a session performs, organized by what they're for, pulled directly from Claude Code's official command reference**.

Command

Category

What It Does

/init

Setup

Scans your codebase and generates a starting CLAUDE.md

/memory

Setup

Opens CLAUDE.md for editing directly

/clear

Context

Starts a fresh conversation while keeping project memory

/compact [focus]

Context

Summarizes conversation history to free up context; accepts instructions on what to preserve

/context

Context

Shows current context window usage

/plan

Planning

Toggles Plan Mode; Claude proposes before it acts, nothing executes until you approve

/diff

Review

Opens an interactive diff of every change made this session

/code-review [--fix]

Review

Checks the current diff for correctness bugs; --fix applies the findings

/security-review

Review

Checks the current diff specifically for security vulnerabilities

/review

Review

Gives a read-only review of a GitHub pull request

/resume [session]

Navigation

Resumes a previous conversation by name or ID

/branch [name] (alias /fork)

Navigation

Forks the current conversation into a new session

/rewind

Navigation

Rolls code and/or conversation back to an earlier checkpoint

/model

Cost & Performance

Switches the active model mid-session without losing context

/effort

Cost & Performance

Sets reasoning depth (low through max) to match task complexity

/cost

Cost & Performance

Shows token usage and spend for API-key users

/agents

Delegation

Manages subagents — view, create, or invoke specialized agents

/permissions

Configuration

Manages permission rules interactively

/hooks

Configuration

Manages hooks interactively

/doctor

Diagnostics

Checks your install for configuration problems

A useful habit for a beginner: build fluency with /compact, /plan, and /diff first, since those three alone solve the majority of early frustration — sessions that degrade from context bloat, edits that go further than intended, and not knowing exactly what changed. Everything else in the table earns its place once those three are muscle memory.

# Building Your Own /truth Command

**

Here's a fair note before this section: /truth isn't a command that ships with Claude Code. It doesn't appear in the official command reference, and it's not something I could confirm across any current documentation or community guide while researching this article. What's genuinely useful, though — and likely what prompted the idea — is a command that makes Claude check its own recent claims against the actual codebase before you trust them and move on. That's a real gap worth closing, and it's a perfect example of Claude Code's custom command system, so here's how to build it yourself.

Custom commands are defined as skills — a folder with a SKILL.md file. Create one at .claude/skills/truth/SKILL.md:

---
description: Verify Claude's most recent claims and edits against the actual codebase
allowed-tools: Read, Grep, Glob, Bash(git diff:*)
---

Re-examine everything you just told me in this conversation against what
actually exists in the codebase right now. Specifically:

1. For every file you claim to have edited, read it again and confirm the
   change is actually present and matches what you described.
2. For every claim about existing code (a function's behavior, a config
   value, an import, a dependency version), verify it against the real
   file rather than your memory of reading it earlier in the session.
3. Run `git diff` and compare the actual diff against what you described
   changing.
4. Report back plainly: which claims checked out, which didn't, and
   exactly what the discrepancy was for anything that failed. Do not
   soften or hedge a discrepancy you find, state it directly.

What this does**: the YAML frontmatter restricts this command to read-only tools plus a scoped git diff, so running /truth can never itself modify anything — which matters since a verification step that can also make changes isn't a trustworthy verification step. The instruction body is deliberately specific about what "verify" means: re-reading actual files rather than trusting the model's own prior description of them, and explicitly telling Claude not to soften a discrepancy if it finds one, since a self-check that's incentivized to sound reassuring isn't actually checking anything.

Once the file is saved, /truth becomes available in any session in that project — the same way any other custom command works — and it shows up if you type / and start filtering. Run it after Claude finishes a multi-step task, especially one where it touched several files or made claims about existing code it hadn't re-read recently, and before you commit anything based on those claims. This is the same grounding principle behind self-correcting agents generally: a check is only worth something if it's forced to look at something outside its own prior output, and pointing /truth at the actual files and the actual git diff is what makes it more than a model agreeing with itself.

# Using Subagents and Parallel Work for Real Speed Gains

**

Everything so far makes a single Claude Code session more reliable. Subagents are what make it faster on the kind of work that doesn't need to happen sequentially. A subagent is a specialized instance with its own context window, its own system prompt, and its own tool permissions, and Anthropic's subagent documentation** describes them as running isolated from the main session, returning a summary rather than dragging every intermediate file read and tool call back into your primary conversation.

That isolation is the actual performance win. Large codebase exploration, dependency audits, and test-writing are all verbose work that would otherwise eat heavily into your main session's context budget. Delegate them to a subagent instead, and only the finished result comes back.

# Inside a session, ask Claude to create a subagent
/agents

Running /agents opens an interactive menu for creating, viewing, and managing subagents, or you can define one directly as a file at .claude/agents/<name>.md with its own frontmatter for model selection and tool access, similar in structure to the skill file above. A common starting pattern is a narrowly scoped code-reviewer or test-runner subagent with read-only access, so it can inspect and report without ever being able to make the change it's reviewing — the same separation-of-concerns idea covered in the hooks section above, just applied to delegation instead of permissions.

**

For genuinely parallel work — editing several unrelated parts of a codebase at once without one change blocking another — /batch and --worktree sessions let multiple Claude Code instances work in isolated git worktrees simultaneously, each with its own working directory so they can't step on each other's changes. That's a more advanced pattern than a beginner setup strictly needs on day one, but it's worth knowing it exists once single-session work stops being the bottleneck.

# A Starter CLAUDE.md and settings.json You Can Actually Use

Pulling everything above together, here's a reasonable starting point for a new project. Save this as CLAUDE.md at your project root:

# Project Context

## Stack
- [Your language/framework here, e.g. Node.js, TypeScript, React]

## Commands
- Test: `npm test`
- Lint: `npm run lint`
- Dev server: `npm run dev`

## Conventions
- [Your code style rules, naming conventions, folder structure]

## Before finishing any task
- Run the test suite and confirm it passes
- Run `/truth` if the task involved editing more than one file

And a starting .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)", "Read(**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Bash(rm -rf /*)", "Bash(sudo:*)", "Read(.env)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python3 .claude/hooks/block-dangerous-bash.py" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\"" }]
      }
    ]
  }
}

That's the entire foundation from this article in two files: sensible permissions that don't interrupt safe, repeated commands, a hard block on the genuinely dangerous ones, automatic formatting on every edit, and a project memory file that points Claude at your actual test and lint commands instead of guessing at them. Commit both to your repository (leaving anything containing secrets out, and using .claude/settings.local.json for personal overrides that shouldn't be shared), and every teammate who clones the project starts from the same high-performance baseline instead of rebuilding it from scratch.

# Wrapping Up

The difference between a beginner's Claude Code setup and a high-performance one isn't a secret feature or a hidden command; it's whether you spent twenty minutes on CLAUDE.md, settings.json, and one or two hooks before diving into real work, or whether you're still running on whatever the installer gave you by default three weeks in. Everything in this guide — the memory files, the permission rules, the hooks, the commands worth learning first — exists to remove friction you'd otherwise hit repeatedly and never fix. Set it up once, commit it to the repository, and every session after that starts from a stronger baseline than the one before it.

Shittu Olumide** is a software engineer and technical writer passionate about leveraging cutting-edge technologies to craft compelling narratives, with a keen eye for detail and a knack for simplifying complex concepts. You can also find Shittu on Twitter.