claude-code-best-practice

Implements a three-tier hierarchical execution model where user commands trigger specialized agents, which decompose work into reusable skills with isolated execution contexts. Commands are defined as markdown files in .claude/commands/, routed to agents (general-purpose, Explore, Plan, or custom), which invoke skills (simplify, batch, loop, or custom) with persistent memory and lifecycle hooks. This architecture enables deterministic automation through 17+ lifecycle events (PreToolUse, SessionStart, Stop, etc.) that intercept and modify agent behavior at runtime.

Implements a 5-level configuration precedence hierarchy (managed > CLI > local > project > user) where settings cascade from highest-priority managed configurations down to user defaults, with each level overriding lower levels. Settings are stored in CLAUDE.md files (project-level) and user config directories, supporting environment variables, model selection, permissions, sandbox security, and context budgets. The system uses a settings resolution algorithm that walks the precedence chain at runtime, enabling dynamic reconfiguration without restarting the agent.

Provides a scheduling system for long-running agent workflows that execute on defined schedules (cron-like expressions) with support for task queuing, retry logic, and progress tracking. The system manages task lifecycle (scheduled, running, completed, failed), persists task state across restarts, and enables resumption of interrupted tasks. Scheduled tasks can be chained (task A triggers task B) and can access shared state through the memory system.

Enables multiple agents to work together as a team with explicit message passing, shared context repositories, and coordination protocols. Agents can send messages to other agents, access shared memory stores, and coordinate on complex tasks through a message queue system. The architecture prevents direct state coupling while enabling controlled information flow between agents through well-defined message interfaces.

Provides a system for agents to automatically update their own documentation, CLAUDE.md files, and configuration based on execution experience and learned patterns. Agents can analyze their own behavior, identify improvements, and propose or apply updates to documentation and configuration without manual intervention. This enables agents to improve over time and maintain accurate documentation as they evolve.

Provides a command-line interface (CLI) with built-in slash commands (e.g., /plan, /explore, /simplify, /batch, /loop) and a power-ups system for extending CLI functionality. Slash commands map to agents and skills, with support for command composition (chaining commands), parameter passing, and output formatting. Power-ups are plugins that add new slash commands or modify existing ones, enabling extensibility without modifying core CLI code.

Provides a structured learning path and best practices guide for transitioning from ad-hoc 'vibe coding' (exploratory, unstructured prompting) to production-grade agentic engineering with formal patterns, configuration management, and architectural discipline. The framework documents anti-patterns, common pitfalls, and recommended practices at each stage of maturity, with examples and case studies demonstrating the progression.

Tracks and enforces context window usage across agent executions using a token accounting system that measures input tokens, output tokens, and cumulative context consumption. The system allocates context budgets per agent, per command, and per session, with real-time monitoring and enforcement that prevents agents from exceeding allocated token limits. Context budgets are configured in settings and can be adjusted per project or per execution, with detailed logging of token usage per skill invocation and agent step.

Provides a multi-tier memory system for agents including short-term context (current conversation), long-term persistent memory (stored between sessions), and episodic memory (task-specific execution logs). Memory is stored in agent-specific directories with structured formats (JSON, markdown), indexed for semantic retrieval, and accessible via memory-aware skills (e.g., recall, summarize). The system supports memory isolation between agents, preventing cross-agent state leakage, while enabling explicit memory sharing through message passing or shared memory stores.

Integrates Model Context Protocol (MCP) servers to connect Claude Code agents with external tools, databases, APIs, and services via a standardized .mcp.json configuration file. The system discovers MCP servers, establishes connections, exposes their capabilities as callable tools within agent skills, and handles request/response marshaling between agents and external services. MCP integration enables agents to access real-time data, execute system commands, query databases, and invoke third-party APIs without hardcoding tool logic.

Provides a system for injecting project-specific context, rules, and knowledge into agent execution through CLAUDE.md files that define project structure, conventions, best practices, and domain-specific instructions. The system parses CLAUDE.md files, extracts context blocks, and injects them into agent prompts at runtime, enabling agents to understand project conventions without explicit training. Context injection is hierarchical (project-level, directory-level, file-level) and respects context budget constraints.

Implements a fine-grained permissions system that controls agent access to files, directories, external services, and system capabilities through a declarative permissions configuration. Permissions are defined per agent, per skill, and per resource type (file read/write, network access, command execution), with a sandbox that enforces capability isolation and prevents unauthorized access. The system supports role-based access control (RBAC) and resource-level permissions, enabling secure multi-tenant agent deployments.

Provides a 17+ event-based hook system that intercepts agent lifecycle events (SessionStart, PreToolUse, PostToolUse, Stop, etc.) and enables deterministic automation through hook handlers that can modify agent behavior, log events, or trigger side effects. Hooks are defined as markdown files or code functions, registered per agent or globally, and executed synchronously at specific lifecycle points. The system enables cross-cutting concerns (logging, monitoring, policy enforcement) without modifying agent logic.

Provides first-class support for monorepo projects where multiple Claude Code agents operate on different packages or services within a single repository. The system enables per-package CLAUDE.md files, isolated agent contexts per package, shared configuration at the monorepo root, and cross-package context references. Agents can operate on specific packages without loading context for unrelated packages, reducing context consumption and preventing cross-package state pollution.

Enables development workflows that span multiple Claude models (Claude 3.5 Sonnet for planning, Claude 3 Opus for execution, etc.) with a plan mode that generates structured task plans before execution and phase-gated execution that validates each phase before proceeding. The system uses the Plan agent to decompose complex tasks into phases, validates each phase's output, and gates progression to the next phase based on validation results. This approach reduces hallucination and improves task success rates by separating planning from execution.