Command → Agent → Skill 架构

Command → Agent → Skill 三层架构关系

用户输入 / 命令触发
       │
       ▼
┌──────────────┐    Command（入口）
│  /command    │    .claude/commands/*.md
└──────┬───────┘
       │ Agent 工具
       ▼
┌──────────────┐    Agent（执行者）
│  Agent       │    .claude/agents/*.md
└──────┬───────┘
       │ 预加载/调用 Skill
       ▼
┌──────────────┐    Skill（知识）
│  Skill       │    .claude/skills/*/SKILL.md
└──────────────┘复制

三者对比

三者的关系与使用场景

Harness 为什么重要

Harness 的 10 项核心能力

"Skills、Commands、Subagents 都最终变成 prompt，所以强 prompt 就够了？"——技术上对，实践上错。以下是 Harness 在 prompt 无法触达的层面做的事：

用户输入: "写一个递归 flatten 函数"        ← (a) ~6 tokens

模型实际看到的:                            ← (b) ~15,000 tokens
  ├── CLAUDE.md (项目规范)
  ├── 匹配的 .claude/rules/*.md (paths 触发)
  ├── 模块化系统提示片段 (110+)
  ├── 工具定义
  ├── 环境上下文 (cwd, git status, 平台)
  ├── 前几轮对话历史
  ├── 通过 Read/Grep 读取的文件
  └── 用户的 6 token 请求复制

Subagents 子代理

5 种内置类型

自定义代理 Frontmatter（16 字段）

Commands 命令系统（82 内置）

Claude Code 内置 82 个斜杠命令，按功能分为 11 类。自定义命令放在 .claude/commands/*.md。

Orchestration 编排实战

Weather Reporter 完整编排流程动画

用户: /weather-orchestrator
       │
       ▼
┌──────────────────────────┐
│  weather-orchestrator    │  ← Command（入口）
│  1. 询问温度单位 C/F     │
│  2. 调用 weather-agent   │
│  3. 调用 svg-creator     │
└──────┬───────────────────┘
       ▼
┌──────────────────────────┐
│  weather-agent           │  ← Agent
│  预加载: weather-fetcher │  ← Skill（预加载）
└──────┬───────────────────┘
       ▼
┌──────────────────────────┐
│  weather-svg-creator     │  ← Skill（调用）
│  输出: weather.svg       │
└──────────────────────────┘复制

Tasks 任务系统

Claude Code 内置的任务跟踪系统，支持创建、查询、更新、依赖管理。可与 Subagents 和 Skills 配合使用。

4 个核心工具

任务生命周期

pending → in_progress → completed
                 ↘ deleted复制

依赖关系

• addBlocks — 标记"此任务完成后，指定任务才能开始"
• addBlockedBy — 标记"此任务必须等待指定任务完成后才能开始"
• 形成 DAG（有向无环图），确保执行顺序

Skills 技能系统

技能存放在 .claude/skills/<name>/SKILL.md，支持自动发现和触发。每次会话启动时，Claude 扫描所有可用技能的 description 字段来决定是否匹配当前任务。

9 种配置模式

2 种加载模式

9 种用途分类

来自 Anthropic 内部数百个技能的实践归纳（Thariq, 2026.03）。好的技能只属于其中一类；跨越多类的技能通常需要拆分。

16 个 Frontmatter 字段

10 个内置技能

Hooks 钩子系统

生命周期事件驱动的自动化脚本。配置在 .claude/settings.json 或 Agent frontmatter 中。

4 种 Hook 类型

27 个生命周期事件

按功能分组。所有事件均支持 async、timeout 选项。

配置示例

Hooks 配置写在 Settings 中，也可通过 Skill frontmatter 按需激活。

{
  "hooks": {
    "Stop": [{
      "type": "command",
      "command": "python3 .claude/hooks/scripts/hooks.py --event Stop"
    }],
    "PostToolUse": [{
      "type": "command",
      "command": "python3 .claude/hooks/scripts/hooks.py --event PostToolUse"
    }]
  }
}复制

高级工具使用

Prompt-to-Code (PTC) — 范式转换

传统方式将大量指令塞入 system prompt，而 PTC 将这些指令编译为可执行的代码规则，由模型在沙箱中运行。结果是：prompt 变短、推理更精确、token 节省约 37%。

{
  "type": "code_execution_20250825",
  "name": "data_processor",
  "allowed_callers": ["code_execution_20250825"],
  "input_schema": {
    "type": "object",
    "properties": {
      "task": { "type": "string" }
    }
  }
}复制

PTC 高级模式

PTC 约束

Dynamic Tool Filtering — 动态筛选

Web Search / Web Fetch 结果由代码预处理后再进入上下文，而非原文塞入。需启用 beta header anthropic-beta: code-execution-web-tools-2026-02-09。

Tool Search — 工具搜索

将不常用的工具标记为 defer_loading: true，需要时由模型按需搜索加载，工具定义量减少约 85%。

// 工具定义示例
{
  "name": "specialized_analyzer",
  "defer_loading": true,
  "description": "..."
}

// Claude Code 环境变量
ENABLE_TOOL_SEARCH=auto:5  // 保留 5 个常用工具，其余延迟加载复制

Tool Use Examples — 使用示例

在工具定义中添加 input_examples 数组（1-5 个），提供真实数据样本，模型调用准确率从 72% 跃升至 90%。

{
  "name": "query_database",
  "input_examples": [
    { "sql": "SELECT * FROM users WHERE active = true LIMIT 10" },
    { "sql": "SELECT COUNT(*) FROM orders WHERE date > '2026-01-01'" }
  ]
}复制

Claude Code 中的可用性

Settings 5 层优先级

Managed Settings 交付方式

核心配置项

托管层内部优先级

托管层内按此顺序使用（只用一个来源，不跨层合并）：

权限模式

在 Settings 中通过 permissions 键配置。

工具权限语法

路径前缀

匹配规则

• 复合命令：&&、||、;、| 等操作符分割后，每个子命令独立匹配。Bash(safe-cmd *) 不覆盖 safe-cmd && other-cmd
• 通配符位置：* 可出现在前缀、后缀或中间。Bash(* install) 匹配 npm install；Bash(git * main) 匹配 git push main
• 词边界：Bash(ls *)（有空格）不匹配 lsof；Bash(ls*)（无空格）两者都匹配
• 符号链接：allow 要求符号链接和目标都在允许目录内；deny 命中任意一个即拒绝
• 进程包装器：timeout、time、nice、nohup 匹配前被剥离。watch、find -exec 始终提示

全局 vs 项目配置

6 大配置维度对比

目录结构对比

~/.claude/                          .claude/
├── settings.json      ← 全局设置    ├── settings.json      ← 团队共享
├── settings.local.json               ├── settings.local.json ← 个人覆盖
├── CLAUDE.md          ← 全局指令    ├── CLAUDE.md          ← 项目指令
├── mcp.json           ← 全局 MCP    ├── agents/            ← 子代理定义
├── agents/            ← 全局代理    │   ├── reviewer.md
│   ├── explorer.md                   │   └── coder.md
│   └── researcher.md                 ├── skills/            ← 技能定义
├── skills/            ← 全局技能    │   ├── lint-check/
│   └── deploy-check/                 │   │   └── SKILL.md
├── commands/          ← 全局命令    │   └── test-runner/
│   └── review.md                     │       └── SKILL.md
├── plans/             ← 计划文件    ├── commands/          ← 自定义命令
├── tasks/             ← 任务持久化  │   └── commit.md
├── memory/            ← 自动记忆    ├── rules/             ← 条件规则
└── plugins/           ← 插件安装    │   ├── tests.md
                                      │   └── security.md
                                      └── mcp.json           ← 项目 MCP复制

6 大设计原则

全局独有功能

• allowedPlugins / deniedPlugins — 插件白/黑名单
• managedSettings — IT 部署的组织级配置
• autoUpdatesChannel — 更新通道控制
• cleanupPeriodDays — 会话自动清理
• pluginRegistry — 自定义插件源
• plansDirectory — 计划文件全局目录
• autoMemoryEnabled — 记忆系统开关

CLAUDE.md 规范

CLAUDE.md 是 Claude Code 中影响最大的单项配置。一个结构良好的 CLAUDE.md 比任何 Settings 调优都更能改善输出质量。

4 种载体

.claude/rules/ 条件加载

写作指南

• 保持在 200 行以内——超出会降低遵从度
• 写 WHY 而非 WHAT——代码已经说明了 WHAT，写隐藏约束、微妙不变量、特定 bug 的变通方案
• 使用否定式指令更有效——"不要使用 X 模式" 比 "使用 Y 模式" 更明确
• 不要写代码能自行表达的显而易见的内容——CLAUDE.md 的价值在于将 Claude 推出默认思维模式
• 不要保存代码模式、架构快照、git 历史等可从代码推导的信息
• 包含项目特有的约束：构建顺序依赖、已知不兼容的库版本、特殊的部署流程

claudeMdExcludes 排除

使用 claudeMdExcludes 设置跳过不需要的 CLAUDE.md 文件：

{
  "claudeMdExcludes": [
    "**/vendor/**/CLAUDE.md",
    "**/node_modules/**/CLAUDE.md"
  ]
}复制

Monorepo 加载机制

CLAUDE.md 在 Monorepo 中的加载机制（Boris Cherny 原图）

场景对比

假设 monorepo 结构：frontend/CLAUDE.md、backend/CLAUDE.md、api/CLAUDE.md、根目录 CLAUDE.md。

场景 1：从根目录启动 cd /mymonorepo && claude

场景 2：从组件目录启动 cd /mymonorepo/frontend && claude

Memory 自动记忆

Claude Code 的自动记忆系统跨会话持久化信息。记忆文件存储在项目 .claude/ 目录或全局 ~/.claude/ 中，以 YAML frontmatter + Markdown 格式组织。

4 种记忆类型

记忆文件结构

每条记忆是一个独立的 Markdown 文件，使用 YAML frontmatter：

---
name: feedback-testing
description: 测试偏好和纠正记录
metadata:
  type: feedback
---

集成测试必须使用真实数据库，不使用 mock。
**Why:** 上季度因 mock/生产环境不一致导致迁移失败。

[[testing-patterns]]  ← 链接到相关记忆复制

MEMORY.md 索引

所有记忆通过 MEMORY.md 索引文件管理，控制在 200 行以内。索引每行格式：

- [标题](文件名.md) — 一行摘要复制

什么不应该保存

• 代码模式、架构、文件路径——可从代码推导
• Git 历史、近期变更——git log 是权威来源
• 调试解决方案——修复在代码中，上下文在 commit message
• CLAUDE.md 已覆盖的内容
• 临时性任务细节——用 Task 或 Plan 管理

配置

Agent Memory 3 种作用域

与 Subagents 配合，Memory 可在代理间持久化知识。

MEMORY.md 索引文件控制在 200 行以内。

MCP 服务

常用 MCP 服务

MCP 设置 Key

配置示例

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-context7"]
    },
    "always-on-server": {
      "type": "http",
      "url": "https://mcp.example.com",
      "alwaysLoad": true
    }
  }
}复制

关键特性

环境变量展开

在 .mcp.json 中可使用 ${ENV_VAR} 语法引用环境变量，避免硬编码敏感信息：

{
  "mcpServers": {
    "my-api": {
      "url": "https://mcp.example.com/mcp?token=${MCP_API_TOKEN}"
    }
  }
}复制

RPI 工作流

Research → Plan → Implement，每阶段有验证门。基于 Subagents 编排多个代理角色。

Step 1: RESEARCH   → RESEARCH.md（GO / NO-GO）
Step 2: PLAN       → PLAN.md + pm.md + ux.md + eng.md
Step 3: IMPLEMENT  → IMPLEMENT.md（分阶段，每阶段有测试门）复制

8 种代理角色

3 个命令

rpi/{feature-slug}/
├── REQUEST.md              # 功能描述
├── research/RESEARCH.md    # GO/NO-GO 分析
├── plan/
│   ├── PLAN.md             # 实施路线图（3-5 阶段）
│   ├── pm.md               # 产品需求文档
│   ├── ux.md               # UX 设计稿
│   └── eng.md              # 技术规格
└── implement/IMPLEMENT.md  # 实施记录（每阶段验证）复制

CRISPY 方法论

C — Clarify      明确需求
R — Research     技术调研
I — Ideate       构思方案
S — Structure    结构设计
P — Plan         制定计划
Y — Yield        产出实施
  + Iterate      迭代优化复制

跨模型协作（Claude + Codex）

Claude Code (Opus) + Codex CLI (GPT) 跨模型 4 步协作流程

STEP 1: PLAN          Claude Code Opus · Plan Mode
STEP 2: QA REVIEW     Codex CLI GPT · 审查计划，插入发现
STEP 3: IMPLEMENT     Claude Code Opus · 逐阶段实施
STEP 4: VERIFY        Codex CLI GPT · 对照计划验证复制

Agent Teams

Agent Teams 多代理协作流程

通过共享 任务列表（TaskCreate/TaskUpdate）实现多 代理 协调。适合可分解为独立子任务的大型重构。

团队协调模式

以 Time Orchestration 为例——三个角色并行构建，共享数据契约 {time, timezone, formatted}：

Agent Teams 组件清单

---
name: time-agent
description: 获取迪拜当前时间（Asia/Dubai, UTC+4）
tools: Bash
model: haiku
color: blue
maxTurns: 3
skills: time-fetcher
---
使用 Bash 执行 `TZ='Asia/Dubai' date`，返回 time/timezone/formatted 三字段。复制

---
description: 获取迪拜时间并生成 SVG 时间卡片
model: haiku
---
1. Agent(time-agent) → 获取 {time, timezone, formatted}
2. Skill(time-svg-creator) → 生成 SVG 卡片
注意：必须顺序执行，不能并行。复制

---
name: time-fetcher
description: 通过 bash 获取迪拜当前时间
user-invocable: false
---
命令: TZ='Asia/Dubai' date '+%Y-%m-%d %H:%M:%S %Z'
返回格式: { time: "HH:MM:SS", timezone: "GST (UTC+4)", formatted: "完整输出" }复制

---
name: time-svg-creator
description: 创建迪拜时间 SVG 卡片
allowed-tools: Write, Read
---
接收 time/timezone/formatted，生成自包含 SVG 卡片。
输出: agent-teams/output/dubai-time.svg + output.md复制

定时任务

# CronCreate 参数
cron: "*/5 * * * *"     # 标准 5 字段 cron（本地时区）
prompt: "检查 CI 状态"   # 触发时执行的提示
recurring: true          # true=循环, false=一次性
durable: true            # true=持久化到文件复制

Goal 目标驱动

配合 任务系统 自动分解和跟踪进度。

1. 用户设定目标
2. Claude 分解为子任务并创建任务列表
3. 逐步实施，每步更新状态
4. 遇到阻塞请求用户输入

社区 Goal 技巧

Session 管理

LLM 性能退化分析

LLM 输出质量的日常波动

9 层推理栈（权重冻结 ≠ 行为冻结）

┌──────────────────────────────────────────────┐
│  用户会话上下文                  ← 会话内退化    │
│  System Prompt                  ← 定期更新      │
│  Post-Training (RLHF/微调)      ← 可静默更新    │
│  采样参数 (temperature/top-p)   ← 可服务端调    │
│  Speculative Decoding (草稿模型) ← 质量波动      │
│  MoE 路由 / 批次组合             ← ±8-14% 方差   │
│  硬件路由 (TPU/GPU/Trainium)    ← 不同故障模式  │
│  量化级别 (FP16/INT8/INT4)      ← 负载下可能变化 │
│  编译器 & 运行时 (XLA:TPU/CUDA) ← 已证实有 bug  │
├──────────────────────────────────────────────┤
│  模型权重（冻结）← 这层不会变                    │
└──────────────────────────────────────────────┘复制

关键结论

Anthropic 2025.9 事后分析：3 个基础设施 Bug

Bug #1 — 上下文窗口路由错误

Bug #2 — TPU 输出损坏

Bug #3 — XLA:TPU 编译器错误编译（最棘手）

MoE 路由方差（Scale AI 研究）

MoE（混合专家）架构中，批次中其他用户的查询组合决定了你的请求被路由到哪些专家——而这个组合是非确定性的。

具体案例：同一模型在越狱抗性测试中一天得分 77%，第二天 63%——14 个百分点波动，零 bug、零变更。

系统提示 & 后训练更新

Stanford 研究（2023）——及其争议

Chen/Zaharia/Zou 的标志性研究发现 GPT-4 在"判断质数"任务上准确率从 97.6% 跌至 2.4%（2023.3→6），但存在方法论问题：

• 3 月版本用 temperature 0.0，6 月版本用 temperature 1.0——根本性混淆变量
• 每个任务仅 500 次查询——样本量太小
• "数学问题"实际是判断题，模型猜测模式改变而非数学能力下降
• 变化可能是有意的后训练安全更新，而非无意退化

心理学因素

Codex 5.3 对比分析

当 Claude 短期退化时，Codex 5.3 可能看起来明显更好，原因：

1. 产品目标契合 — Codex 专为代码生成优化，即使同等模型强度也能产出更好编码结果
2. 推理策略差异 — 各 provider 独立调优延迟/推理深度/解码默认值
3. 服务路径分离 — 不同路由层/编译器/发布管道，一个出问题不影响另一个
4. 发布时机 — 一个 provider 中途发布，另一个稳定，可造成大的临时质量分歧

退化假设排序

实践建议

1. 可用时锁定模型快照（而非使用浮动别名）
2. 存储请求元数据（模型 ID、参数、延迟、错误率）
3. 运行固定每日 canary 测试，回归时报警
4. 多次失败后重置或压缩长会话
5. 保留备用 provider/模型路径
6. 在内部看板中分离"模型质量"和"服务可靠性"

Harness 重要性

常见误解：skill/command/subagent/hook 最终都是 prompt，所以写好 prompt 就够了。这是错的。在工程实践层，Harness 是 prompt 构建系统 + 确定性执行系统 + 上下文架构系统。

Harness 10 大能力（prompt 无法复制）

浏览器 MCP 对比

推荐工作流

# 安装命令
npx playwright install
claude mcp add playwright -s user -- npx @playwright/mcp@latest
claude mcp add chrome-devtools -s user -- npx chrome-devtools-mcp@latest复制

Monorepo 技能发现

Skills 的发现/加载机制与 CLAUDE.md 不同：CLAUDE.md 向上遍历目录树（ancestor loading），Skills 通过嵌套目录自动发现（descendant discovery），且仅在编辑对应目录中的文件时才按需加载。参见 Monorepo 加载机制。

Skills 标准位置

CLAUDE.md vs Skills 加载对比

• 通用工作流放根目录 .claude/skills/
• 包级特定 skill 放对应包的 .claude/skills/
• 危险操作 skill 设置 disable-model-invocation: true
• 用包名前缀避免混淆（如 frontend-review、backend-deploy）

使用量与限额

监控命令

成本优化

• 简单任务用 model: haiku
• effort: low 降低推理
• Background agent 避免阻塞
• API key 用户用 --max-budget-usd 控制成本
• 配置 extra-usage 设置月度消费上限避免意外费用

Spinner 动词

Claude Code 的加载动画使用 179 个随机动词。常见的有：

学习路径

从零构建 Weather Reporter 的完整学习旅程，经历 5 大阶段 · 37 张幻灯片：

阶段顺序（按认知依赖重排）

LEVELS 映射（6 个等级）

const LEVELS = {
  context:     '🔴 上下文窗口',   // context-window.jpeg, context.jpg
  claude_md:   '🟠 CLAUDE.md',   // 项目指令系统
  agents:      '🟡 代理系统',     // 内置 + 自定义代理
  skills:      '🟢 技能系统',     // Skills 体系
  commands:    '🔵 命令系统',     // Commands 编排
  workflow:    '🟣 完整工作流'    // 端到端整合
}复制

37 张幻灯片大纲

资源复用

重设计记账

• goToSlide() 目标：所有 37 处调用需更新新序号
• data-level 属性：每张幻灯片的等级标记需映射到 LEVELS
• 导航组件：上/下页按钮需绑定新的幻灯片顺序
• 进度条：5 段进度指示器对应 5 个阶段

SDK vs CLI 系统提示词

Claude Code CLI 和 Agent SDK 使用不同的系统提示词策略：

核心差异

Billion Dollar Questions

来自社区的 13 个尚未解答的深度问题——如果你有答案，这就是价值十亿美元的洞察。

记忆与指令（4 题）

1. CLAUDE.md 到底该写什么？——什么该放，什么不该放？
2. 已有 CLAUDE.md，还需要 constitution.md 或 rules.md 吗？
3. 多久更新一次 CLAUDE.md？如何判断它已过时？
4. 为什么 Claude 仍会忽略 CLAUDE.md 中的指令——即使用了 MUST 全大写？

代理、技能与工作流（6 题）

1. 何时用 Command vs Agent vs Skill——何时原生 Claude Code 更好？
2. 随着模型升级，agents/commands/workflows 多久更新一次？
3. 通用型 vs 角色/功能专用型子代理——详细 persona 是否真的提升质量？
4. 该用 Claude Code 内置 plan mode，还是自建规划命令/代理来强制团队工作流？
5. 个人 skill 和社区 skill 如何共存？冲突时谁优先？
6. 终极问题：能否将现有代码库转为 spec，删除代码，然后让 AI 仅从 spec 重新生成？

规范与文档（3 题）

1. 仓库中的每个功能都应该有 spec 文件吗？
2. spec 多久更新一次才不会过时？
3. 实现新功能时，如何处理对其他功能 spec 的连锁影响？

Boris Cherny — 13 条法则

Boris Cherny — Claude Code 核心工程师

15 个隐藏功能

来自 Boris Cherny（Meta）的 15 个鲜为人知的 Claude Code 功能，每个都能显著改变使用方式。

12 个定制技巧

10 个进阶技巧

代码审查技巧

PR 统计（Boris Cherny 实测）

2 条合并技巧

6 条 Opus 4.7 效率技巧

Boris Cherny 在 Opus 4.7 发布后总结的 6 条核心效率提升方法。

Thariq — 技能设计

Thariq — 实战技巧

Session 管理 — 深度指南

Thariq 的深度 Session 管理框架：理解上下文退化、分支策略、子代理垃圾回收。

5 种分支策略

关键决策表

83 条分类技巧

来自社区实践和官方推荐，按 16 个类别整理。核心参见：CLAUDE.md 规范、Subagents 并行、RPI 工作流。

视频精选

Boris Cherny × Ryan Peterman

Claude Code 创作者的职业生涯故事 入门

Boris Cherny × Lenny's Podcast

Claude Code 的诞生与产品哲学 产品

Karpathy × AI Engineer

从 Vibe Coding 到 Agentic Engineering 进阶

Matt Pocock Workshop

2 小时 Claude Code 实战教学 教学

常用命令（82 个内置）

CLI Flags（16 类）

完整 CLI 启动参数 速查，按功能分类。

环境变量

配置模板

# 项目名称

## 技术栈
- 前端：React + TypeScript
- 后端：Node.js + Express

## 编码规范
- 文件命名：kebab-case
- 组件：函数式 + hooks
- 测试：Vitest

## 约束
- 不要使用 any 类型
- 不要跳过测试
- API 必须错误处理复制

{
  "permissions": {
    "allow": ["Bash(npm run *)","Bash(git status)","Read","Grep","Glob"],
    "deny": ["Bash(rm -rf *)","Bash(git push --force)"]
  }
}复制

---
name: my-agent
description: 执行特定任务
tools: "Bash,Read,Write,Edit,Grep"
model: sonnet
maxTurns: 20
memory: project
---

# My Agent
1. 读取相关文件
2. 分析代码
3. 实施变更
4. 验证结果复制

---
name: my-skill
description: 做什么
arguments: filename
allowed-tools: "Read,Write,Edit"
paths: "src/**/*.ts"
---

处理 $filename：
1. 读取 → 2. 转换 → 3. 写回复制

工作流速查