ClaudeForge/docs/QUICK_START.md

Quick Start Guide

Get started with ClaudeForge in 5 minutes. This guide walks you through your first CLAUDE.md creation.

---

🚀 5-Minute Tutorial

Step 1: Install ClaudeForge (1 minute)

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash

# Windows (PowerShell)
iwr https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.ps1 -useb | iex

Choose: Option 1 (user-level) for global availability

Restart Claude Code after installation

---

Step 2: Navigate to Your Project (30 seconds)

cd /path/to/your/project

Requirements:

• Any code project (doesn't need to be git-initialized, but recommended)
• Works with TypeScript, Python, Go, Java, Ruby, and more

---

Step 3: Run the Command (10 seconds)

In Claude Code, type:

/enhance-claude-md

---

Step 4: Interactive Workflow (3 minutes)

ClaudeForge will now:

Phase 1: Discovery ✓

Claude explores your project:

Checking for existing CLAUDE.md... Not found
Exploring repository structure...
Analyzing package.json, requirements.txt, etc...

Phase 2: Analysis ✓

Claude shows discoveries:

Based on my exploration, here's what I discovered:

📦 Project Type: Full-Stack Application
🛠️ Tech Stack: TypeScript, React, Node.js, PostgreSQL, Docker
👥 Team Size: Small (5 developers detected from git history)
🚀 Development Phase: MVP
⚙️ Workflows: TDD, CI/CD

📋 Recommended Structure:
- Root CLAUDE.md (navigation hub, ~100 lines)
- backend/CLAUDE.md (API guidelines, ~150 lines)
- frontend/CLAUDE.md (React guidelines, ~175 lines)

Phase 3: Confirmation ✓

Claude asks for your approval:

Would you like me to create these files with these settings?

You respond: Yes or Yes, proceed

Phase 4: Generation ✓

Claude creates your CLAUDE.md files:

Creating customized CLAUDE.md files...

✅ Created CLAUDE.md (108 lines)
   - Quick Navigation section
   - 5 Core Principles
   - Tech Stack summary
   - Common commands

✅ Created backend/CLAUDE.md (156 lines)
   - API design guidelines
   - Database operations
   - Testing requirements

✅ Created frontend/CLAUDE.md (182 lines)
   - Component standards
   - State management
   - Performance tips

---

Step 5: Review Your CLAUDE.md (1 minute)

Open the generated file:

cat CLAUDE.md

You'll see:

• Overview - Project description
• Project Structure - ASCII tree diagram
• Setup & Installation - How to get started
• Architecture - Key patterns and decisions
• Core Principles - Development guidelines
• Tech Stack - Technologies used
• Common Commands - Build, test, lint
• Development Workflow - How to contribute

All in 100% native Claude Code format!

---

🎯 What Just Happened?

1. Explored your codebase automatically
2. Detected project type, tech stack, team size
3. Generated customized CLAUDE.md with:
   • Native format compliance
   • Tech-specific best practices
   • Team-appropriate complexity
4. Created modular files (if needed)

Result: Future Claude Code sessions now have perfect context about your project!

---

🔄 Common Workflows

Scenario A: New Project

# You: Create a new project
mkdir my-new-app && cd my-new-app
npm init -y

# You: Run ClaudeForge
/enhance-claude-md

# Claude: Explores → Analyzes → Creates CLAUDE.md

Time: ~2 minutes

---

Scenario B: Existing Project (No CLAUDE.md)

# You: Navigate to existing project
cd my-existing-project

# You: Run ClaudeForge
/enhance-claude-md

# Claude: Explores → Detects tech → Creates CLAUDE.md

Time: ~3 minutes

---

Scenario C: Improve Existing CLAUDE.md

# You: Have basic CLAUDE.md
cat CLAUDE.md
# Output: Basic file with just tech stack

# You: Run ClaudeForge
/enhance-claude-md

# Claude: Analyzes current file
# Shows: Quality Score: 55/100
# Missing: Project Structure, Setup, Architecture
# Claude: Adds missing sections

# Result: Quality Score: 55 → 88

Time: ~2 minutes

---

Scenario D: Automatic Maintenance

# You: Make significant changes
npm install react-query
mkdir src/components/auth

# You: Start new Claude Code session
# Guardian agent automatically checks changes

# Agent output:
# ✅ CLAUDE.md updated:
# - Tech Stack: Added react-query
# - Project Structure: Updated diagram
# Changes: 2 sections, 8 lines

Time: Automatic, ~10 seconds

---

📚 Next Steps

Learn More

• Architecture: ARCHITECTURE.md - How components work together
• Examples: ../examples/ - Real-world usage patterns
• Troubleshooting: TROUBLESHOOTING.md - Common issues

Customize Your CLAUDE.md

After generation, you can:

1. Edit Core Principles - Add team-specific guidelines
2. Add Custom Sections - Project-specific conventions
3. Update Tech Stack - Add missing dependencies
4. Refine Workflows - Adjust to your process

Enable Automatic Maintenance

Set up the guardian agent to keep CLAUDE.md current:

# Agent runs automatically at session start
# Or invoke manually after major changes:
Claude, invoke claude-md-guardian to update CLAUDE.md

---

💡 Pro Tips

Tip 1: Use Modular Architecture for Large Projects

If your CLAUDE.md approaches or exceeds the 150-line cap, split it (or run /sync-claude-md to split for you):

/enhance-claude-md

# Tell Claude: "Use modular architecture"
# Result: Separate files for backend/, frontend/, database/

Tip 2: Regenerate When Tech Stack Changes

# You: Added new major framework
npm install @nestjs/core

# You: Regenerate with new context
/enhance-claude-md

# Claude: Updates Tech Stack and patterns

Tip 3: Validate Before Committing

# You: Made manual edits to CLAUDE.md
# You: Want to check quality

/enhance-claude-md

# Claude: Analyzes and shows quality score
# If score < 80, Claude suggests improvements

Tip 4: Team Consistency

Install at user-level on all team machines:

# Each team member runs:
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash

# Choose option 1 (user-level)
# Result: Consistent CLAUDE.md standards across team

---

🎓 Understanding the Output

What's in a Generated CLAUDE.md?

Native Format Sections (Always Included):

1. Overview - What this project does
2. Project Structure - ASCII tree diagram
3. File Structure - Directory explanations
4. Setup & Installation - Getting started steps
5. Architecture - Key design decisions (for complex projects)

Team-Specific Sections: 6. Core Principles - Development guidelines 7. Tech Stack - Technologies with versions 8. Development Workflow - How to contribute 9. Testing Requirements - Test standards 10. Common Commands - Build, test, lint scripts

Optional Sections (Based on Project Type):

• Error Handling - Error patterns
• Performance Guidelines - Optimization tips
• Security Checklist - Security requirements
• Deployment Process - How to deploy

---

⚡ Quick Reference

Commands

Command	Purpose
/enhance-claude-md	Initialize or enhance CLAUDE.md
Claude, invoke claude-md-guardian	Manually trigger maintenance

Quality Scores

Score	Meaning	Action
0-40	Poor	Major improvements needed
41-70	Fair	Add missing sections
71-85	Good	Minor improvements
86-100	Excellent	Maintain current quality

File Size Guidelines

Team Size	Recommended Lines	Structure
Solo	50-100	Single file
Small (2-9)	100-200	Single file
Medium (10-50)	200-300	Single or modular
Large (50+)	Modular	Multiple context files

---

🆘 Having Issues?

Issue: Command not recognized

Solution: Restart Claude Code after installation

Issue: Quality score too low

Solution: Run /enhance-claude-md and let Claude add missing sections

Issue: Generated file too generic

Solution: Provide more context:

/enhance-claude-md

"This is a Python FastAPI microservice project with PostgreSQL"

More Help

See TROUBLESHOOTING.md for detailed solutions.

---

🎉 Success!

You now have a fully functional CLAUDE.md file that:

• ✅ Follows native Claude Code format
• ✅ Includes project-specific context
• ✅ Provides clear development guidelines
• ✅ Automatically maintains itself (via guardian agent)

Future Claude Code sessions will be significantly more productive!

---

📖 Further Reading

• Installation Guide: INSTALLATION.md
• Architecture Deep Dive: ARCHITECTURE.md
• Contributing: CONTRIBUTING.md
• GitHub Repository: https://github.com/alirezarezvani/ClaudeForge

---

Ready to create amazing projects with ClaudeForge? Let's build! 🚀