Claude Code Tools 研究系列（七）—— Write：创建与全量重写的边界
内容提要
Write工具用于创建新文件或完全重写文件，是唯一能新建文件的工具，但存在覆盖风险。其设计通过强制Read先行、偏好Edit、禁止主动创建文档和emoji等约束，平衡必要性与危险性。Write与Edit分工明确：Write用于新建或全量重写，Edit用于增量修改。核心哲学是任何写入必须基于对当前文件状态的感知，由runtime强制保障。
延伸解读
Write 与 Edit 的分工：安全与效率的平衡
Write 工具专用于新建文件或全量重写，而 Edit 负责增量修改。这种分工并非随意，而是基于安全与效率的考量。使用 Write 进行小改动会浪费 token、扩大破坏面、增加审阅难度，并可能引发并发冲突。因此，官方 prompt 明确要求优先使用 Edit，仅在新建或重写时使用 Write。理解这一边界，有助于开发者更安全地使用 AI 编程工具。
Read 先行：防止幻觉覆盖的强制机制
Write 工具要求对已存在的文件必须先使用 Read 工具读取，否则写入会失败。这一机制由 runtime 强制实施，旨在防止 AI 基于记忆或幻觉覆盖文件，确保任何写入都建立在对当前文件状态的感知之上。这种设计体现了工具的安全哲学：不依赖 AI 的自律，而是通过硬性约束保障操作的正确性。
不主动生产：Write 工具的行为约束
Write 工具的描述中明确禁止主动创建文档文件（如 README）或添加 emoji，除非用户明确要求。这些约束反映了对 AI 过度生产的担忧，避免生成大量无用文件污染项目。这种设计将“谨慎生产”的价值观编码到工具行为中，提醒开发者在使用 AI 工具时，应明确指定需求，避免默认行为带来的额外负担。
Q&A
Claude Code 中 Write 工具的主要作用是什么？
Write 工具用于创建新文件或完全重写已有文件，是唯一能新建文件的执行工具。它接受绝对路径和完整内容，将内容写入指定文件，若文件已存在则整体覆盖。
Write 工具和 Edit 工具在功能上有什么区别？
Write 用于新建文件或完全重写（改动占80%以上），Edit 用于增量修改（改动占20%以下）。Write 没有匹配安全网，风险更大；Edit 通过 old_string 匹配实现精准替换。两者是分工关系，不能互相替代。
为什么 Write 工具要求先 Read 文件？
为了防止幻觉覆盖，确保 Claude 基于文件当前的真实状态进行写入。如果文件已存在，必须先 Read 才能 Write，否则工具会报错。这是 runtime 强制执行的机制，与 Edit 共享同一套追踪状态。
Write 工具在什么情况下应该使用？
当用户明确要求新建文件（如添加组件、生成配置）、需要创建新模块、完全重写文件（改动占80%以上）、或生成 boilerplate 时使用。微调现有文件、重命名变量、修 typo 等场景应使用 Edit。
Write 工具为什么不自动创建父目录？
为了防止路径拼写错误导致散落目录，强制 Claude 明确目录结构意图。如果父目录不存在，Write 会报错，需要先用 Bash mkdir -p 创建。这样能避免悄悄创建错误目录，且报错更利于纠错。
Write 工具对创建文档和 emoji 有什么限制？
Write 工具明确禁止主动创建文档（*.md 或 README）和添加 emoji，除非用户明确要求。这是为了防止 AI 自动生成无用文件或在不合适的场合添加 emoji，属于描述层的软约束。
Write 工具在 schema 层和 runtime 层分别有哪些约束？
schema 层只有 file_path 和 content 两个必填字段，无其他硬约束。runtime 层有状态机：父目录必须存在、已存在文件必须本会话 Read 过、权限/磁盘/路径合法性检查。真正的安全约束都在 runtime 层。
