Home
cd ../playbooks
Developer ToolsIntermediate

Claude Code Project Architecture

A setup guide for structuring a Claude Code project's full toolkit — layered CLAUDE.md context, slash commands, sub-agents, skills, hooks, and plugins — each used for what it's actually good at instead of one mechanism for everything.

20 minutes
By Product TalkSource
#claude-code-basics#claude-md#slash-commands#sub-agents#skills#hooks#plugins#project-setup#architecture

Your CLAUDE.md has grown to 400 lines of everything you might ever need, your slash commands do the job of what should be a shared skill, and you've never touched a hook — because nobody explained which of the six building blocks is actually right for which job.

Who it's for: Claude Code users setting up a new project properly instead of ad-hoc, teams standardizing how they structure CLAUDE.md/commands/agents/skills across projects, power users who've been reaching for the same mechanism (usually a bloated CLAUDE.md) for every use case, anyone who's heard of hooks or skills but never actually set one up, developers wanting a mental model for when to use an agent vs. a skill vs. a plugin

Example

"Help me set up this project's Claude Code architecture" → A three-layer context system (global preferences, project preferences, on-demand reference files), a slash command for the recurring task you actually invoke by hand, a sub-agent for research work that needs its own context window, and a SessionStart hook that calculates the real current date instead of relying on the model's potentially stale sense of 'today'

CLAUDE.md Template

New here? 3-minute setup guide → | Already set up? Copy the template below.

Or install from your terminal:
npx ccplaybooks add claude-code-project-architecture
# Claude Code Project Architecture

## Your Role

You help set up a Claude Code project's full toolkit correctly from the start — not just a CLAUDE.md file, but the whole system: layered context, slash commands, sub-agents, skills, hooks, and plugins, each used for what it's actually good at rather than reaching for the same mechanism every time. Mastering file organization and context layering is the foundation everything else builds on.

---

## The Six Building Blocks

### 1. Markdown Files for Context Management

Get new playbooks like this one

One email a week with new Claude Code workflows. Free, like everything here.

No spam. Unsubscribe anytime.

README.md

What This Does

A mental model — and setup guide — for Claude Code's six building blocks (layered CLAUDE.md context, slash commands, sub-agents, skills, hooks, plugins/marketplaces) so each gets used for what it's actually built for, rather than defaulting to one bloated CLAUDE.md for everything. Covers when a sub-agent earns its own context window vs. when a simple slash command is enough, what actually distinguishes a skill from a plugin, and where hooks fit as guaranteed-to-run automation rather than a suggestion the model might follow.


Quick Start

Step 1: Create a Project Folder

mkdir claude-code-setup && cd claude-code-setup

Step 2: Download the Template

Click Download above, then:

mv ~/Downloads/CLAUDE.md ./

Step 3: Set Up the Architecture

claude

Then say: "Help me set up this project's Claude Code architecture — I want [describe your recurring workflows]"


The Six Building Blocks

Block Use for Lives in
Layered CLAUDE.md Persistent context, kept lean ~/.claude/CLAUDE.md (global), project/CLAUDE.md (project)
Slash commands Workflows you trigger yourself, explicitly ~/.claude/commands or project/.claude/commands
Sub-agents Work needing its own context window, or parallel execution ~/.claude/agents or project/.claude/agents
Skills Instructions + bundled code, shared across Claude web/Desktop/Code SKILL.md inside a named directory
Hooks Automation guaranteed to run at a specific lifecycle point Configured via /hooks
Plugins/marketplaces Bundled commands+agents+skills+hooks, installable from a git repo /plugin marketplace add <repo>

Tips & Best Practices

  • Keep CLAUDE.md lean; push reference material to separate files loaded on demand. A file that tries to anticipate every possible need stops being read carefully — this is the same principle as progressive disclosure, applied at the whole-project level rather than within a single file.
  • Reach for a sub-agent specifically for context-window isolation or genuine parallelism — not as a default wrapper for every sub-task. Parallel agents save wall-clock time but burn tokens fast, especially noticeable on lighter usage tiers.
  • Skills don't reliably self-invoke yet. Be explicit ("use your [X] skill") rather than assuming the model will pick the right skill automatically just because it's relevant.
  • Hooks are for things that must happen, not things that usually happen. A SessionStart hook calculating the real current date is a good example — anything a workflow genuinely can't function without belongs here, not in a prompt instruction that's merely a strong suggestion.
  • Never install a plugin without reviewing what it does. Structurally a plugin is just someone else's git repo — treat installing one with the same caution as running any third-party script on your machine.

Limitations

  • LLM behavior is non-deterministic even with precise instructions — design workflows (diff review before bulk changes, explicit verification steps) that catch drift rather than assuming perfect consistency run to run
  • Context compacts automatically around 75% fullness — a workflow depending on very long uninterrupted context should account for this rather than assume unlimited room
  • This is an architectural mental model, not a specific task's CLAUDE.md — pair it with a task-specific playbook for the actual workflow you're building, once the project structure itself is set up

$Related Playbooks

Developer Tools

Claude Model Migration Assistant

Migrate code and prompts between Claude models — update model strings, remove incompatible beta headers, and adjust prompts only for reported behavioral differences.

5 minutes
Beginner
Developer Tools

Claude Code Plugin Builder

End-to-end guided workflow for building Claude Code plugins — structure, commands, agents, skills, hooks, and MCP integration — with a validation checklist before you distribute.

15 minutes
Advanced
Developer Tools

CLAUDE.md Progressive Disclosurer

Slim down and restructure a bloated CLAUDE.md (or AGENTS.md) using progressive disclosure — move low-frequency detail to Level 2 references while keeping Level 1 lean, with zero information loss.

15 minutes
Intermediate
Developer Tools

Claude Usage Analyst

Analyze Claude Code token usage, cost, quota burn, model mix, and cache read/write using ccusage evidence — and explain in human terms why your quota got exhausted.

10 minutes
Beginner
Developer Tools

CLI Demo Generator

Generate professional animated CLI demos as GIFs using VHS terminal recordings — with self-bootstrapping setup, output filtering, and frame-level verification.

15 minutes
Intermediate
Developer Tools

Cloudflare Troubleshooting

Investigate and resolve Cloudflare issues with API-driven evidence — ERR_TOO_MANY_REDIRECTS, SSL mode mismatches, DNS, and proxy problems — instead of guessing.

15 minutes
Intermediate
Developer Tools

Changelog Generator

Generate release notes from git commits, updates, or feature lists

10 minutes
Advanced
Developer Tools

CI/CD Pipeline Generator

Create production-ready CI/CD pipeline configurations for GitHub Actions, GitLab CI, CircleCI, and Jenkins with deployment to Vercel, Netlify, or AWS.

15 minutes
Intermediate
Developer Tools

Codebase Documenter

Create comprehensive, beginner-friendly documentation for codebases including READMEs, architecture guides, API docs, and code comments.

10 minutes
Beginner
Developer Tools

Contribution PR Review

Review an external contributor's PR the way an open-source maintainer should — check automated bot security findings first (across every channel they might post to), watch specifically for suspicious AGENTS.md or workflow-permission changes, scale size and test-coverage expectations by contributor experience, and separate intent/scope alignment from code quality that bots already covered.

10 minutes
Intermediate
Developer Tools

Datadog Error Triage to PR

Take Datadog Error Tracking issues from raw occurrence counts to a reviewable, tested PR — a five-class bug taxonomy that filters out infra noise and deploy-skew before ranking, a recency premium that catches fresh regressions early, a mandatory approval gate before any fix is written, and a test-first fix workflow that generalizes past the one reported occurrence.

10 minutes
Advanced
Developer Tools

Documentation Review System

Mode-routed documentation review that diagnoses a page against its doc type and seven quality dimensions before touching a sentence, then picks the intervention level — maintenance, improve, rewrite, author, or strategy — that actually matches what's wrong.

10 minutes
Intermediate

Browse all Developer Tools playbooks →