The 3-Tier Documentation System

The heart of the Claude Code Development Kit is its unique 3-tier documentation architecture. This system is designed specifically for AI-assisted development, solving common problems like context overload, high maintenance, and stale content.

Why a 3-Tier System?

Traditional documentation is often a single, large corpus of text. For an AI, this is inefficient. It has to process the entire set for even simple tasks, leading to high token costs and slow response times. The 3-tier system organizes knowledge hierarchically, allowing the AI to load only the context it needs for a given task.

The Three Tiers

The architecture is organized by stability and scope:

Tier 1: Foundation (Rarely Changes)

This tier contains project-wide standards, core architectural decisions, and the technology stack. It provides a consistent baseline for every AI session. - File: CLAUDE.md (master context), files in docs/ai-context/. - Content: Coding standards, security protocols, system-wide patterns, tech stack. - When it Loads: Automatically loaded for every command and sub-agent.

Tier 2: Component (Occasionally Changes)

This tier defines the architectural charter for a major component of your application (e.g., the backend, the frontend). It describes boundaries, high-level patterns, and integration points without getting into feature-specific details. - File: CONTEXT.md at the root of a component directory (e.g., backend/CONTEXT.md). - Content: Component-specific architecture, major subsystem organization, key dependencies. - When it Loads: When a command operates within that specific component.

Tier 3: Feature (Frequently Changes)

This is the most granular tier, co-located with the code it describes. It contains implementation details, technical specifics, and local patterns that evolve as features are built. - File: CONTEXT.md within a feature-specific subdirectory (e.g., backend/src/api/CONTEXT.md). - Content: Implementation patterns, key file structures, error handling strategies. - When it Loads: When a command targets a specific feature or subsystem.

Benefits Over Traditional Systems

Feature	Traditional Documentation	3-Tier System
Context Loading	AI loads entire corpus for every task.	Commands load only relevant tiers based on complexity.
Maintenance Efficiency	A single code change can require multiple doc updates.	Updates are isolated to the appropriate, co-located tier.
AI Performance	AI struggles to find relevant information in noise.	The structured hierarchy guides the AI to precise context.

Integration with Kit Commands

Commands like /update-docs and /create-docs are designed to work with this structure, making it easy to keep your AI's knowledge base synchronized with your code. The system ensures that simple tasks remain simple (and cheap in tokens), while complex tasks get the detailed context they need to succeed.