Claude Code 入门指南：从工具到工作流的 AI 编程新范式

你的主要工作环境是什么？
│
├─ 图形界面 IDE
│   └─ 选择 Cursor
│       - 可视化调试
│       - 实时预览
│       - 低学习曲线
│
├─ 终端/命令行
│   ├─ 需要可视化调试？ ── 是 ── 考虑 Cursor
│   │
│   └─ 纯终端环境
│       ├─ 已有 ChatGPT Plus？ ── 是 ── Codex CLI
│       │
│       ├─ 已有 Claude Pro？ ── 是 ── Claude Code
│       │
│       └─ 都没有
│           ├─ 需要超长上下文？ ── 是 ── Claude Code
│           ├─ 需要丰富扩展生态？ ── 是 ── Claude Code
│           └─ 追求轻量简单？ ── 是 ── Codex CLI
│
└─ 服务器/远程开发
    └─ Claude Code 或 Codex CLI

推荐：Cursor（主）+ Claude Code（辅）

- 用 Cursor 做日常编码、UI 调试
- 用 Claude Code 处理部署脚本、后端自动化

推荐：Claude Code（主）

- 终端原生，与服务器环境无缝衔接
- 丰富的自动化能力（MCP、Skills、Hooks）
- 可集成到 CI/CD 流程

推荐：Claude Code

- 超长上下文分析大型代码库
- 自动处理 Issue、PR
- 生成发布文档

推荐：Cursor + Claude Code

- Cursor：Notebook 集成、可视化
- Claude Code：数据处理脚本、自动化流程

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

brew install --cask claude-code

winget install Anthropic.ClaudeCode

npm install -g @anthropic-ai/claude-code

$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

claude --version
claude doctor  # 检查安装类型和版本

claude
# 首次运行会提示你登录

cd ~/projects/my-app
claude

> 这个项目是做什么的？总结一下技术栈和文件夹结构。

~/.claude/
├── settings.json              # 用户全局配置
├── mcp_servers.json           # MCP 服务器配置
├── skills/                    # 用户 Skills 目录
│   └── my-skill/
│       └── SKILL.md
├── agents/                    # 用户 SubAgent 目录
│   └── my-agent.md
├── plugins/                   # 插件目录
│   ├── cache/                 # 版本化插件缓存
│   └── data/                  # 插件持久化数据
└── projects/                  # 项目特定会话
    └── my-project/
        ├── sessions/          # 会话历史
        └── memory/            # 跨会话记忆

# 继续最近的对话
claude -c

# 查看并恢复历史对话
claude -r
# 会显示历史对话列表，选择恢复

# 在会话内
> /resume    # 选择恢复某个历史检查点

# 项目说明

这是一个 React + Go 全栈应用。

## 技术栈
- 前端：React 19, TypeScript, shadcn/ui, Tailwind CSS
- 后端：Go 1.23, Echo v4, PostgreSQL
- 基础设施：Docker, GitHub Actions

## 编码规范
- Go：遵循 Effective Go，接口优先
- TypeScript：严格模式，禁用 any
- 提交：使用 Conventional Commits 格式

## 禁止事项
- 不要使用 `console.log`，使用 `logger.info()`
- 不要直接操作 DOM，使用 React 状态管理
- 不要硬编码配置，使用环境变量

## 常用命令
\`\`\`bash
make dev      # 启动开发环境
make test     # 运行所有测试
make lint     # 运行 linter
\`\`\`

┌──────────────────────────────────────────────────────┐
│              跨会话记忆工作流                           │
│                                                      │
│  会话结束时（PostSession Hook）                         │
│       │                                              │
│       ▼                                              │
│  提取关键决策、未完成任务、重要发现                       │
│       │                                              │
│       ▼                                              │
│  写入 ~/.claude/projects/{project}/memory/           │
│  - feedback.md（用户偏好和反馈）                       │
│  - project.md（项目状态和决策）                        │
│  - tasks.md（待办任务）                               │
│       │                                              │
│  会话开始时（PreSession Hook）                          │
│       │                                              │
│       ▼                                              │
│  读取记忆文件，注入到初始上下文                           │
│       │                                              │
│       ▼                                              │
│  Claude 带着历史上下文开始新会话                         │
└──────────────────────────────────────────────────────┘

# 基本语法
claude mcp add --transport http <name> <url>

# 示例：连接 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 示例：连接 Sentry
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 基本语法
claude mcp add --transport sse <name> <url>

# 示例：连接 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 基本语法
claude mcp add --transport stdio <name> -- <command>

# 示例：添加 Airtable 服务器
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

# 列出所有已配置的服务器
claude mcp list

# 获取特定服务器详情
claude mcp get github

# 移除服务器
claude mcp remove github

# 在 Claude Code 会话中
> /mcp
# 选择需要认证的服务器，按提示完成 OAuth 流程

# 添加项目作用域服务器（共享给团队）
claude mcp add --transport http github --scope project https://api.githubcopilot.com/mcp/

# 1. 添加 Sentry MCP 服务器
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. 在 Claude Code 中认证
> /mcp
# 选择 Sentry 完成认证

# 3. 调试问题
> 过去 24 小时最常见的错误是什么？
> 显示错误 ID abc123 的堆栈跟踪
> 哪个部署引入了这些新错误？

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

# 2. 在 Claude Code 中
> 审查 PR #456 并提出改进建议
> 为我们刚发现的 bug 创建一个新 issue
> 显示所有分配给我的开放 PR

> name: Git Commit Messages
> description: 生成清晰的 Git 提交信息。当用户需要写提交信息或审查暂存更改时使用。

# Git Commit Messages

## 指令

1. 运行 `git diff --staged` 查看更改
2. 我会建议一个提交信息，包含：
   - 50 字符以内的摘要
   - 详细的描述
   - 受影响的组件

## 最佳实践

- 使用现在时态
- 解释"做了什么"和"为什么"，而不是"怎么做"

my-skill/
├── SKILL.md          # 必需：主指令文件
├── reference.md      # 可选：详细参考文档
├── examples.md       # 可选：使用示例
├── scripts/
│   └── helper.py     # 可选：辅助脚本
└── templates/
    └── template.txt  # 可选：模板文件

> name: Code Reviewer
> description: 审查代码最佳实践和潜在问题。用于代码审查、检查 PR 或分析代码质量。
> allowed-tools: Read, Grep, Glob

# Code Reviewer

这个 Skill 提供只读的代码审查能力，不会修改任何文件。

# 添加插件市场
/plugin marketplace add <marketplace-url>

# 安装包含 Skills 的插件
/plugin install <plugin-name>@<marketplace-name>

# 创建 Skill 目录
mkdir -p ~/.claude/skills/my-skill

# 创建 SKILL.md 文件
echo '---
name: My Skill
description: 描述这个 Skill 的功能和使用场景

# My Skill

这里是具体指令...
' > ~/.claude/skills/my-skill/SKILL.md

git clone https://github.com/user/skill-repo.git ~/.claude/skills/skill-name

> 能帮我提取这个 PDF 中的文本吗？

ls ~/.claude/skills/my-skill/SKILL.md
ls .claude/skills/my-skill/SKILL.md

cat SKILL.md | head -n 10
# 确保开头的 `---` 在第一行
# 确保结束的 `---` 在 Markdown 内容之前

claude --debug
# 会显示 Skill 加载错误

# 1. 在项目中创建 Skill
mkdir -p .claude/skills/team-skill
# 创建 SKILL.md

# 2. 提交到 git
git add .claude/skills/
git commit -m "Add team Skill for PDF processing"
git push

# 3. 团队成员拉取后自动可用
git pull
claude  # Skills 立即可用

┌────────────────────────────────────────────────────────────────┐
│                    Skills Bootstrap 生命周期                     │
│                                                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │  Built-in    │  │  Plugin      │  │  User (.claude/      │ │
│  │  Skills      │  │  Skills      │  │   skills/)           │ │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘ │
│         └─────────────────┼──────────────────────┘            │
│                           │                                    │
│                           ▼                                    │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                  Skill Classifier（分类器）              │   │
│  │                                                        │   │
│  │  Core Queue（核心队列）  │  Deferred Queue（延迟队列）   │   │
│  │  ● 启动必需的 Skills     │  ● 非关键 Skills              │   │
│  │  ● 同步加载              │  ● 后台异步加载               │   │
│  └────────────────────────────────────────────────────────┘   │
│                           │                                    │
│                           ▼                                    │
│  ┌────────────────────────────────────────────────────────┐   │
│  │              6-Phase Bootstrap（六阶段引导）             │   │
│  │                                                        │   │
│  │  Hydrate → Discover → Validate → Resolve → Activate   │   │
│  │      状态恢复   发现技能    验证      依赖排序    激活   │   │
│  │                                                ↓       │   │
│  │                                             Verify     │   │
│  │                                             验证完成    │   │
│  └────────────────────────────────────────────────────────┘   │
│                           │                                    │
│                           ▼                                    │
│  Progressive Disclosure（渐进式披露）                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │
│  │  Summary    │  │  Compact    │  │  Full               │   │
│  │  摘要级别   │  │  紧凑级别   │  │  完整级别            │   │
│  └─────────────┘  └─────────────┘  └─────────────────────┘   │
└────────────────────────────────────────────────────────────────┘

[App Start]
     │
     ▼
  idle ──runBootstrap()──▶ hydrate（状态恢复）
                               │
                               ▼
                           discover（发现所有 Skills）
                               │
                               ▼
                           validate（验证 Skill 格式）
                               │
                               ▼
                        resolve_order（拓扑依赖排序）
                               │
                               ▼
                           activate（激活 Skills）
                               │
                               ▼
                            verify（验证完成）
                               │
                   ─────────────┼─────────────
                   │                          │
            无延迟 Skills                有延迟 Skills
                   │                          │
                   ▼                          ▼
              full_ready              deferred_load（后台）
                                             │
                                   ──────────┼──────────
                                   │                    │
                              加载成功             加载失败（软错误）
                                   │                    │
                              full_ready           core_only
                                                （退化到仅核心模式）

> name: Advanced Code Review
> description: 高级代码审查，依赖基础代码审查 Skill
> depends_on:
> - basic-code-review
> - security-scanner

# ❌ 太模糊 - 很难触发
description: Helps with code

# ✅ 精确 - 包含触发场景和关键词
description: 审查 Python 代码的类型安全性和异常处理。
  当用户要求 code review、检查 Python 代码、或提到 type hints、
  exceptions、error handling 时使用。

> name: Python Code Reviewer
> description: 审查 Python 代码质量、类型安全和异常处理...

<!-- Summary 级别（简短，必须放在开头） -->
Python 代码审查专家，关注类型安全和异常处理。

<!-- Compact 级别（稍详细） -->
## 快速指南
- 检查所有函数的类型注解
- 验证异常处理的完整性
- 确认资源正确释放

<!-- Full 级别（完整内容） -->
## 完整审查清单

### 类型安全
...（详细内容）

> name: Security Scanner
> description: 安全漏洞扫描
> load_priority: core    # 标记为核心 Skill，优先加载

┌──────────────────────────────────────────────────────┐
│               Hooks 执行时机                           │
│                                                      │
│  用户输入消息 ──▶ [PreToolUse Hook] ──▶ 工具调用       │
│                                             │         │
│                    [PostToolUse Hook] ◀─────┘         │
│                             │                         │
│                             ▼                         │
│  Claude 响应   ◀── [PostSampling Hook]               │
│       │                                               │
│       ▼                                               │
│  [Notification Hook] （异步通知，不阻塞）               │
└──────────────────────────────────────────────────────┘

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[HOOK] 即将执行 Bash 命令' >> /tmp/claude-hooks.log"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_TOOL_RESULT_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "[ -f \"$CLAUDE_TOOL_INPUT_FILE_PATH\" ] && npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf\\|DROP TABLE\\|format C:' && echo '{\"decision\": \"block\", \"reason\": \"危险命令已被拦截\"}' || true"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreSession": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/.claude/projects/$(basename $PWD)/memory/MEMORY.md 2>/dev/null | head -50"
          }
        ]
      }
    ]
  }
}

# 允许继续（默认）
exit 0

# 阻止工具执行并返回自定义消息
echo '{"decision": "block", "reason": "该操作需要审批"}'

# 修改工具输入（PreToolUse）
echo '{"modified_input": {"command": "echo safe_version"}}'

                    需要外部访问？
                         │
            ┌────────────┴────────────┐
           是                          否
            │                          │
     使用 MCP               需要自动触发？
            │                    ┌─────┴─────┐
            │                   是           否
            │                    │           │
            │              使用 Hooks   使用 Skills
            │              或 CLI
            │
     数据源还是服务？
     ┌──────┴──────┐
    数据           服务
     │             │
  数据库类       API 类
  (PostgreSQL,   (GitHub,
   SQLite)        Notion)

1. Skill 指导如何写提交信息
2. Claude 使用 CLI 执行 git add
3. MCP 连接 GitHub 创建 PR
4. Hook 在提交后自动运行 lint 和测试

1. Skill 定义数据库操作规范（命名、索引策略）
2. MCP 连接 PostgreSQL 执行查询
3. Hook 在文件保存后验证 SQL 语法

1. Skill 定义文档格式和结构
2. MCP 读取 Notion 中的需求
3. CLI 生成 Markdown 文件
4. Hook 在文件创建后自动提交

┌─────────────────────────────────────────┐
│           Main Claude Session           │
│                                         │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │SubAgent │ │SubAgent │ │SubAgent │   │
│  │   #1    │ │   #2    │ │   #3    │   │
│  │(代码审查)│ │(测试运行)│ │(文档生成)│   │
│  └────┬────┘ └────┬────┘ └────┬────┘   │
│       │           │           │         │
│       └───────────┴───────────┘         │
│                   │                     │
│           返回结果摘要                    │
└─────────────────────────────────────────┘

/agents

# 选择 "Create New Agent"
# 选择 "Personal"（用户级）或 "Project"（项目级）
# 使用 Claude 生成或手动编写
# 选择允许的工具
# 选择模型
# 保存

name: code-reviewer
description: 代码审查专家。在编写或修改代码后主动审查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: inherit

你是资深代码审查专家，确保高质量的代码标准。

审查清单：
- 代码简洁可读
- 函数和变量命名清晰
- 无重复代码
- 适当的错误处理
- 无暴露的密钥或 API Key
- 输入验证已实现

反馈按优先级组织：
- 关键问题（必须修复）
- 警告（应该修复）
- 建议（考虑改进）

┌─────────────────────────────────────────────────────┐
│                    Team Lead                         │
│         (协调任务、分配工作、综合结果)                  │
│                                                     │
│   TaskList (共享任务列表)                             │
│   ┌─────────────────────────────────────┐           │
│   │ [ ] 任务1: 分析前端组件              │           │
│   │ [ ] 任务2: 审查后端 API              │           │
│   │ [ ] 任务3: 检查数据库层              │           │
│   │ [ ] 任务4: 生成测试用例              │           │
│   └─────────────────────────────────────┘           │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │Teammate 1│  │Teammate 2│  │Teammate 3│          │
│  │ 认领任务1 │  │ 认领任务2 │  │ 认领任务3 │          │
│  │   和 4   │  │          │  │          │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       │             │             │                 │
│       └─────────────┴─────────────┘                 │
│                     │                               │
│            队友间直接通信                             │
└─────────────────────────────────────────────────────┘

> 分析这 5 家竞争对手的市场定位，每家用一个独立的子代理

> 使用 code-reviewer 子代理检查我最近的代码变更
> 让 debugger 子代理调查这个错误

> /agents
# 选择 "Create New Agent"
# 描述你的子代理功能和触发条件
# 选择允许的工具

name: code-reviewer
description: 代码审查专家。在编写或修改代码后主动审查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: inherit

你是资深代码审查专家，确保高质量的代码标准。

审查清单：
- 代码简洁可读
- 函数和变量命名清晰
- 无重复代码
- 适当的错误处理
- 无暴露的密钥或 API Key
- 输入验证已实现
- 良好的测试覆盖

反馈按优先级组织：
- 关键问题（必须修复）
- 警告（应该修复）
- 建议（考虑改进）

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

> 我在开发一个 CLI 工具，帮助开发者追踪代码中的 TODO 注释。
> 创建一个 AgentTeam 从不同角度探索：
> - 一个队友负责 UX
> - 一个队友负责技术架构
> - 一个队友扮演反对者

// settings.json
{
  "teammateMode": "tmux"  // 或 "in-process"
}

> 清理团队

> 创建一个 AgentTeam 审查 PR #142。生成三个审查员：
> - 一个关注安全影响
> - 一个检查性能影响
> - 一个验证测试覆盖
>
> 让他们各自审查并报告发现。

> 用户报告应用在发送一条消息后就断开了。
> 生成 5 个队友调查不同的假设。让他们互相交流，
> 试图推翻彼此的理论，像科学辩论一样。
> 用形成的共识更新发现文档。

> 并行研究这 5 家公司的市场定位，每家用一个独立的子代理：
> - Acme Corp
> - Beta Industries
> - Gamma Tech
> - Delta Solutions
> - Epsilon Labs
>
> 每个子代理应分析：市场地位、近期新闻、竞争优势。
> 完成后综合成对比矩阵。

> 创建一个 AgentTeam 来重构这个项目的认证系统：
> - Teammate 1: 重构登录模块
> - Teammate 2: 重构权限检查
> - Teammate 3: 更新 API 端点
> - Teammate 4: 更新测试用例
>
> 确保所有变更保持 API 兼容性。

> 我想给应用添加一个深色模式

Claude: 好的，在开始之前，我想先了解一些细节：
1. 深色模式应该自动跟随系统设置，还是让用户手动切换？
2. 用户的选择应该持久化吗？用什么方式存储？
3. 切换时需要动画过渡吗？
4. 有没有特定的颜色需要自定义？

## 实现计划

### 任务 1：创建主题 Context (预计 3 分钟)
文件：src/context/ThemeContext.tsx
代码：
- 创建 ThemeProvider 组件
- 定义 light/dark 两种主题状态
- 实现 toggle 函数
验证：TypeScript 编译通过

### 任务 2：添加 localStorage 持久化 (预计 2 分钟)
文件：src/context/ThemeContext.tsx
修改：
- 在 useEffect 中读取 localStorage
- 在切换主题时写入 localStorage
验证：刷新页面后主题保持
...

# 错误的方式（会被拒绝）
Claude: 我先写实现代码...
Superpowers: 错误！没有失败的测试存在。代码已删除。

# 正确的方式
Claude: 首先我写一个测试，期望 toggleTheme 函数存在...
（测试运行 → 失败 ✓）
Claude: 现在我实现 toggleTheme 函数...
（测试运行 → 通过 ✓）

# 添加 marketplace
/plugin marketplace add obra/superpowers-marketplace

# 安装 Superpowers
/plugin install superpowers@superpowers-marketplace

> /help

/superpowers:brainstorm     # 开始头脑风暴会话
/superpowers:write-plan     # 创建实现计划
/superpowers:execute-plan   # 用子代理执行计划

project/
├── .specs/
│   ├── steering.md        # 项目指导原则
│   ├── features/          # 功能规格
│   │   ├── auth.md
│   │   └── dashboard.md
│   └── tasks/             # 任务列表
│       └── auth-tasks.md
├── design.md              # 设计文档
└── src/                   # 源代码

# 通过 MCP Market 安装
# 或手动克隆到 skills 目录
git clone https://github.com/Fission-AI/OpenSpec.git ~/.claude/skills/openspec

/opspec:propose    # 创建提案
/opspec:apply      # 应用规格
/opspec:archive    # 归档变更

评估步骤：
1. 列出规格中的所有需求点（N 个）
2. 检查代码，标记每个需求是否实现（✓ / ✗）
3. 检查是否有多余的实现（规格未要求）
4. 计算 P/R/F1

示例：
- 规格要求：10 个功能
- AI 实现：12 个功能（10 个符合规格 + 2 个额外）
- 遗漏：1 个规格功能未实现

精确率 = 10/12 = 83.3%
召回率 = 9/10 = 90%
F1 = 2 × (0.833 × 0.9) / (0.833 + 0.9) = 86.5%

# 使用测试覆盖来间接评估规格遵守
npm test -- --coverage

# 将规格点映射到测试用例
# 每个规格需求至少有一个对应测试

> 请对照 .specs/features/auth.md 规格文档，审查 src/auth/ 目录下的代码。
>
> 1. 列出规格中的每个需求点
> 2. 检查代码是否实现了该需求
> 3. 检查是否有代码超出了规格范围
> 4. 计算精确率和召回率
> 5. 标记任何偏离规格的决策

## 实现检查清单

- [ ] 用户可以用邮箱注册
- [ ] 用户可以用手机号注册
- [ ] 密码强度验证（≥8位，含数字和字母）
- [ ] 重复密码校验
- [ ] 注册成功后跳转到登录页
- [ ] 注册失败显示错误提示

> ❌ 不要实现：第三方登录、邮箱验证、手机验证码

┌─────────────────────────────────────────────────────────────────┐
│                     Query 执行主链路                              │
│                                                                 │
│  消息原始历史                                                      │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────┐                    │
│  │ 层 0：工具结果预算压缩 (Budget Compression) │ ← 最先执行        │
│  │  大于 200K chars 的工具结果持久化到磁盘      │                  │
│  └────────────────────────────────────────┘                    │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────┐                    │
│  │ 层 1：微压缩 (Microcompact)               │                  │
│  │  time-based 或 cached 两条路径            │                  │
│  └────────────────────────────────────────┘                    │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────┐                    │
│  │ 层 2：上下文折叠 (Context Collapse)        │ ← 特性门控，可选   │
│  └────────────────────────────────────────┘                    │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────┐                    │
│  │ 层 3：自动深压缩 (Auto-Compact)           │                  │
│  │  触发条件：剩余 tokens < 13,000            │                  │
│  │  执行顺序：先 session memory，再 full compact│                 │
│  └────────────────────────────────────────┘                    │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────┐                    │
│  │ 层 4：API 侧 context_management          │                  │
│  │  native compaction 触发阈值：75% of window│                  │
│  └────────────────────────────────────────┘                    │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────┐                    │
│  │ 层 5：手动压缩 (/compact 命令)             │ ← 用户触发        │
│  │  full compact 或 partial compact         │                  │
│  └────────────────────────────────────────┘                    │
│       │                                                         │
│       ▼                                                         │
│  callModel() → queryModelWithStreaming()                         │
└─────────────────────────────────────────────────────────────────┘

当前消息列表
      │
      ▼
有 compact boundary？
      │
    ──┼──
    是│    否│
      │      └── 使用完整历史
      ▼
只保留 boundary 之后的活动上下文
      │
      ▼
工具结果超过 200K chars？
      │
    ──┼──
    是│    否│
      │      │
      ▼      ▼
  持久化到磁盘  原样保留
  替换为预览
      │
      ▼
微压缩决策
      ├── time-based：超过时间阈值的旧工具结果清理
      └── cached：依赖 API cache_editing 机制
      │
      ▼
剩余 token < 13,000？
      │
    ──┼──
    是│    否│
      │      └── 跳过深压缩
      ▼
有 session memory 文件？
      │
    ──┼──
    是│    否│
      ▼      ▼

session-memory  full compact（生成完整摘要）
compact

# 在长对话中，当感觉 Claude 开始"忘事"时
> /compact

# 压缩后 Claude 会生成一个对话摘要
# 后续继续基于摘要进行

> /cost
# 显示当前会话的 token 使用量和预估费用
# 接近上限时会有警告

# 开始一个专注于特定任务的新会话
> /clear  # 清空历史，重新开始

┌─────────────────────────────────────────────────────────┐
│                   插件系统三层模型                         │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Layer 1: Intent（意图层）                         │  │
│  │  settings.json 中声明 enabledPlugins               │  │
│  │  extraKnownMarketplaces, blockedMarketplaces       │  │
│  └────────────────────────┬──────────────────────────┘  │
│                           │                             │
│                           ▼                             │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Layer 2: Materialization（物化层）                │  │
│  │  ~/.claude/plugins/cache/{marketplace}/{plugin}/   │  │
│  │  known_marketplaces.json                           │  │
│  │  installed_plugins.json                            │  │
│  └────────────────────────┬──────────────────────────┘  │
│                           │                             │
│                           ▼                             │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Layer 3: Active Runtime（激活层）                 │  │
│  │  commands / skills / agents / hooks / MCP / LSP    │  │
│  │  接入当前会话运行时                                  │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

my-plugin/
├─ .claude-plugin/
│  └─ plugin.json          # 必需：插件清单
└─ commands/
   └─ hello.md             # 一个命令

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的第一个插件",
  "commands": ["commands/"],
  "skills": ["skills/"],
  "agents": ["agents/"]
}

# 必需字段
description: "命令的简短说明（Claude 用这个判断何时激活）"

# 工具访问控制
allowed-tools: Read, Grep, Glob, Bash

# 用户输入
argument-hint: "<文件路径>"        # 输入框占位符
arguments:                          # 复杂参数定义
  - name: path
    description: 要分析的路径
    required: true

# 触发控制
user-invocable: true               # 是否允许用户用 /命令 触发
when_to_use: "用户要审查代码时"     # 更详细的触发时机说明

# 模型控制
model: sonnet                      # 指定使用的模型
effort: low                        # 任务复杂度（low/medium/high）
disable-model-invocation: false    # 是否禁止模型调用（纯脚本命令）

# 执行控制
shell: true                        # 是否可执行 shell 命令
version: "1.0.0"                   # 命令版本

# 命令内容（Markdown 格式）

高优先级
    │
    ▼
session-only 插件（--plugin-dir / SDK inline）
    │
    ▼
marketplace 插件（已安装）
    │
    ▼
built-in 插件（内置）
    │
    ▼
低优先级

1. 本地开发
   mkdir my-plugin && cd my-plugin
   mkdir -p .claude-plugin commands skills
        │
        ▼
2. 测试（session-only 模式，不需要发布）
   claude --plugin-dir ./my-plugin
   # 在会话中测试命令和技能
        │
        ▼
3. 调试
   /reload-plugins    # 重载插件（修改后生效）
   claude --debug     # 查看详细加载日志
        │
        ▼
4. 发布（可选）
   # 创建 .claude-plugin/marketplace.json
   # 上传到 marketplace
        │
        ▼
5. 安装
   /plugin marketplace add <marketplace-url>
   /plugin install my-plugin@my-marketplace

┌─────────────────────────────────────────────────────────────┐
│                   Agent 协议生态                              │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  MCP（Model Context Protocol）                       │   │
│  │  by Anthropic                                        │   │
│  │  定位：模型 ↔ 工具连接层                               │   │
│  │  解决：如何给模型提供外部工具和数据访问能力              │   │
│  │  传输：stdio / SSE / HTTP                            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  ACP（Agent Communication Protocol）                 │   │
│  │  by IBM / Linux Foundation                           │   │
│  │  定位：Agent ↔ Agent 通信层                           │   │
│  │  解决：不同 Agent 框架之间如何互操作                    │   │
│  │  传输：REST / WebSocket                              │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  A2A（Agent-to-Agent Protocol）                      │   │
│  │  by Google                                           │   │
│  │  定位：企业级 Agent 协作层                              │   │
│  │  解决：企业内部多 Agent 系统的编排和信任机制            │   │
│  │  传输：gRPC / HTTP/2                                 │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

你的 Claude Code 会话
        │
        ├── [原生支持] MCP 工具服务器
        │       ├── GitHub MCP
        │       ├── Notion MCP
        │       └── 你的自定义 MCP
        │
        └── [通过 MCP 桥接] ACP / A2A Agent
                ├── MCP 服务器作为 ACP 网关
                └── 调用远程 Agent，返回结果

用户请求："分析这个 PR 并生成测试用例"
        │
        ▼
主 Claude 会话（Task Coordinator）
        │
        ├── SubAgent 1: PR 代码审查专家
        │       └── 调用 GitHub MCP 获取 PR diff
        │
        ├── SubAgent 2: 测试生成专家
        │       └── 基于 PR 代码生成测试用例
        │
        └── SubAgent 3: 安全扫描专家
                └── 调用安全扫描 MCP 工具
        │
        ▼
主会话综合三个 SubAgent 的结果
        │
        ▼
调用 GitHub MCP 创建 PR Comment 和新的测试文件

# 下载 MSI 安装包或便携版
# https://github.com/farion1231/cc-switch/releases

brew tap farion1231/ccswitch
brew install --cask cc-switch

paru -S cc-switch-bin

# 下载 .deb 或 .AppImage
# https://github.com/farion1231/cc-switch/releases

mkdir github-analyzer
cd github-analyzer
claude

> /superpowers:brainstorm

我想创建一个命令行工具，输入 GitHub 仓库 URL，
输出一份项目概览报告（Markdown 格式），包含：
- 项目结构
- 主要技术栈
- 核心模块说明

Claude: 好的，在开始设计之前，我想确认几点：

1. 这个工具是给自己用还是需要发布给其他人？
2. 需要支持私有仓库吗？
3. 报告需要包含依赖分析吗？
4. 你偏好什么编程语言？

> 看起来不错，继续

Claude: 好的，我来生成详细的实现计划...

## 实现计划

### 任务 1：初始化项目结构
文件：package.json, tsconfig.json, src/index.ts
...

### 任务 2：实现 GitHub API 客户端
文件：src/github/client.ts
...

### 任务 3：实现目录结构分析器
文件：src/analyzer/structure.ts
...

> /superpowers:execute-plan

Claude: 开始执行计划...

[任务 1/6] 初始化项目结构
- 创建 package.json ✓
- 创建 tsconfig.json ✓
- 创建 src/index.ts ✓
- 测试通过 ✓

[任务 2/6] 实现 GitHub API 客户端
- 先写测试...
- 测试失败 (预期) ✓
- 实现代码...
- 测试通过 ✓
...

Claude: 所有任务完成！所有测试通过。

你想如何处理这个分支？
1. 合并到 main
2. 创建 GitHub PR
3. 保留分支
4. 放弃

> 2

Claude: 正在创建 PR...
PR 已创建：https://github.com/you/github-analyzer/pull/1

> /plan

创建一个 GitHub 仓库分析工具...

Claude: 这是我的计划：
1. 初始化 Node.js 项目
2. 添加必要的依赖（@octokit/rest, commander 等）
3. 实现 GitHub API 调用逻辑
4. 实现目录结构分析
5. 实现 Markdown 报告生成
6. 添加 CLI 入口

批准这个计划吗？

> 批准

Claude: 开始执行...
（逐步完成每个步骤）