Claude Engineering Best Practices

Quick Start

Use this Skill for:

• Claude Code configuration (plugins, hooks, sandboxing, settings)
• Claude Dev Agent SDK (tools, sessions, subagents, MCP)
• Plugin development and agent architecture
• Security patterns and best practices

Lookup workflow (verify volatile details):

# 1. Search for topic
rg -n "pattern" references/claude-*/**/*.md

# 2. Find official URL
rg -n "pattern" references/sources/llms_claude_*.txt

# 3. Fetch official doc
curl -sL "https://code.claude.com/docs/en/topic.md" | rg -A 5 "fieldName"

Core Principles (Stable Patterns)

1. Progressive Disclosure

Information revealed in stages based on need:

2. Hook-Based Architecture

Universal event system across Claude Code and SDK:

• PreToolUse: Validate/modify before execution
• PostToolUse: Log/validate after execution
• SessionStart: Initialize context
• Stop: Control completion criteria

3. Security-First Design

Multiple defensive layers:

• Principle of least privilege: Minimal permissions
• Defense in depth: Sandbox + IAM + hooks
• Zero trust: Verify at every layer

Navigation Guide

By Topic

Plugin Architecture

rg -n "plugin" references/claude-code/plugins.md
# Structure, manifest, caching, components

Hooks & Events

rg -n "PreToolUse\|PostToolUse" references/claude-code/hooks.md
# All events, types, schemas, patterns

Sandboxing

rg -n "sandbox\|network\|filesystem" references/claude-code/sandboxing.md
# Security, isolation, configuration

Agent SDK

rg -n "sessions\|hooks\|subagents" references/claude-dev/agent-sdk.md
# Sessions, hooks, tools, permissions

Skills Authoring

rg -n "progressive\|SKILL\.md" references/claude-dev/skills.md
# 3-tier architecture, best practices

By Product

Claude Code (Terminal)

• references/claude-code/plugins.md - Plugin architecture
• references/claude-code/hooks.md - Hook system
• references/claude-code/sandboxing.md - Security isolation
• references/claude-code/settings-permissions.md - Configuration
• references/claude-code/mcp-lsp.md - MCP & LSP integration
• references/claude-code/workflows.md - Common workflows

Claude Dev (Platform)

• references/claude-dev/agent-sdk.md - SDK patterns
• references/claude-dev/skills.md - Skills architecture
• references/claude-dev/tool-use.md - Tool use patterns
• references/claude-dev/prompt-engineering.md - Prompting best practices
• references/claude-dev/security-evaluation.md - Security & testing

Common Workflows

Author Workflow (Design → Implement)

1. Identify capability needed (skill, agent, hook, plugin)
2. Check latest docs for current schema/patterns
3. Design with progressive disclosure (3-tier)
4. Implement with stable patterns
5. Test with verification hooks

Operator Workflow (Use → Execute)

1. Determine tool/agent needed
2. Verify permissions & sandbox settings
3. Execute with appropriate oversight
4. Validate results via hooks/logs

Reviewer/Auditor Workflow (Evaluate → Score)

1. Check objective completion (artifact/verdict)
2. Verify security compliance (permissions, sandbox, hooks)
3. Assess engineering quality (reproducibility, clarity)
4. Review documentation & patterns used

Stable vs Volatile Information

✅ Stable Principles (Always Accurate)

• Progressive disclosure architecture
• Hook-based event system
• Plugin component structure
• Security design patterns
• Three-tier skill architecture

⚠️ Volatile Details (Look Up First)

These change frequently - never hardcode:

• API field names (exact JSON keys)
• Command flags (--debug, --resume, etc.)
• Hook event schemas (input/output structures)
• Plugin.json fields (required/optional)
• Tool permission lists
• Network domain allowlists

Always verify volatile details:

# Find correct URL
rg -n "topic.*\.md" references/sources/llms_claude_code.txt

# Fetch and extract
curl -sL "https://code.claude.com/docs/en/topic.md" | rg -A 5 "fieldName"

Quick Reference

Most Common Lookups

# Plugin.json required fields
curl -sL "https://code.claude.com/docs/en/plugins-reference.md" | rg -A 10 "Required fields"

# Hook events
curl -sL "https://code.claude.com/docs/en/hooks.md" | rg "^### "

# Agent SDK hooks
curl -sL "https://platform.claude.com/docs/en/agent-sdk/hooks.md" | rg -A 5 "PreToolUse"

# Sandbox configuration
curl -sL "https://code.claude.com/docs/en/sandboxing.md" | rg -A 10 "filesystem\|network"

# Structured outputs
curl -sL "https://platform.claude.com/docs/en/build-with-claude/structured-outputs" | rg -A 5 "json_schema"

Decision Matrix

Examples

Example 1: Test Framework Architecture

// Three-Agent Pattern
class TestRunner {
  // Agent A: Executor with hooks and sandbox
  async execute(task: string): Promise<void> {
    const options = {
      allowedTools: ['Read', 'Write', 'Edit', 'Bash'],
      permissionMode: 'acceptEdits',
      sandbox: { enabled: true },
      hooks: getHooks()  // PreToolUse, PostToolUse logging
    };
  }

  // Agent B: Simulator - generates tasks
  // Agent C: Evaluator - multi-step structured evaluation
}

Example 2: Plugin Audit Checklist

# 1. Check structure
rg -n "\.claude-plugin\|plugin\.json" references/claude-code/plugins.md

# 2. Verify hooks pattern
rg -n "PreToolUse\|PostToolUse" references/claude-code/hooks.md

# 3. Check security settings
rg -n "sandbox\|permission" references/claude-code/sandboxing.md

# 4. Verify progressive disclosure
rg -n "3-tier\|progressive" references/claude-dev/skills.md

Example 3: Agent SDK Configuration

# Complete SDK pattern
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="acceptEdits",
    session_persistence=True,
    hooks={
        "PreToolUse": [HookMatcher(...)],
        "PostToolUse": [HookMatcher(...)]
    },
    agents={
        "specialist": AgentDefinition(...)
    },
    setting_sources=["project"]
)

Anti-Patterns (Avoid)

❌ Hardcoding volatile details ❌ Missing progressive disclosure ❌ No validation hooks ❌ Hardcoded paths (use env vars) ❌ Overly verbose descriptions ❌ Deeply nested references (keep one level deep)

Official Documentation

Master Indexes

• Claude Code: https://code.claude.com/docs/llms.txt
• Claude Dev: https://platform.claude.com/docs/llms.txt

Key References

• Agent SDK Overview: https://platform.claude.com/docs/en/agent-sdk/overview.md
• Agent Skills: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview.md
• Tool Use: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md
• Hooks Reference: https://code.claude.com/docs/en/hooks.md
• Sandboxing: https://code.claude.com/docs/en/sandboxing.md
• Plugins: https://code.claude.com/docs/en/plugins-reference.md

Verification & Maintenance

Last verified: 2026-01-13

Always verify volatile details before implementation using the lookup workflow documented above.

Monthly checks:

• Review official documentation for updates
• Check for deprecated features
• Update local references if needed

About this Skill: This Skill applies progressive disclosure - only load what you need. Start with SKILL.md, reference thematic files for details, use lookup workflow for volatile information.