Official guides for Claude Code best practices and the Agent SDK

Anthropic published two official documents worth reading together:

The first focuses on how to use Claude Code well in practice. The second explains how to build agents with the Claude Agent SDK.

Claude Code Best Practices

Claude Code is intentionally low-level and flexible. It does not force a specific workflow, which makes it powerful, but it also means you need to learn how to drive it well. This guide collects best practices from Anthropic’s internal teams and external engineers.

Use `CLAUDE.md` to provide context

If you place CLAUDE.md at the project root, Claude reads it automatically. Good things to put in it:

Frequently used Bash commands for build, test, lint, and so on
Where core files and utility functions live
Code style guidelines
Repository-specific rules and workflows

There are several useful locations for it:

Location	Best use
Project root	Default and recommended
Parent directory	Monorepos
Child directory	Subproject-specific settings
Home directory	Settings shared across all sessions

Anthropic reportedly uses emphatic phrases like IMPORTANT and YOU MUST internally to improve instruction-following.

Create custom slash commands

If you place Markdown files under .claude/commands/, they become slash commands.

.claude/commands/fix-github-issue.md

That lets you call something like /project:fix-github-issue 1234. Parameters can be received through the $ARGUMENTS placeholder. Since teams can share these commands, Anthropic recommends committing them into the repository.

Extend tools with MCP

Claude Code supports MCP, the Model Context Protocol. If you include .mcp.json in the repository, the whole team can use the same tools.

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-puppeteer"]
    }
  }
}

For troubleshooting, the --mcp-debug flag is useful.

Recommended workflow

Explore -> plan -> implement -> commit

Breaking work into phases improves reliability:

Explore: read related files, with an explicit instruction not to write code yet
Plan: use prompts like think or think hard to get a stronger plan
Implement: build the solution and verify it
Commit: commit the changes

The more complex the problem is, the more important the planning phase becomes. Skipping planning too early is a common failure mode.

Test-driven development

This works especially well for verifiable changes:

Write tests from the input/output spec without implementing the feature yet
Run the tests and confirm they fail
Commit the tests
Iterate on the implementation until the tests pass

Visual iteration

This is effective for UI or design work:

Use Puppeteer MCP or screenshots
Reference a design mock
Repeat implementation -> screenshot -> correction

The guide notes that two or three iterations often improve the result significantly.

Prompting tips

More specific instructions lead to better results.

# Weak
Add tests for foo.py

# Strong
Create tests for foo.py. Handle the logged-out edge case. Do not use mocks.

Images also help. On macOS, you can copy a screenshot to the clipboard with Cmd+Ctrl+Shift+4 and paste it with Ctrl+V.

Context management

For long-running sessions, /clear is useful for discarding irrelevant conversation history. For large tasks, it is also effective to have Claude track progress in a Markdown checklist.

Headless mode

The -p flag runs Claude non-interactively, which is useful for CI/CD integration.

claude -p "Review this code" --output-format stream-json

Combined with GitHub Actions, this can be used for things like automatic issue triage or code review.

Multi-instance workflows

You can run multiple Claude Code instances in parallel. This becomes especially effective when combined with Git worktrees.

git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude

Claude Agent SDK

What used to be called the Claude Code SDK has been renamed to the Claude Agent SDK. The reason is straightforward: it is now used for much more than coding, including research, video creation, note taking, and other workflows.

Design philosophy

The core idea is that Claude should have access to the same kinds of tools programmers use every day: file search, editing, execution, and debugging.

Agent loop structure

An agent repeats the following cycle:

Collect context: gather the information it needs
Take action: use tools to perform work
Verify results: check whether the outcome is correct
Repeat: go back to step 1 when necessary

Ways to gather context

Method	Description
File-system search	Use tools like `grep` or `tail` to extract information from files
Semantic search	Use embeddings, though the guide notes this is less precise
Subagents	Run work in parallel while isolating context windows
Compaction	Automatically compress conversation history during long runs

Ways to execute actions

Tool definitions for APIs and databases
Bash and scripts for file operations or PDF conversion
Code generation for producing Excel, PowerPoint, or Word files with Python
MCP integration for tools like Slack, GitHub, Google Drive, and Asana

Verification mechanisms

Rule definitions for checks such as email validation or linting
Visual feedback such as screenshots when generating HTML email
LLM evaluation where another model judges output quality

Example use cases

Finance agent for portfolio analysis and investment review
Personal assistant for scheduling and travel booking
Customer support for handling complex inquiries
Research agent for analyzing large document sets

The difference between the two guides

Topic	Best Practices	Agent SDK
Audience	Claude Code users	Agent developers
Focus	Workflow tips and usage patterns	Architecture and design principles
Goal	Improve day-to-day coding productivity	Build custom agents

The Best Practices guide is about how to use Claude Code well. The Agent SDK guide is about how to build agents on top of the same underlying ideas.