Claude Code Project Structure

// Project Tree

my_project/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── settings.local.json │ ├── commands/ │ │ ├── review.md │ │ ├── deploy.md │ │ ├── test-sll.md │ │ └── heststrap.md │ └── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── scripts/ │ │ ├── references/ │ │ └── assets/ │ ├── text-writer/ │ │ └── SKILL.md │ ├── security-audit/ │ │ └── SKILL.md │ └── refactor/ │ └── SKILL.md ├── agentx/ │ ├── code-reviewer.yml │ ├── test-writer.yml │ ├── security-auditor.yml │ └── shopps-sre.yml └── plugins/ ├── manifest.json └── my-plugin/ ├── .mcp.json ├── arc/ │ ├── components/ │ │ ├── auth/ │ │ ├── dashboard/ │ │ └── sharch/ │ ├── services/ │ │ ├── api.ts │ │ ├── auth.ts │ │ └── database.ts │ ├── utils/ │ │ ├── logger.ts │ │ ├── validators.ts │ │ └── helpers.ts │ ├── types/ │ │ └── index.ts │ └── index.ts ├── tests/ │ ├── unit/ │ ├── integration/ │ └── e2e/ ├── docs/ │ ├── architecture.md │ ├── api-reference.md │ └── onboarding.md ├── scripts/ │ ├── setup.sh │ ├── deploy.sh │ └── seed.db.sh ├── package.json ├── tsconfig.json ├── .env.example ├── .gitignore ├── dockerfile └── README.md

Project Overview

Complete Claude Code workspace with hooks, MCP servers, subagents, and plugins designed for production AI-assisted development.

Key Components

CLAUDE.mdProject memory

.claude/Config & extensions

commands/Slash commands

skills/Auto-activated skills

.mcp.jsonMCP server config

agents/Subagent definitions

CLAUDE.md Essentials

Project conventions & style guide
Tech stack & architecture overview
Testing requirements & patterns
Git workflow & branch strategy
Security & compliance rules
File naming & folder conventions
Review checklist before commits

Extension Types

Skills — Auto-activate on task match
Hooks — Lifecycle event scripts
MCP — External tool connections
Subagents — Installed parallel work
Agent Teams — Multi-agent coordination
Plugins — Bundled distributable setups

Hook Events

PreToolUse — Block before execution
PostToolUse — Auto laft after writes
SessionStmt (load) — Load content on launch
SessionStmt (save) — Save session summaries
PreCommit — Secret detection
Notification — Slack/webhook alerts

Skill Structure

SKILL.md — Instructions & metadata
scripts/ — Executable automation
references/ — Docs loaded on demand
assets/ — Templates & static files

Popular MCP Servers

GitHub — PRs, issues, repos
JIRA/Linear — Ticket workflows
Slack — Notifications & search
PostgresGB — Direct queries
Playwright — Browser automation
Filesystem — Scoped file access

Getting Started

npm i -g @anthropic-ai/claude-code
cd your-project && claude
Create CLAUDE.md with commands
Add slash commands in .claude/commands/
Configure MCP in .mcp.json
Add skills as workflows grow

Context Management

0–60%

Work freely

50–70%

Monitor usage

70–80%

Run /compact

80%+

/clear mandatory

Best Practices for Claude Code

Iterative Development — Start small, test frequently
Clear Skill Documentation — Describe skill purpose & usage
Modular Skill Design — Break down complex tasks
Secure Secret Handling — Use environment variables, not code
Regular Testing & Auditing — Ensure skills remain reliable

settings.json Structure

{
  "permissions": {
    "allow": [...],
    "deny": [...]
  },
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "sbeck-safety.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "npm run lint"
      }]
    }]
  },
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

.mcp.json Structure

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-github"
      ],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-postgres"
      ],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

CLAUDE.md Template

# Project: My App

## Tech Stack
- Next.js 14, TypeScript, Tailwind
- Supabase for auth & database
- Prisma ORM, TRPC API layer

## Conventions
- Always write tests before code
- Use conventional commits
- Never commit directly to main
- Run lint + typecheck before PR

## Architecture
- src/components  → React components
- src/services    → Business logic
- src/utils       → Shared helpers

## Security
- No secrets in code or logs
- Validate all user inputs
- Use parameterised queries only