基础设施工具

# 检查所需的 CLI 工具
ls Makefile 2>/dev/null && echo "make"
ls Dockerfile 2>/dev/null && echo "docker"
ls docker-compose.yml compose.yml 2>/dev/null && echo "docker-compose"
ls .terraform/ terraform/ 2>/dev/null && echo "terraform"
ls k8s/ kubernetes/ 2>/dev/null && echo "kubectl"
ls .github/workflows/ 2>/dev/null && echo "github-actions"

2. 检查当前系统

验证已安装的内容和缺失的内容：

系统信息

# 操作系统
uname -a
cat /etc/os-release 2>/dev/null | head -5

# Shell
echo $SHELL

必需工具检查

# 常用工具 — 检查版本
node --version 2>/dev/null || echo "❌ Node.js 未安装"
npm --version 2>/dev/null || echo "❌ npm 未安装"
yarn --version 2>/dev/null || echo "❌ yarn 未安装"
pnpm --version 2>/dev/null || echo "❌ pnpm 未安装"
python3 --version 2>/dev/null || echo "❌ Python 未安装"
pip3 --version 2>/dev/null || echo "❌ pip 未安装"
go version 2>/dev/null || echo "❌ Go 未安装"
ruby --version 2>/dev/null || echo "❌ Ruby 未安装"
java --version 2>/dev/null || echo "❌ Java 未安装"
rustc --version 2>/dev/null || echo "❌ Rust 未安装"
php --version 2>/dev/null || echo "❌ PHP 未安装"
docker --version 2>/dev/null || echo "❌ Docker 未安装"
docker compose version 2>/dev/null || echo "❌ Docker Compose 未安装"
git --version 2>/dev/null || echo "❌ Git 未安装"
make --version 2>/dev/null | head -1 || echo "❌ make 未安装"

3. 生成分步设置指南

基于发现结果，生成完整的设置指南：

指南结构

# [项目名称] — 本地开发环境设置

## 先决条件

开始前所需的一切：

| 工具 | 所需版本 | 您的版本 | 状态 |
|------|-----------------|-------------|--------|
| Node.js | >= 18.0.0 | v20.10.0 | ✅ |
| npm | >= 9.0.0 | 10.2.0 | ✅ |
| Docker | >= 24.0.0 | 24.0.7 | ✅ |
| PostgreSQL | 15.x | — | ⚠️ 通过 Docker |

### 安装缺失的先决条件

[为每个缺失的工具提供安装命令，根据其操作系统定制]

特定技术栈的设置步骤

Node.js / TypeScript 项目

## 步骤 1: 克隆并安装

git clone <repo-url>
cd <project-name>

# 安装依赖项（使用 [检测到的包管理器]）
npm install          # 或 yarn / pnpm install

## 步骤 2: 环境配置

# 复制示例环境文件
cp .env.example .env

# 需要填写的变量：
# DATABASE_URL    → 您的本地 PostgreSQL 连接字符串
# REDIS_URL       → 您的本地 Redis 连接字符串
# JWT_SECRET      → 用于本地开发的任意随机字符串（例如，"dev-secret-change-me"）
# [列出每个必需的变量，附带解释和示例值]

## 步骤 3: 启动基础设施

# 启动数据库和其他服务
docker compose up -d

# 验证服务正在运行
docker compose ps

## 步骤 4: 数据库设置

# 运行迁移
npm run db:migrate

# 填充开发数据（可选）
npm run db:seed

## 步骤 5: 启动开发服务器

npm run dev

# 服务器应运行在 http://localhost:3000

Python / Django 项目

## 步骤 1: 克隆并设置虚拟环境

git clone <repo-url>
cd <project-name>

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

# 安装依赖项
pip install -r requirements.txt
# 或：poetry install / pipenv install

## 步骤 2: 环境配置

cp .env.example .env
# 填写必需的变量...

## 步骤 3: 启动基础设施

docker compose up -d

## 步骤 4: 数据库设置

python manage.py migrate
python manage.py createsuperuser  # 创建管理员账户
python manage.py loaddata fixtures/dev_data.json  # 可选填充数据

## 步骤 5: 启动开发服务器

python manage.py runserver

# 服务器应运行在 http://localhost:8000
# 管理面板位于 http://localhost:8000/admin

Go 项目

## 步骤 1: 克隆并安装依赖项

git clone <repo-url>
cd <project-name>

go mod download

## 步骤 2: 环境配置

cp .env.example .env
# 填写必需的变量...

## 步骤 3: 启动基础设施

docker compose up -d

## 步骤 4: 数据库设置

go run cmd/migrate/main.go up
# 或：make migrate-up

## 步骤 5: 构建并运行

go run cmd/server/main.go
# 或：make run

# 服务器应运行在 http://localhost:8080

Ruby on Rails 项目

## 步骤 1: 克隆并安装依赖项

git clone <repo-url>
cd <project-name>

bundle install

## 步骤 2: 环境配置

cp .env.example .env
# 填写必需的变量...

# 安装 JavaScript 依赖项（如果适用）
yarn install

## 步骤 3: 启动基础设施

docker compose up -d

## 步骤 4: 数据库设置

rails db:create
rails db:migrate
rails db:seed

## 步骤 5: 启动开发服务器

rails server
# 或：bin/dev（如果使用 Foreman/Procfile）

# 服务器应运行在 http://localhost:3000

Java / Spring Boot 项目

## 步骤 1: 克隆并构建

git clone <repo-url>
cd <project-name>

# Maven
./mvnw clean install -DskipTests

# Gradle
./gradlew build -x test

## 步骤 2: 环境配置

cp src/main/resources/application-local.yml.example src/main/resources/application-local.yml
# 填写必需的属性...

## 步骤 3: 启动基础设施

docker compose up -d

## 步骤 4: 数据库设置

# Flyway 迁移在启动时自动运行
# 或：./mvnw flyway:migrate

## 步骤 5: 启动开发服务器

# Maven
./mvnw spring-boot:run -Dspring.profiles.active=local

# Gradle
./gradlew bootRun --args='--spring.profiles.active=local'

# 服务器应运行在 http://localhost:8080
# Swagger UI 位于 http://localhost:8080/swagger-ui.html

PHP / Laravel 项目

## 步骤 1: 克隆并安装依赖项

git clone <repo-url>
cd <project-name>

composer install
npm install

## 步骤 2: 环境配置

cp .env.example .env
php artisan key:generate

# 填写必需的变量...

## 步骤 3: 启动基础设施

docker compose up -d
# 或使用 Laravel Sail：./vendor/bin/sail up -d

## 步骤 4: 数据库设置

php artisan migrate
php artisan db:seed

## 步骤 5: 启动开发服务器

php artisan serve
npm run dev  # 用于前端资源的 Vite 开发服务器

# 服务器应运行在 http://localhost:8000

Rust 项目

## 步骤 1: 克隆并构建

git clone <repo-url>
cd <project-name>

cargo build

## 步骤 2: 环境配置

cp .env.example .env
# 填写必需的变量...

## 步骤 3: 启动基础设施

docker compose up -d

## 步骤 4: 数据库设置

# 使用 sqlx
sqlx database create
sqlx migrate run

# 使用 diesel
diesel setup
diesel migration run

## 步骤 5: 运行开发服务器

cargo run
# 或：cargo watch -x run（用于自动重载，需要 cargo-watch）

# 服务器应运行在 http://localhost:8080

移动端 (React Native) 项目

## 步骤 1: 克隆并安装依赖项

git clone <repo-url>
cd <project-name>

npm install

# iOS 特定
cd ios && pod install && cd ..

## 步骤 2: 环境配置

cp .env.example .env
# 填写必需的变量...

## 步骤 3: 启动后端（如果包含）

docker compose up -d
# 或连接到暂存 API

## 步骤 4: 在模拟器上运行

# iOS
npx react-native run-ios

# Android
npx react-native run-android

# Expo
npx expo start

Flutter 项目

## 步骤 1: 克隆并安装依赖项

git clone <repo-url>
cd <project-name>

flutter pub get

## 步骤 2: 环境配置

cp lib/config/env.example.dart lib/config/env.dart
# 填写必需的变量...

## 步骤 3: 在模拟器上运行

# 列出可用设备
flutter devices

# 在设备上运行
flutter run -d <device-id>

# 在 Chrome 中运行（Web）
flutter run -d chrome

单体仓库 / Turborepo 项目

## 步骤 1: 克隆并安装依赖项

git clone <repo-url>
cd <project-name>

# 安装所有工作区依赖项
npm install  # 或 pnpm install / yarn install

## 步骤 2: 环境配置

# 根级别
cp .env.example .env

# 每个包（检查每个应用）
cp apps/web/.env.example apps/web/.env
cp apps/api/.env.example apps/api/.env
# 填写必需的变量...

## 步骤 3: 启动基础设施

docker compose up -d

## 步骤 4: 数据库设置

npm run db:migrate --workspace=packages/database
npm run db:seed --workspace=packages/database

## 步骤 5: 启动所有服务

npm run dev  # 通过 Turbo 启动所有工作区

# Web：http://localhost:3000
# API：http://localhost:4000
# 文档：http://localhost:3001

4. 验证清单

设置完成后，验证一切是否正常工作：

## 验证您的设置

运行这些检查以确认一切正常：

### 基础设施
- [ ] `docker compose ps` — 所有服务显示为 "Up"
- [ ] 数据库可访问：`npm run db:check` 或使用您的数据库客户端连接
- [ ] Redis 可访问：`redis-cli ping` 返回 "PONG"

### 应用程序
- [ ] 开发服务器启动无错误
- [ ] 主页在 http://localhost:[PORT] 加载
- [ ] API 健康检查返回 OK：`curl http://localhost:[PORT]/api/health`
- [ ] 可以使用种子用户凭据登录（如果适用）

### 开发工具
- [ ] 测试通过：`npm test`
- [ ] 代码检查通过：`npm run lint`
- [ ] 热重载有效：进行小更改并验证其更新
- [ ] 调试器有效：设置断点并验证其暂停

### 常见首次运行问题
| 问题 | 解决方案 |
|---------|----------|
| 端口已被占用 | 终止进程：`lsof -i :3000` 然后 `kill -9 <PID>` |
| 数据库连接被拒绝 | 检查 Docker 是否运行：`docker compose ps` |
| 模块未找到 | 删除 node_modules 并重新安装：`rm -rf node_modules && npm install` |
| 权限被拒绝 | 检查文件权限：`chmod +x scripts/*.sh` |
| 环境变量缺失 | 将您的 .env 与 .env.example 进行比较 |
| 迁移失败 | 重置数据库：`npm run db:reset` 或 `docker compose down -v && docker compose up -d` |
| Python 版本不匹配 | 使用 pyenv：`pyenv install 3.11 && pyenv local 3.11` |
| Node 版本不匹配 | 使用 nvm：`nvm install && nvm use` |
| Docker 空间不足 | 清理：`docker system prune -a` |
| 种子数据缺失 | 运行填充命令：检查 package.json 中的填充脚本 |

5. IDE 和编辑器设置

## 推荐的编辑器设置

### VS Code
安装这些扩展以获得最佳体验：
- [从 .vscode/extensions.json 或项目类型检测到的扩展列表]

推荐设置（`.vscode/settings.json`）：
- 保存时格式化：启用
- 默认格式化程序：[基于项目的 Prettier/Black/gofmt/rustfmt]
- ESLint/Pylint 保存时自动修复

### JetBrains (IntelliJ / WebStorm / PyCharm)
- 从 `.editorconfig` 或项目设置导入代码风格
- 启用 [相关插件]
- 为开发服务器和测试配置运行配置

### Vim / Neovim
- [项目语言] 的 LSP 配置
- 格式化程序集成
- 测试运行器快捷键绑定

6. 常用命令参考

## 日常命令

| 任务 | 命令 |
|------|---------|
| 启动开发服务器 | `npm run dev` |
| 运行测试 | `npm test` |
| 运行单个测试 | `npm test -- --grep "test name"` |
| 代码检查 | `npm run lint` |
| 格式化代码 | `npm run format` |
| 启动基础设施 | `docker compose up -d` |
| 停止基础设施 | `docker compose down` |
| 查看日志 | `docker compose logs -f [service]` |
| 创建迁移 | `npm run db:migrate:create -- --name=add_users_table` |
| 运行迁移 | `npm run db:migrate` |
| 重置数据库 | `npm run db:reset` |
| 打开数据库 shell | `docker compose exec db psql -U postgres` |
| 打开 Redis CLI | `docker compose exec redis redis-cli` |
| 生产环境构建 | `npm run build` |
| 检查打包大小 | `npm run analyze` |

7. 访问与凭据

## 开发账户与访问

### 本地开发
| 服务 | URL | 凭据 |
|---------|-----|-------------|
| 应用 | http://localhost:3000 | — |
| API | http://localhost:3000/api | — |
| 数据库管理 (pgAdmin/Adminer) | http://localhost:5050 | admin@local.dev / admin |
| Redis Commander | http://localhost:8081 | — |
| Mailhog (邮件测试) | http://localhost:8025 | — |
| Swagger/API 文档 | http://localhost:3000/api/docs | — |

### 种子用户账户（如果适用）
| 角色 | 邮箱 | 密码 |
|------|-------|----------|
| 管理员 | admin@example.com | password123 |
| 用户 | user@example.com | password123 |

### 外部服务凭据
从您的团队负责人或共享保险库获取这些：
- [ ] Stripe 测试 API 密钥
- [ ] AWS 凭据（用于 S3 本地测试）
- [ ] OAuth 客户端 ID/密钥（Google、GitHub 等）

注意：切勿在本地使用生产环境凭据。

8. 设置完成后的后续步骤

## 您已设置完成！接下来做什么？

### 熟悉环境
1. **阅读** `docs/architecture.md` 或运行 `/explain-codebase` 以获取概述
2. **探索** 代码库，从 `src/api/routes/` 开始（跟踪请求在系统中的流程）
3. **运行** 测试套件以了解代码如何测试
4. **查看** 项目看板中的 "good first issue" 工单

### 您的第一个任务
选择一个定义明确的小任务来建立熟悉度：
- 修复 UI 中的拼写错误
- 添加缺失的单元测试
- 更新过时的依赖项
- 改进错误消息

### 关键联系人
| 领域 | 联系人 |
|------|---------|
| 架构问题 | @[技术负责人] |
| 部署问题 | @[运维负责人] |
| 产品问题 | @[产品经理] |
| 一般帮助 | Slack 上的 #[团队频道] |

输出格式

将设置指南结构化为：

1. 先决条件表格 — 所需的工具及其版本检查结果
2. 安装缺失的工具 — 针对未找到的任何内容的命令
3. 分步设置 — 从克隆到运行的编号步骤
4. 验证清单 — 确认一切正常
5. 故障排除 — 常见问题及修复方法
6. 常用命令 — 日常参考表格
7. 后续步骤 — 设置完成后要做什么

适应规则

• 自动检测一切 — 不要询问用户他们使用什么技术栈，扫描项目
• 验证每个步骤 — 实际运行命令以检查是否有效
• 操作系统感知 — 检测用户的操作系统并提供正确的命令（macOS/Linux/Windows）
• 跳过已完成的部分 — 如果工具已安装且版本正确，显示 ✅ 并继续
• 标记阻塞项 — 如果缺少关键内容（未安装 Docker、Node 版本错误），立即突出显示后再继续
• 包含时间估算 — 估计完整设置所需的时间（"在快速连接下约 15 分钟"）

总结

每个设置指南结束时包含：

1. 设置状态 — ✅ 就绪 / ⚠️ 需要注意 / ❌ 受阻
2. 正常工作的部分 — 确认运行的服务
3. 需要手动操作的部分 — 需要获取的凭据、需要创建的账户
4. 预计时间 — 剩余设置应花费多长时间
5. 要运行的第一个命令 — 开始开发的第一个命令

每周安装次数

1

仓库

aakash-dhar/cla…e-skills

首次出现

1 天前

安全审计

Gen Agent Trust HubFailSocketPassSnykPass

安装于

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

Database & Services

# Docker services
cat docker-compose.yml docker-compose.yaml compose.yml compose.yaml 2>/dev/null | grep -E "image:|postgres|mysql|mongo|redis|elasticsearch|rabbitmq|kafka"

# Environment variables that hint at services
cat .env.example .env.sample .env.template 2>/dev/null | grep -E "DATABASE|REDIS|MONGO|ELASTIC|RABBIT|KAFKA|S3|SMTP"

# Prisma / ORM
cat prisma/schema.prisma 2>/dev/null | head -20
cat src/db/config* 2>/dev/null

Infrastructure Tools

# Check for required CLI tools
ls Makefile 2>/dev/null && echo "make"
ls Dockerfile 2>/dev/null && echo "docker"
ls docker-compose.yml compose.yml 2>/dev/null && echo "docker-compose"
ls .terraform/ terraform/ 2>/dev/null && echo "terraform"
ls k8s/ kubernetes/ 2>/dev/null && echo "kubectl"
ls .github/workflows/ 2>/dev/null && echo "github-actions"

2. Check Current System

Verify what's already installed and what's missing:

System Info

# OS
uname -a
cat /etc/os-release 2>/dev/null | head -5

# Shell
echo $SHELL

Required Tools Check

# Common tools — check versions
node --version 2>/dev/null || echo "❌ Node.js not installed"
npm --version 2>/dev/null || echo "❌ npm not installed"
yarn --version 2>/dev/null || echo "❌ yarn not installed"
pnpm --version 2>/dev/null || echo "❌ pnpm not installed"
python3 --version 2>/dev/null || echo "❌ Python not installed"
pip3 --version 2>/dev/null || echo "❌ pip not installed"
go version 2>/dev/null || echo "❌ Go not installed"
ruby --version 2>/dev/null || echo "❌ Ruby not installed"
java --version 2>/dev/null || echo "❌ Java not installed"
rustc --version 2>/dev/null || echo "❌ Rust not installed"
php --version 2>/dev/null || echo "❌ PHP not installed"
docker --version 2>/dev/null || echo "❌ Docker not installed"
docker compose version 2>/dev/null || echo "❌ Docker Compose not installed"
git --version 2>/dev/null || echo "❌ Git not installed"
make --version 2>/dev/null | head -1 || echo "❌ make not installed"

3. Generate Step-by-Step Setup

Based on discovery, generate a complete setup guide:

Guide Structure

# [Project Name] — Local Development Setup

## Prerequisites

Everything you need before starting:

| Tool | Required Version | Your Version | Status |
|------|-----------------|-------------|--------|
| Node.js | >= 18.0.0 | v20.10.0 | ✅ |
| npm | >= 9.0.0 | 10.2.0 | ✅ |
| Docker | >= 24.0.0 | 24.0.7 | ✅ |
| PostgreSQL | 15.x | — | ⚠️ Via Docker |

### Install Missing Prerequisites

[Provide install commands for each missing tool, specific to their OS]

Stack-Specific Setup Steps

Node.js / TypeScript Project

## Step 1: Clone and Install

git clone <repo-url>
cd <project-name>

# Install dependencies (uses [detected package manager])
npm install          # or yarn / pnpm install

## Step 2: Environment Configuration

# Copy the example environment file
cp .env.example .env

# Required variables to fill in:
# DATABASE_URL    → Your local PostgreSQL connection string
# REDIS_URL       → Your local Redis connection string
# JWT_SECRET      → Any random string for local dev (e.g., "dev-secret-change-me")
# [list each required variable with explanation and example value]

## Step 3: Start Infrastructure

# Start database and other services
docker compose up -d

# Verify services are running
docker compose ps

## Step 4: Database Setup

# Run migrations
npm run db:migrate

# Seed development data (optional)
npm run db:seed

## Step 5: Start Development Server

npm run dev

# Server should be running at http://localhost:3000

Python / Django Project

## Step 1: Clone and Set Up Virtual Environment

git clone <repo-url>
cd <project-name>

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
# or: poetry install / pipenv install

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

python manage.py migrate
python manage.py createsuperuser  # Create admin account
python manage.py loaddata fixtures/dev_data.json  # Optional seed data

## Step 5: Start Development Server

python manage.py runserver

# Server should be running at http://localhost:8000
# Admin panel at http://localhost:8000/admin

Go Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

go mod download

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

go run cmd/migrate/main.go up
# or: make migrate-up

## Step 5: Build and Run

go run cmd/server/main.go
# or: make run

# Server should be running at http://localhost:8080

Ruby on Rails Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

bundle install

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

# Install JavaScript dependencies (if applicable)
yarn install

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

rails db:create
rails db:migrate
rails db:seed

## Step 5: Start Development Server

rails server
# or: bin/dev (if using Foreman/Procfile)

# Server should be running at http://localhost:3000

Java / Spring Boot Project

## Step 1: Clone and Build

git clone <repo-url>
cd <project-name>

# Maven
./mvnw clean install -DskipTests

# Gradle
./gradlew build -x test

## Step 2: Environment Configuration

cp src/main/resources/application-local.yml.example src/main/resources/application-local.yml
# Fill in required properties...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

# Flyway migrations run automatically on startup
# or: ./mvnw flyway:migrate

## Step 5: Start Development Server

# Maven
./mvnw spring-boot:run -Dspring.profiles.active=local

# Gradle
./gradlew bootRun --args='--spring.profiles.active=local'

# Server should be running at http://localhost:8080
# Swagger UI at http://localhost:8080/swagger-ui.html

PHP / Laravel Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

composer install
npm install

## Step 2: Environment Configuration

cp .env.example .env
php artisan key:generate

# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d
# or use Laravel Sail: ./vendor/bin/sail up -d

## Step 4: Database Setup

php artisan migrate
php artisan db:seed

## Step 5: Start Development Server

php artisan serve
npm run dev  # Vite dev server for frontend assets

# Server should be running at http://localhost:8000

Rust Project

## Step 1: Clone and Build

git clone <repo-url>
cd <project-name>

cargo build

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

# Using sqlx
sqlx database create
sqlx migrate run

# Using diesel
diesel setup
diesel migration run

## Step 5: Run Development Server

cargo run
# or: cargo watch -x run (for auto-reload, requires cargo-watch)

# Server should be running at http://localhost:8080

Mobile (React Native) Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

npm install

# iOS specific
cd ios && pod install && cd ..

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

## Step 3: Start Backend (if included)

docker compose up -d
# or connect to staging API

## Step 4: Run on Simulator

# iOS
npx react-native run-ios

# Android
npx react-native run-android

# Expo
npx expo start

Flutter Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

flutter pub get

## Step 2: Environment Configuration

cp lib/config/env.example.dart lib/config/env.dart
# Fill in required variables...

## Step 3: Run on Simulator

# List available devices
flutter devices

# Run on a device
flutter run -d <device-id>

# Run in Chrome (web)
flutter run -d chrome

Monorepo / Turborepo Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

# Install all workspace dependencies
npm install  # or pnpm install / yarn install

## Step 2: Environment Configuration

# Root level
cp .env.example .env

# Per-package (check each app)
cp apps/web/.env.example apps/web/.env
cp apps/api/.env.example apps/api/.env
# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

npm run db:migrate --workspace=packages/database
npm run db:seed --workspace=packages/database

## Step 5: Start All Services

npm run dev  # Starts all workspaces via Turbo

# Web: http://localhost:3000
# API: http://localhost:4000
# Docs: http://localhost:3001

4. Verification Checklist

After setup, verify everything works:

## Verify Your Setup

Run these checks to confirm everything is working:

### Infrastructure
- [ ] `docker compose ps` — all services show "Up"
- [ ] Database is accessible: `npm run db:check` or connect with your DB client
- [ ] Redis is accessible: `redis-cli ping` returns "PONG"

### Application
- [ ] Dev server starts without errors
- [ ] Homepage loads at http://localhost:[PORT]
- [ ] API health check returns OK: `curl http://localhost:[PORT]/api/health`
- [ ] Can log in with seed user credentials (if applicable)

### Development Tools
- [ ] Tests pass: `npm test`
- [ ] Linter passes: `npm run lint`
- [ ] Hot reload works: make a small change and verify it updates
- [ ] Debugger works: set a breakpoint and verify it pauses

### Common First-Run Issues
| Problem | Solution |
|---------|----------|
| Port already in use | Kill the process: `lsof -i :3000` then `kill -9 <PID>` |
| Database connection refused | Check Docker is running: `docker compose ps` |
| Module not found | Delete node_modules and reinstall: `rm -rf node_modules && npm install` |
| Permission denied | Check file permissions: `chmod +x scripts/*.sh` |
| Env variable missing | Compare your .env against .env.example |
| Migration failed | Reset DB: `npm run db:reset` or `docker compose down -v && docker compose up -d` |
| Python version mismatch | Use pyenv: `pyenv install 3.11 && pyenv local 3.11` |
| Node version mismatch | Use nvm: `nvm install && nvm use` |
| Docker out of space | Clean up: `docker system prune -a` |
| Seed data missing | Run seed command: check package.json for seed script |

5. IDE & Editor Setup

## Recommended Editor Setup

### VS Code
Install these extensions for the best experience:
- [List extensions detected from .vscode/extensions.json or project type]

Recommended settings (`.vscode/settings.json`):
- Format on save: enabled
- Default formatter: [Prettier/Black/gofmt/rustfmt based on project]
- ESLint/Pylint auto-fix on save

### JetBrains (IntelliJ / WebStorm / PyCharm)
- Import code style from `.editorconfig` or project settings
- Enable [relevant plugins]
- Configure run configurations for dev server and tests

### Vim / Neovim
- LSP config for [project language]
- Formatter integration
- Test runner keybinds

6. Useful Commands Reference

## Daily Commands

| Task | Command |
|------|---------|
| Start dev server | `npm run dev` |
| Run tests | `npm test` |
| Run single test | `npm test -- --grep "test name"` |
| Lint code | `npm run lint` |
| Format code | `npm run format` |
| Start infrastructure | `docker compose up -d` |
| Stop infrastructure | `docker compose down` |
| View logs | `docker compose logs -f [service]` |
| Create migration | `npm run db:migrate:create -- --name=add_users_table` |
| Run migrations | `npm run db:migrate` |
| Reset database | `npm run db:reset` |
| Open DB shell | `docker compose exec db psql -U postgres` |
| Open Redis CLI | `docker compose exec redis redis-cli` |
| Build for production | `npm run build` |
| Check bundle size | `npm run analyze` |

7. Access & Credentials

## Development Accounts & Access

### Local Development
| Service | URL | Credentials |
|---------|-----|-------------|
| App | http://localhost:3000 | — |
| API | http://localhost:3000/api | — |
| DB Admin (pgAdmin/Adminer) | http://localhost:5050 | admin@local.dev / admin |
| Redis Commander | http://localhost:8081 | — |
| Mailhog (email testing) | http://localhost:8025 | — |
| Swagger/API Docs | http://localhost:3000/api/docs | — |

### Seed User Accounts (if applicable)
| Role | Email | Password |
|------|-------|----------|
| Admin | admin@example.com | password123 |
| User | user@example.com | password123 |

### External Service Credentials
Obtain these from your team lead or the shared vault:
- [ ] Stripe test API key
- [ ] AWS credentials (for S3 local testing)
- [ ] OAuth client ID/secret (Google, GitHub, etc.)

Note: Never use production credentials locally.

8. Next Steps After Setup

## You're Set Up! Now What?

### Get Familiar
1. **Read** `docs/architecture.md` or run `/explain-codebase` for an overview
2. **Explore** the codebase starting from `src/api/routes/` (follow a request through the system)
3. **Run** the test suite to see how the code is tested
4. **Check** the project board for "good first issue" tickets

### Your First Task
Pick a small, well-defined task to build familiarity:
- Fix a typo in the UI
- Add a missing unit test
- Update an outdated dependency
- Improve an error message

### Key People
| Area | Contact |
|------|---------|
| Architecture questions | @[tech-lead] |
| Deployment issues | @[devops-lead] |
| Product questions | @[product-manager] |
| General help | #[team-channel] on Slack |

Output Format

Structure the setup guide as:

1. Prerequisites table — tools needed with version check results
2. Install missing tools — commands for anything not found
3. Step-by-step setup — numbered steps from clone to running
4. Verification checklist — confirm everything works
5. Troubleshooting — common issues and fixes
6. Useful commands — daily reference table
7. Next steps — what to do after setup is complete

Adaptation Rules

• Auto-detect everything — don't ask the user what stack they're using, scan the project
• Verify each step — actually run commands to check if things work
• OS-aware — detect the user's OS and provide correct commands (macOS/Linux/Windows)
• Skip what's done — if a tool is already installed and correct version, say ✅ and move on
• Flag blockers — if something critical is missing (Docker not installed, wrong Node version), highlight it immediately before continuing
• Include timings — estimate how long the full setup takes ("~15 minutes on a fast connection")

Summary

End every setup guide with:

1. Setup status — ✅ Ready / ⚠️ Needs attention / ❌ Blocked
2. What's working — services confirmed running
3. What needs manual action — credentials to obtain, accounts to create
4. Estimated time — how long the remaining setup should take
5. First command to run — the one command to start developing

Weekly Installs

1

Repository

aakash-dhar/cla…e-skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubFailSocketPassSnykPass

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1