Claude Code Project Structure

Complete workspace architecture with Skills, Hooks, MCP, Subagents & Plugins for production AI-assisted development

PROJECT DIRECTORY SECTION 1: Project Overview SECTION 10: Getting Started

my_project/ Complete Claude Code workspace with Skills, Hooks, MCP, 1. npm i -g @anthropic-ai/claude-code
|- [Link]
|- .claude/ Subagents & Plugins for production AI-assisted development. 2. cd your-project && claude
|- [Link] 3. Create [Link] with conventions
|- [Link]
|- commands/ 4. Add slash commands in .claude/commands/
|- [Link] SECTION 2: Key Components 5. Configure MCP in .[Link]
|- [Link]
|- [Link] [Link] — Project memory & context 6. Add skills as workflows grow
|- [Link]
|- skills/ .claude/ — Config & extensions hub
|- code-review/
|- [Link] commands/ — Slash commands (.md files) SECTION 11: Context Management
|- scripts/ skills/ — Auto-activated workflows
|- references/ 0-50% context — Work freely
|- assets/ .[Link] — MCP server definitions 50-70% — Monitor token usage
|- text-writer/
|- [Link] agents/ — Subagent definitions (.yml) 70-90% — Run /compact
|- security-audit/
plugins/ — Bundled distributions 90%+ — /clear is mandatory
|- [Link]
|- refactor/
|- [Link] SECTION 3: [Link] Essentials
|- agents/
|- [Link] 1. Tech stack & architecture overview
|- [Link] SECTION 12: Security Best Practices
|- [Link] 2. Project conventions & style guide
|- [Link] Secrets — Never store in [Link]
3. Testing requirements & patterns
|- plugins/
.[Link] — Use for env templates
|- [Link] 4. Git workflow & branch strategy
|- my-plugin/ [Link] — Add to .gitignore
|- .[Link] 5. Security & compliance rules
|- src/ PreCommit hook — Enable secret scanning
|- components/
MCP scope — Minimum permissions only
|- auth/ SECTION 4: Extension Types
|- dashboard/
|- shared/ Skills — Auto-activate on task match
|- services/ SECTION 13: [Link] Anti-Patterns
|- [Link] Hooks — Lifecycle event scripts
|- [Link] 500+ lines — Causes context bloat
|- [Link]
MCP — External tool connections
|- utils/
Vague instructions — 'Write good code'
Subagents — Isolated parallel work
|- [Link] Duplicating docs — Link, don't copy
|- [Link] Agent Teams — Multi-agent coordination
|- [Link] No test guidance — Leads to skipped tests
|- types/ Plugins — Bundled distributable setups
|- [Link] No error patterns — Inconsistent handling
|- [Link]
|- tests/ SECTION 5: Hook Events
|- unit/
|- integration/ PreToolUse — Block before execution
|- e2e/ SECTION 14: Debugging & Logging
|- docs/
PostToolUse — Auto-lint after writes
|- [Link]
--verbose — Enable trace logs
SessionStart — Load context on launch
|- [Link] /cost — Monitor token spend
|- [Link] SessionEnd — Save session summaries
|- scripts/ --resume — Replay failed sessions
|- [Link] PreCommit — Secret detection gate
|- [Link] Notification hook — Alert on failures
Notification — Slack/webhook alerts
|- [Link]
|- [Link]
|- [Link]
|- .[Link]
SECTION 6: Skill Structure
|- .gitignore SECTION 15: Pro Tips
|- Dockerfile
[Link] — Instructions & metadata
Subagents — Use for parallel research
|- [Link] scripts/ — Executable automation
[Link] — Keep under 500 lines
references/ — Docs loaded on demand
[Link] — Git-ignore it
COLOR LEGEND
assets/ — Templates & static files
Skills > prompts — For heavy instructions
Key config files Source & doc files Directories
Hooks = deterministic — Skills = AI
SECTION 7: Popular MCP Servers
/init — Auto-generate [Link]
GitHub — PRs, issues, repos
JIRA / Linear — Ticket workflows
Slack — Notifications & search QUICK DO'S & DON'TS
Postgres / DB — Direct queries DO
Playwright — Browser automation
Run /init first
Use bullet points & short headings
SECTION 8: Common Slash Commands
Put guardrails at the top
/review — Run code review on diff Version-control [Link]
/deploy — Build & push to staging Review & prune regularly
/test-all — Execute full test suite
/bootstrap — Scaffold new module DON'T
/document — Auto-generate docs Dump entire style guides into it
@-include huge files needlessly
SECTION 9: Agent Team Patterns Write vague / aspirational rules

Orchestrator — Central task dispatcher Exceed 500 lines without splitting

Pipeline — Sequential handoff chain Ignore repeated mistake patterns

Map-Reduce — Parallel then merge

Supervisor — Monitor & retry failed
Swarm — Dynamic peer delegation

Claude Code Project Structure | Quick Reference Guide