企业官网建设流程全解析

• 文档
• 提示工程
• 人工智能

本篇文章聚焦开源仓库 gh_mirrors/cl/claude-code-system-prompts 中的核心文档 system-reminder-file-summary-completeness-disclosure.md，深度解析 Claude Code 注入给模型的"文件摘要完整性披露"系统提醒：它要求模型在产出任何总结或分析之前先说明自己实际读取了多少内容，并在读取失败时及时停止重试、如实汇报。读完本文，你将理解该提醒的两条强制行为规则、它与 Read 工具行数上限及截断重试等配套机制如何协同工作，以及如何在真实的文件分析、对话压缩等场景中落地"读了什么就说什么"的可信度底线。

一、这份提醒在 Claude Code 系统提示词体系中的位置

Claude Code 并不只有一段固定的系统提示词。正如仓库 README.md 所述，其系统提示词由"大量根据环境和配置条件性追加的片段"组成，而 System Reminders 正是其中专门承载"大段系统提醒文本"的类别——本仓库将它们逐条提取为独立 Markdown 文件，并标注了对应的 token 数与版本。

本关联文档的 frontmatter 声明如下：

<!-- name: "System Reminder: File summary completeness disclosure" description: "Requires Claude to disclose how much file content was read before summarizing and to stop retrying after repeated read failures" ccVersion: "2.1.173" -->

其中name标识提醒名称，description概括其职责，ccVersion标注该提醒对应的 Claude Code 版本（2.1.173）。整个仓库随每个 Claude Code 版本更新，README 中将其列为107 tks的 System Reminder 条目（见 README 的 "System Reminders" 小节）。它的作用对象是主会话中的模型本体：当模型需要总结或分析某个文件内容时，这段提醒被注入上下文，约束模型在输出结论前先交代"读取范围"。

二、规则一：任何总结与分析之前，必须先披露已读取的内容范围

该提醒的第一条规则原文如下：

Before producing ANY summary or analysis, you MUST explicitly describe what portion of the content you have read.If you did not read the entire content, you MUST explicitly state this.

拆解这条规则，可以得到三个强制行为要求：

1. 前置披露义务（MUST）：在产出任何（ANY）总结或分析之前，必须先明确描述"你读了这个内容的哪一部分"。
2. 覆盖所有产出类型：无论是给用户的文件总结、代码审查结论、日志分析报告，还是对话压缩（compaction）后的摘要，都受此约束。
3. 未读全必须明说（双重强调）：只要没有读完整份内容，就必须显式声明"未读取完整内容"——原文用***...***做了强调，说明这是不可省略的硬性要求。

这一规则的工程动机很清晰：模型在长文件面前容易出现"只读了几行却像读完了一样给出结论"的行为。披露义务把"读取范围"变成输出结论的前置步骤，让用户能判断总结的置信度——例如"我读取了该文件前 500 行（共 1200 行）"与"我已读取全文"，二者的可信度完全不同。这与仓库中另一份系统提示 system-prompt-reporting-outcomes.md（要求报告区分"观察到的结果"与"意图"、避免夸大未经验证的完成度）在精神上一脉相承：结论必须建立在真实读取的证据之上。

三、规则二：多次读取失败后停止重试，降级为部分总结

该提醒的第二条规则原文如下：

If after a few attempts you cannot read the file (file not found, lines too long for Read's offset/limit, no shell access), STOP retrying. Summarize what you were able to read, explicitly state which portion you could not read and why, and proceed.

它针对的是"读不到"的异常路径，同样包含三步：

1. 有限的尝试次数：只在"几次尝试"（a few attempts）后仍无法读取时触发停止条件，避免无意义的反复重试消耗上下文与时间。
2. 明确列举失败原因类型：原文给出了三类典型场景——
   • 文件不存在（file not found）；
   • 行数超出 Read 工具的 offset/limit 能力（lines too long for Read's offset/limit）；
   • 没有 shell 访问权限（no shell access）。
3. 降级输出并继续：停止重试后，要做三件事：总结能读到的部分、显式说明哪部分没读到以及为什么、然后正常继续后续工作（proceed）。

这条规则的设计意图是"不让失败卡死整个会话"：读取失败不该导致任务僵持，也不该导致模型假装读过。诚实的部分总结 + 明确的缺失说明，比"无限重试"或"编造内容"都更符合工程上可继续推进的要求。同时它也呼应了 system-prompt-action-safety-and-truthful-reporting.md 中"如实汇报结果"的总体原则。

四、配套机制一：Read 工具的行数上限与分片读取

要理解"lines too long for Read's offset/limit"为何会成为失败原因，需要看 Read 工具的实际定义。tool-description-readfile.md 中明确写明：

By default, it reads up to ${MAX_LINES_CONSTANT} lines starting from the beginning of the file

即默认最多读取MAX_LINES_CONSTANT（一个随版本变化的行数常量）行，超大文件必须借助 offset/limit 分片读取。同一份工具描述还补充了其他读取边界：

• 读取 PDF 时，超过 10 页的大文件必须用pages参数指定页范围（如pages: "1-5"），且单次最多 20 页；
• 读取存在的空文件时，会收到一个系统提醒作为替代内容（对应 system-reminder-file-exists-but-empty.md）；
• 当 offset 超过文件长度时也会触发提醒（对应 system-reminder-file-shorter-than-offset.md）。

这些边界正是"无法一次读全"的客观来源。在实际操作中，处理长文件的标准做法是多次调用 Read 并携带不同的 offset 分片读取，例如：

Read file_path=/path/to/large.log offset=1 limit=500 # 读取第 1–500 行 Read file_path=/path/to/large.log offset=501 limit=500 # 读取第 501–1000 行

而根据本文档的规则一，无论分片读到哪一步，最终产出总结前都必须说明"已读取了哪些行、占全文多少比例"，未读完的部分则按规则二如实声明。

五、配套机制二：截断提示与"读全为止"的重试指引

围绕"文件太大"这一核心场景，Claude Code 还注入了若干与本文档直接相关的提醒，共同构成完整的读取治理链路：

1. 文件截断通知：system-reminder-file-truncated.md 会在文件过大、系统仅向模型呈现前${MAX_LINES_CONSTANT}行时注入，并说明"无需主动提及截断，需要更多内容就用 Read 工具继续读取"。
2. 截断重试指引：system-reminder-read-truncation-retry-guidance.md 的约束更强——一旦收到"[N lines truncated]"这样的截断警告，就必须缩小分片大小（reduce the chunk size）继续读，直到 100% 读完且无截断，并且原文用DO NOT PROCEED UNTIL YOU HAVE DONE THIS强调"没读完之前不得继续"。该提醒还顺带说明 Bash 输出有${MAX_OUTPUT_CHARS}字符上限。
3. 大文件全文读取指引：system-reminder-large-file-full-content-reading-guidance.md 给出了更省上下文的方案：当需要基于全文做分析时，如果 Agent 工具可用，应把"读全文"这件事交给子代理（subagent）执行，让完整输出停留在子代理上下文中，并明确告诉子代理"必须返回什么"，避免一句含糊的"帮我总结一下"丢失细节。

将这三份提醒与本文档对照可以看出完整的分层策略：先尽力读全（截断时缩分片、必要时交给子代理）→ 读不全时披露范围（本文档规则一）→ 彻底读不到时停止重试并降级总结（本文档规则二）。read-truncation-retry-guidance的"必须读完"与本文档的"没读完必须声明"并不矛盾——前者适用于"文件大但可读"的路径，后者适用于"文件确实读不到"的兜底路径。

六、配套机制三：其他输出截断场景的同类处理

"读取范围披露"的原则不只应用于本地文件读取，Claude Code 在同类"输出被截断"场景中贯彻了完全一致的处理哲学，可以从仓库的以下文档中印证：

• MCP 工具输出截断：system-reminder-mcp-output-truncation-warning.md 声明：当 MCP 工具输出超过 token 上限被截断时，如果该 MCP 服务器提供分页或过滤工具，应使用它们获取特定数据分片；如果无法分页，则必须告知用户当前基于截断输出工作、结果可能不完整——这与本文档"未读全必须明说"是同一原则在不同通道上的复用。
• Hook 条件求值的截断转录：system-prompt-hook-evaluator-truncated-transcript-note.md 告诉 hook 条件求值器：更早的对话因上下文窗口限制被省略（${OMITTED_MESSAGE_COUNT}条消息未呈现），如果所需证据可能位于被省略的前缀中，应返回{"ok": false, "reason": "insufficient evidence in transcript"}——即"证据不足就明确说不足"，而不是强行下结论。
• MCP 资源无内容：另有 system-reminder-mcp-resource-no-content.md 负责"资源没有内容"的提示场景。

这些文件共同表明：Claude Code 在"信息不完整"的所有出入口（本地文件、MCP 输出、对话转录）都要求模型要么补齐信息、要么如实披露不完整，杜绝基于不完整信息做出看似完整的结论。

七、与总结类提示词的协同：完整性如何被制度化

本提醒的"披露读取范围"规则，最终落到仓库中一系列总结类系统提示词所定义的产出格式上。理解它们有助于看清该提醒在真实会话中的生效位置：

• 部分压缩指令：system-prompt-partial-compaction-instructions.md 定义了对话压缩摘要必须包含的 9 个章节（Primary Request and Intent、Key Technical Concepts、Files and Code Sections、Errors and fixes、Problem Solving、All user messages、Pending Tasks、Work Completed、Context for Continuing Work），并要求"详尽总结，让只读摘要和后续新消息的人能完整理解发生了什么"——包括关键代码片段、函数签名、文件编辑记录，以及必须逐字保留的安全相关指令。
• 分析过程指令：system-prompt-analysis-instructions-for-full-compact-prompt-recent-messages.md 要求把分析过程包在<analysis>标签中，按时间顺序逐段识别用户意图、技术决策、错误与修复，并双重检查技术准确性与完整性，确保每个必需要素都被覆盖。
• 上下文压缩摘要（SDK）：system-prompt-context-compaction-summary.md 定义了面向 SDK 的续接摘要格式，同样要求结构化、简洁且可行动，避免重复劳动。

将本文档与上述指令放在一起阅读即可发现完整的信任链：读取阶段靠本文档的"披露读取范围 + 失败停止重试"保证信息源的透明；总结阶段靠压缩指令的结构化模板保证信息不丢失、不掺假。两端的约束共同服务于一个目标——压缩后的摘要依然是可以被信任的"可继续工作的依据"。

八、实践清单与常见误区

基于以上分析，为开发者和使用 Claude Code 的 Agent 总结一份落地清单：

应当这样做：

• 每次总结或分析文件前，先说明读取范围，例如"已读取全部 1200 行"或"已读取前 500 行（共 1200 行），其余部分未读取"；
• 收到[N lines truncated]截断警告时，缩小分片大小（如从 500 行降到 200 行）继续读取，直到读满 100%；
• 大文件全文分析交给子代理执行，并在指令中明确要求其返回的内容粒度（参考 system-reminder-large-file-full-content-reading-guidance.md）；
• 文件不存在、offset/limit 读不了、无 shell 访问时，尝试数次后立即停止重试，输出"已读取部分 + 未读取部分及原因"的总结并继续任务；
• 处理 MCP 输出截断、hook 转录省略等同类场景时，同样遵循"要么分页补齐、要么明确告知不完整"的原则。

应避免的误区：

• 只读了几行就当全文总结，或在未读完整内容时暗示已读完——这是规则一明确禁止的行为；
• 读取失败后无限重试，浪费上下文与时间——规则二要求及时止损；
• 因文件过大就草率放弃阅读——正确做法是先按 system-reminder-read-truncation-retry-guidance.md 缩小分片、必要时派生子代理读全，只有真正读不到时才降级为部分总结。

结语

system-reminder-file-summary-completeness-disclosure.md 虽然只有短短两条规则，却是 Claude Code 可信度体系中的一个关键支点：它用"产出结论前披露读取范围"和"读取失败及时止损并如实说明"两条硬约束，把"信息不完整"这一常态变成了可以显式管理的状态。在长文件分析、对话压缩、MCP 结果处理等所有涉及"信息经截断后流通"的场景中，这套机制与 tool-description-readfile.md、system-reminder-read-truncation-retry-guidance.md、system-prompts/system-reminder-large-file-full-content-reading-guidance.md 等配套提醒协同，最终保证了 Agent 产出的每一条结论都有明确的读取证据边界。理解并遵循这一机制，是使用 Claude Code 进行可靠文件分析、构建可信 Agent 工作流的基础能力。

• 文档
• 提示工程
• 人工智能