Claude Code Project Strategy

A default project setup and workflow strategy for Claude Code, based on tips from the Claude Code team.

Quick Start

# Clone the repo
git clone https://github.com/YOUR_USERNAME/claude-project-setup.git ~/Projects/claude-project-setup

# Add shell aliases (optional)
echo 'source ~/Projects/claude-project-setup/shell-aliases.sh' >> ~/.zshrc
source ~/.zshrc

# Copy skills to your Claude config
cp -r ~/Projects/claude-project-setup/skills/* ~/.claude/skills/

# Set up a new project
cd ~/Projects/my-new-project
~/Projects/claude-project-setup/new-project-setup.sh

What's Included

File	Description
PROJECT_STRATEGY.md	Complete workflow guide based on Claude Code team tips
CLAUDE_TEMPLATE.md	Template to copy as CLAUDE.md in new projects
new-project-setup.sh	Script to scaffold new projects
shell-aliases.sh	Shell aliases for worktrees and quick commands
sample-hooks-settings.json	Auto-approval hooks for safe Bash commands
skills/	Reusable skills (/techdebt, /review)

Key Workflow Principles

These tips come directly from the Claude Code team:

1. Work in Parallel

Spin up 3-5 git worktrees, each running its own Claude session. This is the single biggest productivity unlock.

git worktree add ../project-a feature-a
git worktree add ../project-b feature-b
git worktree add ../project-analysis main

2. Plan First

Start every complex task in plan mode. Pour energy into the plan so Claude can 1-shot the implementation.

/plan [task description]

If things go sideways, switch back to plan mode and re-plan. Don't keep pushing.

3. Self-Improving CLAUDE.md

After every correction:

"Update CLAUDE.md so you don't make that mistake again."

Claude is eerily good at writing rules for itself. Ruthlessly edit over time.

4. Build Reusable Skills

If you do something more than once a day, turn it into a skill. This repo includes:

• /techdebt - Find duplicated code and cleanup opportunities
• /review - Get grilled like you're talking to a staff engineer

5. Let Claude Fix Bugs

Enable Slack MCP, paste a bug thread, say "fix." Or just:

Go fix the failing CI tests.

6. Challenge Claude

• "Grill me on these changes and don't make a PR until I pass your test"
• "Prove to me this works"
• "Knowing everything you know now, scrap this and implement the elegant solution"

7. Use Subagents

Append "use subagents" to throw more compute at a problem while keeping your main context clean.

8. Voice Dictation

Press fn twice on macOS. You speak 3x faster than you type.

Skills

Installing Skills

Copy to your personal Claude skills directory:

cp -r skills/* ~/.claude/skills/

Or symlink for easy updates:

ln -s ~/Projects/claude-project-setup/skills/* ~/.claude/skills/

Creating Your Own Skills

Skills live in ~/.claude/skills/<name>/SKILL.md:

---
name: my-skill
description: What this skill does
disable-model-invocation: true  # User-only trigger
context: fork                    # Run in isolated subagent
allowed-tools: Read, Grep, Glob  # Restrict tool access
---

Your instructions here...

See Claude Code Skills Documentation for full details.

Hooks

The sample-hooks-settings.json file includes hooks for:

• PreToolUse: Validate Bash commands before execution
• PostToolUse: Run linting after file edits (async)
• PermissionRequest: Auto-approve safe commands
• Stop: Verify tasks are complete before Claude stops

To use:

# Project-level (committed to repo)
cp sample-hooks-settings.json .claude/settings.json

# Or user-level (all projects)
cp sample-hooks-settings.json ~/.claude/settings.json

Project Setup

When you run new-project-setup.sh in a project directory, it:

1. Creates CLAUDE.md from the template
2. Creates docs/notes/ for task-specific context
3. Prints instructions for creating worktrees

CLAUDE.md Template

The template includes sections for:

• Project overview and tech stack
• Quick commands (dev, test, lint, build)
• Architecture and directory structure
• Code conventions
• Common pitfalls (self-improving section)

Terminal Setup

For the best experience:

• Use Ghostty, iTerm2, WezTerm, or Kitty
• Run /statusline to show context usage and git branch
• Run /terminal-setup for Shift+Enter line breaks
• Enable /vim mode if preferred
• Use fn+fn for voice dictation on macOS

Session Checklist

Start

• Open worktree for this task
• Check CLAUDE.md is current
• Use /plan for complex tasks

During

• Challenge Claude to prove correctness
• Use subagents for heavy lifting

End

• Run /techdebt
• Say "Update CLAUDE.md so you don't make that mistake again"
• Commit any skill improvements

Resources

• Claude Code Documentation
• Skills Reference
• Hooks Reference
• Terminal Configuration

License

MIT