第四章：.claude 目录完全指南

~/.claude/                      # 全局配置
├── settings.json               # 全局设置
├── CLAUDE.md                   # 全局说明（适用所有项目）
├── commands/                   # 全局自定义斜杠命令
│   └── my-command.md
├── memory/                     # 全局 Memory 存储
│   └── MEMORY.md               # Memory 索引
└── skills/                     # 全局 Skills

.claude/                        # 项目级配置（提交到 Git）
├── settings.json               # 项目设置（覆盖全局）
├── commands/                   # 项目级自定义命令
│   ├── deploy.md
│   └── review-pr.md
├── rules/                      # 规则文件
│   └── coding-style.md
└── skills/                     # 项目级 Skills

# 项目名称

一句话描述项目用途。

## 技术栈
- 前端：React 18 + TypeScript + Vite
- 后端：NestJS + PostgreSQL + Prisma
- 部署：Docker + Kubernetes

## 目录结构
- apps/web/ — 前端应用
- apps/api/ — 后端服务
- packages/shared/ — 共享类型和工具

## 开发规范
- 使用 pnpm 管理依赖，禁止使用 npm/yarn
- 所有新功能必须附带测试，覆盖率不低于 80%
- API 接口遵循 RESTful 规范，错误响应使用统一格式
- 提交前运行 pnpm lint 和 pnpm test

## 常用命令
- `pnpm dev` — 启动开发服务器
- `pnpm build` — 构建生产版本
- `pnpm test` — 运行所有测试

## 禁止操作
- 不要修改 prisma/migrations/ 下的文件
- 不要直接操作生产数据库
- 不要将 .env.local 提交到 Git

project/
├── CLAUDE.md           # 全局项目说明
├── apps/
│   ├── web/
│   │   └── CLAUDE.md   # 前端专属说明（React 组件规范等）
│   └── api/
│       └── CLAUDE.md   # 后端专属说明（API 设计规范等）

{
  // 默认使用的模型
  "model": "claude-sonnet-4-6",

  // 权限配置
  "permissions": {
    "allow": [
      "Read(**)",           // 允许读取所有文件
      "Write(src/**)",      // 只允许写入 src 目录
      "Bash(npm run *)",    // 允许运行 npm 脚本
      "Bash(git *)"         // 允许 git 操作
    ],
    "deny": [
      "Bash(git push *)",   // 禁止推送
      "Bash(rm -rf *)"      // 禁止强制删除
    ]
  },

  // Hooks 配置（见 4.5 节）
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "echo '执行命令：$CLAUDE_TOOL_INPUT'" }]
      }
    ],
    "PostToolUse": [],
    "Notification": [],
    "Stop": []
  },

  // MCP 服务器（见第五章）
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" }
    }
  },

  // 环境变量（注入到所有 Bash 执行环境）
  "env": {
    "NODE_ENV": "development"
  },

  // 是否在启动时自动显示项目说明
  "includeCoAuthoredBy": true
}

# .claude/commands/review.md

Review the staged git changes for:
1. Logic errors and potential bugs
2. Security vulnerabilities (XSS, SQL injection, hardcoded secrets)
3. Performance issues
4. Adherence to project coding standards in CLAUDE.md

Output format:
- Use severity levels: 🔴 Critical / 🟡 Warning / 🟢 Suggestion
- Group findings by file
- End with an overall assessment (Approve / Request Changes)

# .claude/commands/new-feature.md

Create a new feature module for: $ARGUMENTS

Steps:
1. Create the directory structure under src/modules/$ARGUMENTS/
2. Generate: controller, service, dto, module files
3. Register the module in app.module.ts
4. Create a basic test file
5. Add the route to the API documentation

Follow the existing patterns in src/modules/user/ as reference.

/new-feature payment

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_TOOL_OUTPUT_PATH 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{
          "type": "command",
          "command": "npx prettier --write \"$CLAUDE_TOOL_OUTPUT_PATH\" 2>/dev/null || true"
        }]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "osascript -e 'display notification \"Claude 已完成任务\" with title \"Claude Code\"'"
        }]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(rm -rf|DROP TABLE|truncate)' && exit 1 || exit 0"
        }]
      }
    ]
  }
}

# .claude/skills/api-test.md
---
name: api-test
description: 为 REST API 控制器生成完整的集成测试套件
type: skill
---

# API 集成测试生成器

## TRIGGER

当用户：
- 要求为 Controller 或 Router 文件生成测试
- 提及 "API 测试"、"集成测试"、"supertest"
- 代码中包含 `@Controller`、`router.get/post/put/delete`

## 使用指南

生成测试套件时，遵循以下规范：

1. 使用 supertest + jest 框架
2. 每个端点至少覆盖：成功响应、参数缺失、未授权三种场景
3. 测试数据库使用内存 SQLite（不依赖真实数据库）
4. 测试文件放在 `__tests__/` 目录，命名为 `*.integration.test.ts`

## 示例输出结构

```typescript
describe('UserController (integration)', () => {
  describe('GET /users/:id', () => {
    it('should return user when id is valid', ...)
    it('should return 404 when user not found', ...)
    it('should return 401 when not authenticated', ...)
  })
})
```

# .claude/rules/typescript-style.md
---
description: TypeScript 代码风格规范，适用于所有 .ts/.tsx 文件
---

## TypeScript 编码规范

- 所有函数必须有明确的返回类型注解
- 禁止使用 `any` 类型，使用 `unknown` 替代
- 接口名以 `I` 前缀开头（如 `IUserService`）
- 枚举使用 `const enum` 替代普通 `enum`
- 异步函数统一使用 `async/await`，禁止混用 Promise.then

## 文件命名

- 组件文件：PascalCase（UserCard.tsx）
- 工具文件：camelCase（formatDate.ts）
- 类型文件：camelCase + `.types.ts`（user.types.ts）

# .claude/rules/no-console.md
---
description: 禁止在生产代码中使用 console.log
---

不要在 src/ 目录下的任何文件中使用 `console.log`、`console.warn`、`console.error`。

使用项目统一的 logger 工具：
```typescript
import { logger } from '@/utils/logger'
logger.info('message', { context: 'ServiceName' })
```

# memory/feedback_commit_style.md
---
name: Git 提交规范
description: 用户要求每个功能点独立 commit，不可批量合并
type: feedback
---

每个独立功能点或页面必须单独创建 commit，不允许将多个无关变更合并为一次提交。

**Why:** 用户希望保持清晰的 Git 历史，便于 Code Review 和回滚。

**How to apply:** 完成每个小任务后立即提交，不等待积累。

# Memory Index

- [Git 提交规范](feedback_commit_style.md) — 每个功能独立 commit，不可批量合并
- [项目概览](project_overview.md) — React + NestJS 全栈应用，使用 pnpm monorepo
- [用户背景](user_profile.md) — 5 年 Node.js 经验，对 React 较新