Claude Code 开发环境设置

一个全面的开发环境设置，适用于配备MCP服务器、开发容器以及长时间运行任务能力的Claude Code。

🚀 快速开始

1. 克隆此仓库：

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

2. 设置环境变量：

   cp .env.example .env
   # 使用你的API令牌编辑.env文件
   

3. 启动开发容器：

   # 使用VS Code开发容器扩展
   code .
   # 或者直接使用Docker Compose
   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（模型上下文协议）服务器

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

长时间运行的任务

• 自动延续：跨会话持久化的任务
• 监控：实时进度跟踪
• 日志记录：全面的任务日志记录和分析
• 模板：常见任务的预建任务模板

安全与网络

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

🔧 前提条件

• Docker Desktop或Docker Engine（带有Docker Compose）
• 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
   # 使用你的API令牌编辑.env文件
   

方法2：Docker Compose

1. 克隆仓库：

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

2. 配置环境：

   cp .env.example .env
   # 使用你的API令牌编辑.env文件
   

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文件以进行配置：

# 必需：GitHub个人访问令牌
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# 可选：Monday.com API令牌
MONDAY_API_TOKEN=your_monday_token_here

# 可选：Figma API令牌
FIGMA_TOKEN=your_figma_token_here

# 可选：时区（默认为UTC）
TZ=America/New_York

# 可选：Node.js内存限制
NODE_OPTIONS=--max-old-space-size=8192

MCP服务器配置

MCP服务器在容器启动期间自动配置。要手动配置：

# 向Claude添加MCP服务器
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 m
cp add figma "npx figma-developer-mcp --figma-api-key=$FIGMA_TOKEN --stdio"

# 验证配置
claude mcp list

🎯 使用

快捷命令

# 启动MCP服务器
./.devcontainer/start-mcps.sh

# 运行10分钟演示任务
./scripts/ten-minute-job.sh

# 启动自定义长时间运行的任务
./scripts/run-long-claude-job.sh "您的任务描述"

# 监控任务进度
./scripts/monitor-job.sh /workspace/claude-job-*.log

# 检查系统状态
docker-compose ps
ps aux | grep claude

开发工作流程

1. 启动开发环境：

   # 在VS Code中打开
   code .
   # 或者手动启动容器
   docker-compose up -d
   

2. 初始化项目：

   # 创建新项目
   mkdir my-project && cd my-project
   npm init -y
   
   # 启动Claude Code
   claude-code --dangerously-skip-permissions
   

3. 运行长时间分析：

   ./scripts/ten-minute-job.sh
   # 在另一个终端中监控
   tail -f /workspace/claude-job-*.log
   

任务模板

代码分析

./scripts/run-long-claude-job.sh "
执行全面的代码分析：
1. 查看所有组件的性能问题
2. 识别安全漏洞
3. 提出架构改进意见
4. 生成详细报告并提出建议
"

文档生成

./scripts/run-long-claude-job.sh "
创建全面的文档：
1. 为所有函数添加JSDoc注释
2. 创建API文档
3. 编写组件的使用示例
4. 生成架构图
"

测试设置

./scripts/run-long-claude-job.sh "
设置全面的测试基础设施：
1. 配置Jest和测试库
2. 为现有组件创建测试文件
3. 使用Playwright设置端到端测试
4. 添加测试覆盖率报告
"

📚 文档

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

🔍 监控和调试

检查系统状态

# 容器状态
docker-compose ps

# MCP服务器状态
ps aux | grep mcp

# Claude进程
ps aux | grep claude

# 资源使用情况
docker stats

日志文件

# MCP服务器日志
tail -f /tmp/mcp-server.log
tail -f /tmp/monday-mcp.log
tail -f /tmp/figma-mcp.log
tail -f /tmp/playwright-mcp.log

# 任务日志
tail -f /workspace/claude-job-*.log

# 容器日志
docker-compose logs -f claude-dev

健康检查

# 测试MCP连接
claude mcp test filesystem
claude mcp test monday
claude mcp test playwright
claude mcp test figma

# 网络连通性
ping github.com
curl -I https://api.monday.com

🐛 故障排除

常见问题

容器无法启动

# 检查Docker守护进程
docker version

# 检查磁盘空间
df -h

# 重建容器
docker-compose down
docker-compose build --no-cache
docker-compose up -d

MCP服务器无法工作

# 重启MCP服务器
pkill -f mcp
./.devcontainer/init-mcp.sh

# 检查环境变量
echo $MONDAY_API_TOKEN
echo $FIGMA_TOKEN

# 验证安装
npm list -g | grep mcp

长时间运行的任务失败

# 检查Claude认证
claude-code --version

# 验证权限
ls -la /workspace

# 检查可用内存
free -m

# 查看错误日志
grep -i error /workspace/claude-job-*.log

获取帮助

1. 查看日志以查找特定的错误消息
2. 查阅文档在docs/目录下
3. 搜索问题在GitHub仓库中
4. 创建一个问题包括：
   • 错误消息
   • 复现步骤
   • 环境细节（docker version，node --version）

🔒 安全注意事项

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

🤝 贡献

1. 分叉仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 做出更改并彻底测试
4. 提交更改：git commit -m '添加精彩特性'
5. 推送到分支：git push origin feature/amazing-feature
6. 打开拉取请求

开发指南

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

📄 许可证

本项目根据MIT许可证授权 - 详情参见LICENSE文件。

🙏 致谢

• Anthropic为Claude Code和MCP协议
• Microsoft为VS Code开发容器
• Docker为容器化平台
• 社区贡献者为改进和反馈

📞 支持

• 文档：检查docs/目录
• 问题：GitHub问题
• 讨论：GitHub讨论

---

祝你在Claude上编程愉快！🎉