# Course notes extracted from slide PDFs Source material (local): `Youtube-main/Claude Code Crash Course/*.pdf` and CCA slide decks under `Youtube-main/claude-certified-architect/`. Regenerate raw extraction with `scripts/extract_pdf_content.py`. Text below is **rewritten for this repo** (same meaning, different wording). Diagrams in the PDFs were **not** copied — see `assets/*.svg` in the main course for original illustrations. --- ## Setup and surfaces - Install Claude Code on Windows, macOS, or Linux; use `claude doctor` when PATH or auth issues appear. - Surfaces: Claude on the web (chat), Claude Desktop (native chat), Claude Code (terminal/IDE agent with tools). - **Token rule of thumb:** about **four characters** or roughly **three quarters of an English word** per token — useful when estimating context cost. - Pro or API billing: subscription vs pay-as-you-go credits at the Anthropic console. --- ## Sessions, commands, and `.claude/` - Sessions hold conversation + tool history until you `/clear`, `/compact`, or start fresh. - The `.claude/` directory holds project settings, hooks, skills, and agent definitions. - `CLAUDE.md` (root or `.claude/`) is loaded every session; **rules** and **style** files can add scoped guidance. Official reference: [Claude directory docs](https://code.claude.com/docs/en/claude-directory). --- ## CLAUDE.md (and AGENTS.md) — best practices Source: [HumanLayer — Writing a good CLAUDE.md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) (same ideas apply to `AGENTS.md` for Cursor/Zed/OpenCode). **Stateless sessions:** the model starts each chat with no repo memory; `CLAUDE.md` is the default onboarding file every time. **Structure onboarding as WHAT / WHY / HOW:** - **WHAT** — stack, layout, monorepo map (where APIs vs UI live). - **WHY** — purpose of apps/services and design constraints. - **HOW** — commands to build, test, typecheck, and verify work (e.g. `bun` vs `npm`). **Less is more:** - Only universally applicable instructions; niche rules cause Claude to ignore the whole file (system reminder: context may not be relevant). - Rough limits: frontier models ~150–200 instructions; Claude Code system prompt already uses ~50; aim for **< 300 lines**, many teams **< 60**. - Do not paste every command or style rule into one file. **Progressive disclosure:** task-specific docs in `agent_docs/*.md` (or skills); `CLAUDE.md` lists them with short descriptions. Prefer `file:line` pointers over copied snippets. **Not a linter:** use Biome/ESLint/Ruff + hooks; optional slash command for style on demand. **Avoid blind `/init`:** treat auto-generated files as drafts; curate manually — highest leverage file in the harness. **Maintenance (living document):** 1. Review monthly — remove stale conventions. 2. Prune aggressively — fix one-off bugs in code, not in `CLAUDE.md`. 3. Prefer pointers — `agent_docs/`, `docs/`, or skills. 4. Shrink over time; do not grow without bound. --- ## Context management **Primacy and recency bias:** models weight early and late context heavily. Put critical rules where they stay visible; avoid burying must-follow constraints in the middle of huge files. **Context rot strategies:** - Keep `CLAUDE.md` short; move long workflows into **skills** (loaded on demand). - Move repetitive guardrails into **hooks** (zero token cost at runtime). - Watch **MCP tool-definition overhead** — many servers add fixed tokens every turn. - Use **extended thinking** only when reasoning depth justifies the cost. - **Plan before you build** (plan mode) on unfamiliar or large changes. - Version milestones (V1, V2) so Claude does not mix old and new architecture. --- ## Skills Skills are on-demand playbooks (`SKILL.md`) invoked by slash command or description match. They keep the main context lean compared to stuffing the same steps into `CLAUDE.md`. --- ## Hooks (event-driven) Hooks run on lifecycle events without spending model tokens. Typical roles: 1. **Automation** — format, test, or deploy after edits. 2. **Logging** — audit tool use to disk. 3. **Guardrails** — block `rm -rf`, force-push, or destructive bash. The agent loop still follows: plan → tool call → observe → repeat; hooks sit *around* tool execution. --- ## MCP (Model Context Protocol) Open standard (Anthropic) for tools and data sources. Local servers often use **stdio** (stdin/stdout); remote shared servers use **HTTP/SSE**. **Common failure modes to design for:** | Failure | Mitigation | |---------|------------| | Connection closed | Retry with backoff; surface clear user message | | Server disconnected | Health check tool; restart server process | | Auth failed | Validate API keys before long agent runs | | Tool errors | Structured error payloads, not empty strings | | Server timeout | Shorter tool calls; async jobs for slow APIs | Example integrations: search (e.g. Tavily), email (read/draft/label), databases, custom REST APIs. --- ## Sub-agents **Why not one agent for everything?** - **Context overflow** — tool output stacks until the window fills. - **Sequential bottleneck** — one thread cannot explore in parallel. - **Specialization** — narrow agents with focused tools outperform generic instructions. **Cost illustration (order of magnitude):** ten heavy messages in the main session can consume a large context slice (e.g. on the order of tens of thousands of tokens) and several dollars; the same work split into isolated sub-agents can use smaller windows per task. **Benefits:** context isolation, parallelism, specialist prompts, modular agents, per-agent tool allowlists. **Model choice:** Haiku for exploration/tests; Sonnet/Opus for complex reasoning. Types: built-in explorers/reviewers vs custom agents in `.claude/agents/`. **Task tool permission matrix (architect pattern):** | Role | May spawn sub-agents? | Rationale | |------|----------------------|-----------| | Coordinator | Yes | Must delegate work | | Standard worker | No | Prevents runaway recursion | | Sub-coordinator | Only if designed for a third tier | Explicit hierarchy only | --- ## Agent teams (experimental) Peer agents share a task list and coordinate in parallel — unlike sub-agents that report only to the parent. **Strong fit:** large refactors, full-stack features, parallel review + testing, security audits at scale, long codebase onboarding. Enable via experimental flag in `.claude/settings.json` (see course module 13). --- ## Plugins, LSP, scheduling - **Plugins** bundle skills, agents, hooks, and MCP config. - **LSP (Language Server Protocol)** — Claude Code can use language servers for smarter navigation and diagnostics (plugin ecosystem). - **Scheduling:** cron, CI/CD, or in-session `/loop` for recurring prompts. - **Headless / unattended runs:** prefer read-only first; write to safe paths; human approval for irreversible steps; log everything. **Unattended prompt patterns:** | Avoid | Prefer | |-------|--------| | “Deploy when tests pass” | “When tests pass, write summary to `ready-to-deploy.md` and ping Slack for human approval” | | “Fix all lint by editing source” | “List lint issues in `reports/lint.md`; do not modify source” | --- ## Capstone flow (video course) End-to-end build paths: - **From scratch:** `/init`, explore agent, scaffold (e.g. DailyFlow-style productivity app). - **Existing repo:** `@explore-agent` or codebase search, then incremental features. Repo examples: `examples/DailyFlow/`, `examples/Task-Manager-App/`, and `examples/CCA-F-PREP/` for certification prep projects. --- ## CCA-F slide decks (lessons 2–3) Image-only PDFs under `Youtube-main/claude-certified-architect/slide decks/` cover **Domain 1** (27% of CCA-F exam): - Multi-agent coordinator patterns (hub orchestrator + workers). - Single-agent ceiling: overflow, sequential bottleneck, specialization gap. - Subagent session state and `--resume` — always tell the agent what changed on disk since last run. - Task-tool permissions for coordinators vs workers. Cross-study (HTML): [CCA-F prep hub](../examples/CCA-F-PREP/index.html) · [Study map](../examples/CCA-F-PREP/CCA-STUDY-MAP.html) · [Slide notes](../examples/CCA-F-PREP/cca-f-slide-notes.html). --- ## Extended curriculum (Modules 16–19) See [syllabus-coverage.md](syllabus-coverage.md) for the full training-slide checklist. Summary: ### Agentic coding workflows - Map tasks to the agentic loop: understand repo → plan → edit → test → report. - Use plan mode and scoped directories before repo-wide refactors. - `/batch` and sub-agents for parallel multi-file work. ### Extended thinking, AGENTS.md, CI/CD - `/effort high|max` for architecture and hard bugs; monitor cost with `/usage` and `/cost`. - **AGENTS.md** — cross-tool repo rules; **CLAUDE.md** — Claude Code session context. - GitHub: `/install-github-app` for PR review; Actions + `claude -p` for scheduled reports (read-only first). ### Multi-agent pipelines - Orchestrator (LangGraph, Agents SDK, custom) delegates coding to Claude Code via CLI or MCP. - Handoffs carry goal, paths, test status — not full tool traces. - Reviewer agent or human gate before merge. ### API, Co-Work, n8n, enterprise MCP - **Messages API** + structured outputs for apps; rate limits and secrets in production. - **Co-Work** (Desktop) for team collaboration; **Claude Code** for repo + terminal depth. - **n8n**: webhooks and schedules calling Claude API; human approval before production writes. - **Enterprise MCP**: approved server registry, OAuth, hooks for audit, bidirectional tool exposure.