Setting Up Claude-Craft on a New Project

This step-by-step tutorial will guide you through installing Claude-Craft on a brand new project. By the end, you'll have a fully configured development environment with AI-powered assistance.

Time required: ~10 minutes

---

Table of Contents

1. Prerequisites Checklist
2. Create Your Project Directory
3. Initialize Git Repository
4. Choose Your Technology Stack
5. Install Claude-Craft
   • Method A: NPX (No Clone Required)
   • Method B: Makefile (More Control)
6. Verify Installation
7. Configure Project Context
8. First Launch with Claude Code
9. Test Your Setup
10. Troubleshooting
11. Next Steps

---

1. Prerequisites Checklist

Before starting, make sure you have the following installed:

Required

• [ ] Terminal/Command Line - Any terminal application
• [ ] Node.js 16+ - Required for NPX installation
• [ ] Git - For version control
• [ ] Claude Code - The AI coding assistant

Verify Your Prerequisites

Open your terminal and run these commands:

# Check Node.js version (should be 16 or higher)
node --version

Expected output: v16.x.x or higher (e.g., v20.10.0)

# Check Git version
git --version

Expected output: git version 2.x.x (e.g., git version 2.43.0)

# Check Claude Code is installed
claude --version

Expected output: Version number (e.g., 1.0.x)

Install Missing Prerequisites

If any command above fails:

Node.js: Download from nodejs.org or use:

# macOS with Homebrew
brew install node

# Ubuntu/Debian
sudo apt install nodejs npm

Git: Download from git-scm.com or use:

# macOS with Homebrew
brew install git

# Ubuntu/Debian
sudo apt install git

Claude Code: Follow the official installation guide

---

2. Create Your Project Directory

Choose where you want to create your project and run:

# Create project directory
mkdir ~/my-project

# Navigate into it
cd ~/my-project

Verify: Run pwd to confirm you're in the right directory:

pwd

Expected output: /home/yourname/my-project (or /Users/yourname/my-project on macOS)

---

3. Initialize Git Repository

Claude-Craft works best with Git-tracked projects:

# Initialize Git repository
git init

Expected output:

Initialized empty Git repository in /home/yourname/my-project/.git/

Verify: Check that .git folder exists:

ls -la

You should see a .git/ directory in the output.

---

4. Choose Your Technology Stack

Claude-Craft supports multiple technology stacks. Choose the one that matches your project:

Stack	Best For	Command Flag
Symfony	PHP APIs, Web apps, Backend services	--tech=symfony
Flutter	Mobile apps (iOS/Android)	--tech=flutter
Python	APIs, Data services, ML backends	--tech=python
React	Web SPAs, Dashboards	--tech=react
React Native	Cross-platform mobile apps	--tech=reactnative
Common only	Any project (generic rules)	--tech=common

Choose your language:

Language	Flag
English	--lang=en
French	--lang=fr
Spanish	--lang=es
German	--lang=de
Portuguese	--lang=pt

---

5. Install Claude-Craft

You have two installation methods. Choose the one that fits your needs:

Method A: NPX (No Clone Required)

Best for: Quick setup, first-time users, CI/CD pipelines

This method downloads and runs Claude-Craft directly without cloning the repository.

# Replace 'symfony' with your tech stack and 'en' with your language
npx @the-bearded-bear/claude-craft install ~/my-project --tech=symfony --lang=en

Example for a French Flutter project:

npx @the-bearded-bear/claude-craft install ~/my-project --tech=flutter --lang=fr

Expected output:

Installing Claude-Craft rules...
  ✓ Common rules installed
  ✓ Symfony rules installed
  ✓ Agents installed
  ✓ Commands installed
  ✓ Templates installed
  ✓ Checklists installed
  ✓ CLAUDE.md generated

Installation complete! Run 'claude' in your project directory to start.

If you see an error:

• npm ERR! 404 → Check your internet connection
• EACCES: permission denied → Run with sudo or fix npm permissions
• command not found: npx → Install Node.js first

---

Method B: Makefile (More Control)

Best for: Customization, contributing to Claude-Craft, offline use

This method requires cloning the Claude-Craft repository first.

Step B.1: Clone Claude-Craft

# Clone to a permanent location
git clone https://github.com/TheBeardedBearSAS/claude-craft.git ~/claude-craft

Expected output:

Cloning into '/home/yourname/claude-craft'...
remote: Enumerating objects: XXX, done.
...
Resolving deltas: 100% (XXX/XXX), done.

Step B.2: Run Installation

# Navigate to Claude-Craft directory
cd ~/claude-craft

# Install rules to your project
# Replace 'symfony' with your tech and 'en' with your language
make install-symfony TARGET=~/my-project LANG=en

Examples for other stacks:

# Flutter in French
make install-flutter TARGET=~/my-project LANG=fr

# React in Spanish
make install-react TARGET=~/my-project LANG=es

# Python in German
make install-python TARGET=~/my-project LANG=de

# Common rules only (any project)
make install-common TARGET=~/my-project LANG=en

Expected output:

Installing Symfony rules to /home/yourname/my-project...
  Creating .claude directory...
  Copying rules... done
  Copying agents... done
  Copying commands... done
  Copying templates... done
  Copying checklists... done
  Generating CLAUDE.md... done

Installation complete!

---

6. Verify Installation

After installation, verify everything is in place:

# Navigate to your project
cd ~/my-project

# List the .claude directory
ls -la .claude/

Expected output:

total XX
drwxr-xr-x  8 user user 4096 Jan 12 10:00 .
drwxr-xr-x  3 user user 4096 Jan 12 10:00 ..
-rw-r--r--  1 user user 2048 Jan 12 10:00 CLAUDE.md
drwxr-xr-x  2 user user 4096 Jan 12 10:00 agents
drwxr-xr-x  2 user user 4096 Jan 12 10:00 checklists
drwxr-xr-x  4 user user 4096 Jan 12 10:00 commands
drwxr-xr-x  2 user user 4096 Jan 12 10:00 rules
drwxr-xr-x  2 user user 4096 Jan 12 10:00 templates

Verify Each Component

# Count rules (should be 15-25 depending on stack)
ls .claude/rules/*.md | wc -l

# Count agents (should be 5-12)
ls .claude/agents/*.md | wc -l

# Count commands (should have subdirectories)
ls .claude/commands/

If files are missing:

• Re-run the installation command
• Check that you have write permissions to the directory
• See Troubleshooting section

---

7. Configure Project Context

The most important file to customize is your project context. This tells Claude about YOUR specific project.

Option A: Interactive Setup (Recommended)

Use the built-in command to auto-detect your stack and answer targeted questions:

# Start Claude Code
claude

# Run the setup command
/common:setup-project-context

The command will:

1. Auto-detect your tech stack, framework, database, and CI/CD
2. Ask questions for missing information (app type, domain, users, compliance)
3. Generate a complete .claude/rules/00-project-context.md file
4. Suggest next steps (agents to run, sections to complete)

Modes available:

• (default) - Balanced detection + essential questions
• --auto - Maximum auto-detection, minimal questions
• --full - Comprehensive questionnaire including goals and glossary

Option B: Manual Configuration

If you prefer to configure manually, open the file directly:

# Open in your editor (replace 'nano' with 'code', 'vim', etc.)
nano .claude/rules/00-project-context.md

Sections to Customize

Find and update these sections:

## Project Overview
- **Name**: [Your project name]
- **Description**: [What does your project do?]
- **Type**: [API / Web App / Mobile App / CLI / Library]

## Technical Stack
- **Framework**: [e.g., Symfony 7.0, Flutter 3.16]
- **Language Version**: [e.g., PHP 8.3, Dart 3.2]
- **Database**: [e.g., PostgreSQL 16, MySQL 8]

## Team Conventions
- **Coding Style**: [e.g., PSR-12, Effective Dart]
- **Branch Strategy**: [e.g., GitFlow, Trunk-based]
- **Commit Format**: [e.g., Conventional Commits]

## Project-Specific Rules
- [Add any custom rules for your project]

Example: E-commerce API

## Project Overview
- **Name**: ShopAPI
- **Description**: RESTful API for e-commerce platform
- **Type**: API

## Technical Stack
- **Framework**: Symfony 7.0 with API Platform
- **Language Version**: PHP 8.3
- **Database**: PostgreSQL 16

## Team Conventions
- **Coding Style**: PSR-12
- **Branch Strategy**: GitFlow
- **Commit Format**: Conventional Commits

## Project-Specific Rules
- All prices must be stored in cents (integer)
- Use UUID v7 for all entity identifiers
- Soft delete required for all entities

Save the file when done (in nano: Ctrl+O, then Enter, then Ctrl+X).

---

8. First Launch with Claude Code

Now let's start Claude Code and verify everything works:

# Make sure you're in your project directory
cd ~/my-project

# Launch Claude Code
claude

You should see Claude Code start with a prompt.

Test That Rules Are Active

Type this message to Claude:

What rules and guidelines are you following for this project?

Claude should respond mentioning:

• Project context from 00-project-context.md
• Architecture rules
• Testing requirements
• Technology-specific guidelines

If Claude doesn't mention your rules:

• Make sure you're in the project directory (not a subdirectory)
• Check that .claude/ directory exists
• Restart Claude Code

---

9. Test Your Setup

Run these quick tests to verify everything works:

Test 1: Check Available Commands

Ask Claude:

List all available slash commands for this project

Expected: Claude should list commands like /common:analyze-feature, /{tech}:generate-crud, etc.

Test 2: Use an Agent

Try invoking an agent:

@tdd-coach Help me understand how to write tests for this project

Expected: Claude should respond as the TDD Coach agent with testing guidance.

Test 3: Run a Command

Try a simple command:

/common:pre-commit-check

Expected: Claude should run a pre-commit quality check (may report no changes if project is empty).

Validation Checklist

• [ ] Claude Code starts without errors
• [ ] Claude mentions project rules when asked
• [ ] Slash commands are recognized
• [ ] Agents respond with specialized knowledge
• [ ] Project context is reflected in responses

---

10. Troubleshooting

Installation Issues

Problem: Permission denied during installation

# Solution 1: Fix directory permissions
chmod 755 ~/my-project

# Solution 2: Run with sudo (not recommended for npm)
sudo npx @the-bearded-bear/claude-craft install ...

Problem: Command not found: npx

# Solution: Install Node.js
brew install node  # macOS
sudo apt install nodejs npm  # Ubuntu/Debian

Problem: ENOENT: no such file or directory

# Solution: Create the target directory first
mkdir -p ~/my-project

Runtime Issues

Problem: Claude doesn't see the rules

• Verify you're in the project root: pwd
• Check .claude/ exists: ls -la .claude/
• Restart Claude Code: exit and run claude again

Problem: Commands not recognized

• Check commands directory: ls .claude/commands/
• Verify file permissions: ls -la .claude/commands/*.md

Problem: Agents not responding

• Check agents directory: ls .claude/agents/
• Use correct syntax: @agent-name message

Getting Help

If you're still stuck:

1. Check the Troubleshooting Guide
2. Search GitHub Issues
3. Open a new issue with your error message

---

11. Next Steps

Congratulations! Your Claude-Craft environment is ready. Here's what to do next:

Immediate Next Steps

1. Commit your configuration:

   git add .claude/
   git commit -m "feat: add Claude-Craft configuration"

2. Start building your project with AI assistance

3. Read the Feature Development Guide to learn the TDD workflow

Recommended Reading

Guide	Description
Feature Development	TDD workflow with agents and commands
Bug Fixing	Diagnostic and regression testing
Tools Reference	Multi-account, StatusLine utilities
Adding to Existing Project	For your other projects

Quick Reference Card

# Launch Claude Code
claude

# Common agents
@api-designer      # API design
@database-architect # Database schema
@tdd-coach         # Testing help
@{tech}-reviewer   # Code review

# Common commands
/common:analyze-feature     # Analyze requirements
/{tech}:generate-crud       # Generate CRUD code
/common:pre-commit-check    # Quality check
/common:security-audit      # Security review

---

← Previous: Backlog Management | Next: Adding to Existing Project →