跳到主要内容

项目配置指南

概述​

正确配置项目是高效使用 Claude Code 的基础。本指南将介绍如何为不同类型的项目设置合适的配置。

新项目初始化​

使用 /init 命令​

Claude Code 提供了智能的 /init 命令，可以自动分析项目并生成初始配置：

cd your-project
claude
/init

/init 命令会：

  • 扫描项目结构和文件
  • 识别技术栈和框架
  • 生成初始的 CLAUDE.md
  • 推荐常用的开发命令
  • 设置基础的项目规范

手动配置步骤​

如果 /init 生成的配置不够完善，可以手动补充：

  1. 确认技术栈识别
  2. 补充项目特定信息
  3. 添加团队工作流规范
  4. 配置常用命令和脚本

不同类型项目配置​

React 项目​

# React 项目配置

## 项目概述
基于 React 18 的现代前端应用，使用 TypeScript 和 Vite 构建。

## 技术栈
- React 18 + TypeScript
- Vite (构建工具)
- Tailwind CSS (样式)
- React Query (数据获取)
- Zustand (状态管理)

## 目录结构
- src/components/ - 可复用组件
- src/pages/ - 页面组件
- src/hooks/ - 自定义 Hooks
- src/services/ - API 服务
- src/utils/ - 工具函数

## 开发规范
- 使用函数组件 + Hooks
- TypeScript 严格模式
- ESLint + Prettier 自动格式化
- 组件命名使用 PascalCase
- 文件命名使用 kebab-case

## 常用命令
```bash
npm run dev      # 启动开发服务器
npm run build    # 构建生产版本
npm run test     # 运行测试
npm run lint     # 代码检查
npm run preview  # 预览构建结果

注意事项​

  • 所有 API 调用通过 services 层
  • 优先使用 Zustand 进行状态管理
  • 保持组件单一职责原则

### Node.js 后端项目

```markdown
# Node.js 后端项目配置

## 项目概述
基于 Node.js 和 Express 的 RESTful API 服务，使用 TypeScript 开发。

## 技术栈
- Node.js 18+
- Express.js
- TypeScript
- MongoDB + Mongoose
- Redis (缓存)
- JWT (认证)

## 项目结构
- src/controllers/ - 控制器
- src/models/ - 数据模型
- src/routes/ - 路由定义
- src/middleware/ - 中间件
- src/services/ - 业务逻辑
- src/utils/ - 工具函数

## 开发规范
- 使用 ES6+ 语法
- 统一错误处理
- API 返回统一格式
- 完整的类型定义

## 常用命令
```bash
npm run dev      # 开发模式（热重载）
npm run build    # 编译 TypeScript
npm start        # 生产模式启动
npm test         # 运行测试
npm run test:watch # 监听模式测试

环境配置​

  • 复制 .env.example 为 .env
  • 配置数据库连接
  • 设置 JWT 密钥

### Python 项目

```markdown
# Python 项目配置

## 项目概述
基于 FastAPI 的 Web API 项目，使用 Python 3.11+ 开发。

## 技术栈
- Python 3.11+
- FastAPI
- SQLAlchemy (ORM)
- Pydantic (数据验证)
- pytest (测试)
- Black (格式化)

## 项目结构
- app/models/ - 数据模型
- app/api/ - API 路由
- app/core/ - 核心配置
- app/services/ - 业务服务
- tests/ - 测试文件

## 开发规范
- 遵循 PEP 8 代码风格
- 使用类型提示
- 编写单元测试
- 文档字符串遵循 Google 风格

## 常用命令
```bash
uvicorn app.main:app --reload  # 开发服务器
pytest tests/ -v               # 运行测试
black .                         # 格式化代码
mypy .                          # 类型检查

虚拟环境​

  • 使用 venv 或 conda
  • requirements.txt 管理依赖

### Full-Stack 项目

```markdown
# Full-Stack 项目配置

## 项目概述
全栈 Web 应用，包含 React 前端和 Node.js 后端，采用微服务架构。

## 项目结构

project/ ├── frontend/ # React 前端 ├── backend/ # Node.js 后端 ├── shared/ # 共享类型定义 ├── docker-compose.yml # 容器编排 └── docs/ # 项目文档


## 开发工作流
1. 后端先启动，提供 API
2. 前端连接后端 API 开发
3. 使用 Docker 容器化部署
4. CI/CD 自动化部署

## 常用命令
```bash
# 后端
cd backend && npm run dev

# 前端
cd frontend && npm run dev

# Docker
docker-compose up -d

## 团队协作配置

### 多人开发规范

```markdown
# 团队开发规范

## 分支策略
- main: 生产分支
- develop: 开发分支
- feature/*: 功能分支
- hotfix/*: 热修复分支

## 提交规范
- feat: 新功能
- fix: 修复 bug
- docs: 文档更新
- style: 代码格式
- refactor: 重构
- test: 测试相关

## 代码审查
- 所有 PR 需要至少一人审查
- 自动化测试必须通过
- 更新相关文档

## 发布流程
1. 合并到 release 分支
2. 完成测试和修复
3. 合并到 main 分支
4. 打标签发布

Git 配置​

{
  "hooks": {
    "pre-commit": "npm run lint && npm run test",
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

高级配置​

自定义命令​

创建 .claude/commands/ 目录下的命令文件：

<!-- .claude/commands/test-component.md -->
---
name: test-component
description: 🧪 测试组件功能
---

# 测试组件

使用方法：
/test-component <组件名>

这会：
1. 查找组件文件
2. 生成单元测试
3. 运行测试
4. 生成覆盖率报告

MCP 服务器配置​

{
  "mcpServers": {
    "database": {
      "url": "http://localhost:3001/mcp"
    },
    "deployment": {
      "url": "http://localhost:3002/mcp"
    }
  }
}

工作流自动化​

{
  "hooks": {
    "postToolUse": {
      "Write": "npm run format",
      "Bash": "npm run lint"
    }
  }
}

环境特定配置​

开发环境​

{
  "permissions": {
    "allow": [
      "Bash(npm run dev)",
      "Bash(npm run test)",
      "Bash(npm run lint)"
    ]
  },
  "sandbox": {
    "enabled": false
  }
}

生产环境​

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test:prod)"
    ]
  },
  "sandbox": {
    "enabled": true
  }
}

最佳实践​

1. 保持配置简洁​

  • CLAUDE.md < 300 行
  • 只包含必要信息
  • 使用引用减少重复

2. 定期更新​

  • 随项目演进更新配置
  • 移除过时信息
  • 添加新的工作流

3. 团队同步​

  • 将配置纳入版本控制
  • 定期评审和优化
  • 建立配置模板

常见问题​

Q: 技术栈识别不准确？​

运行 /init 后手动修正：

  • 检查 package.json 文件
  • 确认主要框架和库
  • 补充遗漏的依赖

Q: 常用命令缺失？​

在 CLAUDE.md 中添加：

## 常用命令
```bash
# 开发相关
npm run dev
npm run build

# 测试相关
npm test
npm run test:coverage

# 部署相关
npm run deploy

Q: 团队规范不统一？​

创建团队配置文件：

  • 统一的 CLAUDE.md 模板
  • 标准的 .gitignore
  • 共享的 ESLint 配置

相关资源​