Claude Code Project Setup

Overview

The setup-claude-project.sh script creates an optimized, language-agnostic project structure for development with Claude Code. Version 4.0 takes advantage of mature Claude Code features: hooks, modular rules, path-specific loading, auto-memory, and agent teams.

What This Script Does

• Creates a slim, focused CLAUDE.md (~80 lines of project-specific guidance)
• Scaffolds hooks for shell script fixing and notification alerts
• Sets up modular rules with path-specific frontmatter
• Configures permissions and deny rules in settings.json
• Creates skill definitions with YAML frontmatter
• Provides a language-agnostic CI/CD pipeline template
• Initializes git repository with comprehensive commit

Quick Start

Installation

# Download the script
curl -O https://raw.githubusercontent.com/s220284/claude-code-setup/main/setup-claude-project.sh

# Make it executable
chmod +x setup-claude-project.sh

# Run it
./setup-claude-project.sh MyProject "A web application for task management"

# Or run interactively
./setup-claude-project.sh

After Setup

# Navigate to your project
cd MyProject

# Customize rules for your language
edit .claude/rules/code-style.md
edit .claude/rules/testing.md

# Let Claude analyze your codebase
claude
> /init

# Claude automatically loads CLAUDE.md and rules at session start

What's New in v4.0

Files Changed in v4.0

Files Created

v4.0 creates a focused set of files, each with a clear purpose:

Core Documentation

Configuration

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(git status)", "Bash(git diff *)", "Bash(git log *)"],
    "deny": ["Read(.env)", "Read(.env.*)"]
  },
  "hooks": {
    "PostToolUse": [{ "matcher": "Write", "hooks": [{ "type": "command", "command": "..." }] }],
    "Notification": [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }]
  }
}

Rules

Skills

CI/CD

Hooks

Claude Code's hook system lets you run commands automatically in response to events. Hooks are configured in .claude/settings.json and execute shell commands when triggered.

How Hooks Work

Hooks fire on specific events during a Claude Code session:

Each hook entry has a matcher (which tool or pattern to match) and an array of hook commands to run.

Scaffolded Hooks

{
  "matcher": "Write",
  "hooks": [{
    "type": "command",
    "command": "jq -r '.tool_input.file_path // empty' | xargs -I{} sh -c 'case \"{}\" in *.sh) sed -i \"\" \"s/\\r$//\" \"{}\" && chmod +x \"{}\" ;; esac'"
  }]
}

{
  "matcher": "",
  "hooks": [{
    "type": "command",
    "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"' 2>/dev/null || true"
  }]
}

Adding More Hooks

To add your own hooks, edit .claude/settings.json and add entries to the appropriate event array. Examples of useful custom hooks:

• Auto-format on save: Run prettier or black after Write
• Lint check: Run linter after file modifications
• Sound alert: Play a sound on Notification events
• Slack integration: Post to a channel when Claude finishes a task

Rules

The .claude/rules/ directory contains modular rule files that Claude loads automatically. Rules can be scoped to specific file paths using YAML frontmatter.

How Rules Work

1. Place .md files in .claude/rules/
2. Claude loads all rules at session start
3. Rules with paths: frontmatter only activate when working on matching files
4. Rules without frontmatter apply globally

Path-Specific Rules

Use YAML frontmatter with paths: to scope rules to specific directories:

---
paths:
  - "src/**"
---

# Code Style

- Use consistent naming conventions
- Keep functions focused
- Use environment variables for configuration

This rule only loads when Claude is working on files matching src/**.

Scaffolded Rules

Adding More Rules

Create new .md files in .claude/rules/ for different concerns:

# Example: .claude/rules/api-design.md
---
paths:
  - "src/api/**"
  - "src/routes/**"
---

# API Design Rules

- Use RESTful conventions
- Always validate request bodies
- Return consistent error formats
- Include pagination for list endpoints

Global Plugins & Skills

v4.0 documents available global plugins directly in CLAUDE.md. These are pre-installed capabilities you can use across all projects.

Available Global Plugins

Agent Teams

Skill Shortcuts

Common workflow commands available in any project:

Development Workflow

The Three Pillars

Every production code change MUST include ALL THREE:

Session Continuity

v4.0 relies on Claude Code's auto-memory for session continuity. Claude automatically remembers context from previous sessions without manual logging.

Manual Tracking (Optional)

For projects that need explicit status tracking, PROJECT_STATE.md provides a system status snapshot. Update it after completing features or deployments.

Cloud-First Development

# WRONG
path = "/Users/username/projects/myapp"

# CORRECT
path = env_var("APP_ROOT", "/app")  # Use your language's equivalent

Quick Reference

Project Structure

MyProject/
├── CLAUDE.md                  # Main session reference (~80 lines)
├── CLAUDE.local.md            # Personal overrides (gitignored)
├── PROJECT_STATE.md           # System status
├── src/                       # Source code
├── tests/                     # Test files
├── docs/                      # Documentation
├── scripts/                   # Utility scripts
├── .claude/
│   ├── settings.json          # Permissions, hooks, MCP config
│   ├── settings.local.json    # Personal overrides (gitignored)
│   ├── rules/                 # Modular rule files
│   │   ├── code-style.md      # Code conventions (src/**)
│   │   └── testing.md         # Testing standards (tests/**)
│   ├── hooks/                 # Custom hook scripts
│   └── skills/
│       └── commit/
│           └── SKILL.md       # Commit skill (with frontmatter)
└── .github/
    └── workflows/
        └── ci.yml             # CI pipeline template

Key Files

Resources

• Claude Code Documentation
• MCP Specification
• MCP Server Registry
• GitHub Repository