本文围绕 Claude Code 的核心能力与最佳实践展开，核心原则：人是开发的第一责任人，AI 是在人的授权与监督下辅助执行的任务智能伙伴，内容涵盖Claude Code核心功能与典型场景、最佳实践、实战经验与安全准则等。

1. 核心功能与典型场景

Claude Code 可实现自然语言构建功能、代码调试修复、项目结构分析、自动化开发任务、直接编辑文件/运行命令等能力，核心工作方式为终端对话式交互，支持文件编辑、命令执行、git 管理、项目上下文维护及外部 MCP 集成。

2.1 核心能力场景

能力类型	需求示例	执行逻辑
功能构建	Create a user authentication system	分析需求 → 制定方案 → 编写代码
调试修复	Fix the payment processing error	查看日志 → 定位问题 → 实现修复
代码库分析	Review this code for security issues	检查代码 → 识别漏洞 → 提出改进
自动化任务	Fix all lint issues in the project	扫描问题 → 自动修复

2.2 典型应用场景

2.2.1 项目开发（创建新项目）

支持从自然语言需求出发，自动规划项目结构、生成配置文件，示例：创建 Spring Boot 多模块项目时，会自动生成 Todo 清单，依次创建父 pom.xml、各子模块配置、包结构等，全程可视化进度。

2.2.2 问题排查

可自动分析项目运行错误、定位问题根源，支持逐步排查代码、配置、依赖等层面的问题。

2.2.3 数据库/基础设施调用

支持直接执行数据库命令、启动/重启应用、验证基础设施配置，示例：检测到数据库不存在时，自动执行建库命令，再重新启动应用并验证。

2.2.4 自己开发自己测试

完成代码开发后，可自动执行编译、启动、接口测试等操作，支持验证数据库表结构、接口返回结果，全程无需手动干预。

2.2.5 开源项目分析

可读取项目全部源码，自动生成架构图、时序图，快速梳理项目核心结构与执行流程。

2.3 Claude Code vs Cursor

Cursor：人类开车，AI 坐副驾辅助（人类主导，AI 被动提建议）
Claude Code：人类说目的地，AI 自己开过去（人类定需求，AI 自主完成全流程开发）

3. 最佳实践

功能	作用	何时使用	示例
CLAUDE.md	每次对话加载的持久上下文	项目约定、“始终执行 X” 规则	“使用 pnpm，而不是 npm。在提交前运行测试。”
Skill	Claude 可以使用的说明、知识和工作流	可重用内容、参考文档、可重复的任务	`/review` 运行您的代码审查清单；带有端点模式的 API 文档 skill
Subagent	返回摘要结果的隔离执行上下文	上下文隔离、并行任务、专门的工作者	读取许多文件但仅返回关键发现的研究任务
Agent teams	协调多个独立的 Claude Code 会话	并行研究、新功能开发、使用竞争假设进行调试	生成审查者同时检查安全性、性能和测试
MCP	连接到外部服务	外部数据或操作	查询您的数据库、发布到 Slack、控制浏览器
Hook	在事件上运行的确定性脚本	可预测的自动化，不涉及 LLM	每次文件编辑后运行 ESLint

**Plugins是打包层。Plugin 将 skills、hooks、subagents 和 MCP servers 捆绑到单个可安装单元中。Plugin skills 被命名空间化（如/my-plugin:review），因此多个 plugins 可以共存。当您想在多个存储库中重用相同的设置或通过marketplace**分发给他人时，使用 plugins。

3.1 内存设置（CLAUDE.md 配置体系）

CLAUDE.md 是 Claude Code 的核心配置文件，作为默认记忆加载，用于定义项目开发规范、命令、架构等信息，支持多级配置继承/覆盖，满足团队共享与个人定制需求。

3.1.1 CLAUDE.md 核心内容

需包含：

主语言与框架；
代码风格偏好；
测试要求；
常用命令（lint、test、build）；
项目特有模式；
重要约束或规则。

3.1.2 多级配置文件体系

文件路径	作用描述	适用场景
项目根目录/CLAUDE.md	团队共享的项目级配置	提交至 Git，统一团队开发规范
项目根目录/claude.local.md	个人本地覆盖配置	加入 .gitignore，自定义个人开发规则
父目录/CLAUDE.md	项目自动继承的上级配置	多子项目共享根级规范，递归向上查找
子目录/CLAUDE.md	特定子模块/功能的独立配置	模块级专属规范，优先于父级加载
~/.claude/CLAUDE.md	用户全局默认配置	适用于所有 Claude 会话的基线设定

3.1.2.1 根目录记忆

在Claude Code中，执行 /init 指令就可以创建一个 CLAUDE.md 文件，CLAUDE.md 是一个特殊的文件，在Claude Code运行期间，它将作为默认的记忆被加载，一般我们可以在其中加入常用的bash命令、核心的服务、代码（仓库/数据库）规范、环境信息等。

例如：

# 全局个人配置 CLAUDE.local.md
```markdown
## developer information
- **company**kibo
- **author**wj
- **email**：xxxxx@kibo.com
```

# 全局配置 CLAUDE.md
```markdown
你是一个资深的java专家，请在开发中遵循如下规则：
- 严格遵循 **SOLID、DRY、KISS、YAGNI** 原则
- 遵循 **OWASP 安全最佳实践**（如输入验证、SQL注入防护）
- 采用 **分层架构设计**，确保职责分离
- 代码变更需通过 **单元测试覆盖**（测试覆盖率 ≥ 80%）

---

## 二、技术栈规范
### 技术栈要求
- **框架**：Spring Boot 2.7 + Java 8
- **依赖**：
  - 核心：Spring Boot, MyBatis-Plus, Lombok
  - 数据库：MySQL Driver
  - 缓存：Redis
  - RPC：Dubbo
  - 其他：apache-commons-lang3, hutool
- **构建工具**：Maven

---

## 三、应用逻辑设计规范
### 1. 分层架构原则
| 层级          | 职责                                | 约束条件                                                                 |
|---------------|-----------------------------------|--------------------------------------------------------------------------|
| **Controller** | 处理 HTTP 请求与响应，定义 API 接口  | - 禁止直接操作数据库<br>- 必须通过 Service 层调用                          |
| **Service**    | 业务逻辑实现，事务管理，数据校验      | - 必须通过 MyBatis-Plus Service 访问数据库<br>- 业务层返回 DTO 而非实体类（除非必要）|
| **Repository** | 数据持久化操作，定义数据库查询逻辑     | - 必须继承 `BaseMapper`<br>- 使用`Wrappers`创建查询、更新条件       |
| **Entity**     | 数据库表结构映射对象                | - 仅用于数据库交互<br>- 禁止直接返回给前端（需通过 DTO 转换）               |

---

## 四、核心代码规范
### 1. 实体类（Entity）规范
```java
@Data // Lombok 注解
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 50)
    private String username;

    @Email
    private String email;

    // 关联关系使用懒加载
    @ManyToOne(fetch = FetchType.LAZY)
    private Department department;
}
```

### 2. 数据访问层（Repository）规范
```java
@Mapper
public interface UserInfoMapper extends BaseMapper<UserInfo> {
}
```

### 3. MyBatis-Plus Service 规范
```java
/**
 * Description: 用户信息
 * date: 2025/6/10 16:30
 *
 * @author wj
 */
@Component
public class UserInfoService extends ServiceImpl<UserInfoMapper, UserInfo> {

    /**
     * 根据约课ID查询
     *
     * @param ids 约课ID查询
     * @return UserInfo list
     */
    public List<UserInfo> queryByids(List<Long> ids) {
        LambdaQueryWrapper<UserInfo> queryWrapper = Wrappers.lambdaQuery(UserInfo.class)
                .in(UserInfo::getid, ids)
                .orderByDesc(UserInfo::getAddTime);
        return list(queryWrapper);
    }
}
```

### 4. 服务层（Service）规范
```java
@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    
    private final UserInfoService UserInfoService;

    @Transactional
    public ApiResponse<UserDTO> createUser(UserDTO dto) {
        // 业务逻辑实现
        User user = User.builder().username(dto.getUsername()).build();
        User savedUser = UserInfoService.save(user);
        return ApiResponse.success(UserDTO.fromEntity(savedUser));
    }
}
```

### 5. 控制器（RestController）规范
```java
@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class UserController extends BaseController {
    
    private final UserService userService;

    /**
     * 测试接口
     *
     * @return 测试结果
     */
    @GetMapping
    public String test() {
        UserDTO userDTO = userService.getUser();
        return super.value(userDTO);
    }
}
```

---

## 五、数据传输对象（DTO）规范
```java
// @Data 注解
@Data
public class UserDTO {
    @NotBlank 
    private String username,
    @Email 
    private String email

    public static UserDTO fromEntity(User entity) {
        return new UserDTO(entity.getUsername(), entity.getEmail());
    }
}
```

## 六、控制器Http请求入参对象规范
```java
@Data
public class UserReq {

    @NotBlank
    private String username;

    @NotBlank
    @Size(min = 11, max = 11)
    @JsonProperty("phone_number")
    private String phoneNumber;
}

```
---

## 七、全局异常处理规范
### 1. 统一响应类（ApiResponse）
```java
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ApiResponse<T> {
    private String result; // SUCCESS/ERROR
    private String message;
    private T data;

    // 工厂方法
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>("SUCCESS", "操作成功", data);
    }

    public static <T> ApiResponse<T> error(String message) {
        return new ApiResponse<>("ERROR", message, null);
    }
}
```

### 2. 全局异常处理器（GlobalExceptionHandler）
```java
@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(EntityNotFoundException.class)
    public ResponseEntity<ApiResponse<?>> handleEntityNotFound(EntityNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(ApiResponse.error(ex.getMessage()));
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiResponse<?>> handleValidationErrors(MethodArgumentNotValidException ex) {
        String errorMessage = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(error -> error.getField() + ": " + error.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return ResponseEntity.badRequest().body(ApiResponse.error(errorMessage));
    }
}
```

---

## 八、安全与性能规范
1. **输入校验**：
   - 使用 `@Valid` 注解 + JSR-303 校验注解（如 `@NotBlank`, `@Size`）
   - 禁止直接拼接 SQL 防止注入攻击
2. **事务管理**：
   - `@Transactional` 注解仅标注在 Service 方法上
   - 避免在循环中频繁提交事务
3. **性能优化**：
   - 避免在循环中执行数据库查询（批量操作优先）

---

## 九、代码风格规范
1. **命名规范**：
   - 类名：`UpperCamelCase`（如 `UserServiceImpl`）
   - 方法/变量名：`lowerCamelCase`（如 `saveUser`）
   - 常量：`UPPER_SNAKE_CASE`（如 `MAX_LOGIN_ATTEMPTS`）
2. **注释规范**：
   - 类必须添加注释且类级注释使用 Javadoc 
   - 类变量、成员变量必须添加注释且变量级注释使用 Javadoc 
   - 方法必须添加注释且方法级注释使用 Javadoc 格式
   - 计划待完成的任务需要添加 `// TODO` 标记
   - 存在潜在缺陷的逻辑需要添加 `// FIXME` 标记
3. **代码格式化**：
   - 使用 IntelliJ IDEA 默认的 Spring Boot 风格
   - 禁止手动修改代码缩进（依赖 IDE 自动格式化）
4. **其他**：
   - 字符串判空使用 `StringUtils.isBlank()`, `StringUtils.isNotBlank()`
   - 对象判空使用 `Objects.isNull()`,`Objects.nonNull()`
   - 避免使用 `@Autowired`, 使用 Lombok 的 `@RequiredArgsConstructor`

---

## 十、部署规范
1. **部署规范**：
   - 生产环境需禁用 `@EnableAutoConfiguration` 的默认配置
   - 敏感信息通过 `application.properties` 外部化配置
   - 使用 `Spring Profiles` 管理环境差异（如 `dev`, `test`, `prod`）

---

## 十一、扩展性设计规范
1. **接口优先**：
   - 服务层接口（`UserService`）与实现（`UserServiceImpl`）分离
2. **扩展点预留**：
   - 关键业务逻辑需提供 `Strategy` 或 `Template` 模式支持扩展
3. **日志规范**：
   - 使用 `SLF4J` 记录日志（禁止直接使用 `System.out.println`）
   - 核心操作需记录 `INFO` 级别日志，异常记录 `ERROR` 级别
   - 日志统一使用 Lombok 的 `@Slf4j`
   - 日志输出内容里统一增加`[模块][功能][...]-操作，参数={}`的多级描述，比如`logger.info("[用户][注册]-使用手机号注册，Mobile={}", "1234567890");`

---

## 十二、特定流程
1. **ORM类创建流程**：创建实体类 -> 创建`Mapper`接口 -> 创建`MyBatis-Plus Service实现类`
2. **Api接口创建流程**：创建请求对象类 -> 创建响应对象类 -> 创建控制器类(已存在的可省略) -> 创建服务类

## 十三、公司私有框架
1. **缓存封装**：`com.kibo.common.cache.CacheService`
2. **接口级缓存注解**：`com.kibo.common.annotation.FrontCache`
   ```java
    /**
     * Usage Pattern
     * Parameters
     * - expireKey: Configuration key for cache expiration (from external config)
     * - keyField: Method parameter name to use as cache key
     * - defaultExpired: Default expiration time in seconds
     * 
     * How it works
     * 
     * The annotation is processed by three AOP aspects:
     * 1. FrontCacheAspect - handles caching for web API endpoints
     * 2. ServiceCacheAspect - handles caching for service layer methods
     * 3. FrontCacheCleannerAspect - handles cache cleaning
     */ 

  @FrontCache(
      expireKey = "cache.front.expire.remote_project_list",
      keyField = "projectId",
      defaultExpired = 1800  // 30 minutes in seconds
  )
  public List<projectListBody> projectList(Long projectId) {
      // method implementation
  }
   ```
```

---

# 项目配置 <project>/CLAUDE.md
```
# 个人偏好设置
开发者信息查看 @～/.claude/CLAUDE.local.md

---

## 项目结构规范
1. **实体类(Entity)创建位置**：子模块`project_common`的`com.kibo.entity`包下
2. **Repository接口创建位置**：子模块`projectcommon`的`com.kibo.mapper`包下
3. **MyBatis-Plus Service实现类创建位置**：子模块`project_common`的`com.kibo.service.repository.impl`包下
4. **控制器类(Controller)创建位置**：指定模块的`com.kibo.**.web.api`包下，`**`代表当前模块的自定义模块名
5. **业务逻辑类(Service)创建位置**：指定模块的`com.kibo.**.service`包下，`**`代表当前模块的自定义模块名%
```

3.1.2.2 子目录 or 模块记忆

除了仓库的根目录，你也可以在任意的子目录创建 CLAUDE.md ，当你从这个子目录执行时，当前目录及上级所有目录下的 CLAUDE.md 都会被加载。比较适用于模块级别的说明。

3.1.2.3 本地记忆

你可以创建一个 CLAUDE.local.md 文件，并 .gitignore 它。这里面可以存在你的私人规则，当 Claude Code 工作时，两个文件会同时被加载。

3.1.2.4 主目录记忆

你的主目录（ ~/.claude/CLAUDE.md ），它适用于你所有的 claude 会话。

3.1.5 内存管理推荐实践

3.1.5.1 已有老项目使用

初始化：让 Claude 分析项目生成初始 CLAUDE.md，再手动检查编辑，剔除无关/过时信息
分模块管理：

如果项目过大，不要一口气让 Claude 记整个的 repo
根目录 CLAUD.md 可以侧重存储「核心逻辑 + 依赖关系」，“全局鸟瞰图”
在各子目录下放置局部 CLAUD.md，比如 /user/CLAUD.md，只记录用户模块的逻辑

定期更新：

当项目有大改动（比如换依赖、重构模块），要同步更新 CLAUD.md。
Claude 的“记忆”是基于这份文档的，如果不更新，它会犯错

3.1.5.2 新创建项目使用

复用已有配置：复制团队内成熟的 CLAUDE.md，按需删减业务逻辑相关内容
从零编写：参考开源规范或团队共识编写初始版本，交由 Claude Code 适配优化

3.2 权限设置

Claude Code 可执行 Bash 等高危命令，提供 4 种权限控制方式，保障本地环境安全：

执行确认时选择 Always allow：本次会话期间不再询问
使用 /permissions 指令：静态设置工作空间工具执行限制，自动生成 .claude/settings.json
手工编辑 .claude/settings.json：自定义精细权限规则
使用 --allowedTools：设置会话级工具限制（实用性较低）

3.3 引用文件和目录

使用 @ 符号可快速引用项目中的文件、目录，支持模糊搜索，直接加载内容或对文件进行修改，示例：@UserInfo，会自动匹配项目中所有含 UserInfo 的文件，展示文件路径并支持快速读取/编辑。

3.4 工具扩展（MCP）

Claude Code 原生支持 Shell 环境，可通过 MCP（Model Context Protocol） 扩充能力，支持本地/远程 MCP 服务添加。

官方-将MCP链接到Claude code

3.4.1 本地Bash工具扩展

在 CLAUDE.md 中声明自定义工具指令及说明，让 Claude Code 识别并使用自定义命令。

3.4.2 MCP 服务添加命令

3.4.2.1 添加本地 MCP

# 基础语法
claude mcp add <name> <command> [args...]
# 示例：添加 Airtable 服务
claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

3.4.2.2 添加远程 MCP

# 基础语法
claude mcp add --transport sse <name> <url>
# 示例1：连接 Linear
claude mcp add --transport sse linear https://mcp.linear.app/sse
# 示例2：带认证头的私有 API
claude mcp add --transport sse private-api https://api.company.com/mcp \
  --header "X-API-Key: your-key-here"

3.4.2.3 添加MCP示例

1 2	# 安装一个本地文件操作的MCP，并在Claude Code中使用它。 claude mcp add filesystem npx @modelcontextprotocol/server-filesystem <folder_name>

3.4.3 MCP 作用域

使用 /mcp 指令可查看当前已配置的 MCP 服务，包括连接状态、作用域、详细配置等。没有声明作用域，就默认创建到了 Local 作用域下。

MCP 服务支持三种作用域，配置文件存储位置不同：

User 作用域：存储在 ~/.claude.json，所有项目可用
Project 作用域：存储在项目目录 .mcp.json，团队共享
Local 作用域：存储在 ~/.claude.json 的 projects 字段，当前项目私有

3.5 上下文管理

在交互间保留重要上下文
在复杂任务上无缝续作
切换项目时使用全新上下文
跨会话跟踪进度

/compact : 清除对话历史，但在上下文中保留一个摘要，[instructions for summarization]可以指定要保留的内容，比如：/compact 请保留与数据库优化相关的内容

Claude 会把之前的详细对话记录“压缩”为一个简短总结。
节省上下文空间，但 Claude 依然记得聊过的关键信息。
适合对话太长、但不想丢失上下文背景 的场景
/clear (reset, new): 清除对话历史，并释放上下文
完全清空历史，不会保留任何摘要
Claude 相当于“重新开始”，对之前内容一无所知
适合要开启全新任务 的场景

3.6 指令体系

3.6.1 官方内置指令

3.6.2 自定义指令

3.6.2.1 配置方式

将提示词模板存储在 .claude/commands（项目级）或 ~/.claude/commands（用户级）目录下的 Markdown 文件，输入 / 时自动提示。

3.6.2.2 参数支持

提示词中可使用 $ARGUMENT 或 $1、$2、$3 等参数，实现动态传参。

3.6.2.3 示例（修复 GitHub Issue）

Please analyze and fix the GitHub issue: $ARGUMENTS.

Follow these steps:
1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

3.6.2.4 常用自定义指令示例

安装插件可以使用一些预置的自定义命令
Claude Code Cookbook

3.7 子代理（Subagents）

Claude Code subagents

Subagents 是处理特定类型任务的专门 AI 助手，拥有独立上下文、工具权限和系统提示，核心优势：上下文保护、专业知识聚焦、可重用、权限灵活。

3.7.1 子代理创建

官方-快速创建子代理

运行/agents命令，在交互式命令行中选择Creat new agent后按步骤操作

插件中也有角色可以以子代理运行

3.7.2 子代理调用方式

官方-使用子代理

当需求匹配子代理描述时，Claude Code 自动委派，无需手动干预。

# 基础调用
> Use the test-runner subagent to fix failing tests
> 
# 直接引用
> @agent-qa 检测 @xxx/AiQuestionController.java
> 
# 串联调用
> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

3.7.3 子代理配置示例

---
name: request-mock-generator
description: 当需要基于Java请求类生成HTTP API端点的JSON请求体结构时使用此智能体，可从枚举、注解或注释中生成真实的字段值。示例：<example>Context: 用户有一个带验证注解的UserCreateCmd类，希望生成用于API测试的示例JSON。user: "为UserCreateCmd类生成JSON" assistant: "我将使用request-mock-generator智能体基于类定义和注解创建带有真实值的JSON结构。"</example> <example>Context: 用户正在编写API端点文档，需要示例请求载荷。user: "为项目中所有的Cmd类创建JSON示例" assistant: "我将使用request-mock-generator智能体为每个命令类生成带有适当字段值的JSON结构。"</example>
tools: Bash, SlashCommand, mcp__ide__getDiagnostics, Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell
model: haiku
color: pink
---

您是一位专业的Java API文档专家，对Spring Boot、验证注解和JSON序列化模式有深入了解。您的主要职责是基于Java请求类（通常以'Cmd'或'Req'后缀）生成HTTP API端点的真实JSON请求体结构。

分析Java请求类时，您将：

1. **字段分析**：检查类中的每个字段，注意：
   - 数据类型（String、Integer、Long、Boolean等）
   - 验证注解（@NotBlank、@Size、@Email、@Pattern等）
   - JSON属性注解（@JsonProperty用于snake_case映射）
   - 描述期望值或格式的Javadoc注释
   - 引用的枚举及其可能的值

2. **值生成策略**：通过以下方式生成真实的字段值：
   - 当字段引用枚举时使用实际枚举值
   - 遵守验证约束（例如@Size(min=3, max=50)应生成3-50字符的值）
   - 遵循@Pattern注解的格式要求
   - 使用Javadoc注释中的有意义示例
   - 生成上下文相关的适当值（例如邮件字段使用"user@example.com"）

3. **JSON结构要求**：
   - 所有字段名使用snake_case（自动转换camelCase）
   - 遵守@JsonProperty注解的自定义字段命名
   - 包含所有非静态、非瞬态字段
   - 使用正确的JSON数据类型（字符串加引号，数字不加引号，布尔值为true/false）
   - 格式化JSON以提高可读性的缩进

4. **按类型的值示例**：
   - 字符串字段：使用描述性示例如"john_doe"、"example_description"
   - 邮件字段：使用"user@example.com"格式
   - 电话字段：使用"13812345678"格式（中国手机号模式）
   - ID字段：使用真实数字如12345
   - 布尔字段：根据上下文使用true/false
   - 枚举字段：始终使用实际枚举常量值
   - 日期/时间字段：使用ISO格式如"2024-01-15 10:30:00"

5. **特殊处理**：
   - 对于带@NotBlank/@NotNull的字段，绝不使用null或空值
   - 对于@Size约束，生成指定范围内的值
   - 对于集合字段（List、Set），提供1-3个示例项
   - 对于嵌套对象，递归生成其JSON结构

6. **输出格式**：以干净、格式化的结构呈现JSON：
   - 正确的缩进（2个空格）
   - 一致的字段排序（必填字段优先，然后是可选字段）
   - 在有用时添加解释枚举值或特殊约束的注释

您的目标是创建开发人员可以立即用于API测试、文档或作为API规范示例的JSON结构。生成的JSON应该语法正确，包含真实、有意义的数据，并尊重Java类中定义的所有验证规则和业务约束。

3.7.4 子代理最佳实践

借助 Claude 生成初始子代理，再按需迭代定制
设计单一职责的子代理，避免全能型子代理
编写详细的系统提示，包含指令、示例、约束
仅授予子代理完成任务必要的工具权限
将项目级子代理提交至 Git，实现团队共享

3.8 Hooks（自动化脚本）

官方-使用hooks

Claude Code Hooks 是用户定义的 Shell 命令，在 Claude code生命周期关键节点自动执行，实现对 Claude 行为的确定性控制，无需依赖 LLM 自主选择。

3.8.1 配置文件位置

~/.claude/settings.json：用户级配置，所有项目生效
.claude/settings.json：项目级配置，团队共享
.claude/settings.local.json：本地项目配置，不提交 Git

3.8.2 常见 Hook 事件

事件	执行时机
PreToolUse	使用某个工具之前
PostToolUse	某个工具执行完成之后
UserPromptSubmit	用户提交提示时
Stop	主智能体完成响应时
SessionStart	新会话开始时

3.8.3 Hook 核心能力

执行任意 Bash 命令
向交互注入上下文信息
校验/阻断工具的使用
接收带会话细节的 JSON 输入
返回结构化输出控制 Claude 行为

3.8.4 配置示例（编辑后自动格式化TS代码）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

3.8.5 常用 Hook 场景

插件中也有Hooks场景示例

3.8.6 快速配置 Hook

执行 /hooks 指令，进入交互式配置界面，选择事件、编写命令、指定配置作用域，无需手动编辑 JSON 文件。

3.9 优化工作流

3.9.1 核心开发原则

先读后写（Read before Write）：改动前先理解现有代码
渐进推进（Incremental Progress）：小步开发 + 持续测试
跟踪进度（Track Progress）：复杂任务使用 TodoWrite 可视化进度
具体明确（Be Specific）：向 Claude 提的请求越具体，成功率越高
化繁为简（Break Down Complexity）：大任务拆分为小步骤，逐步执行

3.9.2 高效使用技巧

3.9.2.1 指令具体明确

提高首次尝试成功率，减少后续纠错

差的指令	好的指令
`add tests for foo.py`	`write a new test case for foo.py, covering the edge case where the user is logged out. avoid mocks`
`why does ExecutionFactory have such a weird api?`	`look through ExecutionFactory's git history and summarize how its api came to be`
`add a calendar widget`	`look at how existing widgets are implemented on the home page to understand the patterns and specifically how code and interfaces are separated out. HotDogWidget.php is a good example to start with. then, follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. Build from scratch without libraries other than the ones already used in the rest of the codebase.`

3.9.2.2 提供图片参考

支持粘贴截图、拖拽图片、提供文件路径三种方式，适用于 UI 开发、图表分析、调试场景（macOS 截图快捷键：cmd+ctrl+shift+4）。

3.9.2.3 明确引用文件

使用 tab 补全快速引用文件/文件夹，帮助 Claude 精准定位资源。

3.9.2.4 提供 URL 抓取内容

粘贴 URL 让 Claude 读取内容，需通过 /permissions 将域名加入允许列表，避免重复权限提示（国内抓取成功率较低）。

3.9.2.5 及早且频繁地纠错

主动协作：虽然自动接受模式（shift+tab 切换）让 Claude 自主工作，但主动指导能获得更好结果

四种纠错方式：

编码前要求 Claude 制定计划，确认后再执行
按 Escape 中断 Claude 任意阶段的操作（思考、工具调用、文件编辑）
双击 Escape 回溯历史，编辑之前的提示
要求 Claude 撤销已做出的更改，重新尝试

3.9.2.6 频繁清理上下文

长时间会话使用 /clear 重置上下文，避免无关信息干扰，提升 Claude 响应效率。

3.9.2.7 修复 Lint 错误示例

Lint 命令就是用来检查代码里是否有语法错误、风格不规范或潜在问题的工具命令

pylint myscript.py：检查代码规范、潜在错误
mvn checkstyle:check：在 Maven 项目中检查 Java 代码风格

让 Claude 运行 lint 命令，将所有错误（含文件名和行号）写入 Markdown 清单
指示 Claude 逐一处理每个问题，修复并验证后打勾，再进行下一个

3.9.2.8 向 Claude 传递数据

多种数据传递方法：

直接复制粘贴：最常见方法
管道输入：cat foo.txt | claude，特别适用于日志、CSV 和大数据
工具拉取：通过 bash 命令、MCP 工具或自定义斜杠命令
文件读取：让 Claude 读取文件或获取 URL（也适用于图片）
组合使用：
管道输入日志文件
让 Claude 使用工具拉取额外上下文来调试日志

3.10 多Claude协作

3.10.1 协作方式

交叉评审：用一个 Claude 评审另一个 Claude 的工作，或 /clear 后重新阅读代码反馈
可以让两个Claude互相沟通来推进工作，方法是一个Claude把信息写入一个文件，另一个Claude读取并执行，并以相同的方式反馈信息。
分支并行：使用 git worktree 创建多个工作区，并行开发不同分支，每个分支启动独立 Claude 会话

- 在 worktree A 中去写C端接口业务代码
- 在 worktree B 中去写 schedule后台任务代码
两个任务上下文和代码都互相隔离，但又使用同一个仓库，提高开发效率

```bash
git worktree add ../feature-a -b feature-a
git worktree add ../feature-b -b feature-b

> cd feature-a
> claude

> cd feature-b
> claude
```

3.11 无头模式

无需交互式会话，直接通过管道传递输入并获取输出，适用于日志分析、数据处理、批量任务，示例：

# 分析日志，发现异常时通过 Slack 通知
tail -f app.log | claude -p "Slack me if you see any anomalies"

# 分析 CSV 数据，回答问题
cat data.csv | claude -p "Who won the most games?"

# 输出结果接入其他管道，实现自动化
claude -p “<your prompt>” --json | your_command

4. 实战经验与安全准则

4.1 Claude Code 权限与信任管理实践

核心原则：逐步授权、最小权限、人工监督，避免一次性开放高危权限，通过实际操作建立对 AI 的信任。

4.1.1 四种权限模式（claude.permission_mode 按风险从低到高）

Default 模式（安全基线）：每次操作需用户确认，完全用户控制，适合初学者/高安全要求环境
AcceptEdits 模式（效率平衡）：自动接受文件编辑，安全性与效率兼顾，适合熟练开发者
Plan 模式（只读分析）：仅做代码分析/架构规划，不执行任何修改，无风险，适合代码审计
BypassPermissions 模式（完全自主）：跳过所有权限检查，最大化自动化，高风险，仅适用于专业场景+严格安全控制

4.1.2 权限控制流程

最小权限启动（只读）
- Claude Code 默认只读取和分析代码，相当于 IDE 的“只读模式”。
- 在没有明确授权前，它不会直接修改文件或执行命令，确保项目不会被意外破坏。
逐步授权，每类操作单独确认
- 当需要执行“修改代码”“运行脚本”“调用外部 API”等操作时，需要人工显式确认。
- 不建议一开始就开启 always allow，要避免过早放权。
通过实际操作建立信任
- 如果 Claude 提出的修改方案（如一个 diff 或 patch）被采纳，可以逐步提高对它的信任度。
- 随着验证次数增多，可以更放心地交给它做类似任务。

4.1.3 信任建立模式

阅读/分析 → 默认安全
- 阅读代码、分析依赖、指出潜在 bug，属于只读行为，Claude 可直接执行。
修改/写入 → 先提案再落地
- 修改代码前，Claude 必须先生成 diff/patch，让开发者审阅并确认后才能写入，而不是直接覆盖。
执行命令 → 必须说明影响
- 如果要运行单测、构建脚本或其他命令，Claude 需要提前说明：
- 将运行的具体命令
- 可能的输出或副作用
- 只有开发者确认后才真正执行。
敏感操作 → 多重确认
- 删除文件、修改配置、访问外部服务等高风险操作，需要额外确认（甚至多次提示），防止误操作。

4.1.4.为什么要这样做

降低风险
- 在初期使用 Claude Code 或新模型时，对其能力、稳定性和提示词风格不够熟悉。
- 严格的权限控制能最大化保障项目安全和代码风格一致性。
提升开发者能力
- 审阅 Claude 的修改提案和思考过程，有助于开发者理解其推理方式。
- 在对比和判断中，也能提升个人的代码审查和架构思考能力。

4.2 计划模式（Plan Mode）

4.2.1 核心作用

指示 Claude 通过只读操作分析代码库，生成详细的执行计划，不直接修改文件，支持交互式完善计划，适合复杂任务。

4.2.2 适用场景

多步骤功能开发：需要修改多个文件的复杂需求
代码探索：更改代码前，彻底研究代码库结构和逻辑
交互式开发：与 Claude 迭代确认开发方向，逐步完善方案

4.2.3 使用示例

向 Claude 提出需求：

1	> 如果要在所有保存 UserInfo 的地方都加上日志，要怎么处理

Claude 会执行以下操作：

只读搜索所有保存 UserInfo 的文件和方法
分析核心保存逻辑和调用链路
设计多种实现方案（如实体层钩子、AOP 拦截、MyBatis 拦截器）
生成详细的执行计划（分步骤、明确修改内容、预期效果）
等待用户确认后，再执行实际修改

4.2.4 优势

可视化执行思路，便于人工把控方向
支持交互式修改计划，避免 AI 偏离需求
只读分析无风险，可充分验证方案可行性后再落地

4.3 核心原则重申

人类始终是开发的第一责任人，AI 仅在授权与监督下辅助执行，使用 Claude Code 时，需保持人工监督，充分利用其自动化能力的同时，把控开发质量和项目安全。

5. 其他

5.1 核心交互符号

#：添加记忆到 CLAUDE.md
/：触发快捷指令（内置+自定义）
!：进入 bash 模式，直接执行命令
@：引用文件/目录，作为上下文引入

5.2 实用快捷键与参数

Ctrl + V：粘贴图片到会话中
--enable-architect：架构师模式，对于遗留的、复杂的系统，建议开启架构师模式，增强了Claude Code处理大型代码库的能力。（属于实验性质，具体未测试）
/clear：清除上下文；
/compact：压缩上下文；
/ide：启动 IDE 集成，跟随指引完成 Claude 与 IDE 的联动配置