Claude Code Development Environment Setup

Claude Code 开发环境设置

为 Claude Code 提供全面的开发环境设置，包含 MCP 服务、开发容器和长时间运行的任务能力。

🚀 快速开始

1. 克隆此仓库：

   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   

2. 设置环境变量：

   cp .env.example .env
   # Edit .env with your API tokens
   

3. 启动开发容器：

   # Using VS Code Dev Containers extension
   code .
   # Or using Docker Compose directly
   docker-compose up -d
   

4. 初始化 MCP 服务：

   ./.devcontainer/init-mcp.sh
   

5. 启动长时间运行的任务：

   ./scripts/ten-minute-job.sh
   

📋 目录

• 功能
• 先决条件
• 安装
• 配置
• 使用方法
• 文档
• 故障排除
• 贡献

✨ 功能

开发环境

• VS Code 开发容器，预配置扩展
• 基于 Docker 的隔离开发环境
• Zsh 和 Oh-My-Zsh，带来更出色的终端体验
• Git Delta，提供更清晰的差异可视化

MCP（Model Context Protocol）服务

• Filesystem 服务：文件操作和项目管理
• Monday.com 集成：项目管理和任务跟踪
• Figma 集成：设计系统访问和组件管理
• Playwright 集成：浏览器自动化和测试

长时间运行的任务

• 自动续接：可跨会话持续运行的任务
• 监控：实时进度跟踪
• 日志记录：全面的任务日志记录和分析
• 模板：适用于常见任务的预构建任务模板

安全与网络

• 防火墙配置：自动设置网络安全
• 权限管理：受控访问系统资源
• 令牌管理：安全处理 API 凭据

🔧 先决条件

• Docker Desktop 或带有 Docker Compose 的 Docker Engine
• 带有 Dev Containers 扩展的 VS Code（推荐）
• 用于版本控制的 Git
• Node.js 20+（已包含在容器中）

必需的 API 令牌

服务	必需	用途	获取方式
GitHub	✅ 是	仓库操作	GitHub 设置 → 开发者设置 → 个人访问令牌
Monday.com	⚪ 可选	项目管理	Monday.com → 管理员 → API
Figma	⚪ 可选	设计系统访问	Figma → 设置 → 账户 → 个人访问令牌

📦 安装

方法 1：VS Code 开发容器（推荐）

1. 克隆仓库并在 VS Code 中打开：

   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   code .
   

2. 出现提示时，点击“在容器中重新打开”

   • VS Code 将自动构建并启动开发容器
   • 所有依赖项都将自动安装

3. 设置环境变量：

   cp .env.example .env
   # Edit .env with your API tokens
   

方法 2：Docker Compose

1. 克隆仓库：

   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   

2. 配置环境：

   cp .env.example .env
   # Edit .env with your API tokens
   

3. 启动容器：

   docker-compose up -d
   

4. 访问容器：

   docker-compose exec claude-dev zsh
   

方法 3：本地安装

如果希望在不使用容器的情况下运行：

1. 安装 Node.js 依赖项：

   npm install -g \
     @anthropic-ai/claude-code \
     @modelcontextprotocol/server-filesystem \
     @mondaydotcomorg/monday-api-mcp \
     @playwright/mcp \
     figma-developer-mcp
   

2. 设置环境：

   cp .env.example .env
   source .env
   

3. 运行初始化脚本：

   chmod +x .devcontainer/*.sh scripts/*.sh
   ./.devcontainer/init-mcp.sh
   

⚙️ 配置

环境变量

使用你的配置编辑 .env 文件：

# Required: GitHub Personal Access Token
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Optional: Monday.com API token
MONDAY_API_TOKEN=your_monday_token_here

# Optional: Figma API token
FIGMA_TOKEN=your_figma_token_here

# Optional: Timezone (defaults to UTC)
TZ=America/New_York

# Optional: Node.js memory limit
NODE_OPTIONS=--max-old-space-size=8192

MCP 服务配置

MCP 服务会在容器启动时自动配置。如需手动配置：

# Add MCP servers to Claude
claude mcp add filesystem "npx @modelcontextprotocol/server-filesystem /workspace"
claude mcp add monday "npx @mondaydotcomorg/monday-api-mcp --token $MONDAY_API_TOKEN"
claude mcp add playwright "npx @playwright/mcp"
claude mcp add figma "npx figma-developer-mcp --figma-api-key=$FIGMA_TOKEN --stdio"

# Verify configuration
claude mcp list

🎯 使用方法

快捷命令

# Start MCP servers
./.devcontainer/start-mcps.sh

# Run a 10-minute demo job
./scripts/ten-minute-job.sh

# Start custom long-running job
./scripts/run-long-claude-job.sh "Your task description"

# Monitor job progress
./scripts/monitor-job.sh /workspace/claude-job-*.log

# Check system status
docker-compose ps
ps aux | grep claude

开发工作流

1. 启动开发环境：

   # Open in VS Code
   code .
   # Or start container manually
   docker-compose up -d
   

2. 初始化项目：

   # Create new project
   mkdir my-project && cd my-project
   npm init -y
   
   # Start Claude Code
   claude-code --dangerously-skip-permissions
   

3. 运行长时间分析任务：

   ./scripts/ten-minute-job.sh
   # Monitor in another terminal
   tail -f /workspace/claude-job-*.log
   

任务模板

代码分析

./scripts/run-long-claude-job.sh "
Perform comprehensive code analysis:
1. Review all components for performance issues
2. Identify security vulnerabilities  
3. Suggest architectural improvements
4. Generate detailed report with recommendations
"

文档生成

./scripts/run-long-claude-job.sh "
Create comprehensive documentation:
1. Add JSDoc comments to all functions
2. Create API documentation
3. Write usage examples for components
4. Generate architecture diagrams
"

测试设置

./scripts/run-long-claude-job.sh "
Set up comprehensive testing infrastructure:
1. Configure Jest and testing libraries
2. Create test files for existing components
3. Set up E2E testing with Playwright
4. Add test coverage reporting
"

📚 文档

• MCP 设置指南 - MCP 服务配置详解
• 长时间运行的任务 - 任务管理与监控
• 开发容器指南 - 容器配置详情
• 故障排除指南 - 常见问题及解决方案

🔍 监控与调试

检查系统状态

# Container status
docker-compose ps

# MCP server status
ps aux | grep mcp

# Claude processes
ps aux | grep claude

# Resource usage
docker stats

日志文件

# MCP server logs
tail -f /tmp/mcp-server.log
tail -f /tmp/monday-mcp.log
tail -f /tmp/figma-mcp.log
tail -f /tmp/playwright-mcp.log

# Job logs
tail -f /workspace/claude-job-*.log

# Container logs
docker-compose logs -f claude-dev

健康检查

# Test MCP connections
claude mcp test filesystem
claude mcp test monday
claude mcp test playwright
claude mcp test figma

# Network connectivity
ping github.com
curl -I https://api.monday.com

🐛 故障排除

常见问题

容器无法启动

# Check Docker daemon
docker version

# Check disk space
df -h

# Rebuild container
docker-compose down
docker-compose build --no-cache
docker-compose up -d

MCP 服务无法正常工作

# Restart MCP servers
pkill -f mcp
./.devcontainer/init-mcp.sh

# Check environment variables
echo $MONDAY_API_TOKEN
echo $FIGMA_TOKEN

# Verify installations
npm list -g | grep mcp

长时间运行的任务失败

# Check Claude authentication
claude-code --version

# Verify permissions
ls -la /workspace

# Check available memory
free -m

# Review error logs
grep -i error /workspace/claude-job-*.log

获取帮助

1. 检查日志，查找具体的错误消息
2. 查看文档，参阅 docs/ 目录
3. 搜索问题，查看 GitHub 仓库中的相关问题
4. 创建问题，并提供：
   • 错误消息
   • 复现步骤
   • 环境详情（docker version、node --version）

🔒 安全注意事项

• API 令牌：存储在 .env 文件中，切勿提交到仓库
• 权限：仅在可信环境中使用 --dangerously-skip-permissions
• 网络：防火墙规则会自动配置
• 容器：默认以非 root 用户运行

🤝 贡献

1. Fork 此仓库
2. 创建功能分支： git checkout -b feature/amazing-feature
3. 进行更改并充分测试
4. 提交更改： git commit -m 'Add amazing feature'
5. 推送到分支： git push origin feature/amazing-feature
6. 创建 Pull Request

开发指南

• 遵循现有的代码风格和规范
• 为新功能添加文档
• 在容器和本地环境中测试更改
• 更新相关文档文件

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

• Anthropic：感谢其提供 Claude Code 和 MCP 协议
• Microsoft：感谢其提供 VS Code Dev Containers
• Docker：感谢其提供容器化平台
• 社区贡献者：感谢大家的改进和反馈

📞 支持

• 文档：查看 docs/ 目录
• 问题：GitHub Issues
• 讨论：GitHub Discussions

---

祝你使用 Claude 编码愉快！🎉