Claude Code提示词工程与四层定制决策：从高效交互到架构级扩展

graph LR
    A[随手提问<br/>Ad-hoc Prompt] --> B[规则固化<br/>Rules/CLAUDE.md]
    B --> C[技能封装<br/>Skills]
    C --> D[子代理委派<br/>Subagents]
    D --> E[外部工具<br/>MCP Servers]

    style A fill:#e1f5fe
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#4fc3f7
    style E fill:#29b6f6

# ❌ 低效写法
帮我改一下这个函数，让它更快

# ✅ 高效写法
重构 src/utils/parser.ts 中的 parseConfig() 函数：
1. 当前瓶颈：正则匹配在 10MB+ 文件上 O(n²) 复杂度
2. 目标：流式解析，内存占用 < 50MB
3. 约束：保持 API 签名不变，保留现有测试用例
4. 参考：可使用 Node.js 的 readline 模块逐行处理

# 查看 @src/types.ts 中的 User 类型定义，
# 然后基于它改写 @src/api/handlers/user.ts 中的 createUser 函数，
# 确保 input validation 使用 zod schema 并和 User 类型保持同步

# 方式1：使用 Shift+Tab 切换到 Plan Mode 后输入需求

# 方式2：在提示词中明确要求
我需要将当前的 REST API 迁移到 GraphQL。请先制定迁移计划：
1. 列出需要变更的所有文件
2. 标注依赖关系和迁移顺序
3. 识别风险点
不要写任何代码，只给计划。

第1轮：写一个基本的 Express 中间件，负责 JWT 验证
第2轮：加上 token 黑名单机制，用 Redis 存储
第3轮：添加速率限制，同一个 token 每分钟最多 60 次请求
第4轮：写集成测试，覆盖正常/过期/黑名单/限流四种场景

为以下数据结构写一个 TypeScript 格式化函数：

输入示例：
{ "user_name": "张三", "create_at": "2026-06-12T08:30:00Z", "is_active": 1 }

期望输出：
{
  "displayName": "张三",
  "createdAt": "2026年6月12日 08:30",
  "active": true
}

规则：
- snake_case → camelCase
- ISO 8601 → 中文日期格式
- 0/1 → boolean

# 以安全审计员的角色审查以下代码：
@src/auth/login.ts

关注点：
- SQL 注入风险
- XSS 攻击面
- 密码处理流程
- Session 管理漏洞
输出 OWASP Top 10 对照检查清单。

实现一个文件上传 API 端点 /api/upload：

硬约束：
- [ ] 文件大小 ≤ 10MB
- [ ] 仅允许 .pdf, .docx, .png
- [ ] 存储到 S3 兼容对象存储
- [ ] 返回唯一文件 ID (UUID v4)
- [ ] 异步处理，不阻塞 HTTP 响应

性能要求：
- [ ] 单文件上传 < 2s (100MB 带宽)
- [ ] 并发 100 无异常

代码规范：
- [ ] TypeScript strict mode
- [ ] 使用项目现有的 Logger
- [ ] 遵循 @src/api/patterns/ 中的 Handler 模式

graph TB
    subgraph "第一层：规则层 Rules"
        R1[CLAUDE.md<br/>项目级主配置]
        R2[".claude/rules/*.md<br/>领域规则文件"]
        R3["CLAUDE.local.md<br/>个人本地配置"]
    end

    subgraph "第二层：技能层 Skills"
        S1[".claude/commands/*.md<br/>斜杠命令"]
        S2["SKILL.md<br/>技能说明文件"]
    end

    subgraph "第三层：代理层 Subagents"
        A1[".claude/agents/*.md<br/>子代理定义"]
        A2["独立上下文<br/>隔离执行"]
    end

    subgraph "第四层：工具层 MCP"
        M1["MCP Servers<br/>外部工具集成"]
        M2["stdio/SSE 传输<br/>标准化协议"]
    end

    R1 --> S1
    S1 --> A1
    A1 --> M1

    style R1 fill:#fff3e0
    style S1 fill:#e8f5e9
    style A1 fill:#e3f2fd
    style M1 fill:#fce4ec

# 示例：一个精炼的 CLAUDE.md

## 项目架构
- 单体应用，Express + TypeScript + PostgreSQL
- 入口：src/index.ts，路由：src/routes/
- 数据层使用 Drizzle ORM，schema 在 src/db/schema.ts
- 禁止直接写 SQL，必须通过 ORM

## 编码规范
- 使用 pnpm，禁止 npm/yarn
- 测试框架 Vitest，测试文件放在 __tests__/ 目录
- 错误处理统一使用 src/utils/errors.ts 中的 AppError 类
- API 响应格式：{ success: boolean, data?: T, error?: string }

## Git 规范
- commit message 遵循 Conventional Commits
- 禁止直接 push 到 main 分支
- 每次变更必须有对应测试

.claude/
  rules/
    frontend.md      # React 组件规范，仅操作 src/frontend/ 时加载
    database.md      # 数据库操作规范，仅操作 src/db/ 时加载
    api-design.md    # API 设计规范
    security.md      # 安全相关硬规则

# 在项目根目录创建斜杠命令
mkdir -p .claude/commands

# 文件：.claude/commands/create-component.md
# 创建一个新的 React 组件

参数：
- $ARGUMENTS = 组件名称（PascalCase）

请执行以下步骤：

1. 在 src/components/$ARGUMENTS/ 目录下创建：
   - $ARGUMENTS.tsx（组件主体）
   - $ARGUMENTS.styles.ts（样式，使用 styled-components）
   - $ARGUMENTS.test.tsx（测试，使用 @testing-library/react）
   - index.ts（导出入口）

2. 组件模板：
   - 使用 React.forwardRef 支持 ref 转发
   - Props 接口命名为 ${ARGUMENTS}Props
   - 包含 displayName 设置

3. 在 src/components/index.ts 中添加导出

4. 运行 pnpm test 确认测试通过

# 文件：.claude/agents/code-reviewer.md
你是一位严格的高级代码审查员。审查给定的代码变更，输出结构化报告：

## 检查维度
1. **正确性**：逻辑错误、边界条件、空指针风险
2. **安全性**：注入、敏感信息泄露、权限绕过
3. **性能**：N+1 查询、内存泄漏、不必要的计算
4. **可维护性**：命名清晰度、函数复杂度、重复代码

## 输出格式
对每个发现：
- 严重级别：🔴 Critical / 🟡 Warning / 🔵 Info
- 位置：文件:行号
- 问题描述 + 修复建议

最后给出总体评分 (A/B/C/D) 和是否建议合并。

请启动一个子代理来探索 src/legacy/ 目录的结构，
总结每个模块的职责和依赖关系，然后回来告诉我。

// 文件：.claude/settings.json 中的 MCP 配置
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

flowchart TD
    Q1{"Q1: 这个需求是<br/>一次性的吗？"}
    Q1 -->|是| PROMPT["直接提示词<br/>交互即可"]
    Q1 -->|否| Q2{"Q2: 需要访问<br/>外部系统吗？"}

    Q2 -->|是| MCP["第四层：MCP"]
    Q2 -->|否| Q3{"Q3: 任务独立且<br/>可能并行吗？"}

    Q3 -->|是| SUB["第三层：Subagent"]
    Q3 -->|否| Q4{"Q4: 有固定步骤<br/>且需参数化？"}

    Q4 -->|是| SKILL["第二层：Skill"]
    Q4 -->|否| Q5{"Q5: 需要每次会话<br/>都遵守吗？"}

    Q5 -->|是| RULE["第一层：Rule"]
    Q5 -->|否| PROMPT

    style PROMPT fill:#e1f5fe
    style RULE fill:#fff3e0
    style SKILL fill:#e8f5e9
    style SUB fill:#e3f2fd
    style MCP fill:#fce4ec

# 在 Claude Code 对话中
/compact

# 或带指示的压缩
/compact 保留数据库 schema 和 API 路由信息，丢弃探索过程中的中间文件内容

# ❌ 浪费 Token
请阅读整个 src/ 目录然后告诉我用户的认证逻辑在哪里

# ✅ 精准引用
查看 @src/middleware/auth.ts 中的 JWT 验证逻辑，
对比 @src/config/auth.ts 中的 token 过期时间配置

# 任务1：前端组件开发
claude

# 任务2：数据库迁移（开新会话）
claude

# 任务3：CI/CD 配置（又一新会话）
claude

# 使用指定模型启动
claude --model haiku    # 快速探索
claude --model opus     # 深度思考

mkdir my-react-app && cd my-react-app
npx create-react-app . --template typescript
claude init  # 初始化 Claude Code 配置

# 文件：CLAUDE.md

## 技术栈
- React 18 + TypeScript 5 + Vite
- 状态管理：Zustand
- 样式方案：Tailwind CSS
- 测试：Vitest + @testing-library/react

## 架构约定
- 组件放在 src/components/，按功能模块分目录
- 自定义 Hook 放在 src/hooks/，以 use 前缀命名
- API 调用封装在 src/services/，统一使用 src/services/http.ts 中的 axios 实例
- 禁止在组件中直接调用 axios

## 编码规范
- 函数组件优先，禁止 class 组件
- Props 必须定义独立的 TypeScript interface
- 每个组件必须有对应的测试文件
- 使用 cn() 工具函数合并 Tailwind 类名

## Git 规范
- feat/fix/refactor/test/docs 前缀
- 每个 PR 必须通过 CI 检查

# 文件：.claude/rules/api-patterns.md
---
description: API 服务层开发规范
globs: src/services/**/*.ts
---

- 所有 API 函数返回 Promise<AxiosResponse<T>>
- 错误处理使用 services/errors.ts 中定义的 ApiError
- 请求/响应拦截器在 http.ts 中统一配置
- 接口路径常量定义在 services/endpoints.ts

# 文件：.claude/commands/add-feature.md
---
description: 创建新的功能模块（含组件、Hook、服务、测试）
arguments: $ARGUMENTS = 功能模块名称（camelCase）
---

为 $ARGUMENTS 功能模块创建完整结构：

1. 创建 src/features/$ARGUMENTS/ 目录，包含：
   - components/ — 功能相关组件
   - hooks/use$ARGUMENTS.ts — 功能相关 Hook
   - services/$ARGUMENTSService.ts — API 调用封装
   - types.ts — 类型定义
   - index.ts — 导出入口

2. Hook 模板：
   - 使用 Zustand store 管理状态
   - 包含 loading / error / data 三态
   - 导出 reset 方法

3. Service 模板：
   - CRUD 四个基本方法
   - 使用 http.ts 的 axios 实例

4. 在 src/features/index.ts 中添加导出
5. 运行 pnpm test 确认无报错

# 文件：.claude/commands/add-page.md
---
description: 创建新的页面组件和路由
arguments: $ARGUMENTS = 页面名称（PascalCase）
---

1. 在 src/pages/ 创建 $ARGUMENTS.tsx
   - 使用 React.lazy 懒加载
   - 包含 Suspense fallback

2. 在 src/router/ 的路由配置中添加新路由
   - 路径：将 PascalCase 转为 kebab-case
   - 例如 UserProfile → /user-profile

3. 如果需要认证保护，用 @src/components/ProtectedRoute 包裹
4. 创建对应的测试文件

# 文件：.claude/agents/test-writer.md
---
description: 为指定文件或目录生成全面的测试用例
---

你是测试工程师。接收目标文件路径后：

1. 读取目标文件，分析所有导出函数/组件
2. 为每个导出生成测试用例，覆盖：
   - 正常路径（Happy Path）
   - 边界条件（空值、极大值、特殊字符）
   - 错误路径（异常处理）
   - 用户交互（如果是组件）

3. 测试规范：
   - 使用 Vitest + @testing-library/react
   - Mock 外部依赖（API、Router、Store）
   - 测试描述用中文，清晰表达意图
   - 目标覆盖率 ≥ 80%

4. 运行测试确认全部通过
5. 输出覆盖率报告

// 文件：.claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(pnpm test:*)",
      "Bash(pnpm lint:*)",
      "Bash(pnpm build:*)"
    ]
  },
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-browser"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-filesystem", "./src"]
    }
  }
}

# 启动 Claude Code
claude

# 使用技能创建功能模块
> /add-feature shoppingCart

# 使用技能创建页面
> /add-page ShoppingCart

# 委派子代理写测试
> 请使用 test-writer 子代理为 src/features/shoppingCart/ 生成全面测试

# 使用 MCP 浏览器验证页面
> 启动浏览器，访问 localhost:5173/shopping-cart，截图确认页面渲染正常

# 压缩上下文，准备下一个任务
> /compact 保留 shoppingCart 功能模块的架构信息

# ❌ 文档式 CLAUDE.md（浪费 Token）
## 项目介绍
本项目是一个基于 React 的电商平台，目标用户是...

## 技术选型原因
选择 React 而不是 Vue 是因为团队...

# ✅ 指令式 CLAUDE.md（高效）
## 硬约束
- React 18 + TypeScript strict mode
- 禁止使用 any，禁止 @ts-ignore
- API 错误码映射表在 src/constants/error-codes.ts

# .claude/rules/testing.md — 仅操作测试文件时加载
---
description: 测试编写规范
globs: ["**/*.test.ts", "**/*.test.tsx", "**/__tests__/**"]
---

- 测试框架：Vitest
- 组件测试：@testing-library/react
- Mock 工具：vi.mock()
- 命名：describe/it 使用中文描述

# ❌ 同一会话中混合任务
claude
> 帮我写登录页面的组件...
> (写完登录) 现在帮我优化数据库查询...
> (优化完) 帮我配置 GitHub Actions...

# ✅ 每个任务独立会话
claude  # 会话1：登录页面
claude  # 会话2：数据库优化
claude  # 会话3：CI 配置

# 这些不需要定制，直接问就好：
- "这个函数的时间复杂度是多少"
- "帮我把这段代码从 JavaScript 转成 TypeScript"
- "这个报错是什么意思：TypeError: Cannot read property..."

# 这些值得定制：
- "每个新功能都要创建5个文件、3个测试" → Skill
- "项目禁止使用 moment.js" → Rule
- "代码审查要检查5个维度" → Subagent