Claude Code 实用指南：核心机制、关键配置与高频场景

# CLAUDE.md

## 项目背景
本项目为面向电商平台的订单管理系统，涉及支付、物流接口对接，需保证数据一致性。

## 技术栈
- 后端：Node.js + Express + Sequelize
- 数据库：PostgreSQL 14，所有写操作必须加事务
- 前端：Vue3 + Vite + Pinia

## 代码规范
- 所有涉及金额的字段必须做精度校验（保留2位小数）
- 禁止硬编码常量，统一放在 config/constants.js 中
- 新增接口必须添加 JWT 权限校验，无需校验的接口需标注原因

## 测试要求
- 跑测试命令：npm run test:order
- 接口测试覆盖率需达到 80% 以上

## ⚠️ 禁止操作
- 禁止修改 `db/migrations/` 下的历史迁移文件，只能新增
- 不要删除 `config/production.js`，这是生产环境核心配置
- 提交代码前必须运行 `npm run lint` 修复代码格式问题

# CLAUDE.local.md（不提交 git）

## 本地环境
- 本地数据库：postgresql://postgres:123456@localhost:5432/order_dev
- 测试账号：test_admin / Test@456
- 本地 Mock 支付服务器：http://localhost:9000

## 调试说明
- 启动 order-service 前需先启动 `npm run mock:pay`
- 调试时可通过 http://localhost:3000/dev 查看接口日志

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cat | jq -r '.file_path' | xargs eslint --fix"
          }
        ]
      }
    ]
  }
}

{
  "permissions": {
    "deny": [
      "Bash(rm -rf /)",
      "Bash(TRUNCATE TABLE*)",
      "Bash(git rebase --force)"
    ]
  }
}

# ~/.claude/CLAUDE.md（全局生效）

## 我的编码偏好
- 代码注释用中文，变量名和函数名用英文驼峰命名
- 函数超过 40 行提示我拆分，提高可读性
- 生成 SQL 时默认加上 LIMIT 100，避免全表查询

## 沟通方式
- 回答问题先给结论，再分点解释原因
- 不确定的方案列出 2 个选项并说明优缺点，让我选择

---
name: performance-reviewer
description: 接口性能审查专家，当用户要求性能测试或上线前调用
model: claude-sonnet-4-5
tools: [Read, Bash]
color: blue
---

## 职责
对指定接口模块进行性能扫描，重点检查：

1. **查询性能**：是否存在未加索引的慢查询、全表扫描
2. **接口响应**：接口响应时间是否超过 500ms，是否需要分页
3. **资源占用**：接口调用时 CPU、内存占用是否异常

## 输出格式
### 性能审查报告
**扫描范围**：xxx
**发现问题**：
- 🔴 高危：[描述 + 文件位置 + 影响]
- 🟡 中危：[描述 + 文件位置 + 优化建议]
**优化方案**：...

你：帮我审查一下 order-api 模块的接口性能

Claude Code 启动 performance-reviewer（蓝色标注）
  → SubAgent 读取 25 个接口文件，模拟 1000 次请求测试...
  → 主对话上下文完全没有变化

SubAgent 完成，汇报结果：
  🔴 高危：OrderController.java:67 订单列表查询未加索引，响应时间 800ms
  🟡 中危：订单详情接口未分页，大数据量下响应缓慢，建议添加分页参数

---
name: api-doc
description: 根据当前接口代码，生成标准化的接口文档，包含请求参数、响应格式、错误码
---

## 输出格式

### 📄 接口文档 {apiName}

**接口路径**：/api/{path}
**请求方法**：GET/POST/PUT/DELETE
**请求参数**：
| 参数名 | 类型 | 必选 | 描述 |
|--------|------|------|------|
| param1 | String | 是 | 描述信息 |

**响应格式**：
{
  "code": 200,
  "message": "success",
  "data": {}
}

**错误码说明**：
- 400：参数错误
- 401：未授权
- 500：服务器内部错误

1. 启动 claude
   ↓ 加载 CLAUDE.md          → 知道：电商订单项目、禁止硬编码
   ↓ 加载 ~/.claude/CLAUDE.md → 知道：驼峰命名、回答先给结论

2. 你说："帮我做订单列表接口"
   ↓ Claude Code 写代码（遵守 CLAUDE.md 规范）
   ↓ 写完触发 PostToolUse Hook → 自动跑 ESLint 修复格式

3. 你说："帮我做接口性能审查"
   ↓ 启动 performance-reviewer SubAgent（独立上下文）
   ↓ 审查完毕，主对话收到报告，上下文无影响

4. 你说："生成这个接口的文档"
   ↓ 调用 api-doc Skill（共享上下文）
   ↓ 根据接口代码生成标准化文档

5. 同事拉代码，用他自己的 CLAUDE.local.md
   ↓ 本地环境配置各自独立，互不影响

# 默认模式（每次改文件都问你）→ 自动模式（不再打扰）→ Plan Mode（只聊不动手）
Shift + Tab  # 循环切换三种模式

# 双击 ESC 或输入 /rewind
# 选择回滚点 → 选回滚代码+会话 / 仅代码 / 仅会话

# 安装 Figma MCP Server 后，通过 /mcp 授权
# 然后把 Figma 设计稿链接直接贴给 Claude Code
修改当前页面，使其与 Figma 设计稿完全一致
https://www.figma.com/file/xxx...

# 在 /hooks 中配置
# 触发时机：PostToolUse → Write/Edit
cat | jq -r '.file_path' | xargs prettier --write --single-quote

假设审查 150 个接口性能：

❌ 用 Skill：150 个接口的性能数据全部塞进主对话上下文
            → Token 爆炸，后续 Claude 响应变慢、逻辑出错

✅ 用 SubAgent：独立窗口处理，主对话只收到最终性能报告
            → 主对话干干净净，可继续正常开发工作

/plugin          # 进入插件管理器
# Discover → 找到目标插件 → 回车安装
# 安装后重启 Claude Code 即可生效

/compact         # 压缩上下文（保留关键信息，减少 Token 消耗）
/compact 重点保留接口开发相关内容  # 带策略的压缩，精准保留核心内容

/clear           # 清空所有上下文（开始全新任务时用）

/tasks           # 查看后台任务（如 npm run dev）
Ctrl + B         # 把前台任务放到后台，让 Claude Code 继续响应

claude -c        # 启动并自动恢复上一次对话（continue 缩写）
/resume          # 手动选择要恢复的历史会话

claude --dangerously-skip-permissions
# 跳过所有权限确认，Claude 可执行任意终端命令
# 模式显示为：bypass permissions on
# ⚠️ 慎用，理论上 Claude 拥有与你相同的终端权限