Passion8Docs
Claude Code

工作原理与扩展地图

Claude Code 的 agentic loop、模型、工具、上下文加载、执行环境、扩展能力和 5 分钟/1 小时缓存影响。

这页把官方 Overview、How Claude Code works 和 Extend Claude Code 合成一张结构图。先理解 Claude Code 怎么工作,再决定该写 CLAUDE.md、Skill、Subagent、MCP、Hook 还是 Plugin。

Claude Code 不是普通聊天窗口。它是围绕 Claude 模型的一层 agentic harness:负责加载项目上下文、暴露工具、执行命令、管理权限、保存会话,并把每一步结果反馈给模型继续决策。

#Agentic loop

Claude Code 的核心循环是三步,但真实任务会反复穿插:

阶段Claude 做什么你怎么配合
Gather context读文件、搜索符号、查看 git 状态、加载 CLAUDE.md、rules、skills 和 MCP 信息给目标、目录、日志、截图和边界
Take action编辑文件、运行命令、调用 MCP、派发 subagent、写计划或生成产物控制权限模式,及时打断错误方向
Verify results跑测试、lint、build、查看 diff、用浏览器或 GUI 验证给验收命令和失败证据

这个循环不是固定脚本。模型会根据上一轮工具结果决定下一步,可能先查代码,再改文件,再跑测试,再根据失败回头修。

#模型和工具分工

部分作用典型配置
模型理解代码、拆任务、判断下一步、解释结果/model、--model、/effort、fast mode、fallback model
工具让 Claude 真正行动,例如读文件、改代码、跑命令、访问网页、调用外部系统permissions、MCP、Hooks、tool search、sandbox
Harness负责会话、上下文、权限、工具调用、checkpoint、transcript、状态栏和 UIsettings、CLAUDE_CONFIG_DIR、~/.claude/projects

模型切换和 effort 切换会进入 prompt cache key。中途频繁 /model 或 /effort 会让 5m/1h TTL 都失去意义,因为缓存不能跨不同模型配置复用。

#内置能力地图

能力类别Claude 能做什么本地文档
文件操作Read、Edit、Write、MultiEdit、检查 diff工具参考
搜索Glob、Grep、代码结构探索、history 搜索大型代码库与 Monorepo
执行Bash、测试、构建、git、后台 Bash、Monitor交互模式与终端体验
Web 与浏览器WebFetch、WebSearch、Chrome、Computer UseChrome 与 Computer Use
外部系统MCP、Channels、GitHub、Slack、数据库、工单MCP 工具接入
自动化Headless、Routines、/loop、CI、Code ReviewHeadless 自动化

#执行入口

入口代码在哪里运行Provider 和缓存边界
Terminal CLI本机工作目录最容易接 Passion8,缓存和本地配置可控
VS Code / JetBrainsIDE 管理的 Claude Code 进程要确认 IDE 继承 Base URL、Token、代理和证书
DesktopDesktop 管理的本地或组织环境取决于登录方式和组织策略
Web / Slack / cloud reviewAnthropic 云端环境通常不继承本机 Passion8 env 和本地 prompt cache
Agent SDK你的服务启动 claude 子进程每个 worker/session 要自己规划状态、隔离和缓存

如果从本地 CLI 切到 web/cloud review,不要假设会共享 5m/1h 缓存。它们通常是不同 session、不同 provider、不同执行环境。

#上下文加载顺序

Claude Code 会自动加载多类上下文。越靠前、越稳定的内容,越容易成为 prompt cache 的可复用前缀。

来源何时加载缓存影响
System prompt 和工具定义会话开始和能力变化时最关键的缓存前缀
CLAUDE.md启动时加载当前目录及父级,子目录按需加载改后通常新会话才生效,也会改变缓存前缀
.claude/rules/会话开始或匹配文件时加载path-specific rules 可减少无关上下文
Skill 描述会话开始用于模型判断是否调用描述越多,每轮固定成本越高
Skill 正文调用或匹配时加载作为消息追加,通常不破坏旧前缀
MCP 工具名和 schemaserver 启动时或按 tool search 延迟加载工具 schema upfront 时最容易造成 miss
Hook 输出Hook 返回内容时进入上下文输出越长,后续每轮成本越高
Subagent 结果子代理总结返回主会话中间过程不占主会话上下文

不要把百科式长文都塞进 CLAUDE.md。稳定、短、每次都需要的规则放 CLAUDE.md;偶尔用到的参考资料放 Skill;外部系统接 MCP;必须强制执行的规则放 Hook 或 permissions。

#扩展选择

你遇到的问题用什么为什么
Claude 总是忘记构建命令或目录约定CLAUDE.md每个会话都要知道
某个流程经常重复,但不是每次都用Skill按需加载,可用 /skill-name 调用
一个规则只对某些目录或文件类型有效.claude/rules/降低根 CLAUDE.md 噪音
需要访问 Jira、Slack、数据库、浏览器、内部 APIMCP外部系统连接和认证由 server 管理
需要让 Claude 自动格式化、拦截危险命令、发通知Hook生命周期事件上确定性执行
一个任务要读很多文件,但主会话不需要中间过程Subagent隔离上下文,只返回摘要
多个 Claude session 要互相协作Agent Teams独立 session 之间通信和共享任务
多个项目要共享同一套 skills/hooks/MCPPlugin版本化、可分发、可市场化

#容易混淆的能力

对比结论
CLAUDE.md vs SkillCLAUDE.md 是 always-on,Skill 是 on-demand。根文件超过 200 行时通常该拆 Skill 或 rules。
Skill vs SubagentSkill 是知识或流程,Subagent 是独立 worker。Skill 增加主上下文,Subagent 隔离主上下文。
MCP vs SkillMCP 提供工具和数据连接,Skill 教 Claude 如何使用这些工具。两者经常组合。
Hook vs SkillHook 必定在事件上运行,适合强制规则。Skill 需要模型理解,适合需要推理的流程。
Subagent vs Agent TeamSubagent 回报给主会话,Agent Team 是多个完整 Claude Code session 互相协作。

#缓存和成本视角

动作5m / 1h 影响
连续在同一会话追问命中会刷新 TTL,5m 足够高频工作
离开 10 到 45 分钟回来5m 通常冷,1h 更可能继续读旧前缀
改 CLAUDE.md 后重启前缀变,5m/1h 都会重新写缓存
增删 MCP server工具定义变化,容易 miss;tool search 更友好
调用 Skill正文作为消息追加,通常保留旧前缀
大量 Hook 输出不一定破坏前缀,但会抬高后续输入 token
Subagent 做大范围探索子代理自己付 token,主会话只拿摘要,主上下文更干净
Plugin 带 MCP可能同时改变 skill 描述和工具定义,首次 reload 后要观察 cache creation

更细的逐命令影响看 命令与缓存影响。底层 TTL 和 usage 字段看 Prompt 缓存。

#建议的扩展顺序

  1. 先跑 /init,把项目基础约定写进 CLAUDE.md。
  2. 把敏感路径放进 permissions deny,不要只写自然语言提醒。
  3. 把重复 prompt 固化成 Skill 或自定义命令。
  4. 给必须执行的格式化、审计、通知写 Hook。
  5. 需要外部系统时再接 MCP,并确认 tool search。
  6. 大任务再引入 Subagent、Worktree、Agent Teams 或 SDK。
  7. 多项目复用后再打包成 Plugin 或内部 marketplace。

#官方参考

上一页配置教程下一页安装与登录排错

Support / 支持

Need help? / 需要帮助？

接入、计费与模型异常可邮件联系；服务可用性以状态页为准。For setup, billing, or model issues, email us. Check the status page for uptime.

Support Emailsupport@passion8.ccService Statusstatus.passion8.cc

也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right