上篇 Claude Code 上手指南 介绍了Claude Code的安装、国产大模型配置和常用的基础操作，本篇以实际工作为背景，结合官方文档说明，总结Claude Code的最佳实践，最后再自定义完善.claude目录下的扩展功能，对AI Coding达到得心应手，灵活驾驭。

编写有效的CLAUDE.md

1、对于已有项目，先执行/init命令
执行该命令时，Claude Code会分析当前工程代码，并总结成CLAUDE.md文档，后续工程变更了继续执行一次该命令，会继续分析并将结果更新到文档中。如果对自动生成的文档不满意或者需要部分调整，直接编辑就行，当然也可以通过和Claude Code对话让它修改调整，直到满意。

2、尽可能简洁
CLAUDE.md 文件没有必需的格式，但应该保持简短和易读，超过 200 行时会消耗更多上下文并可能降低遵守度。对于每一行，问自己：“删除这个会导致 Claude Code 犯错吗？” 如果不会，删除它。

不好的例子：

## 技术栈

前端使用 Vite 进行构建，`vite.config.ts` 中包含了针对 TypeScript 和 Vue 的插件配置，支持热更新（HMR）和按需加载（code splitting）。Vite 使用 ESBuild 进行开发时的快速构建，并通过 Rollup 进行生产环境打包，打包配置项包括插件和外部依赖的预构建……

后端使用 NestJS 构建，采用 TypeORM 连接 PostgreSQL。NestJS 配置位于 `src/main.ts`，所有模块通过装饰器声明，数据库连接配置文件在 `ormconfig.json` 中……

好的例子：

## 技术栈

- 前端：使用 Vite 构建，支持 TypeScript 和 Vue。
- 后端：使用 NestJS + TypeORM 构建，连接 PostgreSQL。

3、只写广泛适用的东西
CLAUDE.md 会在每个会话中加载，应该只包括广泛适用的东西。对于只在部分情况下才会用到的知识，改用 skills，Claude Code 会按需加载它们。

不好的例子：

## 商品模块 API 设计

- GET /api/products: 获取商品列表
- POST /api/products: 创建商品（仅管理员权限）
- PUT /api/products/:id: 更新商品（仅管理员权限）

好的例子：

## API 设计规范

- 所有 API 采用 RESTful 风格。
- 数据交互格式：JSON。
- 所有请求和响应必须遵循统一的错误处理格式。

这样，CLAUDE.md 文件会更加简洁，只有适用于所有模块的通用信息，而每个模块的详细设计则可以单独放在 skills 中，它会在需加时自己加载。

善用计划模式

在开始复杂的任务前，强烈推荐先进入计划模式，告诉Claude Code自己的需求，Claude Code会根据需求制定一份完善的执行计划，不清楚的地方它会很智能的弹出对话框或者选择面板，让用户做决定。对于生成的计划，可以不断和Claude Code对话调整打磨，直到最符合需求。执行计划时如果前面已经经过多轮讨论了，建议再新开一个会话，告诉Claude Code计划文件的地址，再开始执行。

做好的计划默认会以markdown文件的形式存储到用户目录/.claude/plans目录下，可以通过配置修改到项目根目录下，如在项目根目录.claude/settings.json中配置：

{
    "plansDirectory": "./plans"
}

命令行版进入计划模式：执行/plan命令或者按两次shift+tab均可：

VS Code插件版进入计划模式：选择 Plan mode ：

保持清醒的秘诀

让大模型保持清醒的秘诀是做好上下文管理。

使用@ 引用文件
告诉Claude Code代码时， 使用@符号引用文件，而不是文字描述代码所在的位置。

直接粘贴图像
如果有图片，可以直接将图片粘贴到对话框中，Claude Code是支持在对话时贴入图片的。

使用/clear命令重置上下文
在不同任务之间频繁使用 /clear 来完全重置上下文，避免任务一的上下文干扰任务二。

善用subagents
当 Claude Code 直接研究代码库时，需要读取大量文件，这些内容都会占用主对话的上下文，很容易导致上下文变得臃肿混乱。而 subagents 可以在独立的上下文窗口中运行，只将总结结果返回，从而避免污染主对话。

例如一个任务的中间需要分析一下认证相关的代码逻辑时：

使用 subagent 分析我们的认证系统是如何处理 token 刷新的，以及是否已有可复用的 OAuth 工具。

subagent 会自行探索代码库、读取相关文件，并整理出关键发现，而不会占用主对话的大量上下文。此外，在 Claude Code完成某个功能之后，也可以使用 subagents 进行进一步验证，例如：

使用 subagent 审查这段代码，检查是否存在边界情况（edge cases）。

claude-hud^[1]插件可以实现在控制台实时显示当前模型名称、上下文占用情况等数据：

个性化扩展

Claude Code的个性化扩展是打造最佳实践的重要途径。这部分上一篇 Claude Code 上手指南 已经做了基础介绍，这里再完整介绍主要的几个可扩展的功能，在使用过程中根据实际情况扩展。

一个基础的的.claude目录如下：

📄 CLAUDE.md
🧩 .mcp.json
📦 .claude
    ⚙️ settings.json
    🗂 rules
    🗂 skills
    🗂 commands
    🗂 agents

• • .mcp.json 配置项目需要的MCP服务器

• • settings.json Claude Code配置

• • rules 定义规则约束，如代码规范、架构原则等

• • skills 定义技能，如生成组件、生成CRUD接口/页面

• • commands 定义命令，如git提交、部署等

• • agents 定义不同职责的子 Agent，如开发者、Reviewer、debugger

实际开发中，可以根据项目需求不断扩展。以下是一个比较完整的结构：

📄 CLAUDE.md
🧩 .mcp.json
📦 .claude
    ⚙️ settings.json
    🗂 rules
        📄 testing.md
        📄 api-design.md
    🗂 skills
        🗂 security-review
            📄 SKILL.md
            📄 checklist.md
    🗂 commands
        📄 fix-issue.md
    🗂 agents
        📄 code-reviewer.md

扩展并不是越多越好，无用的skills、rules、agents等只会占用太多的上下文，应该根据项目需求做到按需扩展。

rules

.claude/rules/testing.md
这是一个示例规则，仅在Claude Code处理测试文件时加载。Frontmatter 中的 paths: 通配符定义了哪些文件会触发此规则；在这里，任何以 .test.ts 或 .test.tsx 结尾的文件都会触发。对于其他文件，此规则不会被加载到上下文中。

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
---

# 测试规范

- 使用描述性的测试名称：例如 `"should [预期结果] when [条件]"`
- 模拟外部依赖，而不是内部模块
- 在 `afterEach` 中清理副作用

<!-- 根据需求补充完善 -->

.claude/rules/api-design.md
一个仅针对后端代码的规则。Frontmatter 中的 paths: 通配符匹配 src/api/ 下的文件，因此这些规范仅在 Claude Code 编辑 API 路由文件时加载。

---
paths:
  - "src/api/**/*.ts"
---

# API 设计规范

- 所有接口必须使用 Zod schema 验证输入
- 返回格式：`{ data: T }` 或 `{ error: string }`
- 对所有公共接口进行速率限制（Rate Limit）

<!-- 根据需求补充完善 -->

skills

.claude/skills/security-review
所有security-review技能的文件都放在这里

.claude/skills/security-review/SKILL.md
该技能使用 disable-model-invocation: true，因此只有你可以触发它；Claude Code不会自行调用。! 开头的行会执行一个 shell 命令，并将其输出注入到提示中。$ARGUMENTS 会替换你在技能名称后输入的内容。Claude Code可以访问技能目录路径，因此提到像 checklist.md 这样的文件时，Claude Code可以读取它。

---
description: 审查代码变更，检查安全漏洞、认证缺口和注入风险
disable-model-invocation: true
argument-hint: <branch-or-path>
---

## 待审查的 Diff

!`git diff $ARGUMENTS`

请审查上述变更，关注以下内容：

1. 注入漏洞（SQL、XSS、命令注入）
2. 认证和授权缺口
3. 硬编码的密钥或凭证

使用此技能目录中的 `checklist.md` 获取完整审查清单。

请报告发现的问题，并提供严重性评级及修复步骤。

<!-- 根据需求补充完善 -->

.claude/skills/security-review/checklist.md
技能可以包含任何支持的文件：如参考文档、模板、脚本等。

# 安全审查清单

## 输入验证
- [ ] 所有用户输入在数据库查询前进行清理（Sanitize）
- [ ] 验证文件上传的 MIME 类型
- [ ] 文件操作中防止路径遍历

## 认证
- [ ] JWT 令牌在 24 小时后过期
- [ ] API 密钥存储在环境变量中
- [ ] 密码使用 bcrypt 或 argon2 哈希处理

commands

命令（Commands）和技能（Skills）现在使用相同的机制。对于新的工作流，请使用 skills/ 目录：调用方式仍然是 /name。

agents

每个 Markdown 文件都定义了一个子Agent，它有自己的系统提示（system prompt）、工具访问权限，并且可以单独指定模型。子Agent在一个全新的上下文窗口中运行，这能保持主对话干净。适用于并行工作或隔离任务。

.claude/agents/code-reviewer.md
这是一个仅限只读工具的子Agent示例。Frontmatter 中的 description 告诉 Claude 何时自动将任务委派给它；tools: 将其限制为 Read、Grep 和 Glob，因此它可以检查代码，但永远不会修改。Markdown 正文部分会成为子Agent的系统提示（system prompt）。

---
name: code-reviewer
description: 审查代码的正确性、安全性和可维护性
tools: Read, Grep, Glob
---

你是一名资深代码审查员。请关注以下方面：

1. 正确性：逻辑错误、边界情况、空值处理
2. 安全性：注入漏洞、认证绕过、数据泄露
3. 可维护性：命名规范、复杂度、重复代码

每个发现的问题都必须提供具体的修复方案。

<!-- 根据需求补充完善 -->

引用链接

[1] claude-hud: https://github.com/jarrodwatts/claude-hud