# CC-02｜Claude Code 的项目上下文与扩展

核验日期：2026-10-10；本机 CLI 2.1.295。本章合并旧版上下文与扩展专题，按“把信息和方法放到合适位置”组织。

![上下文与扩展逻辑架构图](<../../图表/CC-02_架构.svg>)

## 1. 先分清信息的寿命

项目目标、编码约束与运行方法适合稳定入口；一次任务的输入与接受标准适合任务说明；长日志与详细规范适合按需读取；当前失败和下一步适合交接。不是所有信息都应该每轮加载。

过长规则会占用空间，也更难维护。短入口能给出准确路径，详细说明继续留在文件。摘要必须保留约束与未完成项；重复工具输出可以移到记录中。

## 2. CLAUDE.md 和规则范围

[官方 memory 文档](<https://code.claude.com/docs/en/memory>) 说明项目指令、用户指令和自动记忆等载体。项目可用 `CLAUDE.md`，较多主题可用 `.claude/rules/` 分类，路径相关规则可以按匹配文件加载。父目录、子目录、额外目录、设置来源和版本会影响实际加载。

不能把“放了一个文件”当成已经加载。先检查当前版本、目录与会话上下文，再确认是否能查到对应入口。用户规则与项目规则不一致时应消除冲突，不要编造“后加载一定覆盖”的硬性执行保证。

一个精简教学规则可以只写：输入 CSV 只读；规则以 docs/资产规则.md 为准；运行 run_checks.py；报告写指定目录；禁止把未运行检查写成通过。规则中的路径必须存在，运行命令必须能复现。

## 3. 维护规则与长会话

每项规则说明它解决的问题和适用范围。一次故障修复后，优先改错误代码、补对应检查和更新原文入口，避免不断追加与已有规则重叠的长段落。

长会话需要阶段摘要：当前目标、已确认事实、决定、实际结果、剩余问题和下一步。`/compact` 等入口以该版本 `/help` 为准；压缩后仍要确认业务条件没有丢失。恢复会话与保留知识是不同用途。

## 4. Skill 保存方法

Skill 适合重复的任务方法，例如读取清单、按规则检查、生成报告、核对证据。一个清楚的 Skill 要有名称与描述、触发场景、所需输入、操作顺序、输出和检查办法。

[官方 skills 文档](<https://code.claude.com/docs/en/skills>) 说明 `.claude/skills/<name>/SKILL.md` 等入口及支持资源。方法可以调用已有 CLI，详细模板按需读取，不必把所有执行逻辑写成长提示。

配套 [asset-audit Skill](<../../示例/ClaudeCode/CC-02-04_asset_workflow/.claude/skills/asset-audit/SKILL.md>) 是教学配置；本次检查了文本与脚本，没有发起 Claude 会话验证自动触发。`allowed-tools` 也不能被随意解释成完整隔离机制。

## 5. MCP 提供外部工具

MCP 连接客户端与能力服务，工具描述和 schema 说明参数与结果。它可以连接项目数据、引擎或外部服务，不能替代任务方法、身份校验和结果检查。

[官方 MCP 文档](<https://code.claude.com/docs/en/mcp>) 区分配置范围、连接、授权与工具发现。调试时依次确认配置是否被读取、服务是否可连接、工具是否可见、参数是否正确、调用结果是否满足目标。

教材的 `.mcp.example.json` 是未连接模板，`example.com` 是占位地址；不要直接把它作为真实端点调用。此次没有连接 UE 或外部 MCP。实际接入应保留工具请求与响应，并核对服务版本。

## 6. Hook 执行确定性检查

Hook 在指定事件附近执行确定性动作。常见用途是格式、检查、记录或执行边界，不是要求模型每次记住再运行一次。

[官方 hooks 文档](<https://code.claude.com/docs/en/hooks>) 的事件语义不同：`PreToolUse` 可以在操作前检查；`PostToolUse` 发生时操作已经执行，不能把它当作撤销机制。退出码和 JSON 控制字段应按事件核对。

配套 guard_write.py 的 `PreToolUse` 只匹配 Edit／Write，保护教学 `protected/` 目录。配置命令经 stdin JSON 接收事件，利用项目根与实际路径判断目标。脚本已做十二种输入检查；这不证明其他工具、终端命令或符号链接场景都被它覆盖，也不证明实际 Claude 触发已测。

## 7. 子代理的条件

[官方 subagents 文档](<https://code.claude.com/docs/en/sub-agents>) 描述独立上下文、提示、工具与权限。适合资料研究、只读评审等边界清楚的任务，能够返回摘要并减少主会话细节。

委派前写清目标、输入、产物、允许文件与汇总方式；多个任务修改同一文件会产生冲突；串行依赖不能仅凭开更多角色加速。子代理请求也有用量成本。本次制作没有运行教材里的子代理。

## 8. 选择最少且足够的机制

| 问题 | 优先载体 | 原因 |
|---|---|---|
| 一次性的明确任务 | 普通任务提示 | 无额外维护成本 |
| 长期项目约束 | CLAUDE.md／规则 | 让约束可发现、可更新 |
| 重复流程 | Skill＋现有 CLI | 复用方法和确定性执行 |
| 外部实时数据 | MCP／已有 API 工具 | 取得实际环境事实 |
| 每次特定事件必须检查 | Hook／CI | 明确触发与反馈 |
| 独立研究或只读评审 | 子代理 | 隔离上下文、明确产物 |

清单报告案例先用普通提示和项目规则即可。重复几十次后再整理 Skill；真的需要查询引擎时再接工具；误写某目录反复发生时增加执行检查。每项扩展都应说明它解决的具体问题。

## 9. 维护、练习与验收

配置变化可能改变发现、权限或触发时机，需要同时更新运行说明与证据。服务升级、规则路径变化、Skill 入口变化时重新检查当前会话。大而全配置不自动提高质量。

练习：写一张机制选择表、一份短项目规则和一个清单报告流程。运行配套检查，另在自己的 Claude 会话确认配置实际加载；记录脚本、配置与模型行为三个验证层。验收时能够指出每个机制解决的问题，移除无用途配置。

![本章思维导图](<../../图表/CC-02_思维导图.svg>)

## 来源

现行机制来自以上五个官方页面，核验日期均为 2026-10-10。详例来自 [V1 扩展参考副本](<../../sources.html#ref-f52c4e5223bafe>)，已迁入版本内；实时运行边界见 [示例说明](<../../示例/ClaudeCode/CC-02-04_asset_workflow/README.md>)。下一章：[CC-03](<CC-03_调试测试与评审.md>)。