Command → Agent → Skill 架构

Command → Agent → Skill 三层架构关系

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

Command

用户入口。编排 Agent 调用顺序。内置 82 个命令，支持自定义扩展。

Agent

独立上下文的执行者。可并行。 5 内置 自定义

Skill

可复用指令包。被加载或调用。 10 内置 自定义

三者对比

💡 决策指引：需要编排多步骤、串联多个 Agent → Command。需要独立上下文、并行执行、工具隔离 → Agent。需要可复用的指令包、在多个场景被加载 → Skill。

三者的关系与使用场景

Harness 为什么重要

ℹ️ 输出质量公式：质量 = f(有效上下文, 模型能力, 迭代循环) Harness 直接影响”有效上下文”和”迭代循环”。

Harness 的 10 项核心能力

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

用户输入 vs 模型实际看到的（点击展开）

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

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

**输出质量取决于 (b)，而非 (a)。**Harness 构建 (b)。“强 prompt” 无法复制 (b)，因为大部分不是用户写的。

Subagents 子代理

5 种内置类型

自定义代理 Frontmatter（16 字段）

展开全部 16 个字段

Commands 命令系统（82 内置）

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

查看全部 82 条命令详细说明

Auth 认证（5）

Config 配置（15）

Context 上下文（7）

Debug 调试（7）

Export 导出（2）

Extensions 扩展（9）

Memory 记忆（1）

Model 模型（6）

Project 项目（7）

Remote 远程（10）

Session 会话（13）

💡 自定义命令：放在 .claude/commands/*.md，支持 16 个 frontmatter 字段（name、description、argument-hint、arguments、context 等）。用 !command“ 注入动态上下文。

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（有向无环图），确保执行顺序

ℹ️ 环境变量：CLAUDE_CODE_TASK_LIST_ID 标识当前任务列表，文件持久化在 ~/.claude/tasks/。

Skills 技能 & Hooks 钩子可复用的指令包 + 生命周期事件的自动化脚本

Skills 技能系统

ℹ️ 核心认知：Skill 是一个文件夹（不只是 Markdown 文件）。可以包含脚本、数据、资源文件、配置模板——任何 Agent 可以发现、读取和操作的东西。SKILL.md 是入口，但不是全部。参见 Orchestration 实战示例。

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

渐进式信息加载

在 SKILL.md 中告诉 Claude 文件夹里有什么文件，它会在需要时才读取详细内容。避免一次性加载所有信息浪费上下文。

description 是给模型看的

description 字段不是摘要，而是触发条件描述。写清楚”什么情况下应该使用这个技能”，Claude 据此自动匹配。

9 种配置模式

2 种加载模式

预加载模式（Agent Skills）

通过 Agent 的 skills: 字段加载。Agent 启动时自动注入。

调用模式（Invoked Skills）

通过 Skill 工具或 /skill-name 触发。Claude 也可自动匹配调用。

9 种用途分类

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

9 条技能设计建议（Thariq）

• 别说显而易见的事 — Claude 已经知道很多，聚焦于改变其默认行为的信息
• 建一个 Gotchas 节 — 最高信号内容，从常见失败点中积累
• 用文件系统做渐进式加载 — 告诉 Claude 文件夹里有什么，它会按需读取
• 避免强制定路线 — 给目标和约束，不要给步骤
• 想清楚 Setup — 用 config.json 存配置，未设置时让 Claude 用 AskUserQuestion 询问
• description 是给模型看的 — 写”何时触发”而非”做什么”
• 用 Agent Skills 做复杂流程 — 预加载到 Agent，隔离上下文
• Skills 可以引用其他 Skills — 但避免循环依赖
• 持续迭代 — 从失败案例中提取 Gotchas，更新技能

16 个 Frontmatter 字段

展开完整列表

10 个内置技能

Hooks 钩子系统

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

4 种 Hook 类型

💡 **Agent Frontmatter 限制：**Agent 中只能使用 6 个 Hook 事件：PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、Stop、SubagentStop。其他 21 个事件仅在主会话中可用。

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%。

PTC 配置示例

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

PTC 高级模式

批量处理

单次 PTC 调用中循环处理多条记录，减少工具调用次数。适合批量翻译、批量分类等场景。

提前终止

在代码中加入条件判断，满足阈值时立即 return 跳过剩余处理。避免不必要的计算。

条件选择

根据输入类型动态选择不同的处理分支，而非为每种类型单独定义工具。

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 中的可用性

💡 **CLI 用户优先级：**先在 CLAUDE.md 中配置 Tool Use Examples 和 Tool Search（ENABLE_TOOL_SEARCH=auto:5），这两项对 CLI 用户收益最大。PTC 和 Dynamic Filtering 主要面向 SDK/API 深度集成场景。

配置体系与记忆系统：5 层配置优先级 · CLAUDE.md 规范 · 自动记忆 · MCP 扩展

Settings 5 层优先级

Managed Settings 交付方式

核心配置项

80+ Settings 完整列表（点击展开）

⚠️ Deny 规则始终最高——任何层级的 deny 都会覆盖所有 allow。数组类设置跨层级合并去重，不替换。

托管层内部优先级

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

托管层专用策略 Key（点击展开）

ℹ️ v2.1.126 变更：/config 现在将修改持久化到 ~/.claude/settings.json，不再仅存于内存。通过交互式 Config UI 做的编辑重启后保留。

权限模式

在 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 项目配置

全局 ~/.claude/

settings.json 全局设置 CLAUDE.md 所有项目指令 适合：个人偏好、通用配置、Shell 别名

项目 .claude/

settings.json 团队共享（已提交） settings.local.json 个人覆盖（git-ignored） CLAUDE.md 项目指令 agents/ 子代理定义 skills/ 技能定义 commands/ 自定义命令

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/ 条件加载

有 paths: frontmatter

仅在操作匹配路径时延迟加载。适合框架特定的规则，如 paths: ["src/**/*.test.ts"] 只在编辑测试文件时加载。

无 frontmatter

每次会话都加载，效果等同 CLAUDE.md。适合全项目通用的规则。

写作指南

• 保持在 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 原图）

向上加载（Ancestor）

启动时向上遍历，立即加载所有 CLAUDE.md。立即加载

向下加载（Descendant）

子目录 CLAUDE.md 在操作该目录时才加载。延迟加载

场景对比

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

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

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

💡 **最佳实践：**共享约定放根 CLAUDE.md，组件特有指令放组件 CLAUDE.md。个人偏好用 CLAUDE.local.md（git-ignored）。

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
    }
  }
}

关键特性

alwaysLoad（v2.1.121）

在服务器配置中设 "alwaysLoad": true，该服务器的所有工具立即加载而非延迟发现。仅用于每轮都需要的小型工具集。

热重载（v2.1.139）

/mcp 的 Reconnect 操作重新读取 .mcp.json，无需重启会话。同时注入 CLAUDE_PROJECT_DIR 到 stdio 服务器环境。

环境变量展开

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

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

⚠️ workspace 是保留的 MCP 服务器名称（v2.1.128），用户定义的同名服务器会被跳过并记录警告。

💡 OAuth 兼容的服务器自动完成认证（遵循 RFC 9728），无需手动配置 apiKeyHelper。

开发工作流RPI · CRISPY · 跨模型协作 · Agent Teams · 自动化

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      迭代优化

ℹ️ CRISPY 是 RPI 的进化版，增加了 Ideate 和 Structure 阶段，强调方案设计比实施更重要。

跨模型协作（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 · 对照计划验证

💡 **核心思路：**不同模型互相审查。Codex 追加 “Codex Finding” 标注，不重写原计划。

Agent Teams

Agent Teams 多代理协作流程

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

团队协调模式

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

Agent Teams 组件清单

time-agent 定义

---
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 三字段。

time-orchestrator 命令

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

time-fetcher Skill

---
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: "完整输出" }

time-svg-creator Skill

---
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 目标驱动

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

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

社区 Goal 技巧

• 让 Agent 自己提议 Goal — 先描述问题背景，再让 Agent 提出合适的目标，通常比手写目标更精准
• 让 Agent 起草 /goal 提示 — Agent 更了解自己的能力边界，写出的 goal prompt 更可行
• /goal 条件式目标 — 如 /goal 所有测试通过且无 lint 错误，Agent 会持续工作直到条件满足
• Goal + TaskCreate 联动 — Goal 拆解为 TaskCreate 任务列表，每完成一个标记 done

Session 管理

⚠️ Context Rot 在 ~300-400k 时开始出现。回退 > 纠正。

深度报告LLM 性能分析 · 工具对比 · 使用量 · 学习路径

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 编译器错误编译（最棘手）

⚠️ Claude 运行在三种不同硬件平台（AWS Trainium、NVIDIA GPU、Google 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 可能看起来明显更好，原因：

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

退化假设排序

实践建议

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

💡 **最重要的一条：**感觉质量下降时用 /compact 或重新开始会话。这是你能做的最有效的单一操作——大多数”Claude 变笨了”是上下文污染，而非模型退化。

Harness 重要性

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

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

💡 输出质量 = f(有效上下文, 模型能力, 迭代循环)。用户只控制有效上下文的极小部分，harness 控制其余部分以及整个迭代循环。强 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

💡 Playwright token 效率最高（剩余 186.3k），Chrome DevTools 最低（剩余 181k）。差距 ~5.3k tokens。

Monorepo 技能发现

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

Skills 标准位置

CLAUDE.md vs Skills 加载对比

ℹ️ 字符预算默认 15,000 字符，可通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量调整。用 /context 检查是否有 skill 因超限被排除。

• 通用工作流放根目录 .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 设置月度消费上限避免意外费用

⚠️ Fast Mode（/fast）从第一个 token 起就计入 extra usage，不消耗订阅计划的包含额度。必须启用并充值 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 张幻灯片大纲

展开全部幻灯片内容

Agents 阶段（Slides 1-7）

• 什么是 Agent？— 代理 = 模型 + 工具 + 上下文
• 5 种内置代理类型 — general-purpose / Explore / Plan / statusline-setup / claude-code-guide
• 代理 Frontmatter — 16 个字段详解
• model 选择 — inherit / haiku / sonnet / opus 的取舍
• 工具控制 — tools vs disallowedTools
• 权限模式 — acceptEdits / plan / bypassPermissions
• Weather Agent 设计 — 天气代理实战

Skills 阶段（Slides 8-15）

• 什么是 Skill？— 技能 = 提示词模板 + 元数据
• 技能触发 — 自动（PROACTIVELY）vs 手动（/skill-name）
• Frontmatter 字段 — name / description / tools / model
• weather-fetcher 技能 — 从 API 获取天气数据
• weather-analyzer 技能 — 分析天气趋势
• 技能组合 — 多技能协同工作
• 技能测试 — 验证技能输出质量
• 技能最佳实践 — 编写可复用技能

Context 阶段（Slides 16-22）

• 上下文窗口 — 200K tokens 的边界
• 上下文压缩 — 自动摘要机制
• Memory 系统 — user / project / local 三级
• MEMORY.md 索引 — 持久化记忆管理
• CLAUDE.md 注入 — 上下文加载策略
• 资源复用 — context-window.jpeg / context.jpg
• 上下文窗口可视化 — 理解 token 分配

CLAUDE.md 阶段（Slides 23-29）

• 什么是 CLAUDE.md？— 项目级指令文件
• 三级加载 — global / project / local
• 编写规范 — 结构化指令写法
• 环境配置 — 开发环境约定
• 代码风格 — 项目代码规范
• 安全规则 — 敏感操作约束
• Weather Reporter 的 CLAUDE.md — 实战案例

Commands 阶段（Slides 30-37）

• 什么是 Command？— 命令 = 编排层
• 命令 vs 技能 vs 代理 — 三层架构对比
• weather-orchestrator — 天气编排命令
• 命令流程 — prompt → steps → output
• 动态上下文注入 — !command“ 语法
• 错误处理与重试 — 健壮性设计
• 端到端整合 — Agents + Skills + Commands
• 回顾与展望 — 从零到完整的 Weather Reporter

资源复用

重设计记账

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

ℹ️ 从简单开始 → 逐步组合 → 完整编排。不要一开始就搭建复杂架构。阶段顺序按认知依赖重排：先理解”谁”（Agents），再理解”能做什么”（Skills），再理解”环境”（Context），再定”规则”（CLAUDE.md），最后”编排”（Commands）。

SDK vs CLI 系统提示词

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

Agent SDK

• 基础提示词约 ~269 tokens
• 极简引导，高度可定制
• modular 类型支持自定义系统提示词
• 110+ 系统提示词字符串可选
• 适合构建自定义代理应用

CLI 模式

• 系统提示词包含完整工具定义
• 预装 Bash/Read/Write/Edit 等工具描述
• CLAUDE.md 自动注入
• 包含安全规则和行为约束
• 开箱即用，无需配置

核心差异

💡 SDK 提供了 modular 提示词类型，可以逐个添加工具描述，比 CLI 的全量加载节省大量 tokens。

Billion Dollar Questions

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

记忆与指令（4 题）

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

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

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

规范与文档（3 题）

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

⚠️ 这些问题的答案决定了 Agentic Engineering 的最佳实践走向。如果你有见解，这就是前沿。

专家经验：Boris Cherny · Thariq · 社区最佳实践

Boris Cherny — 13 条法则

Boris Cherny — Claude Code 核心工程师

• 写好 CLAUDE.md——投入产出比最高的优化
• 200 行以内——超过则遵循度下降
• 否定式指令——“不要做 X” 更有效
• 手动 /compact——50% 时主动压缩
• 先规划再实施——复杂任务用 /plan
• 子代理并行——无依赖任务同时派出
• 明确指定模型——简单 haiku，复杂 opus
• 回退 > 纠正——/undo 比事后修复可靠
• 信任代码阅读——不需要手动粘贴代码
• Hooks 自动化——重复操作用钩子
• CLAUDE.local.md——个人偏好不污染团队
• Rules 做条件加载——paths 限定范围
• /doctor 诊断问题——出问题先跑 /doctor

15 个隐藏功能

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

• Claude 移动端 App — iOS/Android 可作为 Claude Code 的语音+文本入口，通勤时也能与代码对话
• Teleport（远程控制） — claude --teleport 或 remote-control MCP，从浏览器/手机远程控制本地终端会话
• /loop 与 /schedule — 设定循环任务或定时唤醒：让 Agent 持续监控、周期执行（如每 5 分钟检查 CI）
• Hooks 自动化 — settings.json 配置 PreToolUse/PostToolUse/Stop 等事件钩子，实现自动通知、校验、格式化
• Cowork Dispatch — 多 Agent 协同调度，不同 Agent 各自独立工作、互不干扰
• Chrome 扩展 — Claude in Chrome MCP，让 Agent 直接操作浏览器、读取 console 日志、截图对比
• Desktop Web Server — Claude 桌面版内嵌 Web 服务器，Agent 可直接访问本地开发页面
• /branch Fork — 一键从当前对话 fork 到新分支，保留完整上下文，实验失败可丢弃
• /btw 旁路查询 — 在不中断主流程的情况下提出临时问题，答案注入当前上下文
• Git Worktree 并行 — /batch 扇出多个 worktree，每个独立分支处理不同任务
• --bare SDK 加速 — SDK 模式去掉交互 UI，纯函数调用，速度提升显著
• --add-dir 多仓库 — 同时加载多个项目目录到同一会话，跨仓库操作
• --agent 自定义提示 — 命令行直接指定 Agent 类型或自定义系统提示
• /voice 语音输入 — 通过麦克风语音下达指令，自动转文字
• Background Agent — 后台长任务不阻塞主会话，完成后自动通知

12 个定制技巧

• 自定义子代理 — .claude/agents/*.md，YAML frontmatter 定义工具/模型/记忆
• 自定义命令 — .claude/commands/*.md，可带 $ARGUMENTS 参数化
• 自定义技能 — .claude/skills/*/SKILL.md，description 决定自动发现
• Hooks 自动化 — settings.json 配置生命周期钩子（PreToolUse/PostToolUse/Stop）
• Rules 条件加载 — .claude/rules/*.md + paths: 限定范围
• 权限模板 — allowed-tools 按工具+路径粒度控制
• Model 选择 — 简单 haiku，复杂 opus，平衡 sonnet
• Effort 调节 — low 快速响应，max 深度推理
• Memory 作用域 — user（全局）/ project（团队）/ local（个人）
• MCP 集成 — 连接外部工具（数据库、浏览器、API）
• Worktree 隔离 — --worktree 或 isolation: "worktree" 独立实验
• Background 任务 — 长任务后台运行，完成后通知

10 个进阶技巧

• Plan Mode 先规划 — 复杂任务先用 /plan，给出目标而非步骤
• Agent 并行编排 — 无依赖任务同时派出，利用上下文隔离
• Skills 渐进披露 — description 始终加载，完整内容按需加载
• 上下文预算 50% — 主动 /compact，保持在智能区
• code-reviewer 做一致性检查 — 交叉验证跨文件逻辑
• 迭代式精炼 — 优于一次完美，逐步逼近目标
• Error Recovery 先 /undo — 回退比修复更可靠
• Testing First — TDD 红绿重构与 AI 结合
• 文档即上下文 — 好文档 = 好输出，注释写 WHY 不写 WHAT
• 监控上下文用量 — /context 可视化检查 token 分布

代码审查技巧

💡 Test Time Compute：Code Review 让模型在独立上下文中”再想一遍”，输出量增加 200%。多 Agent 并行审查（安全 + 性能 + 架构）比单次审查质量更高。

• effort: high 获得更全面审查，effort: low 少而准
• 让 AI 扮演**“对手”角色**——提出反对意见，而非表面审查
• PR 提交前自动触发（Hooks PreToolUse 配置）
• 配合 --comment 添加 PR 评论
• 审查范围：正确性、安全漏洞、代码质量、项目规范
• 不同 Agent 扮演不同角色（安全审查 vs 性能审查 vs 架构审查）

PR 统计（Boris Cherny 实测）

ℹ️ Boris 约 100% 新代码由 AI 编写，人类负责审查和指导方向。关键是每个文件独立 commit，历史更清晰。

2 条合并技巧

• 逐文件提交 — 每个文件独立 commit，历史更清晰、易 review/revert
• 不要 amend — 创建新 commit 保留历史，避免覆盖预提交钩子检查

6 条 Opus 4.7 效率技巧

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

• Auto Mode（Shift+Tab） — 一键切换全自动模式，Agent 自主决定读写、执行操作，无需逐步确认
• /fewer-permission-prompts Skill — 预设技能，自动配置常用工具权限，大幅减少弹窗中断
• Recaps 摘要 — 每轮对话后 Agent 自动生成执行摘要，保持上下文清晰
• Focus Mode（/focus） — 过滤无关输出，只显示核心决策和结果，适合长时间任务
• Effort Level — low 快速响应（简单查询）、medium 默认、high 深度推理（代码审查）、xhigh/max 极致深度（架构设计）
• Verification 模式 — 后端：自动启动服务器验证；前端：Chrome 扩展检查渲染；桌面：Computer Use 自动化 UI 测试

💡 Auto Mode 最佳实践：配合 effort: high 和 /focus 使用，让 Agent 在高推理深度下自主工作，只汇报关键决策点。

Thariq — 技能设计

• 单一职责——每个 Skill 只做一件事
• 描述要精确——决定自动发现准确度
• 善用 when_to_use——降低误触发
• 参数化模板——arguments 动态替换
• 路径限定——paths 避免无关激活
• progressive disclosure——渐进加载

Thariq — 实战技巧

17 Mar 技巧

• /doctor 诊断环境
• CLAUDE.md 写约束
• haiku 省成本
• background 长任务
• disallowedTools 限制危险操作

16 Apr 技巧

• Session 管理 > Skill 设计
• 50% 时 /compact
• /undo > 手动修复
• 拆分为独立子代理
• 每个 < 50% 上下文

Session 管理 — 深度指南

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

⚠️ Context Rot（上下文腐烂）：约 300k-400k tokens 时模型开始”遗忘”早期对话，输出质量显著下降。这不是 bug，而是注意力的数学特性。

5 种分支策略

关键决策表

💡 Compact vs Fresh：如果对话历史高度相关（如调试链），用 compact + brief；如果话题已完全转向，clear 后从 CLAUDE.md 重建上下文更高效。Bad compact 的典型原因：压缩指令模糊导致关键约束被丢弃。

83 条分类技巧

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

Prompting 提示（3 条）

• 给目标非步骤 — 告诉 Claude 你想要什么结果，而非每步怎么做
• 否定式指令更有效 — “不要做 X” 比 “请做 Y” 更可靠
• 示例驱动 — 提供输入/输出示例，比抽象描述更准确

Planning 规划（7 条）

• 复杂任务先用 /plan，给出目标而非详细步骤
• 拆分为独立子任务，每个 < 50% 上下文
• 使用 TaskCreate 跟踪进度，设置依赖关系
• Plan Mode 应清晰描述期望，让模型自主规划路径
• 多轮迭代优于一次完美——逐步逼近目标
• 优先级排序：先核心后边缘，先阻塞后独立
• 估算上下文消耗，避免单任务过大

Context 上下文（5 条）

• /compact 在 50% 上下文时主动压缩
• 可用 /compact [聚焦指令] 保留关键信息
• 上下文预算管理——长对话中定期清理
• --resume / --continue 恢复历史会话
• 好文档 = 好输出，注释写 WHY 不写 WHAT

Session 会话（6 条）

• Session 管理比 Skill 设计更重要——长会话更智能
• 50% 时 /compact，避免质量退化
• /undo > 手动修复——回退比事后纠正更可靠
• 拆分为独立子代理，每个 < 50% 上下文
• --continue 无缝继续上次会话
• maxTurns 限制子代理轮次，防止无限循环

CLAUDE.md（8 条）

• 写好 CLAUDE.md 是投入产出比最高的优化
• 200 行以内——超过则遵循度下降
• 否定式指令——“不要做 X” 更有效
• CLAUDE.local.md 个人偏好不污染团队
• 只写模型无法自行推断的信息
• .claude/rules/*.md + paths: 条件加载
• claudeMdExcludes 排除不需要加载的 CLAUDE.md
• 4 级载体：全局 / 项目 / 目录 / 个人

Agents 代理（4 条）

• 自定义子代理 .claude/agents/*.md，YAML frontmatter 定义工具/模型/记忆
• 子代理并行——无依赖任务同时派出
• context: fork 隔离子代理上下文，防止污染主对话
• 明确指定模型——简单 haiku，复杂 opus

Commands 命令（3 条）

• .claude/commands/*.md 自定义命令
• $ARGUMENTS 参数化——命令模板动态替换
• /project:命令名 调用项目命令

Skills 技能（9 条）

• 单一职责——每个 Skill 只做一件事
• description 精确——决定自动发现准确度
• 善用 when_to_use——降低误触发
• progressive disclosure——渐进加载内容
• paths 限定——避免无关激活
• arguments 参数化模板——动态替换
• forceLoadSkills 强制加载——关键技能预加载
• disallowedTools 限制——技能级工具控制
• 9 种类型选对——skill/agent/Explore/code-simplifier 等

Hooks 钩子（5 条）

• PreToolUse 在工具执行前拦截和修改
• PostToolUse 在工具执行后触发自动化
• Stop 在会话结束时执行清理
• PR 提交前自动触发代码审查
• 重复操作用钩子——格式化、lint、通知等

Workflows 工作流（5 条）

• RPI 循环：Research → Plan → Implement
• CRISPY：Context → Research → Identify → Structure → Plan → Y-execution
• 跨模型协作：Claude 规划 + Codex/Gemini 执行
• Agent Teams：多 Agent 并行（Amp, Codex, Claude）
• Scheduled Tasks：CronCreate 定时调度自动执行

Advanced Workflows 进阶工作流（9 条）

• Background Agent 不阻塞主会话
• Worktree 隔离实验——独立分支 + 上下文
• Goal 目标驱动——设定目标让模型自主达成
• Session 管理 > Skill 设计——长会话策略优先
• Browser MCP 自动化测试——Playwright 或 Chrome DevTools
• Multi-Provider 多云部署——Bedrock/Vertex/Foundry
• Sandbox 沙盒隔离——网络白名单 + 文件系统限制
• Agent SDK 构建自定义 Agent——Python/TS SDK
• Computer Use GUI 交互——操控桌面应用

Git / PR（5 条）

• 逐文件提交——每个文件独立 commit
• 不要 amend——创建新 commit 保留历史
• --comment 自动添加 PR 评论
• 141 PRs / 45K 行 / 全部 squash merge
• Code Review 200% 输出增加——Test Time Compute

Debugging 调试（6 条）

• /doctor 诊断环境问题——出问题先跑这个
• /undo 回退操作和代码变更
• context: fork 隔离实验——安全试错
• maxTurns 限制轮次——防止无限循环
• effort: low 快速诊断——提高效率
• /context 可视化检查 token 分布

Utilities 工具（5 条）

• disallowedTools 禁止特定工具——安全边界
• MCP Server 连接外部服务——数据库/API/浏览器
• allowedTools 预批准工具——减少确认
• includeContext 注入额外文件——丰富上下文
• env 环境变量注入——统一配置

Daily 日常（2 条）

• 键盘快捷键 — Escape 中断、Shift+Tab 切换模式
• 定期 /compact — 50% 上下文时主动压缩

视频精选

🎬 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 实战教学 教学

Boris × Lenny’s Podcast — Claude Code 的诞生与 100% AI 编码时代

• Claude Code 诞生于内部黑客马拉松，从简单 CLI 演变为 Anthropic 核心产品
• **“潜在需求”（Latent Demand）**是产品成功的核心——降低门槛后需求自然爆发
• Claude Code 中约 100% 新代码由 AI 编写，人类负责审查和指导方向
• Plan Mode 应给出清晰目标而非详细步骤，让模型自主规划
• “苦涩教训”：不要为当前模型优化工作流，为 6 个月后的更强模型构建系统
• CLAUDE.md 应极简，只写模型无法自行推断的信息
• 安全层设计为多层防护：权限系统 + 确认提示 + 沙箱执行

Boris × Pragmatic Engineer — 从 Meta 到 Anthropic 的工程之旅

• Boris 职业路径从初创到 Meta E8，体现通才工程师哲学——跨领域解决问题
• Claude Code 架构刻意保持简单，用 Bash 工具替代复杂文件操作工具
• Anthropic 内部用 Agentic Search（glob/grep）完全替代 RAG
• Boris 每天提交 20-30 个 PR，使用并行 Agent 同时处理多个任务
• 代码审查时应让 AI 扮演”对手”角色，提出反对意见
• 原型文化是核心——快速构建、快速迭代、快速抛弃不适用的方案

Boris × Ryan Peterman — 从 E4 到 E8 的工程师成长

• Meta 晋升关键是寻找”潜在需求”机会——Groups、Marketplace、Dating 都是典型案例
• 侧项目（Undux ORM、TypeScript 实战手册）是技术成长的重要途径
• 通才哲学：不定义为”前端”或”后端”，要能跨领域解决问题
• Claude Code 诞生源于与 Codex 的竞争压力，极短时间内从原型到产品
• 在大型组织中，最好的影响力是通过工具和系统放大整个团队的效率
• “反搬运”（Ant-Fooding）：内部大规模使用自己的产品是发现问题的最佳方式

Boris × Y Combinator — CLI 的意外崛起与 AI Agent 拓扑

• Claude Code 选择 CLI 而非 IDE 插件是意外而非计划——CLI 的简洁性反而成为优势
• Agent 拓扑结构多样：单 Agent、并行 Agent、层级 Agent，不同任务适合不同拓扑
• 多个 Agent 的上下文窗口是不相关的（uncorrelated），这是并行执行的理论基础
• CLAUDE.md 应该极简——只写模型无法自行推断的项目特定信息
• Plan Mode 是临时工具，随着模型能力提升将不再需要专门的规划模式
• 插件生态系统由”蜂群”式开发完成——大量外部贡献者同时构建不同插件

Cat & Boris × Every — 双用工具设计与复合工程

• 双用工具：Claude Code 同时服务人类和 AI，Slash 命令是人机共用接口
• “对手 Subagent”模式：一个 Agent 提交报销，另一个扮演审计员提出质疑
• 复合工程（Compounding Engineering）：每个代码变更都让后续变更更容易
• “反发布”（Unshipping）策略：移除不常用功能比添加新功能更能提升聚焦度
• Subagent 架构让复杂任务分解为多个专注的小任务并行执行

Dex Horthy × MLOps — RPI 到 Crispy 方法论的演进

• RPI 中最常见的错误是跳过 Research 直接进入 Plan
• “阅读代码而非阅读计划”——规划之前必须先深入理解现有代码库
• 指令预算应控制在 150-200 行以内，超出后模型遵从率显著下降
• 上下文窗口分**“智能区”和”愚笨区”**——前半部分理解良好，后半常被忽略
• 垂直切片计划优于水平分层——每次交付端到端可验证的功能
• “Crispy”方法论 7 步，核心是每一步都有明确的完成标准
• 设计讨论应产出 200 行精炼计划而非 1000 行冗长文档
• “No slop in 2026” — 不要容忍 AI 生成的冗余代码和泛泛之谈
• 不要外包思考 — 你必须理解 AI 产出的每一行代码，否则无法验证
• CRISPY 方法论演进 — 从 RPI（Research→Plan→Implement）进化为更精确的 7 步流程，每步有 crispy（明确）的完成标准

Karpathy × AI Engineer — Software 3.0 与可验证性原则

• Software 1.0（手写代码）、2.0（神经网络权重）、3.0（LLM 提示词）三种范式并存
• “锯齿状智能”：LLM 在某些任务上超人类，在另一些简单任务上却犯错
• 可验证性是 AI 编码核心原则——只让 AI 做能被自动验证的任务
• Vibe Coding 适合快速原型，Agentic Engineering 适合生产代码
• “动物 vs 幽灵”框架：理解代码是可观察的”动物”还是不可捉摸的”幽灵”
• 教育理念：“外包思考，但不要外包理解”

Matt Pocock Workshop — 智能区/愚笨区、垂直切片与 TDD

• 智能区/愚笨区：上下文前半部分是高效处理区，关键指令放这里
• “Grill Me”技能：让 AI 在编码前通过问答确认它真正理解了需求
• PRD 目标文档：将需求转化为明确的”终点文档”，让 AI 知道成功标准
• 垂直切片（Tracer Bullets）：每次从 UI 到数据库的完整功能切片
• AFK Agent 循环（“Ralph Loop”）：Agent 在无人值守时持续工作的循环模式
• TDD 红绿重构与 AI：先写失败测试（红），AI 实现（绿），AI 重构优化
• 深模块 vs 浅模块：设计接口简洁的深模块，减少 AI 需理解的表面积
• Sand Castle 并行化：独立任务分配给多个 Agent，逐步叠加

速查表：常用命令 · CLI Flags · 环境变量 · 配置模板

常用命令（82 个内置）

Session（会话管理）

Model（模型）

Config（配置）

Context（上下文 & 费用）

Extensions（扩展）

Project（项目）

Remote（远程 & 自动化）

Debug & Auth

Export（导出）

子命令（终端直接运行）

CLI Flags（16 类）

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

Session Management（会话）

Model & Configuration（模型）

Permissions & Security（权限）

Output & Format（输出）

System Prompt（系统提示）

Agent & Subagent（代理）

MCP & Plugins

Directory & Workspace

Budget & Limits

Integration

Initialization & Maintenance

Debug & Settings Override

Version & Help

环境变量

启动环境变量（shell 设置）

认证 & 模型 & Provider

沙盒 & 安全 & 性能

显示 & MCP & 插件 & 遥测

配置模板

CLAUDE.md 模板

# 项目名称

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

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

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

.claude/settings.json 模板

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

Agent 定义模板

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

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

Skill 定义模板

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

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

工作流速查

RPI 工作流

• /rpi:research REQUEST.md
• 检查 GO/NO-GO
• /rpi:plan feature-name
• /rpi:implement feature-name

跨模型协作

• Claude Code Plan Mode
• Codex CLI QA 审查
• Claude Code 实施
• Codex CLI 验证

日常开发

• /plan 规划
• 确认方案
• 实施
• /code-review 审查
• /verify 验证

故障排查

• /doctor 检查
• /debug 调试
• /undo 回退
• /compact 清理