claude-engineering-best-practices

name	claude-engineering-best-practices
description	General-purpose guidance for Claude Code (terminal) and Claude Dev (platform). Covers stable principles (progressive disclosure, hooks, security) and volatile details with lookup workflows.

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)

MANDATORY : If it works, it works. Always compare the pro and cons before implementing complex logic, "Keep it Simple, Stupid" should be your main guideline.

1. Progressive Disclosure

Information revealed in stages based on need:

Level	What	Token Cost	When Loaded
Metadata	name + description	~100 tokens	Always (startup)
Instructions	SKILL.md body	<5k tokens	On trigger
Resources	Bundled files	Unlimited	As needed (via bash)

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

Situation	Action
curl succeeds, domain allowed	Use fetched data, cite source
curl succeeds, domain blocked	Document limitation, use local refs
curl fails (network error)	Use local refs, mark outdated
curl fails (403/permission)	Request permission, use local refs
Can't fetch docs	Use local reference files

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.