cc-insider

Claude Code v2.1.88 深度掌握。整合架构体系、源码解析、实战模式。涵盖 Tool/Task/Agent 三层模型、Coordinator 协调、Hooks 钩子、权限系统、Context 缓存、MCP 集成。触发场景：理解 Claude Code 内部工作原理、行为异常诊断、扩展开发（Tool/...

Security Scan

This is an instruction-only documentation skill that matches its name and claims (deep internal docs for Claude Code v2.1.88); it contains rich implementation details and references to internal file paths but requests no installs, binaries, or credentials.

Purpose & Capability

The skill claims to provide deep mastery of Claude Code internals and the bundled SKILL.md + reference files are precisely internal architecture docs, code snippets, and developer guidance. Nothing declared (no env vars, no binaries, no installs) is disproportionate to the stated purpose.

Instruction Scope

The runtime instructions are documentation and do not instruct the agent to fetch external code or secrets. However the references contain explicit file paths and operational behavior (e.g., ~/.claude/, ~/.claude/.task-output, restored-src/src/, CLAUDE.md nesting, sed simulated-edit semantics, Task output persistence) that a model or a separately-enabled toolchain could use to access or modify local state. The SKILL.md itself does not require or perform those accesses, but it provides detailed guidance that could be acted on if the agent is granted file/system access elsewhere.

Install Mechanism

No install spec, no downloads, and no code files that would be executed at install time. Being instruction-only lowers install-time risk.

Credentials

The skill does not request any environment variables or credentials. It does include examples that reference environment flags (e.g., CLAUDE_CODE_COORDINATOR_MODE) and configuration locations, which are plausible for internal docs but should be considered when granting the agent host-level permissions.

Persistence & Privilege

The skill does not request persistent/always-on privileges (always:false) and has no install-time behavior. Autonomous invocation by the agent remains platform-default and is not elevated by this skill.

Assessment

This skill is essentially a packaged set of internal design and source-code excerpts for Claude Code; it is internally coherent with its description and doesn't request credentials or install anything. Before enabling it, check whether your agent is allowed to run host-level tools (Read, Bash, Write, or similar). If the agent has those capabilities, the detailed file paths and sed/write semantics in this skill could guide the agent to read or modify local configuration and task outputs—only grant file or shell access if you trust the agent and need those behaviors. If you only want passive reference material, it's safe to install but avoid enabling tools that allow filesystem or network operations.

Claude Code Mastery

源码位置：restored-src/src/
版本：v2.1.88
来源：架构分析 + 源码解析 + 实战模式（三合一）

---

核心理念：三层架构

Claude Code 的核心是 Tool → ToolUse → Task 三层递进模型：

Tool（定义层）     → 我是什么工具，有哪些接口
ToolUse（执行层）   → 实际调用时的完整运行时状态
Task（封装层）     → 后台任务的生命周期管理

理解这三层的区别和交互，就掌握了 Claude Code 的骨架。

---

快速导航

详细内容和源码引用见各 reference 文件：

主题	参考文件
架构全景、子系统关系、源码位置	architecture.md
Tool 接口、buildTool 工厂、ToolUseContext、Zod schema	tool-internals.md
Task 类型、生命周期、ID 生成、LocalShellTask	task-system.md
AgentTool、spawn/fork/continue/stop、AgentDefinition	agent-system.md
Coordinator 协调原则、Synthesize-first、决策树	coordinator.md
Hooks 事件类型、执行流程、匹配规则	hooks.md
权限模型、SedEdit 安全设计、isConcurrencySafe	permissions.md
Context 缓存、CLAUDE.md 嵌套、fork-safe 设计	context-system.md
SKILL.md 格式、Tool 实现模板、命令注册、Prompt 精选	patterns.md
设计亮点、调试线索、常见问题 Q&A	design-highlights.md

---

关键概念速查

Tool ≠ 函数

Tool 是包含接口定义 + 执行逻辑 + 权限检查 + UI渲染的完整对象，不是简单的函数调用。

buildTool 默认 Fail-Closed

const TOOL_DEFAULTS = {
  isConcurrencySafe: () => false,  // 默认不允许并发
  isReadOnly: () => false,         // 默认会修改
  isDestructive: () => false,       // 默认不破坏
  checkPermissions: () => ({ behavior: 'allow' }),
}

spawn vs fork vs continue

• spawn：独立 session，新 context
• fork：复用父进程 system prompt cache，在同一 session 并行
• continue：复用已有 context 继续执行
• stop：停止但不删除 session

Coordinator 核心原则

1. 永远先 Synthesize，不 delegation of understanding
2. 并行是默认策略
3. Worker 结果 = 内部信号，不是对话伙伴

Fork 安全三剑客

contentReplacementState、renderedSystemPrompt、messages 必须在 fork 时从父进程克隆，保证上下文一致。

SedEdit 安全关键

_simulatedSedEdit 在 inputSchema 中被 omit，模型不能自己设置这个字段——防止构造任意文件写入。

---

扩展开发速查

实现新 Tool 检查清单

1. inputSchema — Zod schema 定义参数
2. description() — 人类可读描述（3-10 词，无句号）
3. call() — 执行逻辑，包含错误处理
4. maxResultSizeChars — 超过→写磁盘
5. checkPermissions() — 权限逻辑，默认 allow
6. toAutoClassifierInput() — 安全分类，默认空字符串
7. renderToolResultMessage() — UI 渲染
8. isConcurrencySafe() — 并发安全，默认 false
9. isReadOnly() / isDestructive() — 操作类型
10. getPath()? — 文件路径权限检查
11. preparePermissionMatcher()? — Hook pattern 匹配

添加新 Hook 事件

1. 在 src/types/hooks.ts 添加事件类型
2. 在相关位置调用 hooks(event, context)
3. 在 SKILL.md 中配置规则

Skill 触发方式

1. 显式：/skill-name
2. 自动发现：ToolSearch 根据 description/whenToUse 匹配
3. 路径过滤：paths 字段 glob 模式

Skills 加载优先级

.claude/（项目）> ~/.claude/（用户）> plugin/