Claude Code 大文件全文读取指引解析：借助子代理隔离上下文完成完整文件分析-平芜编程栈

文档
提示工程
人工智能

【免费下载链接】claude-code-system-prompts

All parts of Claude Code's system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.

项目地址：https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts

点击查看免费下载

导读

本文围绕 claude-code-system-prompts 仓库中维护的系统提醒 system-reminder-large-file-full-content-reading-guidance.md 展开，剖析 Claude Code 在面对"需要读取大文件完整内容才能分析或总结"的场景时给出的两条核心规则：如何完整读取，以及如何把读取交给子代理以保护主上下文。读完本文，你将理解这套提醒机制的设计动机、它与文件截断/重试机制、完整性披露机制的配合方式，并能写出一份不会丢失细节的、合格的子代理任务书（prompt）。

一、这份系统提醒是什么：文件位置、形态与触发场景

在claude-code-system-prompts仓库中，Claude Code 的各种系统提醒（System Reminder）以独立 Markdown 文件的形式维护，文件名即提醒名称。本文对应的文件是：

system-prompts/system-reminder-large-file-full-content-reading-guidance.md（ccVersion: "2.1.173"）

该文件在 frontmatter 中声明了三个模板变量，表明其内容在运行时由宿主注入后才会成为完整指令：

${FULL_CONTENT_READING_INSTRUCTION}：针对"需要读取全文"场景的具体读取指令；
${AGENT_TOOL_NAME}：子代理工具的实际名称（例如Task或Agent）；
${SUBAGENT_READING_INSTRUCTION_EXAMPLE}：一段"子代理读取指令示例"，用于示范如何向子代理明确交代返回要求。

正文仅两条规则，但信息密度很高，是整个大文件处理策略的纲领：

对于需要读取完整内容才能进行的分析或总结：执行${FULL_CONTENT_READING_INSTRUCTION}。
如果${AGENT_TOOL_NAME}工具可用，请在子代理内部完成这件事，使完整输出不进入你的主上下文。把上面的指令逐字交给子代理，并明确说明它必须返回什么——例如${SUBAGENT_READING_INSTRUCTION_EXAMPLE}。一句含糊的"summarize this"可能会丢失细节。

触发的典型场景包括：用户把大型源码文件、长日志或超大文档作为附件放入对话；模型需要对某份文件做完整分析或总结，而不是只查其中一段。

二、规则一：需要全文时怎么读——读取、截断与重试的配套机制

第一条规则要求：凡分析或总结依赖全文，就必须真正读完全部内容。它不是一个孤立的提醒，而是与仓库中另外几份"读取约束"类提醒配套生效。

2.1 文件过大时会发生什么：截断提醒

当附加文件过大时，Claude Code 会注入"文件被截断"提醒（system-reminder-file-truncated.md，ccVersion: "2.1.239"）：

文件过大，已被截断为前${MAX_LINES_CONSTANT}行。无需提及截断这件事。如果需要，请使用${READ_TOOL_NAME}读取文件的更多内容。

注意${MAX_LINES_CONSTANT}是模板变量，由宿主按版本配置注入（如默认读取行数上限），文中不写死具体数值。这条提醒的要点是：截断只是起点，不是终点，模型应继续用读取工具取回剩余部分。

2.2 遇到截断警告怎么办：缩小分块直到读满 100%

配套的"读取截断重试"提醒（system-reminder-read-truncation-retry-guidance.md，ccVersion: "2.1.173"）给出了硬性要求：

如果读取文件时收到截断警告（如 "[N lines truncated]"），请缩小分块大小，直到在不截断的情况下读完 100% 的内容。在完成之前不要继续。Bash 输出被限制为${MAX_OUTPUT_CHARS.toLocaleString()}个字符。

这意味着：

使用读取工具时主动传入offset/limit分块读取；
若单次返回仍带截断警告，就进一步缩小limit，直到每块都能完整返回；
未读满 100% 之前，不得进入分析/总结阶段；
若走 Bash（cat等）路线，输出有字符上限，同样需要分块规避。

2.3 Read 工具的基础能力

全文读取的实际执行者是文件读取工具。其工具描述（tool-description-readfile.md，ccVersion: "2.1.288"）说明了几个关键约束：

默认从文件开头读取至多${MAX_LINES_CONSTANT}行；
通过offset/limit参数控制分块与起始位置；
file_path必须使用绝对路径；
支持图片（PNG/JPG 等，以多模态方式呈现）、PDF（大 PDF 必须用pages参数分页读取，单次最多 20 页）与 Jupyter Notebook（.ipynb，返回所有单元格及输出）；
只读文件、不读目录；读取空文件会收到专门的系统提醒。

结合这些约束，一条可复用的全文读取流程是：先用小分块试探文件规模 → 出现截断警告就缩小limit→ 用offset逐块推进 → 直到最后一块的返回长度小于分块上限，确认已覆盖 100% → 才开始输出分析。

三、规则二：把全文读取交给子代理——上下文隔离的核心手段

第二条规则是本提醒最精妙的部分：不要自己读，交给子代理读。

3.1 为什么要在子代理内完成

直接理由是"让完整输出留在子代理的上下文中，不进主上下文"。子代理工具的使用指南（system-prompt-tool-usage-subagent-guidance.md，ccVersion: "2.1.53"）明确写道：子代理的价值在于"并行化独立查询，或保护主上下文窗口免于过量的结果"。一份 10 万行文件的全文会瞬间吞掉大量主上下文 token，而子代理只需把最终结论带回主线程，原始内容留在子代理侧。

3.2 什么时候用、什么时候别用

同一份指南也给出了边界：子代理"不应在不需要时被过度使用"；system-prompt-subagent-delegation-cost-guidance.md（ccVersion: "2.1.271"）进一步说明了成本账——新开的子代理只知道你写进 prompt 的东西、只返回它的摘要，两次交接都会丢失细节；因此"当答案是寥寥几次工具调用、或你已知道目标的一两次查询时，自己干；不确定时不要开子代理"。对于确实需要扫读多文件/大文件全文的场景，才值得把"阅读 + 提炼结论"委托出去。

3.3 委托的两条铁律

本提醒强调了两点，缺一不可：

把读取指令逐字（verbatim）交给子代理：子代理没有主对话的任何上下文（参见 system-prompt-fresh-subagent-delegation-example.md 中的说明："the agent starts with no context from this conversation"），所以必须把${FULL_CONTENT_READING_INSTRUCTION}原样嵌入其任务书，否则它可能只读片段就交差；
明确交代返回内容，拒绝含糊指令：模糊的 "summarize this" 会丢失细节。必须显式说明要返回什么（结论？逐项清单？问题列表？），以及格式与长度约束。

四、写一份合格的子代理任务书：结构拆解与示例

仓库中若干委托示例给出了任务书的黄金结构。综合 system-prompt-fresh-subagent-delegation-example.md 与 system-prompt-non-fork-subagent-delegation-examples.md（ccVersion: "2.1.235"），一份面向"全文读取 + 分析"的任务书应包含：

目标：要分析什么、产出什么判断；
已排除/已确认的背景：你已经做过什么、排除了什么，避免子代理重复劳动（tool-description-agent-usage-notes.md 中的"Trust but verify"也提醒：子代理的摘要描述的是它打算做什么，不一定等于实际做了什么）；
指向文件而不是转述内容：给出文件路径，让子代理自己去读；
逐字嵌入全文读取指令；
显式、窄范围的返回要求：形式（清单/结论）+ 长度上限（如 "Under 200 words"）。

一个可直接套用的示意（JSON 参数形式，与仓库示例保持一致）：

Task({ description: "Full-content analysis of large log file", prompt: "Read the COMPLETE content of /data/logs/order-service.log using chunked reads (offset/limit), reducing chunk size on any truncation warning until 100% of the file is read WITHOUT truncation. Do NOT summarize before you have read 100%. Then report, as a punch list: (1) every distinct error code with its line numbers, (2) the sequence of events around the first timeout, (3) anything anomalous. Under 250 words." })

对照本提醒的要求检查这份任务书：读取指令逐字在内、返回形式明确（清单 + 行号 + 上限字数）、范围窄（只针对该文件）——这正是"别让细节丢失"的落地写法。委托一旦发出，就不应再自己重复同样的搜索（见 system-prompt-tool-usage-subagent-guidance.md："avoid duplicating work that subagents are already doing"）。

五、配套约束：完整性披露与失败止损

全文读取之外，模型还有一项"诚实披露"义务，见 system-reminder-file-summary-completeness-disclosure.md（ccVersion: "2.1.173"）：

在产出任何摘要或分析之前，必须明确描述你已读取了内容的哪一部分。如果你没有读完全部内容，必须明确说明这一点。如果尝试几次后仍无法读取文件（文件不存在、行过长超出 Read 的 offset/limit、没有 shell 权限），停止重试：总结你读到的部分，明确说明哪部分没读到及原因，然后继续。

它与本文主题互为表里：规则一要求"读完 100% 再分析"，披露规则则兜底了"万一确实读不完"的情形——不掩盖、不假装读全，明说覆盖范围后继续。两者共同保证了分析的可信度边界。

六、边界辨析：全文读取 vs 只读搜索代理

需要区分两种不同定位的代理行为。仓库中另有"只读搜索代理"（agent-prompt-read-only-search-agent.md，ccVersion: "2.1.173"）：

面向广度扫描（fan-out）的只读搜索代理——当答案需要扫过许多文件、目录或命名约定，而你只需要结论而不是文件转储时使用。它读片段而不是读全文，所以它能定位代码，但不能审查或审计代码。

两者对照关系如下：

维度	全文读取（本文提醒）	只读搜索代理
读取方式	分块读满 100%，逐字执行全文读取指令	读片段（excerpts）
目标	对单份大文件做完整分析/总结/审计	跨多文件定位代码、给出结论
产出	完整覆盖后的分析结论	结论而非文件转储
适用	需要全文依据的审查、总结	广度搜索、命名约定扫描

简单说：全文读取解决"读得够不够全"，搜索代理解决"搜得够不够广"。需要逐行审计一份文件时用前者，需要确认"哪个文件实现了某功能"时用后者。

七、仓库中的相关文件索引

以下文件可在仓库中继续深入阅读，理解整套大文件处理与子代理委托机制的全貌：

核心提醒：system-prompts/system-reminder-large-file-full-content-reading-guidance.md
截断与重试：system-prompts/system-reminder-file-truncated.md、system-prompts/system-reminder-read-truncation-retry-guidance.md
完整性披露：system-prompts/system-reminder-file-summary-completeness-disclosure.md
读取工具能力：system-prompts/tool-description-readfile.md
子代理工具与委托成本：system-prompts/tool-description-agent-usage-notes.md、system-prompts/system-prompt-tool-usage-subagent-guidance.md、system-prompts/system-prompt-subagent-delegation-cost-guidance.md
委托示例与边界：system-prompts/system-prompt-fresh-subagent-delegation-example.md、system-prompts/system-prompt-non-fork-subagent-delegation-examples.md、system-prompts/agent-prompt-read-only-search-agent.md

小结

这份篇幅不长的系统提醒，浓缩了 Claude Code 处理大文件的两条关键工程原则：要么不分析，要分析就真正读满 100%（通过分块读取、遇截断缩小分块、配合完整性披露实现）；凡是可能污染主上下文的全文读取，就委托给子代理（通过逐字传递读取指令 + 显式返回要求来对抗交接过程中的细节丢失）。理解这套机制，不仅有助于读懂 Claude Code 的提示工程设计，也可以直接迁移到你自己编写的 Agent 工作流中：为"长文/大文件分析"类任务设计子代理时，任务书里永远要有完整的读取指令、明确的返回契约，以及对"没读完"状态的诚实披露。