Claude Code: The Complete Guide (From Install to AI-Powered Workflows)
Everything you need to master Claude Code — install, architecture, agents, hooks, and the spec-driven workflow that changes how you build software.
Most people see “Code” in the name and assume Claude Code is for developers. It isn’t — or at least, it isn’t only for developers. I use it for marketing campaigns, financial analysis, content strategy, business operations, and yes, software development. It’s a cognitive amplifier for any complex, multi-step task.
But here’s the thing: most people use it at maybe 20% of its capability. They type a prompt, get a response, and move on. That’s like buying a CNC machine and using it as a drill press. The architecture underneath Claude Code — agents, skills, hooks, commands — is what turns it from a nice chatbot into a genuine productivity system.
This guide walks you through that architecture from scratch.
The Mindset Shift: It’s Not a Coding Tool
Claude Code excels at any complex work that benefits from:
- Persistent memory — it remembers your project context across interactions
- File access — it reads, writes, and organizes documents
- Tool integration — it connects to external services
- Specialized expertise — domain-specific agents bring focused knowledge
- Quality gates — automated verification catches mistakes
I’ve used it for P&L analysis, SEO audits, sales proposals, documentation overhauls, and content creation. The “Code” in the name is misleading — think of it as a command center for getting complex work done.
The key insight: push as much work as possible to deterministic, non-token-consuming parts of the system. Scripts, templates, and YAML files cost zero tokens and execute with 100% reliability. Reserve the AI for what actually requires judgment.
The Architecture: Six Layers That Work Together
Understanding these six layers is the difference between 2x results and 10x results.
Layer 1: CLAUDE.md — The Foundation
A markdown file that loads into every session. Think of it as the company handbook — universal context that applies to everything.
Keep it under 300 lines (60 is ideal). Include your tech stack, project structure, build commands, workflow expectations, and critical rules. Point to detailed docs for specifics — don’t paste them inline.
Where it lives:
~/.claude/CLAUDE.md # Global (all projects)
./CLAUDE.md # Project root (team shared)
./CLAUDE.local.md # Personal overrides (gitignored)Research shows LLMs reliably follow 150-200 instructions. Claude Code’s system prompt uses ~50. Your CLAUDE.md gets the rest. Make every line count.
Layer 2: Commands — Workflow Triggers
User-triggered prompt templates that standardize complex workflows. Think of them as department procedures — you invoke them when you need a specific workflow.
# .claude/commands/analyze-pl.md
Analyze the provided P&L statement with focus on:
1. Revenue trends and growth patterns
2. Cost structure and margin analysis
3. Seasonality detection
4. Cash flow estimation
5. Profit lever identification
Use the financial-analyst agent and financial-statement-analysis skill.
Output a comprehensive report with visualizations.Invoke with /project:analyze-pl. Commands are thin — orchestration only, no procedures. The procedures live in skills.
Layer 3: Agents — Specialized Experts
Domain-specific AI personas with focused capabilities, tools, and permissions. These are your expert consultants.
# .claude/agents/legendary-copywriter.md
---
name: legendary-copywriter
description: Master copywriter channeling Kennedy, Halbert, Hormozi techniques
tools: Read, Write, Edit, Bash, WebSearch, WebFetch
model: sonnet
skills: hormozi-offer-analysis, sugarman-copywriting-framework
---
You are a master copywriter trained in direct response techniques...Agents define what and why, not how. The how lives in skills.
Layer 4: Skills — Expert Knowledge
Self-contained knowledge packages that agents load on-demand. These are your training manuals — detailed procedures, decision trees, and domain expertise.
Skills use progressive disclosure: the agent sees the description (~100 tokens), decides if it’s relevant, loads the full skill (~1,000 tokens), and references supporting files only if needed. Maximum expertise, minimum context consumption.
Layer 5: Hooks — Automated Guarantees
Shell commands that execute automatically at specific lifecycle points. This is where determinism lives.
| Approach | Reliability | Speed | Context Cost |
|---|---|---|---|
| ”Please format your code” | ~70% | Slow | Uses tokens |
| Hook: prettier —write | 100% | Fast | Zero tokens |
Hooks turn suggestions into guarantees. Configure them for formatting, linting, type checking, security scanning — anything with a binary right/wrong answer.
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{"type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS"}]
}],
"Stop": [{
"matcher": "*",
"hooks": [{"type": "command", "command": "npm run typecheck && npm run lint"}]
}]
}
}Layer 6: Plugins and MCP — External Connections
Connect Claude to external tools via MCP (Model Context Protocol):
claude mcp add github --scope user
claude mcp add obsidian --scope projectThis gives Claude access to GitHub PRs, knowledge bases, web research, browser automation, and anything else with an MCP server.
👉 Tip: Start with just CLAUDE.md and one command. Add agents when you find yourself repeating the same expertise setup. Add skills when agents need detailed procedures. Add hooks when you catch yourself wishing Claude would “just always do X.” Build the layers as you need them, not all at once.
Spec-Driven Development: The Most Important Workflow
Here’s the workflow pattern that changed everything for me.
One fix in a spec saves you 100,000 bad lines of code.
| Review Point | Leverage | Why |
|---|---|---|
| Research review | 10x+ | Prevents architectural misunderstandings |
| Plan review | 5-10x | Catches strategy errors before building |
| Build review | 1x | Verifies correctness (too late to pivot) |
The three phases:
Phase 1: Planning. Create requirements, design, and task breakdown. Human approves at each stage. This is where you catch the mistakes that would cost 100x to fix later.
Phase 2: Implementation. Execute tasks one at a time with approval gates. Delegate to specialized agents for domain expertise.
Phase 3: Quality. Automated quality gates — coverage thresholds, security scans, complexity checks — produce structured reports. Not “it works” but “it’s verified against specific criteria.”
Benefits of spec-driven development:
- 1-2 iterations typical instead of 5-10
- Features aligned to requirements, not interpreted loosely
- Technical debt prevented instead of accumulated
- Auditable trail from requirement to implementation
- Quality verified against specific, measurable criteria
YAML, Templates, and Checklists
These three tools keep Claude targeted and fed the exact data it needs:
YAML as mini databases — quality gates, configuration values, decision criteria. Version controlled, human readable, zero interpretation errors.
Markdown templates — exact output format every time. Claude fills in blanks instead of inventing structure. Consistent across runs.
Checklists — binary pass/fail verification. Executable by scripts or Claude. Progressive (stop at first failure). Auditable.
Together, they ensure Claude doesn’t guess, hallucinate, or vary. It orchestrates deterministic operations and fills structured outputs.
Getting Started: Day 1 to Month 1
Day 1: Basic Setup
Create your CLAUDE.md with project overview, tech stack, key commands, and workflow rules. Create one command for your most common workflow. Test it.
Week 1: Expand
Add specialized agents for common tasks. Configure hooks for automatic formatting and quality checks. Create more commands for standardized workflows.
Month 1: Master
Implement spec-driven development. Build your skill library. Optimize your context — measure what’s working, remove what isn’t, document what you learn.
👉 Tip: The businesses winning with AI aren’t the ones with the biggest budgets. They’re the ones who understand the architecture, build systematic workflows, and iterate on what works. Claude Code is the same — it rewards systematic thinking over brute-force prompting.
Quick Reference
Essential Commands
| Command | Purpose |
|---|---|
/clear | Reset conversation |
/compact | Compress context, preserve decisions |
/resume | Continue previous session |
/rewind | Undo to previous checkpoint |
/permissions | Manage tool permissions |
/project:name | Run project command |
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
Escape | Interrupt current operation |
Escape Escape | Go back, retry different approach |
Shift+Tab | Toggle auto-accept mode |
# | Let Claude update files automatically |
Tab | File path completion |
CLI Flags
| Flag | Purpose |
|---|---|
-p "prompt" | Headless mode (no REPL) |
-c | Continue most recent session |
-r "session" | Resume specific session |
--model opus | Use Opus model |
--agent name | Use specific agent |
Sources and Further Reading
- Anthropic Claude Code Best Practices
- Advanced Context Engineering for Coding Agents
- Writing a Good CLAUDE.md
- Claude Skills Tutorial
- Claude Code: The Complete Guide
- 12-Factor Agents Framework
Continue reading:
- 10 Claude Code Best Practices I Wish Someone Told Me on Day One — The quick-reference companion to this guide
- How to Implement AI in Your Business — Where Claude Code fits in the broader AI adoption picture
- Building Effective Business Systems — The systems thinking that makes AI workflows stick