claude code 基础分享

Claude Code 基础分享

本文介绍 Claude Code 的核心功能、OMC 插件编排能力及最佳实践。

目录：

01 Claude Code 是什么
02 核心功能介绍（Context / Commands / Memory / Skills / Subagents / MCP / Hooks / Plugins / Checkpoints）
03 OMC 插件介绍（多 Agent 编排层）
05 安装与上手
06 最佳实践

Claude Code 是什么

Anthropic 推出的开发者代理（Developer Agent），以交互式 REPL 运行在终端中。

核心能力

**高度自主的智能体：**理解项目结构，在多文件间推理协作
**直接的环境操作：**读写文件、执行 Shell、管理 Git
**全流程工作闭环：**规划 → 执行 → 测试 → 验证
**强大的扩展能力：**通过 MCP 连接外部工具和数据库

典型场景

**自动化重复任务：**Git 操作、运行测试、代码格式化
**跨文件重构：**大型代码库的逻辑重构和多文件修改
**新项目脚手架：**根据需求快速生成项目初始结构
**调试与错误修复：**分析和修复复杂错误逻辑链条

本质区别：Assistive → Agentic

**Assistive：**你写代码，AI 建议下一行
**Agentic：**你描述目标，AI 规划并执行完整任务
主动读取文件、运行测试、修复错误

Claude CLI 启动界面

╭── Claude Code v2.1.132 ───────────────────────╮

Welcome back!

▐███▌

▝█████▘

▘▝

K2.6

Tips for getting started

Run /init to create CLAUDE.md

───────────────

What's new

/release-notes for more

╰─────────────── ~/my-project ──────────────────╯

可以理解为一位常驻终端的资深工程师，拥有整个项目的上下文。

01 Claude Code 是什么

交互模式与安全机制

交互模式

启动：在项目根目录执行 claude
交互：直接输入自然语言描述任务
退出：/exit 或按 Ctrl+D
单次模式：claude "给 utils.js 添加 JSDoc"

会话生命周期

**启动：**自动加载 CLAUDE.md、skills、hooks
**对话：**多轮交互，上下文持续累积
**压缩：**接近 token 上限时自动总结历史
结束： /clear 清空，或 /exit 退出

权限分层

**文件读取：**自动进行，无需确认
**文件写入：**默认需确认（可配置 auto-apply）
**Shell 命令：**每次执行前询问 y/n
**外部网络：**通过 MCP 访问，受配置约束

交互示意

$ claude

Starting Claude Code...

给 utils.js 添加单元测试

I'll analyze and add tests...

Allow edit 3 files? (y/n)

y

01 Claude Code 是什么

Claude 项目目录结构

Claude Code 的项目级配置藏在 .claude/ 目录下，团队共享靠 git：

your-project/（项目根目录）

├── CLAUDE.md项目规则文件，建议不超过200行

├── CLAUDE.local.md个人自定义配置，gitignored

├── .gitignore规定哪些文件不应被Claude读取

├── .mcp.json模型上下文协议（MCP）配置，必须放在根目录

└── .claude/Claude寻找项目上下文的优先级最高的地方

├── hooks/脚本钩子，这里的脚本在特定时机一定会触发

│ ├── PostToolUse.sh在工具使用后自动执行

│ ├── SessionStart.sh启动会话时加载项目上下文

│ └── PreCompact.sh在上下文压缩前保存状态

├── commands/用于自定义快捷命令

│ └── chup.md例：一键完成构建、代码检查和部署

├── skills/存放模型可以随时调用的具体skill

│ ├── carousel/例：自动生成社媒插图/轮播图的skill

│ └── crill/例：生成练习或训练教程的skill

├── agents/存放agent文件夹，每个都具有独立上下文窗口

│ ├── code-reviewer.md例：代码审查agent，负责分析代码差异并总结

│ ├── researcher.md例：研究员agent，负责抓取并整合网页信息

│ └── log-analyzer.md例：日志分析agent，专门解析报错信息

├── output-styles/定义Claude的回复风格

│ └── terse.md例：只给代码，不废话

├── plugins/通过插件形式集成命令、代理和MCP

│ └── vercel/示例插件目录

├── rules/局部规则，根据文件路径匹配加载

│ └── api.md仅当处理API相关目录时才加载的规则

├── statusline/命令行底部状态栏的显示配置

├── settings.json权限设置，模型选择及钩子注册中心

└── settings.local.json本地个人偏好设置，gitignored

核心价值：所有配置版本化、可复现。新人 clone 仓库后，.claude/ 里的 skills、agents、hooks 自动生效，不需要再手动 cp 七八遍配置文件。项目的规范、审查标准、常用命令全部随代码一起版本控制，不会因为某个老成员离职而丢失。

02 核心功能介绍

上下文（Context）

Claude Code 与传统工具最本质的区别在于上下文管理。

传统工具的上下文

通常只有当前文件或最近几个文件
每次对话从零开始，没有记忆积累
无法感知项目规范、代码风格、团队约定
跨文件修改需要人工传递上下文

Claude Code 的上下文

加载整个项目的 CLAUDE.md、skills、hooks
形成持续积累的项目级记忆
自动感知规范、风格、常用命令
Subagent 拥有独立的 context window，隔离复杂任务

上下文占用与压缩

**查看状态：**输入 /status 查看当前模型配置
**自动压缩：**接近上限时自动总结历史，保留决策，丢弃细节
**触发时机：**系统内部 token 计数器监控，无需手动干预

满了的后果与应对

**细节丢失：**早期代码片段、试错过程可能被压缩
**决策保留：**核心结论、架构方向通常不会丢失
**应对方式：**关键节点 /clear 开启新会话，或 /memory 持久化

主流模型上下文窗口对比（参考）

模型	上下文窗口	说明
Claude Opus	100万 Token (1M)	自2026年3月起，1M上下文已成为官方服务的默认配置，并向所有用户开放
DeepSeek V4	100万 Token (1M)	官方API文档确认1M上下文是V4-Pro和V4-Flash的标配，但有开发者实测其"专家模式"为128K
GLM-5	128K - 205K Token	该模型的上下文长度在不同平台或微调阶段有不同数值，主流平台如SiliconFlow标注为205K，而Vultr等平台标注为128K
Kimi K2	262K / 256K Token	这是其当前主流版本（K2-0905）的规格。其基础版本曾为128K/131K，早期宣传中的理论上限为2M Token

注：具体数值以各厂商官方文档为准，模型迭代频繁，建议定期核实。

02 核心功能介绍

核心能力 ①：Slash Commands

用户在 REPL 输入 /name 触发的快捷指令。把复杂操作流程压缩成几个字符，只需记住意图，无需记住参数顺序和路径。

类型	来源	触发方式	示例
Built-in	Claude Code 原生	`/command`	`/help`、`/clear`、`/status`
Skill	项目或个人 skill 文件	`/skill-name` 或自然语言	`/autopilot "build a REST API"`
Plugin Command	已安装插件	`/plugin:command`	`/oh-my-claudecode:setup`
MCP Prompt	MCP Server	`/mcp__service__action`	`/mcp__github__list_prs`

自动建议机制

**触发条件：**对话内容匹配 skill 的 description 关键词时，Claude 自动弹出建议
**description 写法：**使用"动词 + 场景"格式，如"从自然语言描述生成完整项目代码"
**交互流程：**Claude 问"是否需要运行 /xxx？" → 用户确认 → 自动执行
**最佳实践：**每个 skill 聚焦一个具体任务，description 避免笼统描述

常用示例

复制代码

# 初始化项目配置
/init

# 打开多层记忆编辑器
/memory

# 查看当前状态与模型
/status

02 核心功能介绍

核心能力 ②：Memory

Claude Code 的持久化上下文系统，启动时自动按层级加载，不会互相覆盖。

优先级	层级	文件位置	作用
1	Project Memory	`./CLAUDE.md`	项目规范、代码风格、常用命令，随 Git 共享给团队
2	Project Rules	`.claude/rules/*.md`	局部规则，按文件路径匹配加载
3	User Memory	`~/.claude/CLAUDE.md`	个人偏好，如常用快捷键、模型选择
4	Auto Memory	自动持久化	记录常用文件路径、最近修改模块、团队偏好

官方书写标准

**简洁优先：**建议不超过 200 行，过长则拆分到 rules/
**分层存储：**团队约定与个人习惯各得其所，不会互相覆盖
**版本控制：**项目级配置随 Git 提交，clone 即生效
**即时生效：**改完保存后 Claude 立即加载新版本

使用方式

每次启动自动进入上下文，无需手动加载
输入 /memory 打开多层编辑器直接修改
新人不需要问"我们项目的规范是什么"

02 核心功能介绍

核心能力 ③：Skills

可复用能力包，封装"重复 5 步以上的工作流"。支持 YAML frontmatter、子脚本、模板、动态上下文注入（!command）。

官方推荐结构

复制代码

---
name: check
description: Run full quality pipeline
allowed-tools: Bash(cmake *), Bash(ninja *)
---

## Task
按顺序执行：
1. cmake -S . -B build -GNinja
2. ninja -C build
3. ninja -C build ctest
任一失败立即停，并输出日志摘要。

编写要点

**description 要具体：**写清楚做什么、何时触发，Claude 才能自动建议
**allowed-tools 限定范围：**避免 Claude 误操作，只给必要的工具权限
**渐进式加载：**启动只读 frontmatter（~100 token），触发时才加载完整指令（~5000 token）
**存放位置：**个人级 ~/.claude/skills/ 或项目级 .claude/skills/

Skill 类型

**Workflow：**封装固定步骤的流水线，如 /check 跑全量测试
**Generator：**从模板生成代码，如 /scaffold 创建模块骨架
**Analyzer：**分析并输出报告，如代码审查、日志解析

触发方式

**手动：**输入 /skill-name 直接触发
**自动建议：**对话匹配 description 时 Claude 主动推荐
**Hook 绑定：**特定事件（如保存文件）自动触发

02 核心功能介绍

核心能力 ④：Subagents

独立上下文的专用 Agent，主 Agent 可委派任务，实现并行计算 + 上下文隔离。

核心优势

**隔离：**每个 Subagent 拥有独立的 context window，复杂任务不污染主对话
**并行：**多个 Subagent 同时处理不同子任务，缩短总耗时
**专精：**可为不同任务配置不同的 system prompt 和工具集

官方推荐类型

**code-reviewer：**自动审查代码 diff，输出问题清单和改进建议
**researcher：**抓取网页、搜索文档，整合技术背景信息
**implementation-agent：**执行复杂多文件修改，专注实现细节
**debugger：**分析报错日志和堆栈跟踪，定位根因
**security-reviewer：**审查安全风险，如注入、越权、敏感信息泄露

委派示例

场景	触发方式	命令示例
代码审查	手动指定 Agent	`> 用 code-reviewer 审查当前分支相对于 main 的代码差异`
代码审查	斜杠命令直接调用	`> /code-reviewer 审查当前分支的代码变更`
代码审查	自动建议（description 含 PROACTIVELY）	`> 帮我 review 一下当前分支的代码改动，看看有没有潜在问题`

02 核心功能介绍

核心能力 ⑤：MCP

Model Context Protocol ------ Claude Code 与外部服务的标准接口，实现工具即服务。

架构原理

**Client-Server 模式：**Claude 作为 Client，通过标准协议调用外部 Server
**Request/Response：**Claude 发请求 → MCP Server 查询 → 返回结构化数据
**与 Memory 互补：**Memory 存不变规范，MCP 读实时数据

常见场景

**GitHub：**查询 PR、Issue、分支状态，自动评论
**数据库：**直接执行 SQL，查询表结构和数据
**文件系统：**跨项目读取文件，批量操作
**Slack/钉钉：**发送通知，同步讨论结论

配置与使用

复制代码

# 添加 MCP Server
claude mcp add --transport http github https://api.github.com/mcp

# 使用方式
> 列出最近 5 个 open PR 的状态
> /mcp__github__get_pr 456

02 核心功能介绍

核心能力 ⑥：Hooks

事件驱动的自动化脚本，在特定时机自动触发，支持 28 种生命周期事件。

核心机制

**事件绑定：**SessionStart、PreToolUse、PostToolUse、Stop 等 28 种事件
**Matcher 匹配：**按工具类型、文件名、操作等条件过滤
**阻断决策：**退出码 0=继续执行，2=阻断当前操作
**Hook 类型：**shell 命令、HTTP webhook、LLM prompt、MCP tool

常用模式

**自动格式化：**保存 .cpp/.h 后自动跑 clang-format
**提交前检查：**PreToolUse 拦截，确保测试通过才允许写入
**会话恢复：**SessionStart 自动加载上次工作状态
**审计日志：**记录所有工具调用到本地日志文件

常用事件详解

SessionStart
会话启动时触发，自动加载项目上下文、设置环境变量、恢复上次工作状态。适合初始化。
PreToolUse
工具执行前拦截，可验证参数、检查安全策略、阻断危险操作。返回 2 可阻止执行。
PostToolUse
工具执行后触发，可自动格式化代码、更新索引、发送通知。配合 Write/Edit 实现保存即格式化。
Stop
会话结束前触发，自动保存未提交的修改、生成会话摘要、清理临时文件。

模板：提交前自动格式化

复制代码

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": {
        "tools": ["Write", "Edit"],
        "pattern": "\\.(cpp|c|h)$"
      },
      "type": "command",
      "command": "ninja format"
    }
  ]
}

当 Write 或 Edit 操作涉及 .cpp/.c/.h 文件时，自动执行 ninja format 格式化代码。

02 核心功能介绍

核心能力 ⑦：Plugins

把 commands、agents、skills、hooks、MCP 打包成单个可分发单元，一键部署完整工作流。

核心特性

**一键安装：**安装 plugin = 一次性部署一整套工作流
**标准结构：**plugin.json 清单 + skills/ + agents/ + hooks/ 目录
**版本管理：**支持升级、回滚、依赖声明

安装来源

**Marketplace：**官方或社区维护的插件市场
**GitHub：**直接从仓库安装，适合内部团队插件
**本地路径：**开发调试时从本地文件系统加载

官方与社区插件示例

oh-my-claudecode
多 Agent 编排插件，提供 autopilot、ralph、team 等核心工作流和 20+ 专用 agents。
pr-review
完整 PR 审查工作流，集成安全检查、测试验证、文档同步。
devops-automation
DevOps 自动化：部署、监控、事件响应一体化。

插件管理与生命周期

复制代码

# 安装
/plugin install oh-my-claudecode

# 更新
/plugin update oh-my-claudecode

# 禁用 / 启用
/plugin disable oh-my-claudecode
/plugin enable oh-my-claudecode

# 查看已安装
/plugin list

02 核心功能介绍

核心能力 ⑧：Checkpoints

会话快照机制，保存对话状态 + 文件状态的组合快照，实现无损实验和快速回滚。

核心机制

**自动快照：**每次用户 prompt 后自动产生 checkpoint
**组合状态：**同时保存对话上下文和文件系统状态
**快速回滚：**按 Esc Esc 或输入 /rewind 回到任意历史点

五种恢复模式

**全部恢复：**对话和文件都回滚到快照点
**仅对话：**保留当前文件，只恢复对话上下文
**仅代码：**保留对话，只恢复文件状态
**总结压缩：**将历史压缩为摘要，释放上下文空间
**取消：**放弃回滚，保持当前状态

与 Git 的关系

**Checkpoint：**实验阶段的快速回滚，秒级操作
**Git：**持久化验证通过的改动，版本化管理

最佳实践

用 checkpoint 做快速实验，确定方向后再 git commit
大改动前先手动 /checkpoint 建立安全点
与 /clear 区分：checkpoint 保留恢复能力，clear 彻底清空

02 核心功能介绍

Skill、Command、Subagent 核心区别

三者解决不同层面的问题，合理组合才能发挥最大效能。

维度	Skill（技能）	Command（命令）	Subagent（子代理）
本质	可复用的任务模板	预置的快捷操作	独立的执行实体
解决什么问题	「怎么做」------ 标准化复杂任务的执行流程	「做什么」------ 快速触发常用功能	「谁来做」------ 委派专业任务给专家代理
触发方式	`/skill-name` 或关键词自动匹配	`/command` 直接调用	`Agent` 工具调用或命令委派
内容形态	YAML frontmatter + Task body	内置指令或自定义脚本	独立上下文 + 专用工具集
典型场景	代码审查、TDD 循环、文档生成	`/clear`、`/commit`、`/cost`	复杂重构、安全审计、多文件协调

**组合建议：**用 Command 快速启动 → Skill 规范流程 → Subagent 处理重活，形成「触发 → 标准 → 委派」的完整工作流。

03 OMC 插件介绍

OMC 是什么

oh-my-claudecode ------ Claude Code 的多 Agent 编排层，把单个能力点组装成生产线。

核心哲学

不是独立的 AI，而是 Claude Code 的插件
把底层能力封装成高阶工作流
理念："Don't learn Claude Code. Just use OMC."

解决的核心痛点

**学习曲线陡峭：**Claude Code 功能丰富但零散，OMC 提供统一入口
**质量不稳定：**手动操作容易遗漏步骤，OMC 强制验证闭环
**上下文溢出：**复杂任务塞满主窗口，OMC 自动委派子代理
**重复劳动：**相同调试步骤每次都手动，OMC 提取为可复用 Skill

五大维度能力全景

维度	代表能力	作用
Skills	/check / autopilot / commit	把重复工作流压成一行命令
Agents	executor / planner / architect / critic	19 种专家角色自动委派
Hooks	keyword-detector / persistent-mode	11 个生命周期事件自动触发
Teams	/team / omc-teams / ccg	多模型并行交叉验证
Modes	/autopilot / /ralph / /ultrawork	不同复杂度匹配不同策略

配置层级

项目级： ./.claude/CLAUDE.md，仅当前项目生效，安全隔离
全局级： ~/.claude/CLAUDE.md，所有项目共享，默认覆盖
**优先级：**项目级 > 全局级，团队协作时项目级优先

03 OMC 插件介绍

OMC 配置与 HUD

配置方式

方式	命令	适用场景
项目级	`/omc-setup --local`	仅当前项目生效，不影响其他项目
全局级	`/omc-setup`	所有项目共享，覆盖默认配置
本地开发	`omc setup --plugin-dir-mode`	从源码加载，无需 marketplace 更新

环境变量

变量	用途
`OMC_STATE_DIR`	集中化状态目录，跨 worktree 保留
`DISABLE_OMC=1`	禁用所有 OMC hooks
`OMC_SKIP_HOOKS`	跳过指定 hook（逗号分隔）

诊断工具

/status --- 查看 OMC 版本和加载状态
/omc-doctor --- 诊断配置冲突和缺失项

HUD 状态栏

OMC 安装后自动在 Claude Code 底部显示实时状态栏，约 300ms 刷新一次。