# 項(xiàng)目 AI 協(xié)作規(guī)范
## 項(xiàng)目概覽
- **項(xiàng)目名稱**: [Your Project Name]
- **技術(shù)棧**: 前端 Vue 3 + Vite / React 18 + Next.js，后端 Java 17 + Spring Boot 3.x
- **架構(gòu)風(fēng)格**: 前后端分離，RESTful API，DDD 領(lǐng)域驅(qū)動(dòng)設(shè)計(jì)
- **目標(biāo)用戶**: [內(nèi)部系統(tǒng) / SaaS 產(chǎn)品 / 移動(dòng)端 H5]
## 編碼規(guī)范（強(qiáng)制）
### 通用規(guī)則
- 所有代碼注釋和文檔使用中文
- 變量命名采用駝峰式（camelCase），常量使用全大寫下劃線（UPPER_SNAKE_CASE）
- 禁止在代碼中硬編碼敏感信息（密碼、密鑰、Token）
- 每個(gè)函數(shù)不超過 50 行，超過必須拆分
- 所有 API 調(diào)用必須包含錯(cuò)誤處理邏輯
### Vue 前端規(guī)范
- 使用 Composition API + `<script setup>` 語(yǔ)法
- 組件命名采用 PascalCase，文件名為大駝峰（如 `UserProfile.vue`）
- Props 必須定義類型和默認(rèn)值
- 使用 Pinia 進(jìn)行狀態(tài)管理，禁止直接修改 Store 中的 State
- 組件模板層級(jí)不超過 5 層嵌套
- API 請(qǐng)求統(tǒng)一封裝在 `services/` 目錄，使用攔截器處理認(rèn)證和錯(cuò)誤
### React 前端規(guī)范
- 使用函數(shù)組件 + Hooks，禁止使用 Class 組件
- 組件文件使用 PascalCase 命名（如 `UserCard.tsx`）
- 自定義 Hook 以 `use` 開頭，統(tǒng)一放在 `hooks/` 目錄
- 狀態(tài)管理使用 Zustand 或 Redux Toolkit
- 必須配置 ESLint + Prettier，遵循團(tuán)隊(duì)共享的 `.eslintrc` 配置
- 使用 React Query 處理服務(wù)端狀態(tài)，禁止在組件內(nèi)直接調(diào)用 fetch
### Java 后端規(guī)范
- 使用 Java 17 特性（Record、Pattern Matching、Stream API）
- 遵循阿里巴巴 Java 開發(fā)手冊(cè)（嵩山版）
- 分層架構(gòu)：Controller → Service → Repository → Entity
- 所有 API 返回統(tǒng)一封裝為 `Result<T>` 對(duì)象
- 數(shù)據(jù)庫(kù)操作使用 MyBatis-Plus 或 JPA，禁止手寫 SQL（復(fù)雜查詢除外）
- 日志使用 SLF4J + Logback，禁止 `System.out.println`
- 異常統(tǒng)一在 GlobalExceptionHandler 中處理
## 安全紅線（禁止）
- ? 生成、修改或詢問生產(chǎn)環(huán)境密碼、密鑰、Token
- ? 將內(nèi)部代碼、數(shù)據(jù)庫(kù) schema、業(yè)務(wù)邏輯上傳至公共 AI 服務(wù)
- ? 自動(dòng)生成數(shù)據(jù)庫(kù) Migration 腳本并直接執(zhí)行
- ? 在日志中打印敏感字段（手機(jī)號(hào)、身份證號(hào)、銀行卡號(hào)）
- ? 修改 `.claudeignore` 文件以繞過安全限制
- ? 使用 AI 生成代碼后不經(jīng)過 Review 直接提交
## 協(xié)作流程
1. 開發(fā)前閱讀 `CLAUDE.md` 確認(rèn)當(dāng)前任務(wù)規(guī)范
2. 使用 `/clear` 開始新任務(wù)上下文
3. AI 生成代碼后，開發(fā)者必須逐行 Review 再接受
4. 提交前運(yùn)行本地測(cè)試：`npm run test` / `./mvnw test`
5. 所有提交必須關(guān)聯(lián) Jira/Tapd 工單號(hào)
## 常用命令
- `npm run dev` —— 啟動(dòng)前端開發(fā)服務(wù)器
- `npm run test:unit` —— 運(yùn)行單元測(cè)試
- `./mvnw spring-boot:run` —— 啟動(dòng)后端服務(wù)
- `./mvnw test` —— 運(yùn)行 Java 測(cè)試
- `npm run lint` —— 代碼格式檢查

~/.claude/CLAUDE.md          ← 用戶級(jí)（個(gè)人全局）
  ↓
<repo>/CLAUDE.md             ← 項(xiàng)目級(jí)（團(tuán)隊(duì)共享）★ 最優(yōu)先
  ↓
<repo>/.claude/commands/     ← 項(xiàng)目級(jí)自定義命令
  ↓
<repo>/.claude/settings.json ← 項(xiàng)目級(jí)設(shè)置

{
  "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/
# 日志與數(shù)據(jù)
logs/
*.log
*.sql
data/
# IDE 配置（可能含服務(wù)器地址）
.idea/
.vscode/settings.json
# 測(cè)試數(shù)據(jù)（可能含真實(shí)數(shù)據(jù)）
src/test/resources/fixtures/
mock/
# 文檔中的敏感信息
docs/internal/
*機(jī)密*
*密級(jí)*

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

請(qǐng)按照以下規(guī)范生成 Vue 3 組件：

1. 使用 `<script setup lang="ts">` + Composition API
2. Props 使用 `withDefaults(defineProps<...>(), {...})` 定義
3. 組件放在 `src/components/` 目錄下
4. 樣式使用 `<style scoped lang="scss">`
5. 包含 JSDoc 注釋說(shuō)明組件用途
6. 導(dǎo)出組件名稱使用 PascalCase

生成以下文件：
- `src/components/$ARGUMENTS/$ARGUMENTS.vue` —— 主組件
- `src/components/$ARGUMENTS/index.ts` —— 導(dǎo)出文件
- `src/components/$ARGUMENTS/types.ts` —— 類型定義

<!-- .claude/commands/review.md -->
請(qǐng)對(duì)當(dāng)前變更進(jìn)行代碼審查，按以下維度檢查：

- [ ] 是否符合 CLAUDE.md 中的編碼規(guī)范
- [ ] 是否包含充分的錯(cuò)誤處理
- [ ] 是否包含單元測(cè)試（新增功能必須）
- [ ] 是否引入安全風(fēng)險(xiǎn)（SQL 注入、XSS、敏感信息泄露）
- [ ] 性能是否存在明顯問題（N+1 查詢、大數(shù)據(jù)量未分頁(yè)）
- [ ] 命名是否清晰語(yǔ)義化

對(duì)每個(gè)問題給出：
1. 嚴(yán)重級(jí)別（阻斷 / 警告 / 建議）
2. 具體位置（文件:行號(hào)）
3. 修復(fù)建議

<!-- 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 {
  /** 用戶信息對(duì)象 */
  userInfo: UserInfo
  /** 是否顯示角色標(biāo)簽 */
  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>

請(qǐng)生成一個(gè) Vue 3 組件，要求：
- 技術(shù)棧：Vue 3.4 + TypeScript + Vite + SCSS + Pinia
- 組件名稱：[組件名]
- 功能描述：[具體功能]
- Props：[列出需要的 props 及類型]
- 必須包含：加載狀態(tài)、錯(cuò)誤處理、空數(shù)據(jù)展示
- 樣式使用 BEM 命名規(guī)范
- 組件復(fù)雜度較高時(shí)，拆分子組件

// 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 {
  /** 用戶數(shù)據(jù) */
  user: User
  /** 卡片尺寸 */
  size?: 'sm' | 'md' | 'lg'
  /** 點(diǎn)擊回調(diào) */
  onSelect?: (userId: string) => void
}
/**
 * 用戶卡片組件
 * @description 展示用戶基本信息，支持點(diǎn)擊查看詳情
 */
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} 的詳細(xì)信息`}
    >
      <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>
  )
})

請(qǐng)生成一個(gè) React 函數(shù)組件，要求：
- 技術(shù)棧：React 18 + TypeScript + Tailwind CSS + Zustand + React Query
- 組件名稱：[組件名]
- 使用 memo 優(yōu)化重渲染
- 事件處理使用 useCallback
- 類型定義放在獨(dú)立 interface 中
- 支持 a11y（role, aria-label, tabIndex）
- 加載/錯(cuò)誤/空狀態(tài)使用 Suspense + ErrorBoundary 模式
- 遵循 FSD（Feature-Sliced Design）架構(gòu)

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));
    }
    /**
     * 創(chuàng)建用戶
     */
    @PostMapping
    @Operation(summary = "創(chuàng)建用戶")
    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("創(chuàng)建用戶, name={}", dto.getName());
        // 校驗(yàn)用戶名唯一性
        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("用戶創(chuàng)建成功, userId={}", entity.getId());
        return entity.getId();
    }
}

請(qǐng)生成 Java Spring Boot 代碼，要求：
- 技術(shù)棧：Java 17 + Spring Boot 3.2 + MyBatis-Plus + MySQL 8
- 遵循分層架構(gòu)：Controller → Service → Repository
- 使用 Record 定義 DTO（Java 17 特性）
- 所有返回使用 Result<T> 統(tǒng)一封裝
- 使用 @Slf4j 記錄日志，禁止 System.out.println
- 數(shù)據(jù)庫(kù)操作使用 MyBatis-Plus，禁止手寫 SQL
- 事務(wù)使用 @Transactional 注解
- 包含 Swagger 注解 (@Operation, @Tag)
- 參數(shù)校驗(yàn)使用 Jakarta Validation (@Valid, @NotBlank)
- 異常統(tǒng)一拋出自定義 BusinessException

# .env.example（納入版本控制，作為模板）
# 復(fù)制為 .env 后填入真實(shí)值（.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=

# 開發(fā)環(huán)境默認(rèn)值寫在 application-dev.yml 中
# 敏感值通過環(huán)境變量注入，禁止硬編碼

## MCP 工具使用規(guī)范

### 允許的 MCP 工具（白名單制）
- [x] 文件系統(tǒng)工具（只讀模式）
- [x] Git 工具（只讀查詢，禁止寫入）
- [x] 測(cè)試運(yùn)行工具（npm test / mvn test）
- [x] 代碼檢查工具（ESLint / Checkstyle）

### 禁止的 MCP 工具
- [ ] 數(shù)據(jù)庫(kù)直接操作工具
- [ ] 遠(yuǎn)程部署工具
- [ ] 郵件/通知發(fā)送工具
- [ ] 第三方 API 調(diào)用工具（未經(jīng)審批）

### 審批流程
新增 MCP 工具需經(jīng)技術(shù)負(fù)責(zé)人審批，評(píng)估：
1. 工具來(lái)源是否可信
2. 權(quán)限范圍是否最小化
3. 是否記錄操作日志
4. 是否有撤銷機(jī)制

{
  "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"]
    }
  }
}