Project Creation Guide

This guide walks you through setting up a new project with Claude-Craft, from choosing your technology stack to configuring your development environment.

---

Table of Contents

1. Choosing Your Technology
2. Installation Methods
3. Single Technology Projects
4. Monorepo Projects
5. Post-Installation Configuration
6. Project Startup Checklist

---

Choosing Your Technology

Technology Comparison

Technology	Best For	Architecture	Key Features
Symfony	Backend APIs, Web apps	Clean Architecture + DDD	Doctrine, Messenger, API Platform
Flutter	Mobile apps	Feature-based + BLoC	Material/Cupertino, State management
Python	APIs, Data services	Layered architecture	FastAPI, async/await, type hints
React	Web SPAs	Feature-based + Hooks	State management, accessibility
React Native	Cross-platform mobile	Navigation-based	Native modules, platform-specific code

Choosing Based on Project Type

Project Type	Recommended Stack
REST API	Symfony or Python
Mobile app (native feel)	Flutter
Mobile app (JS team)	React Native
Web SPA	React
Full-stack web	Symfony + React
Full-stack mobile	Symfony + Flutter
Microservices	Python (FastAPI)

Common Combinations

Web Application:     Symfony (backend) + React (frontend)
Mobile Application:  Symfony (API) + Flutter (mobile)
Full Platform:       Symfony (API) + React (web) + Flutter (mobile)
Data Platform:       Python (API) + React (dashboard)

---

Installation Methods

Claude-Craft offers multiple installation methods to fit different workflows.

Method 1: Makefile (Recommended)

The simplest and most flexible approach.

# Basic syntax
make install-{technology} TARGET=path LANG=language

# Examples
make install-symfony TARGET=./backend LANG=en
make install-flutter TARGET=./mobile LANG=fr
make install-python TARGET=./api LANG=es
make install-react TARGET=./frontend LANG=de
make install-reactnative TARGET=./app LANG=pt

Available Options

Option	Description	Example
TARGET	Installation path	TARGET=~/projects/myapp
LANG	Language code	LANG=fr
OPTIONS	Additional flags	OPTIONS="--force --backup"

Option Flags

# Preview changes without applying
make install-symfony TARGET=./backend OPTIONS="--dry-run"

# Force overwrite existing files (creates backup)
make install-symfony TARGET=./backend OPTIONS="--force"

# Create backup before installation
make install-symfony TARGET=./backend OPTIONS="--backup"

# Interactive mode (prompts for project info)
make install-symfony TARGET=./backend OPTIONS="--interactive"

# Update only (preserve project-specific files)
make install-symfony TARGET=./backend OPTIONS="--update"

Method 2: Direct Script Execution

Run installation scripts directly for more control.

# Syntax
./Dev/scripts/install-{technology}-rules.sh [OPTIONS] [TARGET]

# Examples
./Dev/scripts/install-symfony-rules.sh --lang=fr ~/my-project
./Dev/scripts/install-flutter-rules.sh --lang=en --dry-run .
./Dev/scripts/install-python-rules.sh --force --backup ~/api

Script Options

--lang=XX       # Language (en, fr, es, de, pt)
--install       # Full installation mode
--update        # Update common rules only
--force         # Overwrite all files
--dry-run       # Preview without changes
--backup        # Create backup first
--interactive   # Prompt for project info
--help          # Show help
--version       # Show version

Method 3: YAML Configuration

Best for monorepos and multi-project setups.

# Create configuration
cp claude-projects.yaml.example claude-projects.yaml

# Edit configuration
nano claude-projects.yaml

# Validate configuration
make config-validate CONFIG=claude-projects.yaml

# Install specific project
make config-install CONFIG=claude-projects.yaml PROJECT=my-project

# Install all projects
make config-install-all CONFIG=claude-projects.yaml

---

Single Technology Projects

Symfony Project

# Create project directory
mkdir ~/my-symfony-api
cd ~/my-symfony-api
composer create-project symfony/skeleton .
git init

# Install Claude-Craft rules
make install-symfony TARGET=. LANG=fr

# Verify installation
ls -la .claude/

Installed content:

• 21 Symfony-specific rules (Clean Architecture, DDD, CQRS, etc.)
• 10+ Symfony commands (/symfony:generate-crud, /symfony:check-compliance, etc.)
• Symfony reviewer agent
• Code templates (Service, ValueObject, Aggregate, etc.)
• Quality checklists

Flutter Project

# Create project
flutter create my_flutter_app
cd my_flutter_app
git init

# Install Claude-Craft rules
make install-flutter TARGET=. LANG=en

# Verify
ls -la .claude/

Installed content:

• 13 Flutter-specific rules (BLoC, state management, testing)
• 10 Flutter commands
• Flutter reviewer agent
• Widget and BLoC templates
• Quality checklists

Python Project

# Create project
mkdir ~/my-python-api
cd ~/my-python-api
python -m venv venv
git init

# Install Claude-Craft rules
make install-python TARGET=. LANG=en

# Verify
ls -la .claude/

Installed content:

• 12 Python-specific rules (FastAPI, async, typing)
• 10 Python commands
• Python reviewer agent
• Service and API templates
• Quality checklists

React Project

# Create project
npx create-react-app my-react-app
cd my-react-app

# Install Claude-Craft rules
make install-react TARGET=. LANG=en

# Verify
ls -la .claude/

React Native Project

# Create project
npx react-native init MyApp
cd MyApp

# Install Claude-Craft rules
make install-reactnative TARGET=. LANG=en

# Verify
ls -la .claude/

---

Monorepo Projects

Understanding Monorepo Structure

A typical monorepo might look like:

my-platform/
├── backend/          # Symfony API
├── web/              # React frontend
├── mobile/           # Flutter app
├── shared/           # Shared types/contracts
└── claude-projects.yaml

YAML Configuration Structure

# claude-projects.yaml

settings:
  default_lang: "fr"              # Default language for all projects
  claude_craft_path: "~/claude-craft"  # Path to claude-craft (optional)

projects:
  - name: "my-platform"
    description: "Full-stack SaaS platform"
    path: "~/Projects/my-platform"
    modules:
      - name: "api"
        path: "backend"
        technologies: ["symfony"]
        lang: "en"                # Override default language

      - name: "web"
        path: "web"
        technologies: ["react"]

      - name: "mobile"
        path: "mobile"
        technologies: ["flutter"]

Configuration Fields

Project Level

Field	Required	Description
name	Yes	Project identifier
description	No	Project description
path	Yes	Absolute path to project root
lang	No	Language override
modules	No	List of modules (for monorepos)
technologies	No	Technologies if no modules

Module Level

Field	Required	Description
name	Yes	Module identifier
path	Yes	Relative path from project root
technologies	Yes	List of technologies
lang	No	Language override
skip_common	No	Skip common rules (default: false)

Installation Commands

# Validate configuration
make config-validate CONFIG=claude-projects.yaml

# List configured projects
make config-list CONFIG=claude-projects.yaml

# Install specific project
make config-install CONFIG=claude-projects.yaml PROJECT=my-platform

# Install specific module
make config-install CONFIG=claude-projects.yaml PROJECT=my-platform MODULE=api

# Dry-run to preview
make config-install CONFIG=claude-projects.yaml PROJECT=my-platform OPTIONS="--dry-run"

# Install all projects
make config-install-all CONFIG=claude-projects.yaml

Real-World Examples

Example 1: SaaS Platform

projects:
  - name: "saas-platform"
    path: "~/Projects/saas"
    modules:
      - name: "api"
        path: "services/api"
        technologies: ["symfony"]
      - name: "admin"
        path: "apps/admin"
        technologies: ["react"]
      - name: "mobile"
        path: "apps/mobile"
        technologies: ["flutter"]

Example 2: Microservices

projects:
  - name: "microservices"
    path: "~/Projects/micro"
    modules:
      - name: "gateway"
        path: "gateway"
        technologies: ["python"]
      - name: "users"
        path: "services/users"
        technologies: ["symfony"]
      - name: "orders"
        path: "services/orders"
        technologies: ["symfony"]
      - name: "analytics"
        path: "services/analytics"
        technologies: ["python"]

Example 3: Multiple Independent Projects

settings:
  default_lang: "fr"

projects:
  - name: "client-a"
    path: "~/Clients/client-a"
    technologies: ["symfony", "react"]

  - name: "client-b"
    path: "~/Clients/client-b"
    technologies: ["flutter"]
    lang: "en"

  - name: "internal-tool"
    path: "~/Internal/tool"
    technologies: ["python"]

---

Post-Installation Configuration

After installation, configure these files for your specific project.

1. Project Context (rules/00-project-context.md)

This is the most important file to customize. It tells Claude about your specific project.

Option A: Interactive Setup (Recommended)

Run this command in Claude Code to auto-detect your stack and answer targeted questions:

/common:setup-project-context

Option B: Manual Configuration

Edit the file directly with your project details:

# Project Context

## Project Information
- **Name**: My Awesome API
- **Type**: REST API for e-commerce platform
- **Team Size**: 3 developers

## Technical Stack
- PHP 8.3 with Symfony 7.0
- PostgreSQL 16
- Redis for caching
- RabbitMQ for messaging

## Conventions
- PSR-12 coding standard
- Strict typing enabled
- English code, French documentation

## Constraints
- RGPD compliance required
- Must support multi-tenant architecture
- Maximum response time: 200ms

## External Dependencies
- Stripe for payments
- SendGrid for emails
- S3 for file storage

2. Main Configuration (CLAUDE.md)

The CLAUDE.md file in .claude/ directory contains the main configuration. Key sections to review:

# Project Configuration

## Language Settings
- Code: English
- Documentation: French
- Comments: English

## Architecture
Clean Architecture + DDD + Hexagonal

## Quality Requirements
- Test coverage: 80%+
- PHPStan level: 9
- No critical security issues

## Docker Requirements
All commands must use Docker via make targets.

3. Agent Configuration

Review installed agents in .claude/agents/ and customize if needed:

ls .claude/agents/
# api-designer.md
# database-architect.md
# symfony-reviewer.md
# tdd-coach.md
# ...

---

Project Startup Checklist

Use this checklist when setting up a new project:

Pre-Installation

• [ ] Project directory created
• [ ] Git repository initialized
• [ ] Technology stack decided
• [ ] Language preference chosen

Installation

• [ ] Claude-Craft rules installed
• [ ] Installation verified (ls .claude/)
• [ ] No errors in installation output

Configuration

• [ ] 00-project-context.md customized with project details
• [ ] CLAUDE.md reviewed and adjusted
• [ ] Team conventions documented
• [ ] Constraints and requirements listed

Verification

• [ ] Claude Code started in project directory
• [ ] Commands available (try /symfony:check-compliance)
• [ ] Agents responding (try @symfony-reviewer hello)

Team Setup

• [ ] .claude/ directory committed to git
• [ ] Team members informed of available commands
• [ ] README updated with Claude-Craft usage info

---

Common Patterns

Installing Common Rules Only

For shared libraries or packages that don't fit a specific technology:

make install-common TARGET=./shared-lib LANG=en

Installing Project Management Tools

For sprint tracking and backlog management:

make install-project TARGET=. LANG=fr

Installing Infrastructure Tools

For Docker and CI/CD support:

make install-infra TARGET=. LANG=en

Full Installation (All Technologies)

make install-all TARGET=. LANG=fr

---

Updating Rules

When Claude-Craft releases new versions:

# Update to latest (preserves project-specific files)
make install-symfony TARGET=./backend OPTIONS="--update"

# Force full reinstall (backup created automatically)
make install-symfony TARGET=./backend OPTIONS="--force"

---

Next Steps

Your project is now set up! Continue with:

1. Feature Development Guide - Learn the TDD workflow
2. Bug Fixing Guide - Handle bugs effectively
3. Tools Reference - Explore additional tools

---

← Getting Started | Feature Development →