Chapter 25: Best Practices Reference

Created: 2026-01-05 Source: Production Entry #189 (Best Practices Index) Pattern: Research-backed patterns from Anthropic + Claude documentation Coverage: 33 articles indexed, 15 fully extracted

Overview

This chapter provides a comprehensive index of Anthropic best practices research, organized by category with extraction status and implementation guidance.

📊 Index Statistics

Metric	Count	Status
Total Articles	33	Indexed ✅
Anthropic Engineering	18	Indexed ✅
Claude.com Blog	15	Indexed ✅
Fully Extracted	15	Implementation-ready
Priority 1 IMPLEMENTED	3	Production patterns

🚀 Priority 1: Critical Patterns (Extracted & Implemented)

Context Engineering

Article: Effective Context Engineering for AI Agents Key Patterns:

Just-in-time retrieval (load context when needed, not upfront)
Hybrid strategy (always-loaded core + on-demand details)
Structured notes for multi-session continuity
34-62% token reduction with zero functionality loss

Implementation: See memory-bank/always/ (always-loaded) + memory-bank/ondemand/ (on-demand)

Long-Running Agent Harnesses

Article: Effective Harnesses for Long-Running Agents Key Patterns:

Feature list guardrails (track what’s done)
Incremental progress (one feature at a time)
Git + progress file pairing
Session checkpoints

Implementation: See SESSION-PROTOCOL.md, system-status.json

Advanced Tool Use

Article: Advanced Tool Use on Claude Developer Platform Key Patterns:

Tool Search (51k token savings)
Parallel Tool Calling (PTC) - 37% latency reduction
Tool examples (+18% accuracy)
Consolidation over proliferation

Implementation: See Chapter 20 (Skills Filtering), Entry #198

Writing Effective Tools

Article: Writing Effective Tools for Agents Key Patterns:

Pagination defaults (LIMIT 10, not unlimited)
Tool consolidation (733% ROI)
Meaningful responses (not just “done”)
Error context in responses

Implementation: See Chapter 17-24 (skill patterns)

🤖 Skills & Agents Category

Article	URL	Key Takeaway
Equipping Agents with Skills	Link	84% activation rate with numbered triggers
Building Agents with Claude Agent SDK	Link	SDK patterns for custom agents
Building Effective Agents	Link	Workflow patterns vs custom agents
Multi-Agent Research System	Link	Agent coordination patterns

🛠️ Context & Tools Category

Article	URL	Key Takeaway
Effective Context Engineering	Link	Just-in-time retrieval, hybrid strategy
Writing Effective Tools	Link	Pagination defaults, consolidation
Advanced Tool Use	Link	Tool Search, PTC, examples
The “Think” Tool	Link	Extended thinking for complex tasks
Contextual Retrieval	Link	RAG optimization patterns

🪝 Hooks & Configuration Category

Article	URL	Key Takeaway
How to Configure Hooks	Link	11 hook events for workflow automation
Using CLAUDE.md Files	Link	Project context customization
Building Skills for Claude Code	Link	Skill creation workflow

🔌 MCP & Execution Category

Article	URL	Key Takeaway
Code Execution with MCP	Link	MCP server patterns
Desktop Extensions	Link	One-click MCP installation

💰 Cost Optimization Category

Article	URL	Key Takeaway
Prompt Caching	Link	90% cost reduction on repeated loads
Building Effective Agents	Link	Workflow patterns (3x faster than custom agents)

📚 Claude.com Blog Articles (15)

Skills Category

Hooks & Configuration

How to Configure Hooks ⭐
Using CLAUDE.md Files ⭐

Enterprise & Use Cases

🎯 Extraction Workflow

When extracting patterns from new articles:

EXTRACTION_WORKFLOW:
  Step_1: "WebFetch(url, 'Extract key patterns, rules, anti-patterns, code examples')"
  Step_2: "Pattern analysis (5 min)"
  Step_3: "Cross-reference check (3 min)"
  Step_4: "Create entry if new patterns (15 min)"
  Step_5: "Update this index with extraction status (2 min)"
  Step_6: "Update implementation guide if significant (10 min)"

📅 Maintenance Schedule

Frequency	Task
Weekly	Check for new Anthropic blog posts
Monthly	Review extraction priorities based on active work
Quarterly	Validate existing entries still align with latest research

🔗 Cross-Reference with Implementation Guide

Chapter	Related Research
Chapter 13: Claude Code Hooks	How to Configure Hooks
Chapter 17: Skill Detection	Equipping Agents with Skills
Chapter 20: Skills Filtering	Advanced Tool Use, Writing Tools
Chapter 21: Pre-prompt Optimization	Effective Context Engineering
Chapter 24: Keyword Enhancement	Skills patterns + context engineering
Chapter 36: Agents and Subagents	Building Effective Agents, Agent SDK
Chapter 37: Agent Teams	Multi-Agent Research System
Chapter 38: Context Costs & Budget	Best Practices, Skills, Features Overview

📖 Official Documentation References

These are pages from Anthropic’s official Claude Code documentation site (code.claude.com) that cover core concepts referenced throughout this guide:

Documentation Page	URL	Key Topics
Best Practices	Link	Context management, CLAUDE.md pruning, verification patterns, subagent best practices
Sub-agents	Link	Agent memory (project/user), skills preloading, permission modes, hooks for agents
Skills	Link	Description budget (2% / `SLASH_COMMAND_TOOL_CHAR_BUDGET`), description format, `disable-model-invocation`, `context: fork`
Features Overview	Link	Context cost table (what loads when), comparison of extension points (skills vs agents vs hooks vs MCP)

Related chapters: Chapter 36 (agents), Chapter 38 (context costs & skill budget), Chapter 20 (skill filtering)

📊 Implementation Priority Matrix

High ROI (Implement First)

Context Optimization (34% token reduction) - Chapter 21
Skill Detection (100% accuracy) - Chapter 17, 24
Tool Consolidation (733% ROI) - Chapter 20
Session Protocol (3x continuity) - Chapter 12

Medium ROI (Phase 2)

MCP Integration (zero-token validation)
Perplexity Caching (80% cost savings)
Playwright E2E (100% test coverage)

Lower Priority (As-Needed)

Enterprise patterns
Slack integration
Advanced RAG

🎯 Quick Reference Links

Most Important Articles (Start Here):

Effective Context Engineering - Foundation pattern
Building Skills for Claude Code - Skill creation
How to Configure Hooks - Automation
Writing Effective Tools - Tool design

Implementation Guide Chapters:

Chapter 17 - 4-phase skill detection
Chapter 20 - Score-at-match-time
Chapter 21 - 68% reduction
Chapter 24 - Synonym expansion

📈 Success Metrics

Metric	Target	Current	Status
Articles indexed	30+	33	✅
Priority 1 extracted	4	4	✅
Implementation coverage	80%	85%	✅
ROI documented	10+ patterns	15+	✅

Best Practices Audit Methodology (Entry #363)

A systematic approach to auditing your Claude Code setup against official documentation:

Step 1: Fetch Official Docs

Review all pages at code.claude.com/docs/en/:

best-practices, skills, sub-agents, hooks-guide, memory, features-overview

Step 2: Inventory Current Setup

Run verification commands to count what you have:

# Skills with each feature
grep -rl "^model:" .claude/skills/*/SKILL.md | wc -l
grep -rl "^allowed-tools:" .claude/skills/*/SKILL.md | wc -l
grep -rl "^context: fork" .claude/skills/ | wc -l

# Agent features
grep -rl "^memory:" .claude/agents/*.md | wc -l
grep -rl "^skills:" .claude/agents/*.md | wc -l
grep -rl "^permissionMode:" .claude/agents/*.md | wc -l

# Global agents
ls ~/.claude/agents/*.md 2>/dev/null | wc -l

# Hook types
grep -c '"type": "prompt"' .claude/settings.json
grep -c '"async": true' .claude/settings.json

Step 3: Gap Analysis

Compare features available in docs vs features you’re using. Common gaps:

paths: YAML frontmatter in rules files (conditional loading)
memory: field on agents (cross-session learning)
skills: preloading on agents (faster startup)
model: field on skills (cost optimization)
allowed-tools: on read-only skills (safety)
!command`` dynamic injection in skills (live context)
Prompt-based hooks (intelligent validation)
Global agents at ~/.claude/agents/ (cross-project reuse)

Step 4: Prioritize by Impact

Priority	Feature	Impact	Effort
P0	Path-specific rules	HIGH (reduces context per message)	1h
P0	Agent memory	HIGH (cross-session learning)	30min
P1	Skills model: field	MEDIUM (cost savings)	2h
P1	Dynamic injection	HIGH (live context)	2h
P2	Prompt-based hooks	MEDIUM (intelligent validation)	2h
P2	allowed-tools	LOW (safety improvement)	1h

Reference: Entry #363 implemented 11 gaps across 120+ files in ~25 hours total.

Research Authority: Anthropic engineering + Claude.com blog Sacred Compliance: All patterns validated against Sacred Commandments ROI: 50-100h/year saved with research-backed patterns vs trial-and-error Updates: Monthly review of new Anthropic publications