Part 1 — Foundations

1.1 The Three Levels of Working with AI

Most people are stuck at Level 1 or 2. This guide takes you to Level 3.

Level 1 — The Chat

Level 2 — The Configured Assistant

Level 3 — The Agentic System

1.2 What Are Agentic Flows?

Definition: A structured AI system where specialized agents — each with bounded responsibilities and defined tools — are coordinated by an orchestrator to produce a reliable, repeatable output from a given input.

Three things make a flow "agentic" rather than just a long system prompt:

1. Specialized agents — each knows exactly what it does and what it doesn't. A Fact-Checker doesn't style-edit. A Style Reviewer doesn't check facts. Constraint is a feature.
2. An orchestrator — receives the high-level goal, breaks it into tasks, routes to the right agent, handles exceptions, assembles output. Think: project manager, not doer.
3. Reliable, repeatable output — runs the same way every time. If results vary wildly between runs, the flow is broken.

The Mental Shift

1.3 Why Claude Code?

Claude Code is a platform where you define AI systems using files, and Claude executes them. The name says "code" — the reality is much broader. It works equally well for:

• Content pipelines (research → draft → edit → publish)
• Operations (data extraction → classification → reporting)
• Research (gather → synthesize → summarize)
• Customer support (triage → draft response → escalate)
• Business intelligence (monitor → analyze → report)

Your System Lives in Files

your-project/
├── CLAUDE.md                    ← system constitution (always loaded)
└── .claude/
    ├── agents/
    │   ├── researcher.md        ← subagent: research specialist
    │   ├── writer.md            ← subagent: content writer
    │   └── editor.md            ← subagent: review & editing
    ├── skills/
    │   └── weekly-report/
    │       └── SKILL.md         ← reusable workflow
    └── settings.json            ← hooks & permissions

2.1 What You Need

2.2 Opening the Code Tab

Claude Desktop is the primary interface — no terminal required.

1. Open Claude Desktop → click the Code tab
2. Click Select folder → choose your project folder
3. Pick a model — Sonnet 4.6 for most tasks
4. Start prompting in natural language

2.3 Your First Session

Start with a read-only prompt so Claude can explore without changing anything:

Analyze this project folder and tell me what it contains.

Every modification goes through the same approval loop:

2.4 How Your Files Connect

Claude Code works entirely with local files — nothing is uploaded to the cloud. When you select a folder, Claude automatically discovers CLAUDE.md and everything inside .claude/.

your-project/
├── CLAUDE.md                  ← always loaded at session start
├── .claude/
│   ├── agents/                ← subagent definitions
│   ├── skills/                ← reusable workflows
│   └── settings.json          ← hooks & permissions
└── your-other-files/

2.5 The CLI Alternative

# Install
npm install -g @anthropic-ai/claude-code

# Run inside your project folder
cd your-project && claude

2.6 Authentication

3.1 The Conversation Loop

Claude Code is not a chatbot that happens to touch files. It's a read-modify-execute loop with you as the approver at every step.

3.2 Essential Commands

3.3 Plan Mode — Think Before You Build

What it is: Claude analyzes your request, produces a plan, and waits for your approval before touching any file. Enter with /plan or Shift+Tab.

Explore ──→ Plan ──→ Implement ──→ Commit

  Read files   Design approach   Execute steps   Done

3.4 Context Management

Every file read, tool call, and response consumes tokens from Claude's context window. When it fills, quality degrades.

3.5 Model Selection

Use /model to switch mid-session. Default rule: start with Sonnet, escalate to Opus when needed.

In agent and skill frontmatter, use the alias — not the full model string:

---
model: sonnet    # fast, cost-effective — use by default
model: opus      # complex reasoning
model: haiku     # fast, simple tasks
---

4.1 Core Components

Every agentic system — regardless of complexity — is built from ten entity types. In Claude Code, each maps to a specific file, directory, or configuration.

Naming Conventions

Every entity file follows a strict prefix system. This makes entities identifiable at a glance and enables automatic discovery.

All names use kebab-case, no spaces, no uppercase. The name field in frontmatter is limited to 64 characters; the description to 250. Descriptions should follow a "what + when" pattern: what it does, and when it should be used.

4.2 How They Relate

• Workflow (wor-) orchestrates the flow — invokes Agents, manages handoffs
• Specialists (age-spe-) execute domain work; Supervisors (age-sup-) validate output
• Agents use Skills and run Scripts
• Commands are invoked directly by the user — they bypass the Workflow
• Rules constrain everyone — including the Workflow
• Knowledge Base and Resources are consulted, never executed
• Hooks fire on events, not on commands

4.3 Component Reference

Workflow (wor-)

• Receives the high-level goal; breaks it into steps; routes to the right agents; manages handoffs; assembles output
• In Claude Code: .claude/commands/wor-*.md
• The orchestrator of the system — not a worker, but a coordinator

Agent Specialist (age-spe-)

• Exactly one domain of responsibility — nothing more
• Defined in .claude/agents/age-spe-*.md with YAML frontmatter
• Has its own isolated context window
• Invoked automatically (description match) or explicitly via @agent-name

Agent Supervisor (age-sup-)

• Reviews, validates, or scores output produced by Specialists
• Defined in .claude/agents/age-sup-*.md
• Acts as a quality gate — does not produce primary work, only evaluates it
• Use when you need a "second pair of eyes" before results leave a step

Skill (ski-)

• A named, reusable capability package — not a worker, but a procedure
• Triggered by name (/skill-name) or automatic description match
• Lives in .claude/skills/ski-*/SKILL.md
• Can fork a new context window for heavy work

Command (com-)

• A direct, deterministic action — a "saved prompt" that always produces the same behavior
• User-invoked only via /command-name — no agent or workflow delegates to a Command
• Lives in .claude/commands/com-*.md with minimal YAML frontmatter
• Use for atomic, repeatable tasks: export a system, publish a version, apply optimizations

Rule (rul-)

• A constraint, not a capability
• Two locations: in CLAUDE.md (always-on, every session) or as standalone files in .claude/rules/rul-*.md (loaded on demand)
• Always written as "Instead of X, do Y" — never just a prohibition
• Standalone rule files use a structured format: Context, Hard Constraints, Soft Constraints

Knowledge Base (kno-)

• Static reference content: style guides, API docs, domain glossary
• Lives in .claude/knowledge-base/kno-*.md
• Tell agents when to read it: "If you encounter an error, read kno-error-codes.md"

Resource (res-)

• Support document that extends another entity when its content is too long or too detailed
• Lives in .claude/resources/res-*.md
• Referenced conditionally: "For complex API usage, read res-api-full-reference.md"
• Keeps the main entity lean — the agent loads the resource only when needed

Script (scp-)

• Executable automated procedure — validation, deployment, data processing
• In Claude Code: .claude/scripts/scp-*.sh or scp-*.py (executable files)
• Run by agents or hooks, not invoked directly by users

Hook (hok-)

• Fires automatically on system events — file save, session start, task complete
• Configured in .claude/settings.json (the runtime configuration)
• Documentation lives in .claude/hooks/hok-*.md (what the hook does and why)

4.4 Decision Tree: Which Component Do I Need?

4.5 A Minimal Working System

The smallest valid agentic system needs just three things:

your-project/
├── CLAUDE.md
└── .claude/
    └── agents/
        └── age-spe-researcher.md

CLAUDE.md

# Project: Market Research Assistant

## Purpose
This system researches topics and returns structured summaries.

## Rules
- Always cite sources
- Use the researcher agent for all information gathering
- Output in Markdown with clear section headers

## Agents
- **@age-spe-researcher** — handles all research and fact-finding tasks

.claude/agents/age-spe-researcher.md

---
name: age-spe-researcher
description: Researches topics using web search and returns structured
  summaries with citations. Use for any information gathering,
  fact-checking, or background research task.
model: sonnet
tools: WebSearch, Read
---

You are a research specialist. When given a topic:
1. Search for current, authoritative sources
2. Synthesize findings into a clear summary
3. List all sources with URLs

Output format:
## Summary
[2-3 paragraph synthesis]

## Key Facts
- [bullet list]

## Sources
- [URL] — [one-line description]

One rule set, one specialist. Start here — add complexity only when the task demands it.