Skip to main content

Lesson 01.2: Development Environment Setup

Duration: 60 minutes | Difficulty: Beginner

Learning Objectives​

By the end of this lesson, you will have:

  • Node.js and npm installed
  • A code editor (VS Code) configured
  • Git installed and configured
  • SpecWeave installed globally
  • Claude Code ready to use

Overview​

A professional development environment includes:

┌─────────────────────────────────────────────────────────┐
│                   Your Computer                          │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   Node.js    │  │   VS Code    │  │     Git      │  │
│  │  (Runtime)   │  │   (Editor)   │  │  (Version)   │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐                     │
│  │  SpecWeave   │  │ Claude Code  │                     │
│  │  (Specs)     │  │    (AI)      │                     │
│  └──────────────┘  └──────────────┘                     │
└─────────────────────────────────────────────────────────┘

Step 1: Install Node.js​

Node.js is the JavaScript runtime that powers modern web development.

macOS​

# Using Homebrew (recommended)
brew install node

# Verify installation
node --version  # Should show v18+ or v20+
npm --version   # Should show 9+ or 10+

Windows​

  1. Download from nodejs.org
  2. Choose "LTS" (Long Term Support) version
  3. Run the installer, accept defaults
  4. Open PowerShell and verify:
node --version
npm --version

Linux (Ubuntu/Debian)​

# Using NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version
npm --version

Step 2: Install VS Code​

Visual Studio Code is the most popular code editor for modern development.

All Platforms​

  1. Download from code.visualstudio.com
  2. Install and launch

Essential Extensions​

Open VS Code and install these extensions (Cmd/Ctrl + Shift + X):

ExtensionPurpose
ESLintCode quality
PrettierCode formatting
GitLensGit visualization
Error LensInline error display

Open Settings (Cmd/Ctrl + ,) and add:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "files.autoSave": "onFocusChange"
}

Step 3: Install Git​

Git is version control — essential for all software development.

macOS​

# Usually pre-installed, or:
brew install git

# Verify
git --version

Windows​

  1. Download from git-scm.com
  2. Run installer, accept defaults
  3. Verify in PowerShell:
git --version

Linux​

sudo apt-get install git
git --version

Configure Git​

# Set your identity (required for commits)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default branch name
git config --global init.defaultBranch main

# Verify
git config --list

Step 4: Install SpecWeave​

SpecWeave transforms how you build software with AI.

# Install globally
npm install -g specweave

# Verify installation
specweave --version

What SpecWeave Provides​

specweave
├── /sw:increment    → Create new feature specs
├── /sw:do           → Execute tasks
├── /sw:done         → Complete with quality gates
├── /sw:progress     → Check status
├── /sw:validate     → Validate specs
└── /sw:qa           → Quality assessment

Step 5: Install Claude Code​

Claude Code is the AI that powers SpecWeave.

Installation​

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Authenticate (requires Anthropic API key)
claude auth

Verify​

claude --version

First Run​

# Navigate to any project
cd ~/projects/my-project

# Start Claude Code
claude

Step 6: Initialize a Test Project​

Let's verify everything works:

# Create a test directory
mkdir ~/academy-test
cd ~/academy-test

# Initialize a Node.js project
npm init -y

# Initialize SpecWeave
specweave init .

# You should see:
# ✅ Created .specweave/ directory
# ✅ Created .specweave/config.json
# ✅ Ready to create increments!

Project Structure After Init​

~/academy-test/
├── package.json
└── .specweave/
    ├── config.json          ← SpecWeave configuration
    ├── increments/          ← Your specs will live here
    └── docs/                ← Living documentation

Troubleshooting​

"npm: command not found"​

Node.js isn't installed or not in PATH. Reinstall Node.js.

"specweave: command not found"​

# Check if npm global bin is in PATH
npm config get prefix

# Add to PATH (macOS/Linux)
export PATH="$PATH:$(npm config get prefix)/bin"

"Permission denied" on npm install -g​

# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Or use a Node version manager (recommended)
# See: https://github.com/nvm-sh/nvm

Git "Author identity unknown"​

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Environment Checklist​

Before proceeding, verify all tools:

# Run these commands
node --version      # ✅ v18+ or v20+
npm --version       # ✅ 9+ or 10+
git --version       # ✅ 2.30+
specweave --version # ✅ Latest
claude --version    # ✅ Latest

All showing versions? You're ready!

Key Takeaways​

  1. Node.js — JavaScript runtime for building applications
  2. VS Code — Professional code editor with extensions
  3. Git — Version control for tracking changes
  4. SpecWeave — Spec-driven development framework
  5. Claude Code — AI assistant that integrates with SpecWeave

Next Lesson​

Now let's learn the command line basics you'll use daily.

→ Continue to Lesson 01.3: Command Line Essentials