当前位置：首页 > news >正文

Claude Code 从入门学习

news 2026/8/15 10:55:37

Claude Code 简介

https://www.runoob.com/claude-code/claude-code-intro.html

Claude Code 是 Anthropic 推出的面向开发者的 AI 编程协作工具，与在聊天窗口里写几段代码不同，Claude Code 的核心目标是理解你的整个项目，并参与到真实的编码、修改和重构过程中。

Claude Code 不是一个代码生成器，而是一个能读项目、懂上下文、遵守约束的 AI 编程搭档。
简单说:Claude Code 是 Claude 的命令行版本,专门为编程场景设计。

Claude Code 适合：1.需要解释、文档、设计的场景；2.探索性的，不确定的编程；3.结对编程，边想边做的。是资深顾问。

Claude Code 的核心理念：协作，而不是替代。

三如何工作

Claude 的工作流程

Claude Code 常见工作流程指南
探索、规划、编码、提交
https://ctok.ai/claude-code-common-workflows

本文介绍了使用 Claude Code 的常见工作流程。每个任务都包含清晰的说明、示例命令和最佳实践，以帮助更好地利用 Claude Code。

Claude Code 推荐提示词大全

Prompt中文常译为“提示词”或“提示”，是指你输入给 AI 模型的指令、问题、描述或文本，用来引导模型生成你想要的输出。

简单理解：把 AI 想象成一个极度聪明但需要明确指令的助手。Prompt 就是你给这个助手布置的任务说明——说得越清楚，它做得越符合你的期望。

Claude Code 的强大功能很大程度上取决于如何与它有效沟通。本文汇总了各种开发场景下的高效提示词模板，帮助开发者快速掌握 Claude Code 的使用技巧。

为什么 Prompt 很重要？ 同样的 AI 模型，不同的 Prompt 会得到完全不同的结果。一个好的 Prompt 可以： ✅ 提高输出质量：更精准、更符合需求 ✅ 节省迭代时间：减少反复修改的次数 ✅ 控制输出格式：得到结构化的、易于处理的内容 ✅ 发挥模型潜力：让 AI 更好地理解上下文和任务目标 在 PR 审查场景中,可以利用 Prompt 让 AI 帮忙： “你是一名资深代码审查专家，请从代码逻辑、性能、安全性、可读性四个维度审查以下代码 diff，指出潜在问题并给出改进建议：[粘贴代码]” 这就是一个典型的结构化 Prompt，能让 AI 给出更专业、更全面的审查结果。

代码调试与优化

## 代码重构 请重构 [文件名] 中的 [函数/类] ，目标是： - 提高代码可读性 - 减少重复代码 - 遵循最佳实践 - 保持功能不变 请先分析现有代码，然后提供重构计划。 ## 代码审查 请对 [文件/功能] 进行代码审查，重点检查： - 代码规范 - 安全问题 - 性能问题 - 最佳实践 - 潜在 bug ## 后端开发 请为 [功能] 设计数据库表结构，包括： - 表结构定义 - 索引设计 - 关系约束 - 迁移脚本 ## 文档编写 ### 代码注释 请为 [文件/函数] 添加详细的代码注释，包括： - 功能描述 - 参数说明 - 返回值说明 - 使用示例 ## 代码分析 ### 架构分析 请分析项目的整体架构，评估： - 模块职责是否清晰 - 耦合度是否合理 - 扩展性如何 - 有哪些改进空间

理解新代码库

1.1 快速获取代码库概览

1.导航到项目根目录 cd /path/to/project 2.启动 Claude Code claude 3.请求高级概览 > give me an overview of this codebase > explain the main architecture patterns used here > what are the key data models? > how is authentication handled? 提示： - 从广泛的问题开始，然后缩小到特定领域 - 询问项目中使用的编码约定和模式 - 请求项目特定术语的词汇表

CLAUDE.md 项目核心指令

这是 Claude 进入项目时第一个读取的文件，相当于项目欢迎手册。
CLAUDE.md 放置在项目根目录，所有团队成员共享，它告诉 Claude：这个项目是什么、如何运行、有什么约定。

CLAUDE.md 会成为 Claude 系统提示的一部分，使每次对话都能预先加载项目上下文，不再需要重复解释基本信息。

一份好的 CLAUDE.md 应该覆盖三个维度：

WHAT（是什么）：技术栈、项目结构，为 Claude 提供代码库的全局地图
WHY（为什么）：项目的目的，各模块的功能与定位
HOW（怎么做）：开发方式，例如使用 bun 而非 node，以及 Claude 如何验证改动是否正确 Humanlayer。

以下是一份典型的 CLAUDE.md 结构示例：

# 项目名称 ## 项目概述 简述这个项目的目的和功能。 ## 技术栈 ## 目录结构 ## 常用命令 - 启动开发服务器：`pnpm dev` - 运行测试：`pnpm test` - 代码检查：`pnpm lint` ## 开发规范 ### 文件位置与层级 项目的核心文件结构如下： your-project/ ├── CLAUDE.md # 项目主记忆文件（团队共享） ├── .claude/ │ ├── settings.json # Hooks、权限、环境配置 │ ├── settings.local.json # 个人配置（建议加入 .gitignore） │ └── commands/ # 自定义斜杠命令 │ └── my-command.md └── .mcp.json # MCP 服务配置

提示： Claude 会自动递归读取父目录中的 CLAUDE.md。在 monorepo 中，子包内可再放一个 CLAUDE.md，Claude 会将两层指令合并理解。

使用 # 快捷键持续更新 在对话中，随时用 # 前缀给 Claude 发送记忆指令： # 我们始终使用 pnpm，不用 npm # 所有组件必须包含单元测试 验证初始化效果 初始化完成后，可以通过以下对话确认 Claude 是否正确理解了项目： 这个项目是做什么的？ 解释一下目录结构。 项目用了哪些技术？ 运行测试的命令是什么？

CLAUDE.local.md

个人专属的覆盖层，叠加在 CLAUDE.md 之上。

CLAUDE.local.md 存放只与你本人相关的偏好或临时指令，不应共享给团队。

典型内容： 本地数据库地址：localhost:5433（非默认端口） 调试时请优先输出详细日志。 ## 临时规则（本次任务用） 目前专注于重构 auth/ 模块，其他模块暂时不要改动。

.claude/settings.json 权限与配置中心

核心要点：你的 settings.json 是进行高级定制的强大工具。

团队共享的配置文件，控制 Claude 允许或禁止执行哪些操作，作为团队安全基线。

{ "permissions": { "allow": [ "Bash(npm run *)", "Bash(pytest:*)", "Bash(git diff:*)", "Bash(git log:*)" ], "deny": [ "Bash(rm -rf *)", "Bash(curl * | bash)" ] }}

settings.local.json

个人本地权限覆盖，临时放开或收紧某些权限，不影响团队其他成员。

{ "permissions": { "allow": [ "Bash(rm ./tmp/*)" ] }}

最后，我有一些特定的 settings.json 配置，我发现在个人和专业工作中都至关重要。

HTTPS_PROXY/HTTP_PROXY : 这对调试非常有用。我会用它来检查原始流量，看看 Claude 究竟发送了什么Prompt。对于Background Agent，它也是一个强大的细粒度网络沙盒工具。

MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS : 我调高了这些值。我喜欢运行长而复杂的命令，而默认的超时时间通常过于保守。

ANTHROPIC_API_KEY : 在工作中，我们使用企业 API 密钥。这将我们从“按席位付费”的许可证模式转变为“按使用量付费”的模式，这更适合我们的工作方式。

“permissions” : 我会偶尔自我审计一下我允许 Claude 自动运行的命令列表。
（实际上env还有许多非常有用的环境变量属性）

Claude Code 项目结构

.claude/rules/ --模块化行为规则

将 CLAUDE.md 中的规则拆分模块化存放，Claude 在整个会话中始终遵守。适合存放长期稳定执行的行为约定，避免 CLAUDE.md 过于臃肿。

示例：rules/code-style.md
示例：rules/testing.md
示例：rules/api-conventions.md

.claude/skills/ --自动调用的工作流

Skills 是更高级的复合工作流。当 Claude 判断某个任务适合某个 skill 时，会自动读取并执行对应的 SKILL.md，无需手动调用。

每个 skill 是一个子目录，目录内包含 SKILL.md。

示例：skills/security-review/SKILL.md

# Security Review Skill ## 触发条件 当用户请求代码审查、代码涉及认证/授权/加密/用户输入处理时自动触发。 ## 执行步骤1.扫描 SQL 注入风险（检查所有数据库查询）2.检查 XSS 防护（验证输出转义）3.审计权限边界（确认最小权限原则）4.检查敏感数据处理（日志、错误信息中是否泄露）5.输出 OWASP Top10对照检查表 ## 输出格式 按 CVSS 评分排列，高危问题优先展示。

⚡ Skills vs Commands 的区别：

Commands 需要用户主动输入斜杠命令触发，是"工具箱"
Skills 由 Claude 根据上下文自动判断是否调用，是"智能本能"

.claude/agents/ --子代理角色

定义可被主 Claude 实例派遣的专业子代理。在复杂任务中，主代理将子任务委派给对应专家角色，实现多代理协作。子代理在隔离上下文中运行，拥有独立的权限范围。

示例：agents/code-reviewer.md

---name:code-reviewer description:资深代码审查员，专注代码质量与可维护性---# 代码审查员 ## 角色定位 你是一名拥有10年经验的资深工程师，专注于代码可读性、性能优化和最佳实践。 ## 审查重点-命名是否清晰表达意图-函数/类的单一职责原则-边界条件和错误处理-性能瓶颈（N+1查询、不必要的循环等） ## 权限 只读访问，不直接修改文件。 ## 输出格式 使用 Markdown 表格输出，包含：问题位置、严重程度、建议方案。

示例：agents/security-auditor.md

---name:security-auditor description:安全审计专家，专注漏洞扫描与合规审计---# 安全审计员 ## 角色定位 你是一名安全工程师，熟悉 OWASP、CVE 数据库和常见攻击向量。 ## 审计范围-认证与授权逻辑-输入验证与输出转义-依赖包已知漏洞（结合 npm audit/pip audit）-敏感信息泄露风险 ## 权限 只读访问+可运行安全扫描工具。 ## 输出格式 按 CVSS3.1评分排列，包含：漏洞描述、影响范围、修复建议、参考链接。

速查表

最佳实践建议

Claude Code 操作说明

Claude Code 项目初始化
https://www.runoob.com/claude-code/claude-code-init.html

Claude Code 交互模式
https://www.runoob.com/claude-code/claude-code-cli.html
Ask（询问）Plan（规划）Edit（编辑）
理解这三种模式的边界与职责，是高效、安全使用 Claude Code 的关键。

Claude Code 操作说明
https://www.runoob.com/claude-code/claude-code-symbols.html

Claude Code 的 16 个实用小技巧

1、把你的需求说具体点
2、把复杂的需求分步执行
3、先理解项目代码
4、快捷键
5、使用免授权模式（开启 Bypassing Permissions）
启动 claude 时增加参数：claude --dangerously-skip-permissions

6、激活深度思考模式

比如我来测试一下：1+1 ultrathink
一个 1+1 计算耗费了 0.06 美元，大概不到 5 毛 RMB。

Sequential Thinking

在使用复杂业务的时候，告诉Ai需求的最后，加上一句话：用Sequential Thinking 思考，用software-planning-tool规划。如“列出当前项目的详细设计文档”。

7、输错指令，随时打断它工作

在 Claude Code 工作时，有时给的命令描述的不对，如果你想让它停止，只需要按ESC

8、发送图片处理

9、恢复历史会话

非交互模式

claude --continue 或者 claude -c 自动继续最近的对话，无需任何提示.
claude --resume 或者 claude -r 显示历史对话选择器；

2、分叉会话（推荐！尝试新方案不影响原对话）
命令：claude --continue --fork-session
适用场景：想试试"另一种实现方式"又不想把原对话搞乱时，就用这个。

10、记忆管理

Claude Code 提供三种记忆位置，每种都有不同用途：

其中， CLAUDE.md 文件是 Claude Code 自动读取的记忆文件，类似于 Cursor 中 rules 规则文件，但比它要更强大，它可以为 Claude 提供更多项目相关的上下文信息，如：

常用的 bash 命令 核心文件和工具函数 代码风格指南 测试说明 代码库规范 开发环境设置 更多希望 Claude 记住的信息等等

当 Claude Code 启动时，以上所有记忆文件会自动加载到运行环境中。
可在多个位置放置 CLAUDE.md 文件，Claude Code 会递归读取这些文件，从当前工作目录开始，向上递归到根目录，读取找到的任何 CLAUDE.md 文件。

编辑记忆文件
在会话期间使用/memory 斜杠命令，在系统编辑器中打开记忆文件：

11、和 Git 进行交互

12、和Linux交互

在非交互模式下：

claude -p “列出行数最多的前3个.java文件”

13、模型切换

14、查看消耗情况 /cost

使用/cost命令查看当前会话使用情况：如图，显示我当前会话已经消耗了 1.23 美金。

15、上下文压缩 /compact

Claude Code 提供了一个/compact压缩命令。

避免使用这个命令。它的自动压缩过程不透明、容易出错，而且优化得不好。

16、自定义快捷命令

.claude/commands/ 自定义斜杠命令
目录下每个 .md 文件自动映射为一条 /project:文件名命令。

.claude/commands/ 是团队将重复性任务标准化的核心机制。

核心要点：把斜杠命令当作简单、个人化的快捷方式，而不是用它来替代构建更直观的 CLAUDE.md 和更好的工具化Agent。

钩子 (Hooks)

CLAUDE.md 会成为 Claude 系统提示的一部分，使每次对话都能预先加载项目上下文，不再需要重复解释基本信息。

示例：commands/review.md

# Code Review 请对当前修改执行完整的代码审查： 1. 检查是否有安全漏洞（SQL 注入、XSS 等） 2. 验证错误处理是否完整 3. 确认测试覆盖率是否达标 4. 检查是否符合代码风格规范 5. 评估性能影响 用中文输出结构化审查报告，按严重程度排列问题。

示例：commands/fix-issue.md（带参数）

参数传递：命令文件中可使用$ARGUMENTS占位符接收调用时传入的参数。

# Fix GitHub Issue 给定 Issue 编号 $ARGUMENTS，请：1.读取并理解 Issue 描述2.定位相关代码文件3.实现最小化修复方案4.编写对应的单元测试5.更新 CHANGELOG.md 调用方式：/project:fix-issue BugID-123

实时监控 claude-monitor

https://ctok.ai/claude-monitor-usage-guide

MCP

https://www.runoob.com/claude-code/claude-code-mcp.html
如果说 Claude Code 是一个优秀的打字员（代码生成）和测试员（代码校验），那么加上 MCP（Model Context Protocol，模型上下文协议）则是让 Claude 真正拥有了外部感官和手脚——它不再局限于当前项目的代码文件，而是能主动连接外部世界的资源与工具，成为你的全链路开发协作伙伴。

查看 mcp 列表

安装指令：claude mcp add memory --scope user -- cmd /c npx -y @modelcontextprotocol/server-memory Memory MCP 功能 Memory MCP 服务器提供持久化记忆功能，让 Claude 能够： 跨会话记住关于用户的信息 使用本地知识图谱存储信息 在不同对话中保持上下文 安装指令：claude mcp add sequential-thinking --scope user -- cmd /c npx -y @modelcontextprotocol/server-sequential-thinking Sequential Thinking 功能 Sequential Thinking MCP 服务器提供结构化的问题解决能力： 将复杂任务分解为逻辑步骤 适合架构设计或大规模重构 提供详细的、逐步的思考过程 帮助进行系统分析和问题拆解 安装指令：claude mcp add software-planning-tool --scope user -- cmd /c npx -y @iflow-mcp/software-planning-tool 主要功能 交互式规划会话 开始新的开发规划 管理规划会话 待办事项管理 创建开发任务 更新任务状态 跟踪任务进度 复杂度评分 为任务分配复杂度分数 更好的工作量估算 代码示例 在任务描述中包含代码片段 提供实现参考 实现计划 保存详细的开发计划 结构化的问题引导方法 示例：用Sequential Thinking来分析一个问题 安装指令：claude mcp add server-filesystem --scope user -- cmd /c npx -y @modelcontextprotocol/server-filesystem claude mcp add playwright --scope user -- cmd /c npx @playwright/mcp@latest 用途：网页自动化测试、爬虫、截图、表单填写、点击操作等。 安装指令：claude mcp add server-puppeteer --scope user -- cmd /c npx -y @modelcontextprotocol/server-puppeteer 用途：网页自动化、表单填写、点击操作、网页测试、爬虫等。

为什么 Claude Code 需要 MCP？
在没有 MCP 之前，Claude Code 的能力被严格限制在你当前打开的项目文件夹内，就像一个坐井观天的助手，只能看到眼前的代码，无法感知项目之外的任何信息。而 MCP 的出现，彻底打破了这个信息孤岛，让 Claude 能深度参与全流程开发。

管理 MCP 服务器

配置完成后，你可以通过以下命令管理服务器：

# 列出所有已配置的服务器 claude mcp list # 查看指定服务器详情（如github） claude mcp get github # 删除指定服务器 claude mcp remove github # 在Claude Code中检查服务器状态/mcp

配置范围（控制服务器可见性）

实用示例

在对话中使用 MCP 的高级方式

关键注意事项1.身份验证：远程MCP服务器（如GitHub/Sentry）需在Claude Code中执行/mcp 完成OAuth2.0授权；2.Windows兼容：本地stdio服务器若用npx，需加cmd/c包装（如--cmd/c npx-y 包名），否则会报"Connection closed"错误；3.第三方风险：使用非官方MCP服务器时，需确认来源可信，避免提示注入/安全风险；4.参数顺序：stdio服务器配置时，--前后的参数不可颠倒，否则会执行失败。

Claude Code 子代理（Subagent）

https://www.runoob.com/claude-code/claude-code-subagent.html

在 Claude Code 中，你可以创建专门的 AI 子代理（Subagent），用于处理特定类型的任务，从而获得更好的上下文管理、更强的约束控制和更高的执行效率。

当 Claude 判断你的请求符合某个子代理的描述（description）时，就会自动将任务委托给该子代理，由它独立完成并返回结果。

重要：子代理只接收自身的系统提示和基础环境信息（如工作目录），不会继承完整的 Claude Code 系统提示。这保证了行为的纯净和可控。

理论上，SubAgent是 Claude Code 在上下文管理方面最强大的功能。它的理念很简单：一个复杂任务需要 X token 的输入上下文（例如，如何运行测试），在工作过程中累积了 Y token 的上下文，并产出一个 Z token 的答案。运行 N 个这样的任务意味着你的主窗口中会有 (X + Y + Z) * N 个 token。
https://mp.weixin.qq.com/s/n_QrGxErb-MkOcSGs7gPwA

为什么要使用子代理？

Claude Code 内置的子代理

快速入门：创建你的第一个子代理

略

子代理的作用范围

子代理本质是带 YAML frontmatter 的 Markdown 文件，不同位置代表不同作用范围。

当同名子代理存在冲突时，优先级高的会覆盖低的。可通过 /agents 查看当前哪个版本生效。

使用建议

项目子代理（.claude/agents/）

跟代码一起提交，团队共享
可引用项目专属工具和领域知识
自动继承项目 CLAUDE.md 中的编码规范和架构规则

用户子代理（~/.claude/agents/）

个人习惯与通用工具，跨项目生效

CLI 子代理（-- agents）

临时测试 / 自动化脚本，不保留到磁盘

子代理配置文件结构

配置文件由两部分组成：YAML frontmatter（元数据与配置）+ Markdown 正文（系统提示）。

必填字段

name：唯一标识（小写 + 连字符，如 code-reviewer）
description：最重要的字段，Claude 是否以及何时调用该代理完全依赖于此；建议写成"何时调用 + 能做什么"的动作式描述

完整字段说明

tools 与 disallowedTools 的区别

权限模式（务必理解）

持久记忆（Memory）

通过 memory 字段，子代理可以在会话之间积累知识，例如代码库规律、调试经验、架构决策等，无需每次重新探索。

worktree 隔离模式

后台运行（Background）

禁用特定子代理

如果你不希望 Claude 调用某个特定的子代理，可以在 .claude/settings.json 中将其加入 deny 列表：
{
“subagents”: {
“deny”: [“explore”, “plan”]
}
}

生命周期钩子（Hooks）

子代理支持以下钩子事件，可用于日志、验证、通知等自动化场景

如何使用子代理

典型使用模式

子代理上下文与恢复

什么时候该用子代理？

最佳实践

description 怎么写
用动作式描述：当用户要求审查/分析/检查代码质量时调用
说明前置条件：在规格文档确认后使用，产出架构决策记录
写清楚代理的边界和不擅长的场景，防止被错误调用

工具权限设计
只读代理（审查、审计）：Read, Grep, Glob
研究代理（信息收集）：Read, Grep, Glob, WebFetch, WebSearch
实现代理（写代码）：Read, Write, Edit, Bash, Glob, Grep
遵循最小权限原则，只给代理完成任务所需的工具

单一职责
每个代理只做一件事，给出清晰的输入/输出/交接规则
不要试图用一个代理包办所有事情

system prompt 建议
在系统提示中明确代理的性格：请保持批判性，不要只说好话
指出代理的弱点和局限，避免过度自信
如果启用了记忆，在系统提示里写入"主动维护记忆"的指令

并行 vs 串行
域之间相互独立 → 并行，节省时间
下一步依赖上一步结果 → 串行，保证质量
避免为了并行而并行：10 个并行代理处理简单任务反而浪费 token 和协调成本

Agent Skills（智能体技能）

https://www.runoob.com/claude-code/claude-agent-skills.html

Agent 是智能体，Skills 是技能的意思，Agent Skills（智能体技能）是将专业知识、工作流规范固化为可复用资产的核心工具。

Agent Skills 本质上是一个模块化的 Markdown 文件，能教会 AI 工具（如 Claude、GitHub Copilot、Cursor 等）执行特定任务，且支持自动触发、团队共享与工程化管理，彻底告别重复的提示词输入。

Agent Skills 的本质不是工具，而是：行为规范 + 专业知识 + 使用时机的组合

在 Claude Code 中，Skill 是一种可复用的能力扩展包。

为什么需要 Skills？它解决了什么问题？

Skill 本质上是一个模块化知识包，可以给 Claude 添加： - 专业领域知识 - 固定工作流程 - API / 工具使用方式 - 模板和脚本 简单理解：Skill = 给 AI 写的一份“操作说明书”。

Skill 执行流程

1.从用户指令开始，先进行 Skill 意图识别，决定是否进入受控执行路径。
2.命中 Skill 后，系统加载 SKILL.md，建立工具权限与行为边界，再结合上下文进行推理。
3.只有在确实需要时才调用被允许的外部工具，否则在规则内完成逻辑。
4.最终结果经过约束整合后输出，用户的下一次输入触发新一轮完整流程。

Skill 的结构

一个Skill结构通常包含： skill-name/ ├── SKILL.md # 核心说明（必须） ├── reference.md # 文档或知识 ├── examples.md # 存放示例文件 └── scripts/ # 可执行脚本 └── helper.py Skill 的最小结构 my-skill/ └── SKILL.md （唯一必需）

SKILL.md 基本模板:

元数据字段:

Skills 支持在内容中插入动态变量:

SKILL.md 文件的核心构成

SKILL.md 的作用就是：教 Claude 如何使用某个工具或完成某个流程。

以 Claude 的 PDF 文档编辑技能为例，Claude 原生可解析 PDF，但无法直接操作（如填写表单），该技能补足了这一短板。

核心形态：一个包含 SKILL.md 的目录
必填元数据：SKILL.md 开头的 YAML 块，需包含 name（名称）和 description（描述），启动时预加载至系统提示词

多文件 Skill（渐进式披露）

第一个Skill.md

创建 Skill 目录
Skills 存放在 ~/.claude/skills/（个人全局）或项目目录下的 .claude/skills/（项目专用）。

编写配置文件 SKILL.md
在目录下创建 SKILL.md，这是 Skill 的大脑，告诉 Claude 什么时候用它。

你的项目现在是这样的：

my-project/├─ src/│ └─ test.py # 项目源码 ├─.claude/│ ├─ skills/│ │ └─ hello-world/│ │ ├─ skill.md # Skill 定义（YAML+Instructions，机器可执行） │ │ └─ README.md # Skill 说明（人类阅读，可选） │ └─ config.yml # Claude 项目级配置（可选） ├─.gitignore └─ README.md # 项目整体说明

字段要求：
name：必须仅使用小写字母、数字和连字符（最多 64 个字符）
description：Skill 的简要描述及其使用时机（最多 1024 个字符）

--- name: Python 内部命名规范技能 description: 当用户要求重构、审查或编写 Python 代码时，请参考此规范。 --- ## 指令 1. 所有的内部辅助函数必须以 `_internal_` 前缀命名。 2. 如果发现不符合此规则的代码，请自动提出修改建议。 3. 在执行 `claude commit` 前，必须检查此规范。 ## 参考示例 - 正确：`def _internal_calculate_risk():` - 错误：`def _calculate_risk():`

在终端输入任务：“帮我写一个计算用户折扣的函数”，验证是否匹配。

官方市场

将本仓库注册为 Claude Code 的插件市场，执行以下命令：
/plugin marketplace add anthropics/skills

注意：使用插件安装的 skills 目录在～/claude/plugins/marketplaces/ 下。

通过命令安装上述两类插件：

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

使用的时候只需在指令中提及技能名称即可调用，例如安装 document-skills 插件后，可向 Claude Code 下达指令：

使用 PDF 技能提取 path/to/some-file.pdf 文件中的表单字段

或者创建一个 PPT：创建一个 Agent Skill 的演示文稿：
可以看到，调用了 /document-skills:pptx 并告诉你生成的文件位置。

Agent Skills 相关资源整理

skill-creator 使用

skill-creator 就是 Anthropic 官方提供的 Skill 开发助手，帮助开发者创建、优化和打包技能。
GitHub 地址：https://github.com/anthropics/skills/tree/main/skills/skill-creator

Claude Code 插件（Plugin）

Claude Code 插件参考手册
https://www.runoob.com/claude-code/claude-code-plugin-ref.html

插件（Plugin）是 Claude Code 中最高级别的扩展机制，用于将命令、代理、Skills、钩子、MCP、LSP 等能力打包、版本化、共享和分发。

Claude Code 记忆系统（Memory）

每次 Claude Code 会话结束，上下文就会清空。
有时候我们每次都要重新告诉 Claude “用 pnpm 而不是 npm”、“我们的缩进是 2 个空格”？记忆系统（Memory）正是为此而生。

什么是 Claude Code 的记忆系统？
Claude Code 没有跨会话的自动记忆——每个新会话都从一个全新的上下文窗口开始。
记忆系统通过两种互补机制，让知识能够跨会话持久保存，并在每次对话开始时自动加载。

Auto Memory（自动记忆）详解

Claude Code 只在处理对应目录的文件时加载子目录的 CLAUDE.md，节省 token 的同时提供更精准的上下文。

自动记忆

参考官方文档：Memory System https://code.claude.com/docs/en/memory

Claude Code 钩子（Hook）

https://www.runoob.com/claude-code/claude-code-hooks.html
Claude Code 钩子是用户自定义的 Shell 命令，会在 Claude Code 生命周期的特定节点自动执行。

借助钩子，你可以对 Claude Code 的行为实现精准控制，确保某些操作（如代码格式化、日志记录）必定触发，而非依赖大模型自主选择是否执行。

钩子的典型应用场景

钩子能帮你实现很多实用功能，常见场景包括：

消息通知：当 Claude Code 等待输入或需要权限时，自动发送桌面/邮件提醒
自动格式化：编辑 .ts 文件后自动运行 prettier，修改 .go 文件后执行 gofmt
操作日志：记录 Claude 执行的所有命令，用于合规审计或调试排障
代码规范校验：若 Claude 生成的代码不符合项目规范（如命名规则），自动给出反馈
文件权限管控：阻止 Claude 修改生产环境配置文件或敏感目录（如 .env、.git）

相比于通过提示词约束 Claude 的行为，钩子是应用级的硬规则，只要触发对应事件就会强制执行，稳定性和可靠性更高。

重要安全提醒
钩子运行时会直接使用当前系统环境的凭证（如环境变量、用户权限），存在一定安全风险：

恶意钩子代码可能泄露你的敏感数据（如 API 密钥、项目源码）
错误的钩子命令可能导致文件误删、系统异常
必做安全操作：

注册钩子前，务必逐行审查命令的逻辑和权限
避免在钩子中执行来源不明的脚本
详细安全最佳实践，可参考官方文档的安全注意事项

钩子事件类型说明

Claude Code 内置了多个生命周期事件，你可以为不同事件绑定钩子命令。每个事件会传递不同的上下文数据，且对 Claude 行为的影响方式不同。

快速入门：实现命令日志记录
下面以记录 Claude 执行的所有 Bash 命令为例，带你一步步完成钩子的配置和使用。
输入 /hooks 命令，可查看已配置的钩子列表

其他

清理本地 Claude Code 缓存和配置
https://ctok.ai/claude-code-cleanup

在 c:/用户/你的用户名/ 目录下面找到 .claude 目录和 .claude.json 文件

Claude Code 基础用法 https://www.runoob.com/claude-code/claude-code-basic.html 常见高质量提问方式 Claude Code 的上限，取决于你的提问质量。 提问结构模板（强烈推荐） 一个稳定好用的提问模板： 背景： （我现在在做什么） 目标： （我希望达到什么效果） 约束： （不能做什么/必须遵守什么） 输出要求： （代码/解释/步骤）

问题探讨

这些智能体之间如何通信？是用自然语言直接对话，还是通过结构化的API消息？

这是一个非常核心的问题。答案是：**两者都用，而且通常是“结构化包装的自然语言”。** 单纯用自然语言对话（像两个人聊天）太随意、容易出错；单纯用结构化API（像程序调用）太死板、缺乏灵活性。当前最先进的多智能体系统，采用了一种**取长补短的混合模式**。 让我给你拆解一下： ### 1. 纯自然语言对话：直观但危险 **方式**：Agent A直接发一段文字给Agent B：“嘿，我测试发现登录模块挂了，你能回滚一下上个版本吗？” **优点**： - **极其灵活**：能处理意外情况，比如“那个...顺便把缓存也清一下，我觉得可能有关系。” - **对人类友好**：调试时人可以直接看懂。 **缺点**： - **歧义性**：Agent B可能误解“挂了”是崩溃了还是响应慢？“上个版本”是具体哪个版本号？ - **难以解析**：如果要自动根据消息内容执行代码，从“回滚一下上个版本”这句话里提取出`rollback(version=“v1.2.3”)`这个函数调用，很不稳定。 - **效率低**：需要消耗大量token去理解和生成寒暄语、修饰词。 ### 2. 纯结构化API消息：精确但僵硬 **方式**：Agent A调用Agent B暴露的一个API端点，发送JSON： { "action": "rollback", "parameters": { "service": "login-module", "target_version": "v1.2.2", "clear_cache": true }, "request_id": "req-001" } **优点**： - **精确无误**：字段清晰，Agent B可以直接用代码处理，无需“理解”。 - **高效**：消息极短，无需消耗token进行语义解析。 - **可靠**：自带错误处理（比如返回`{"status": "error", "code": 404}`）。 **缺点**： - **僵化**：如果Agent A想告诉Agent B一个API定义里没有的信息（比如“我发现日志里有个新规律，你先别回滚，等我再测5分钟”），API里没有这个字段，就传不过去。 - **难扩展**：每增加一种新的协作方式，都得修改API定义，重新部署两端。 ### 3. 最佳实践：工具调用/函数调用模式 目前最流行的方式（OpenAI、Anthropic、LangChain等都在用）是：**Agent之间用“工具调用”的范式通信，本质上是用结构化参数包装的指令，但指令本身可以包含自然语言描述。** **它是如何工作的？** 假设有一个**协调器Agent**（Manager）和一个**运维Agent**。 - **内部通信协议**：协调器Agent并不直接对运维Agent说话。而是，协调器Agent的“大脑”（LLM）决定调用一个叫 `ask_ops_agent` 的**工具/函数**。 - **实际发生的通信**：协调器Agent输出一个**结构化调用**： { "tool": "ask_ops_agent", "args": { "instruction": "执行回滚操作", "details": { "service": "login-module", "version": "v1.2.2", "reason": "测试Agent报告登录失败率超过15%，疑似最新部署引入bug。请回滚并观察5分钟。", "fallback_plan": "如果回滚失败，请执行服务隔离" } }} - **执行层**：系统将这个JSON交给一个**执行器**（一个简单的程序）。执行器解析后，通过消息队列、HTTP API或gRPC，将这个结构化的任务发给运维Agent。 - **运维Agent的回应**：运维Agent完成任务后，返回结构化结果： { "status": "success", "details": { "rolled_back_to": "v1.2.2", "observation": "回滚后登录失败率在2分钟内降至5%，问题解决。缓存已按指令清除。" } } **总结这种模式的本质：** > **“用自然语言填充结构化的参数。”** - **外壳是结构化的**：`instruction`, `details.service`, `details.reason` 这些字段是固定的，方便程序路由、解析、存储。 - **内核是自然语言的**：`reason` 和 `observation` 里的文字是自由的，让Agent可以传递复杂、非预期的上下文信息（比如那个“我发现日志里有个新规律...”）。 ### 4. 现实中不同架构的选择 | 架构风格 | 通信方式 | 适用场景 | 例子 | | :--- | :--- | :--- | :--- | | **闲聊/辩论式** | 纯自然语言 | 创意、分析、辩论（不直接执行动作） | 两个Agent讨论产品方案 | | **主从/调用式** | 结构化API + 自然语言参数 | 任务执行、工具调用（**最常见**） | 项目经理Agent分配任务给开发/测试/运维Agent | | **消息总线式** | 结构化事件（Event） | 大规模、解耦、事件驱动的系统 | 测试Agent发出`test_failed`事件，运维Agent订阅并响应 | | **黑板式** | 共享数据结构 | 需要高度协同、逐步求解的问题 | 多个Agent共同在同一个“黑板”上修改一份设计文档 | ### 结论 对于你提到的**测试人员和运维人员智能体协作**的场景： - **它们不会像两个人在微信群里聊天那样协作**（那样不可靠）。 - **它们也不会像两个微服务那样只交换冷冰冰的JSON**（那样不够灵活）。 **实际做法是：** 它们之间有一个**协调器（或直接通过消息队列）**，传递**结构化的事件或指令**，但每个指令的“内容描述”或“附注”字段里，可以包含**自然语言**。这样，程序可以精确路由和执行，而Agent们又能理解彼此的意图和异常情况。 **简单记忆：“程序之间用API，Agent之间用带附件的API——附件就是自然语言。”**

遇到问题

API Error:502{"error":{"message":"Upstream request failed after retries","type":"upstream_error"},"type":"error"}API Error:Claude's response exceeded the32000output token maximum.To configure this behavior,set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable