Claude Code

Claude Code 是 Anthropic 开发的一款命令行 AI 编码助手，设计哲学是”低层次、无偏见”（intentionally low-level and unopinionated），提供接近原始模型能力的访问，不强制特定工作流程。它既是一个强大的开发工具，也是 Agent 工程实践的典型案例。

核心架构

单一主循环设计

Claude Code 的核心逻辑建立在**一个单一的主循环（Query Loop）**之上。与层层嵌套的多代理对话树不同，所有历史消息都被维护在一个扁平的消息列表中。

用户输入 → 系统提示词组装 → 工具列表组装 → API 调用 → 工具执行 → 循环判断

这种设计让 Claude Code 成为一个极简的纯 Agent 运行时，而非复杂的框架。

Prompt Caching：命脉级基础设施

Claude Code 团队将 Prompt Caching 视为与服务器 uptime 同级别的核心指标（../sources/2026-05-04-Claude-Code-Prompt-Caching即一切）。核心原则：“Cache rules everything around me.”

缓存机制：API 从请求第一个字节开始前缀匹配，完全一致才能命中缓存。命中时节省约 90% 成本。

七条铁律：

提示词顺序 = 账单顺序：静态系统指令 + 工具定义（全局）→ CLAUDE.md（项目级）→ 会话上下文（会话级）→ 对话消息（动态，放最后）。越稳定越靠前
别碰系统提示词：修改 = 缓存前缀分裂 = 缓存红利归零。解法：用 <system-reminder> 标签在消息流中注入动态信息。系统提示词是承重墙，消息流是家具
换小模型反而更贵：Opus 的缓存 Haiku 不认。解法：父 Agent 整理 hand-off message，子 Agent 只读交接文档而非完整历史
不增减工具：工具定义在系统提示词前缀中，增减 = 缓存报废。Plan Mode 设计为两个工具本身（EnterPlanMode/ExitPlanMode），工具定义纹丝不动
工具延迟加载：轻量占位符（工具名 + defer_loading: true），模型通过 tool search 按需发现完整定义。前缀永远稳定
Compaction 用 Fork：用完全相同系统提示词+工具定义的子请求做总结，前缀完全共享，缓存全部命中
缓存命中率 = SEV：实时监控告警，掉几个百分点直接触发 SEV（与服务器宕机同级）

核心反直觉原则：连续性 > 模型单价。几乎所有直觉做法（换便宜模型、增减工具、改系统提示词）都会炸缓存。

系统提示词的动态组装

系统提示词不是固定文本，而是由多个模块动态拼接而成，精心设计以命中 Anthropic API 的 Prompt Caching（命中时节省约 90% 成本）：

静态段落（缓存友好，几乎不变）：

身份和角色定义
工具使用指南（优先用 Read 不用 cat，优先用 Edit 不用 sed）
编码哲学（不过度工程、不提前抽象）
语气风格（简洁直接、不用 emoji）

动态段落（每轮刷新）：

当前目录、git 分支、最近提交
CLAUDE.md 的内容和 MEMORY.md
MCP 工具描述
Hook 指令
输出风格配置

工具列表按字母顺序排列：这不是随意决定，而是为了保持 prompt cache 稳定性——顺序变了缓存就失效。

四层记忆系统

层级	机制	作用
1	CLAUDE.md	静态配置，项目/用户/全局规则，手动维护
2	MEMORY.md	自动维护的跨会话笔记，由子代理在后台更新
3	Session Memory	面向当前会话的运行摘要，记录当前任务进度
4	上下文压缩	Micro 压缩（清工具返回值）+ 标准压缩（API 生成摘要）

权限系统

Claude Code 有多层权限检查流水线：

否决规则 → 询问规则 → 工具自身权限 → 模式决策 → Hook 一票否决

权限模式从严到宽：plan → default → acceptEdits → auto → dontAsk → bypassPermissions

Bash 命令的风险评估通过 LLM 实时判断（非硬编码规则），能理解语义（如”删除 node_modules 再重装”虽含 rm 但属合理操作）。

Ecosystem Tools

Simon Willison 的 Claude Code Transcripts 将 Claude Code CLI 会话转换为可读、可分享、可归档的静态 HTML，补强 AI 编程记录的知识资产化。

Deep Research / Dynamic Workflows

Claude Deep Research Architecture 补充了 Claude Code 作为 Harness 的一个新层级：当任务超过单会话/单 Agent 的编排能力时，Claude 可以先写一段 JavaScript workflow script，由后台 runtime 管理循环、分支、中间状态和 subagent fan-out，主会话只接收最终报告。

与 Claude.ai Research 的 Lead Agent 动态调度相比，Claude Code /deep-research 更偏“代码化编排”：

状态外置：中间结果留在脚本变量和 workflow run state，不挤占主上下文。
大规模 fan-out：从多个研究角度并行搜索、抓取来源、交叉验证。
对抗式验证：独立 agent 对 claim 做 cross-check / survival vote，通过多来源一致性筛掉弱结论。
可观测后台执行：通过 /workflows 查看阶段、agent 数、token 和各 agent 发现。

关键启示：Claude Code 的 Harness 不只是工具调用循环，也可以把“重复、可审计、可扩展”的复杂任务下沉到代码化 workflow 中。

CLAUDE.md 最佳实践

CLAUDE.md 是 Claude Code 的核心配置机制，Claude 在每次对话开始时自动读取。

文件位置优先级

~/.claude/CLAUDE.md — 全局生效（所有项目）
项目根目录 CLAUDE.md — 项目级（推荐 git 管理，团队共享）
CLAUDE.local.md — 本地个人偏好（.gitignore 排除，不同步）
子目录 CLAUDE.md — 子目录级覆盖

从根目录向当前目录遍历，越靠近当前位置的文件优先级越高。

内容建议

CLAUDE.md 适合包含：

常用 bash 命令和工具
代码风格指南
测试指令
项目环境设置说明
分支命名、合并策略等仓库规范

关键原则（Karpathy 四原则）：

编码前先思考：不假设，明确权衡，不确定时先提问
简单优先：只写解决问题所需的最少代码，不做预先扩展
外科手术式修改：只改必要部分，每行修改可追溯到用户请求
目标驱动执行：定义成功标准，循环验证直到达成

指令精炼原则：过多规则会稀释注意力权重。一个只有 4 条原则的 CLAUDE.md，比 50 条规则的效果更好，因为每条获得 25% 注意力而非 2%。

使用 `#` 键快速更新

在对话中按 # 键，可以直接向 Claude 提供应写入 CLAUDE.md 的指令，Claude 会自动将内容写入相关文件。

Hooks 系统

Claude Code Hooks 是用户定义的 shell 命令，在生命周期的各节点执行，提供确定性控制（非依赖 LLM 选择）。

四种 Hook 类型

Hook	触发时机	典型用途
PreToolUse	工具执行前	安全检查、阻止危险操作
PostToolUse	工具执行后	自动格式化、运行 lint
Notification	需要注意时	发送通知（手机推送等）
Stop	任务完成时	清理、提交 git

示例：自动格式化 Python 文件

[[../entities/Claude-Code]]
event = "PostToolUse"
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py"]
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

Hooks 在 Harness Engineering 中的地位

Hooks 是 Harness 的”确定性约束层”。把质量控制从”依赖模型判断”变为”机械执行”，这是 Harness Engineering 的核心理念之一——约束比指令更可靠。

双 Agent 架构

Anthropic 官方提出的长时任务解决方案：Initializer Agent + Coding Agent 双 Agent 架构。

为什么需要双 Agent

单 Agent 在长时任务中容易出现：

过于激进，一口气写大量代码然后爆上下文
误判完成，看到部分成果就宣布任务结束

核心问题不在模型能力，而在缺乏跨上下文继承任务逻辑的结构化方式。

Initializer Agent（首席架构师）

第一次运行，奠定工程基础：

将用户需求分解为 JSON 格式的功能清单（含描述、步骤、验收条件，全标记未完成）
创建状态记录机制（progress 文件 + git 仓库）
生成标准化启动脚本（init.sh）

Coding Agent（迭代工程师）

每一轮只做一件事，但把它做好：

检查目录结构、git 记录、progress 文件、运行 init.sh
从功能清单选一个未完成功能
实现、端到端测试（如用 Puppeteer 驱动浏览器）
写回 "passes": true、git commit、更新 progress 文件

这种模式将”无人监督的长时任务”转换为”每轮可验证的开发迭代”。

工具与技能（Tools vs Skills）

工具（Tool）：模型可以直接调用的函数

Read、Edit、Write、Bash、Grep、Glob 等
以 API tools 参数发送，模型通过 tool_use 调用

技能（Skill）：能力增强模块，本质是可执行的提示词模板

触发方式：斜杠命令 /commit 或模型自动匹配自然语言
技能不能发明新工具，但可以组合调用工具
支持三级优先级：用户私有 > 项目级 > 默认技能

多 Claude 工作流

多实例协作

最强大的模式之一是并行运行多个 Claude 实例：

Git Worktrees：轻量级多分支隔离，每个 worktree 独立运行 Claude
多检出：3-4 个独立文件夹，各自处理不同任务
双 Claude 审查：一个写代码，另一个独立审查（不同上下文避免盲点）

无头模式（Headless Mode）

claude -p 将 Claude Code 集成到 CI/CD 或自动化流程中：

# 扇出模式：批量处理
claude -p "migrate foo.py from React to Vue. Return OK or FAIL." --allowedTools Edit Bash
 
# 管线模式：集成现有流程
claude -p "<your prompt>" --json | your_command

终端生态工具

Claude Code 的用户倾向于「一切在终端内完成」。以下工具填补了终端工作流的关键空白，保护心流（flow）：

Yazi — 终端文件管理器

Rust 编写的 TUI 文件管理器，支持图片/视频/PDF 实时预览，视频时间轴拖拽（J/K 前进后退），退出自动 cd 到目标目录。安装后 Finder 使用率降低 80%+。详见 ../sources/2026-05-05-yazi：终端里的文件管家，给重度 Claude Code 用户。

ai-translate — 终端内翻译技能

stormzhang 开源的翻译 Skill，/t word 两字符触发翻译，无需 API Key（复用 Claude / GPT），Context Fork 模式极低 token 消耗。适配 Claude Code、Codex、Cursor 等。详见 ../sources/2026-05-05-我开源了一个 AI 轻量翻译工具。

Claude Code Transcripts — 会话记录转 HTML

Simon Willison 开源工具，将 JSON/JSONL 会话文件转为静态 HTML 页面，支持一键 Gist 分享。详见 ../sources/2025-12-30-开源推荐 Claude Code Transcripts。

官方课程：Claude Code in Action

Anthropic 官方推出的 15 模块课程（约1小时视频），覆盖上下文管理、自定义命令、MCP、GitHub 整合、Hook 开发等。课程地址：https://anthropic.skilljar.com/claude-code-in-action。详见 ../sources/2025-07-24-Anthropic官方课程推荐掌握Claude Code加速开发工作流：上下文管理、自动化命令、MCP与GitHub整合等。

这些工具的组合形成了完整的终端工作台：Claude Code 处理代码与命令，yazi 处理文件浏览，ai-translate 处理语言障碍，Transcripts 处理知识归档。核心价值在于注意力不被中断。参见 Terminal-Ecosystem-Tools。

Explore-Plan-Code-Commit

让 Claude 读相关文件（不写代码）
让 Claude 制定计划（使用”think hard”触发深度思考）
让 Claude 实现方案
让 Claude 提交并创建 PR

TDD 工作流

让 Claude 写测试（明确 TDD 模式，避免 mock 实现）
确认测试失败
提交测试
让 Claude 写通过测试的代码
提交代码

上下文管理技巧

使用 /clear 在任务间重置上下文
使用 Escape 中断当前操作并重定向
使用 # 快速更新 CLAUDE.md
对复杂任务使用 Markdown 检查清单作为工作便签

远程工作模式

Claude Code 不仅可以在本地终端使用，还可以通过 tmux 等工具实现远程接管：

tmux + Bridge 模式

将 Claude Code 放入 tmux 后台会话，通过 bridge 中间件（如飞书 bridge) 实现手机远程控制：

完整保留上下文：MCP tools、自定义 skills、持久记忆不丢失
实时卡片推送：思考过程、工具调用、文字回复同步到飞书
权限审批：危险操作（删文件、git push）需手机端批准
无人值守：bridge 崩溃自动重启，Claude Code 退出自动 resume

与新开 API 会话不同，bridge 模式是”遥控器”而非”新 Agent”——你接管的是同一个 session，昨晚聊到哪，今天继续从哪开始。

2026 Agentic Coding 八大趋势

来自 Anthropic 官方报告的预测：

SDLC 彻底改变：工程师角色从”写代码”变为”编排 AI Agent”
单体 Agent → 协同战队：多 Agent 系统、编排者 + 专家 Agent
长时运行 Agent：任务跨度从分钟扩展到数天（案例：7小时完成 vLLM 特性开发，准确率 99.9%）
扩展人类监督：AI 学会识别何时需要人类判断，AI 审查 AI 生成代码
扩展到新领域：COBOL/Fortran 传统语言支持，非技术人员可编程
生产力收益重塑经济：TELUS 节省 50 万小时，发布速度提升 30%
非技术用例蔓延：销售、法律、运营团队自建工具
双刃剑：安全防御与攻击同步升级

[2026-07-25] 生产级批量 Harness、Skills 工程化与 Opus 4.8（新增综合）

本节综合本批次新摄入来源，补充 Claude Code 作为生产级评测/批量基础设施与 Skills 工程化两个维度。

生产级批量 Harness 与成本可观测性

Production-Grade Batch Harness on Claude Code 把 Claude Code 从交互工具改造为批量评测基础设施：

入口：claude -p 无头模式 + Agent SDK query()，脱离 TUI 跑成百上千个评测任务（呼应上文”无头模式”，但用途从 CI/CD 扩展到批量评测）。
Hooks 的 exit 2 杠杆：hook 返回 exit 2 可阻断流程并把信息回灌模型——是上文”确定性约束层”的具体强化控制点。
Initializer + Coding Agent 长任务架构：即上文”双 Agent 架构”在批量评测场景的应用，分离规划与执行以改善长任务上下文稳定性。
Subagents 隔离与并行：.claude/agents/*.md 定义专职子智能体做并行评测与上下文隔离。
成本可观测性：OpenTelemetry / Langfuse 记录 token/成本/延迟，prompt caching 显著降本——成本是生产级 harness 的一等公民。

Agent Harness 综述（71 页）从学术视角印证：harness 可抽象为规划器 + 记忆 + 工具接口 + 编排器 + 评测反馈环五组件；Claude Code 的 prompt caching / compact / hooks / subagents 正是这套抽象的成熟工程实现。综述强调 trace 可观测性是调试与评测的前提。

Skills 工程化：从手工艺到可治理资产

Skills 深度研究提出 8 类分类法与核心原则：Skill = Context Engineering（渐进式暴露）、Gotchas > Instructions、Description = 路由规则、先传播后审批。
企业实施与治理指南把 skill 升级为可治理企业资产（版本/owner/审批/权限/registry/ROI 度量），并采用 agentskills.io 开放标准（2025-12-18）避免厂商锁定。
专家知识蒸馏模板提供”专家隐性知识 → SKILL.md + references”的标准化生产流程。
2026 最火 Skills 评测（PDF/XLSX/Frontend-Design/Skill-Creator/Superpowers）与 ai-native-startup-coach.skill 是 skill 的成品实例；后者展示阶段路由 + 魔鬼代言人机制。详见 Agent-Skills 主题页。

Opus 4.8 与定价

Opus 4.8 研究给出 $5/$ 25 定价、编码/Agent/诚实度代际提升，背景为 Anthropic $965B 估值 /$ 65B H 轮。⚠️ 一个安全回归：prompt-injection 鲁棒性受影响率从 4.7 的 6.0% 升至 9.6%——能力增强不等于安全增强。Claude Code 作为 Opus 的主要变现场景，其能力与安全性直接受底层模型影响。

源码架构概览

基于 51 万行 TypeScript/Bun 源码的分析：

消息生命周期：

用户输入 → REPL.tsx(onSubmit) → 图片处理(imagePaste.ts) → 
系统提示词组装(getSystemPrompt) → 工具列表(assembleToolPool) → 
查询循环(queryLoop) → StreamingToolExecutor → 权限检查 → 
工具执行 → 记忆提取 → 响应渲染

关键设计决策：

工具分 isConcurrencySafe（可并行）和串行两类
stop_reason 字段被认为不可靠，通过检测 tool_use 块判断是否继续
压缩阈值约为 context - 13000 buffer tokens（200K 模型约在 167K 触发）
子代理模式：压缩、记忆提取等管理操作通过子代理完成，共享父对话的 prompt cache

10xAI Wiki

导航