First to Second Edition: What Changed
Written 2026-10-04.
The first edition (March 2026) taught you to use one agent well. The second edition (October 2026) is about working when agents write most of the code: checking their work, owning the harness, running many agents, containing them and measuring cost. For the five shifts in one page, read What's New. This page is the lookup table: for every first-edition page, where its content lives now.
The first edition stays online as an archive. Links in the left column go to the original. Links in the middle column go to the new chapter.
Quick map of the big moves
- Several chapters became one. Parallel Agent Orchestration (Book 2, ch. 6) and Multi-session Workflows (ch. 18) are now The Agent View and Sessions. MCP Fundamentals, Database MCP and Building Custom MCP Servers (ch. 11, 13, 14) are now MCP in Practice. Browser MCP (ch. 12) is now part of Agents That See.
- Chapters moved. Book 2 was reordered: plugins moved up to chapter 4, subagents to 5, and the agent catalog to 6. In Book 3, the old chapters 19 to 23 had been numbered continuing from Book 2; the sidebar now numbers each book from 1. Appendices A to D lost their letters; they are now plain pages in Book 3.
- Chapters rewritten. Book 1: How It Works, Permission Modes (now Auto Mode and Permissions), Debugging (now Check the Work). Book 2: Sub-agents, Context Window Management, Token Optimization, Plugins. Book 3: Harness Engineering, Agent Teams, Security, Cost Reality.
Eight new pages
| New page | What it covers |
|---|---|
| What's New | The five shifts, and how to read the first edition. |
| Who to Follow | Practitioners and official sources worth reading. |
| MCP, CLI or Skill? | How to choose between the three ways to give an agent a capability. |
| Agents That See | Letting the agent look at the UI it built (also receives Browser MCP and computer use). |
| Verification and Evals at Scale | Checking agent output when you no longer read every line. |
| Agents Checking Agents | Using one agent to review another's work, and where that fails. |
| Portability: Many Tools, Many Models | Working across tools and models without being locked in. |
| The Builder's Job Now | An essay on what the human is for. |
Chapter-by-chapter map
Book 1: Getting Started
| First edition | Second edition | How it changed |
|---|---|---|
| What Is Claude Code? | What Is Claude Code? | Updated for current behavior; same job. |
| Why Claude Code? | Why Claude Code? | Updated for current behavior; same job. |
| How It Works — The Mental Model | How It Works | Now explains the harness, the context window and the current model line-up. |
| Installation | Installation | Updated for current behavior; same job. |
| Your First Conversation | Your First Conversation | Kept with a light refresh. |
| Permission Modes | Auto Mode and Permissions | Auto mode is now the starting point; the other modes become the exception. |
| Reading and Understanding Code | Reading and Understanding Code | Updated for current behavior; same job. |
| Editing Files | Editing Files | Kept with a light refresh. |
| Running Commands | Running Commands | Kept with a light refresh. |
| Git Workflows | Git Workflows | Updated for current behavior; same job. |
| Building a Simple Website — Hands-On Tutorial | Building a Simple Website | Updated for current behavior; same job. |
| Debugging Like a Pro | Check the Work | Debugging is now part of a wider habit: checking that the agent's work is right. |
| Working with APIs | Working with APIs | Kept with a light refresh. |
| CLAUDE.md — Your AI's Instruction Manual | CLAUDE.md and AGENTS.md | Adds AGENTS.md support and how the two files interact. |
| Memory System | Memory | Updated for current behavior; same job. |
| IDE Integration | IDE Integration | Kept with a light refresh. |
| Glossary | Glossary | Updated for current behavior; same job. |
| Keyboard Shortcuts | Keyboard Shortcuts | Updated for current behavior; same job. |
| Troubleshooting | Troubleshooting | Updated for current behavior; same job. |
Book 2: Power User
| First edition | Second edition | How it changed |
|---|---|---|
| Built-in Slash Commands | Slash Commands | Updated for current behavior; same job. |
| Custom Skills | Custom Skills | Updated for current behavior; same job. |
| Skill Composition | Skill Composition | Kept with a light refresh. |
| Sub-agents Explained | Subagents | Covers background, nested and forked subagents. |
| Agent Types Catalog | Agent Catalog | Updated for current behavior; same job. |
| Parallel Agent Orchestration | The Agent View and Sessions | Merged with Multi-session Workflows; built around the agent view. |
| Large Project Patterns | Large Projects | Updated for current behavior; same job. |
| Hook System Deep Dive | Hooks | Updated for current behavior; same job. |
| Automated Workflows | Automated Workflows | Updated for current behavior; same job. |
| Custom Tool Creation | Custom Tools | Kept with a light refresh. |
| MCP Fundamentals | MCP in Practice | Merged with the database and custom-server chapters into one. |
| Browser MCP | Agents That See | Reworked around agents checking UI themselves; browser MCP is one tool among several. |
| Database MCP | MCP in Practice | Merged into MCP in Practice (the database example lives there). |
| Building Custom MCP Servers | MCP in Practice | Merged into MCP in Practice (writing a small server). |
| Context Window Management | Context Engineering | Rewritten for the current models and context handling. |
| Token Optimization | Tokens, Limits and Caching | Rewritten around limits, usage and prompt caching. |
| Memory Architecture | Memory Architecture | Updated for current behavior; same job. |
| Multi-session Workflows | The Agent View and Sessions | Merged into the agent view chapter. |
| Desktop App & Computer Use | Agents That See Desktop and Web | Split: computer use moves to Agents That See; the app itself stays in Desktop and Web. |
| Plugins & Marketplaces | Plugins, Marketplace and Mods | Rewritten; adds the marketplace and mods. |
| Worktree & Isolation | Worktrees | Updated for current behavior; same job. |
| Voice, Fast Mode & Effort Levels | Voice, Fast Mode and Effort | Updated for current behavior; same job. |
Book 3: Architect
| First edition | Second edition | How it changed |
|---|---|---|
| Harness Engineering | Harness Engineering | Rewritten around measuring and auditing your own harness. |
| Agent Teams | Orchestrating Many Agents | Rewritten as orchestration of many agents. |
| Scheduled Tasks & Automation Loops | Scheduled Agents and Routines | Updated for current behavior; same job. |
| Cloud Providers & Remote Control | Cloud and Managed Agents | Updated for current behavior; same job. |
| CLAUDE.md Best Practices | CLAUDE.md and Agent-File Patterns | Updated for current behavior; same job. |
| Team Workflows | Team Workflows | Updated for current behavior; same job. |
| Remote Connection | Remote Connection | Kept with a light refresh. |
| Security and Privacy | Containment and Security | Rewritten as containment: what stops an agent, not just what to avoid. |
| Cost Reality — What Claude Code Actually Costs | Cost Reality, Measured | Rewritten as a method for measuring your own spend. |
| Agent Type Reference | Agent Type Reference | Refreshed against the current sub-agents documentation. |
| Performance Benchmarks | Performance Benchmarks | Old per-task token estimates removed; sourced benchmarks and harness studies added. |
| MCP Server Registry | MCP Server Registry | Every server re-checked; dead or archived entries removed. |
| Migration Guide | This page | Rewritten as this map. |
Index pages
Each book's overview page was rewritten to match the new contents: Book 1, Book 2, Book 3. The originals are at Book 1, Book 2 and Book 3.
What was dropped
- The first edition's Migration Guide (Appendix D) was a guide to switching from other AI coding tools. It is not repeated here, because tool features change monthly and the old comparisons are stale. It is still readable at /v1/en/book3-architect/migration-guide; for working across tools, read Portability.
- Unsourced numbers (the token-per-task tables in the benchmarks appendix) and MCP servers that could not be re-checked.
Check that it worked
Pick any first-edition chapter you relied on, find its row above, and open the new link. If a command or setting you used in the original no longer appears, the new chapter's Verified line and Sources section say which version of Claude Code and which documentation it was checked against.