从配置到落地详解Claude Code企业级开发的规范指南

# 项目 AI 协作规范
## 项目概览
- **项目名称**: [Your Project Name]
- **技术栈**: 前端 Vue 3 + Vite / React 18 + Next.js，后端 Java 17 + Spring Boot 3.x
- **架构风格**: 前后端分离，RESTful API，DDD 领域驱动设计
- **目标用户**: [内部系统 / SaaS 产品 / 移动端 H5]
## 编码规范（强制）
### 通用规则
- 所有代码注释和文档使用中文
- 变量命名采用驼峰式（camelCase），常量使用全大写下划线（UPPER_SNAKE_CASE）
- 禁止在代码中硬编码敏感信息（密码、密钥、Token）
- 每个函数不超过 50 行，超过必须拆分
- 所有 API 调用必须包含错误处理逻辑
### Vue 前端规范
- 使用 Composition API + `<script setup>` 语法
- 组件命名采用 PascalCase，文件名为大驼峰（如 `UserProfile.vue`）
- Props 必须定义类型和默认值
- 使用 Pinia 进行状态管理，禁止直接修改 Store 中的 State
- 组件模板层级不超过 5 层嵌套
- API 请求统一封装在 `services/` 目录，使用拦截器处理认证和错误
### React 前端规范
- 使用函数组件 + Hooks，禁止使用 Class 组件
- 组件文件使用 PascalCase 命名（如 `UserCard.tsx`）
- 自定义 Hook 以 `use` 开头，统一放在 `hooks/` 目录
- 状态管理使用 Zustand 或 Redux Toolkit
- 必须配置 ESLint + Prettier，遵循团队共享的 `.eslintrc` 配置
- 使用 React Query 处理服务端状态，禁止在组件内直接调用 fetch
### Java 后端规范
- 使用 Java 17 特性（Record、Pattern Matching、Stream API）
- 遵循阿里巴巴 Java 开发手册（嵩山版）
- 分层架构：Controller → Service → Repository → Entity
- 所有 API 返回统一封装为 `Result<T>` 对象
- 数据库操作使用 MyBatis-Plus 或 JPA，禁止手写 SQL（复杂查询除外）
- 日志使用 SLF4J + Logback，禁止 `System.out.println`
- 异常统一在 GlobalExceptionHandler 中处理
## 安全红线（禁止）
- ❌ 生成、修改或询问生产环境密码、密钥、Token
- ❌ 将内部代码、数据库 schema、业务逻辑上传至公共 AI 服务
- ❌ 自动生成数据库 Migration 脚本并直接执行
- ❌ 在日志中打印敏感字段（手机号、身份证号、银行卡号）
- ❌ 修改 `.claudeignore` 文件以绕过安全限制
- ❌ 使用 AI 生成代码后不经过 Review 直接提交
## 协作流程
1. 开发前阅读 `CLAUDE.md` 确认当前任务规范
2. 使用 `/clear` 开始新任务上下文
3. AI 生成代码后，开发者必须逐行 Review 再接受
4. 提交前运行本地测试：`npm run test` / `./mvnw test`
5. 所有提交必须关联 Jira/Tapd 工单号
## 常用命令
- `npm run dev` —— 启动前端开发服务器
- `npm run test:unit` —— 运行单元测试
- `./mvnw spring-boot:run` —— 启动后端服务
- `./mvnw test` —— 运行 Java 测试
- `npm run lint` —— 代码格式检查

~/.claude/CLAUDE.md          ← 用户级（个人全局）
  ↓
<repo>/CLAUDE.md             ← 项目级（团队共享）★ 最优先
  ↓
<repo>/.claude/commands/     ← 项目级自定义命令
  ↓
<repo>/.claude/settings.json ← 项目级设置

{
  "autoUpdaterStatus": "disabled",
  "preferredNotifChannel": "bell",
  "theme": "dark",
  "verbose": true,
  "commandHistoryDebounceMs": 15000,
  "disabledTools": [
    "Write",
    "Edit",
    "MultiEdit",
    " bash",
    "Exit',
    "GlobTool",
    "GrepTool",
    "LSTool",
    "View",
    "URLFetchTool",
    "ViewRange",
    "Task"
  ],
  "limitPrompts": true,
  "permissionRequirements": {
    "edit": "always-ask",
    "write": "always-ask",
    "bash": "always-ask",
    "delete": "always-ask"
  }
}

# 配置文件（含敏感信息）
*.env
*.env.local
*.env.production
application.yml
application-prod.yml
application-dev.yml
# 密钥与证书
*.pem
*.key
*.crt
certs/
keystore/
# 依赖目录
node_modules/
target/
build/
dist/
# 日志与数据
logs/
*.log
*.sql
data/
# IDE 配置（可能含服务器地址）
.idea/
.vscode/settings.json
# 测试数据（可能含真实数据）
src/test/resources/fixtures/
mock/
# 文档中的敏感信息
docs/internal/
*机密*
*密级*

<!-- .claude/commands/gen-vue.md -->
$ARGUMENTS: 组件名称（如 UserProfile）

请按照以下规范生成 Vue 3 组件：

1. 使用 `<script setup lang="ts">` + Composition API
2. Props 使用 `withDefaults(defineProps<...>(), {...})` 定义
3. 组件放在 `src/components/` 目录下
4. 样式使用 `<style scoped lang="scss">`
5. 包含 JSDoc 注释说明组件用途
6. 导出组件名称使用 PascalCase

生成以下文件：
- `src/components/$ARGUMENTS/$ARGUMENTS.vue` —— 主组件
- `src/components/$ARGUMENTS/index.ts` —— 导出文件
- `src/components/$ARGUMENTS/types.ts` —— 类型定义

<!-- .claude/commands/review.md -->
请对当前变更进行代码审查，按以下维度检查：

- [ ] 是否符合 CLAUDE.md 中的编码规范
- [ ] 是否包含充分的错误处理
- [ ] 是否包含单元测试（新增功能必须）
- [ ] 是否引入安全风险（SQL 注入、XSS、敏感信息泄露）
- [ ] 性能是否存在明显问题（N+1 查询、大数据量未分页）
- [ ] 命名是否清晰语义化

对每个问题给出：
1. 严重级别（阻断 / 警告 / 建议）
2. 具体位置（文件:行号）
3. 修复建议

<!-- UserProfile.vue -->
<template>
  <div class="user-profile">
    <Avatar :src="userInfo.avatar" :size="64" />
    <div class="user-info">
      <h3 class="user-name">{{ userInfo.name }}</h3>
      <p class="user-role">{{ displayRole }}</p>
    </div>
  </div>
</template>
<script setup lang="ts">
import { computed } from 'vue'
import { Avatar } from '@/components/common'
import type { UserInfo } from './types'
/**
 * 用户 profile 展示组件
 * @description 显示用户头像、名称和角色
 */
interface Props {
  /** 用户信息对象 */
  userInfo: UserInfo
  /** 是否显示角色标签 */
  showRole?: boolean
}
const props = withDefaults(defineProps<Props>(), {
  showRole: true
})
const displayRole = computed(() => {
  if (!props.showRole) return ''
  const roleMap: Record<string, string> = {
    admin: '管理员',
    editor: '编辑',
    viewer: '访客'
  }
  return roleMap[props.userInfo.role] || '普通用户'
})
</script>
<style scoped lang="scss">
.user-profile {
  display: flex;
  align-items: center;
  gap: 12px;
  .user-name {
    font-size: 16px;
    font-weight: 600;
    margin: 0;
  }
  .user-role {
    font-size: 14px;
    color: var(--text-secondary);
    margin: 4px 0 0;
  }
}
</style>

请生成一个 Vue 3 组件，要求：
- 技术栈：Vue 3.4 + TypeScript + Vite + SCSS + Pinia
- 组件名称：[组件名]
- 功能描述：[具体功能]
- Props：[列出需要的 props 及类型]
- 必须包含：加载状态、错误处理、空数据展示
- 样式使用 BEM 命名规范
- 组件复杂度较高时，拆分子组件

// UserCard.tsx
import { memo, useCallback } from 'react'
import { useNavigate } from 'react-router-dom'
import { Avatar, Badge } from '@/components/ui'
import { useUserStore } from '@/stores'
import type { User } from '@/types'
interface UserCardProps {
  /** 用户数据 */
  user: User
  /** 卡片尺寸 */
  size?: 'sm' | 'md' | 'lg'
  /** 点击回调 */
  onSelect?: (userId: string) => void
}
/**
 * 用户卡片组件
 * @description 展示用户基本信息，支持点击查看详情
 */
export const UserCard = memo(function UserCard({
  user,
  size = 'md',
  onSelect
}: UserCardProps) {
  const navigate = useNavigate()
  const { setSelectedUser } = useUserStore()
  const handleClick = useCallback(() => {
    setSelectedUser(user)
    onSelect?.(user.id)
    navigate(`/users/${user.id}`)
  }, [user, onSelect, navigate, setSelectedUser])
  const sizeClasses = {
    sm: 'p-3 gap-2',
    md: 'p-4 gap-3',
    lg: 'p-6 gap-4'
  }
  return (
    <div
      className={`flex items-center rounded-lg border border-gray-200 
        hover:shadow-md transition-shadow cursor-pointer 
        bg-white ${sizeClasses[size]}`}
      onClick={handleClick}
      role="button"
      tabIndex={0}
      aria-label={`查看 ${user.name} 的详细信息`}
    >
      <Avatar src={user.avatar} alt={user.name} size={size === 'lg' ? 56 : 40} />
      <div className="flex-1 min-w-0">
        <h4 className="font-medium text-gray-900 truncate">{user.name}</h4>
        <p className="text-sm text-gray-500 truncate">{user.email}</p>
      </div>
      <Badge variant={user.status === 'active' ? 'success' : 'default'}>
        {user.status === 'active' ? '在职' : '离职'}
      </Badge>
    </div>
  )
})

请生成一个 React 函数组件，要求：
- 技术栈：React 18 + TypeScript + Tailwind CSS + Zustand + React Query
- 组件名称：[组件名]
- 使用 memo 优化重渲染
- 事件处理使用 useCallback
- 类型定义放在独立 interface 中
- 支持 a11y（role, aria-label, tabIndex）
- 加载/错误/空状态使用 Suspense + ErrorBoundary 模式
- 遵循 FSD（Feature-Sliced Design）架构

package com.company.project.controller.user;
import com.company.project.common.Result;
import com.company.project.controller.request.UserCreateRequest;
import com.company.project.controller.response.UserDetailResponse;
import com.company.project.dto.UserDTO;
import com.company.project.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
/**
 * 用户管理 API
 */
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
@Tag(name = "用户管理", description = "用户的增删改查接口")
public class UserController {
    private final UserService userService;
    /**
     * 获取用户详情
     */
    @GetMapping("/{userId}")
    @Operation(summary = "获取用户详情")
    public Result<UserDetailResponse> getUserDetail(
            @PathVariable Long userId) {
        UserDTO userDTO = userService.getUserDetail(userId);
        return Result.success(UserDetailResponse.from(userDTO));
    }
    /**
     * 创建用户
     */
    @PostMapping
    @Operation(summary = "创建用户")
    public Result<Long> createUser(
            @Valid @RequestBody UserCreateRequest request) {
        Long userId = userService.createUser(request.toDTO());
        return Result.success(userId);
    }
}

package com.company.project.service.impl;
import com.company.project.dto.UserDTO;
import com.company.project.entity.User;
import com.company.project.enums.UserStatus;
import com.company.project.exception.BusinessException;
import com.company.project.exception.ErrorCode;
import com.company.project.mapper.UserMapper;
import com.company.project.repository.UserRepository;
import com.company.project.service.UserService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Slf4j
@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    private final UserRepository userRepository;
    private final UserMapper userMapper;
    @Override
    @Cacheable(value = "user", key = "#userId")
    public UserDTO getUserDetail(Long userId) {
        log.info("获取用户详情, userId={}", userId);
        User user = userRepository.findById(userId)
            .orElseThrow(() -> new BusinessException(ErrorCode.USER_NOT_FOUND));
        if (user.getStatus() == UserStatus.DELETED) {
            throw new BusinessException(ErrorCode.USER_ALREADY_DELETED);
        }
        return userMapper.toDTO(user);
    }
    @Override
    @Transactional(rollbackFor = Exception.class)
    public Long createUser(UserDTO dto) {
        log.info("创建用户, name={}", dto.getName());
        // 校验用户名唯一性
        if (userRepository.existsByName(dto.getName())) {
            throw new BusinessException(ErrorCode.USER_NAME_EXISTS);
        }
        User entity = userMapper.toEntity(dto);
        entity.setStatus(UserStatus.ACTIVE);
        userRepository.save(entity);
        log.info("用户创建成功, userId={}", entity.getId());
        return entity.getId();
    }
}

请生成 Java Spring Boot 代码，要求：
- 技术栈：Java 17 + Spring Boot 3.2 + MyBatis-Plus + MySQL 8
- 遵循分层架构：Controller → Service → Repository
- 使用 Record 定义 DTO（Java 17 特性）
- 所有返回使用 Result<T> 统一封装
- 使用 @Slf4j 记录日志，禁止 System.out.println
- 数据库操作使用 MyBatis-Plus，禁止手写 SQL
- 事务使用 @Transactional 注解
- 包含 Swagger 注解 (@Operation, @Tag)
- 参数校验使用 Jakarta Validation (@Valid, @NotBlank)
- 异常统一抛出自定义 BusinessException

# .env.example（纳入版本控制，作为模板）
# 复制为 .env 后填入真实值（.env 在 .gitignore 和 .claudeignore 中）
DATABASE_URL=jdbc:mysql://localhost:3306/project
DATABASE_USERNAME=
DATABASE_PASSWORD=
REDIS_HOST=localhost
REDIS_PORT=6379
JWT_SECRET=
OSS_ACCESS_KEY=
OSS_SECRET_KEY=

# 开发环境默认值写在 application-dev.yml 中
# 敏感值通过环境变量注入，禁止硬编码

## MCP 工具使用规范

### 允许的 MCP 工具（白名单制）
- [x] 文件系统工具（只读模式）
- [x] Git 工具（只读查询，禁止写入）
- [x] 测试运行工具（npm test / mvn test）
- [x] 代码检查工具（ESLint / Checkstyle）

### 禁止的 MCP 工具
- [ ] 数据库直接操作工具
- [ ] 远程部署工具
- [ ] 邮件/通知发送工具
- [ ] 第三方 API 调用工具（未经审批）

### 审批流程
新增 MCP 工具需经技术负责人审批，评估：
1. 工具来源是否可信
2. 权限范围是否最小化
3. 是否记录操作日志
4. 是否有撤销机制

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/project/src"],
      "env": {
        "READ_ONLY": "true"
      }
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/project"],
      "allowedCommands": ["status", "log", "diff", "branch"],
      "blockedCommands": ["push", "force-push", "reset", "checkout"]
    }
  }
}