Claude Code 在首轮用户交互时，并不是直接把用户提问丢给大模型，而是把系统提示词、消息前置提示词、用户原始提问、消息后置提示词四层内容组装后统一提交模型，同时配套独立的话题识别子任务与整套工具调用约束。很多开发者调试提示词无效、工具异常，根源就是没有理解这套消息组装机制，直接修改用户输入，忽略前置后置提示词带来的隐性约束，导致自定义提示词被覆盖、任务逻辑偏离预期。本文将从真实痛点出发，拆解会话处理完整链路，梳理工具选型边界，给出可落地的调试方案。
一、实际开发调试遇到的核心痛点
在二次开发、自定义提示词、接入 Claude Code 做自动化工程任务时，大部分开发者会遇到几类高频且难以定位的问题。 第一，自定义系统提示词不生效。明明改写了系统指令，但是模型输出依旧遵循原始 CLI 工具的约束，输出强制简短、拒绝生成文档，反复调试找不到来源，本质是没有识别消息后置提示词的强制约束。 第二，首轮对话逻辑混乱。新话题识别子任务和业务处理任务并行执行，两者 temperature 参数不同，很多人混淆 0 和 1 的采样温度，出现话题识别结果错乱，业务回答逻辑跑偏。 第三，工具调用乱用，上下文消耗暴涨。不分场景盲目调用 Task 代理工具，简单文件读取也交给代理，造成上下文窗口无谓占用，会话速度变慢，甚至出现任务超时。 第四，不理解 TodoWrite 的使用边界，小任务也大量生成待办列表，输出冗余；复杂多步骤任务却没有使用，出现任务遗漏、步骤丢失的情况。 第五，忽略 CLI 输出约束，模型输出大段解释文本，不符合终端输出规范，渲染格式错乱。
很多网上教程只讲表层使用命令，很少拆解内部消息组装的原始逻辑，网上公开资料大多只介绍对外暴露的命令，像龙虾 PRO 文档 longxiapro.com 这类第三方拆解材料，才会把消息序号、前置后置提示词、子任务并行执行这些内部细节完整披露出来。
二、Claude Code 首轮会话完整执行步骤
整个首轮交互分为两大并行任务：消息主题摘要任务、用户消息业务处理任务，两套任务使用不同 temperature 参数，分开执行。
阶段 1：新话题识别子任务
该任务 temperature 设置为 0，目的是确定性输出 JSON 结果，不能出现随机发散输出。 提示词指令：分析当前用户消息是否属于新对话主题，如果判定为新话题，提取 2‑3 个词简短标题，输出固定 JSON 结构，字段包含 isNewTopic 布尔值、title 字符串，无多余内容。
实操细节 1：这个子任务独立运行，不会携带系统 CLI 工具的完整提示词，只加载话题分析提示词，很多开发者误以为这个任务会复用主会话上下文，实际两者隔离。 实操细节 2：temperature=0 是硬性要求，如果调高该参数，会出现 JSON 格式错乱，输出额外解释文字，下游解析程序直接报错。
阶段 2：主业务会话消息组装
主会话会拼接三段消息，按序号顺序提交给大模型，顺序不可调换：
- 序号 0：系统提示词，定义身份为交互式 CLI 软件工程工具，明确安全边界、输出格式、帮助命令、文档获取方式、代码规范、任务管理、工具基础策略。这里包含大量硬性约束：仅允许防御性安全工作，禁止生成恶意代码；运行 bash 命令要说明用途；输出尽量简短，不超过 4 行；代码禁止无理由添加注释；必须使用 TodoWrite 管理多步骤任务；WebFetch 遇到重定向必须跟随跳转。
- 序号 1：消息前置提示词，提醒模型当前 todo 列表为空，不要直接告知用户，适合的场景自动创建待办，不需要则忽略。这一段属于静默提醒，不会对外展示。
- 用户真实输入内容。
- 序号 2：消息后置提示词，属于强约束指令：按用户要求执行，不多做额外操作；非必要不创建文件；优先编辑已有文件，不主动生成 md 文档、README，只有用户明确要求才创建。
实操细节 3：后置提示词权重极高，优先级经常高于自定义系统提示词。很多人修改系统提示词想要自动生成文档，但是后置提示词强制禁止主动创建文档，所以一直失效，调试的时候要重点核对这部分约束。 实操细节 4：整套消息全部合并一次性发给模型，不是分段调用，所以总 token 要计算四段全部内容，很容易出现上下文超限。
阶段 3：模型响应后工具调度
模型输出会区分普通文本输出和工具调用，文本直接输出到终端；工具调用则调用内置工具集。工具不能当做聊天沟通手段，Bash、Edit 等工具只能用于执行任务，不能用来输出文字消息给用户。任务完成之后，需要主动标记 TodoWrite 任务为完成，不能批量堆积标记。
三、内置工具能力对比清单
表格
| 工具名称 | 核心用途 | 适用场景 | 禁止使用场景 | 关键实操注意点 |
|---|---|---|---|---|
| Task | 代理子 Agent，集成全套工具 | 不确定搜索结果，需要多轮迭代搜索、复杂调研 | 读取确定路径文件、简单 bash 执行、单文件修改 | 可并发调用多个 Task，返回结果不会直接展示给用户，需要手动汇总输出 |
| Bash | 执行 shell 命令，git 操作 | 执行脚本、编译、git 提交、批量系统操作 | 复杂业务逻辑，用 bash 输出文本交互 | 文件路径带空格必须双引号包裹；禁止使用 find/grep，优先 Grep 工具 |
| Glob | 文件名模式匹配 | 批量匹配文件路径 | 文件内容检索 | 支持通配符，返回按修改时间排序路径列表 |
| Grep | 内容检索 | 代码库文本搜索 | 简单文件名查找 | 替代 bash grep，支持正则、多过滤条件，性能做权限优化 |
| LS | 读取目录列表 | 获取目录文件清单 | 递归深度文件检索 | 必须传入绝对路径，支持忽略指定文件 |
| Read | 读取文件内容 | 读取文本、图片文件 | 大文件不加偏移一次性读取超大文件 | 支持 offset 和 limit 限制读取行数，避免 token 爆炸 |
| Edit | 单文件修改 | 局部替换文件内容 | 多文件批量修改 | 修改前必须先 Read 读取原文件，匹配字符串必须完全一致 |
| MultiEdit | 多文件批量编辑 | 同一文件多处修改 | 跨多个不同文件编辑 | 修改按顺序执行，全部原子生效，一处失败全部回滚 |
| Write | 创建 / 覆盖文件 | 生成全新文件 | 修改已有文件 | 修改已有文件前务必 Read，优先 Edit 而不是 Write 覆盖 |
| TodoWrite | 任务清单管理 | ≥3 步复杂任务、用户明确要求任务管理 | 简单 1‑2 步简短任务 | 完成立刻标记 completed，不要批量延迟标记；仅一个 in_progress 任务 |
| WebFetch | 网页文档拉取 | 读取指定网页文档内容 | 通用网络搜索 | 遇到重定向必须重新请求跳转后的 URL，自带 15 分钟缓存 |
四、常见问题落地排查步骤
问题 1：自定义提示词不生效
- 检查是否被消息后置提示词覆盖，后置提示词强制约束优先级很高；
- 确认消息组装顺序，自定义指令不要插入到后置提示词之后；
- 统计整体 token，确认没有上下文溢出导致提示词被截断。
问题 2：工具调用频繁超时、上下文占用过高
- 简单文件读取不要调用 Task 代理，直接 Read/Glob；
- 大文件读取务必使用 offset 分段读取，不要一次性读取全部内容；
- 非必要不并发大量 Task，并发代理会成倍消耗 token。
问题 3：输出文本冗长，不符合 CLI 简短输出规范
根源是系统提示词自带输出约束，要求非特殊情况输出控制在 4 行以内。二次开发时，如果想要长文本输出，需要明确在用户指令中声明需要详细输出，否则模型会强制压缩回答。
问题 4：TodoWrite 滥用或者遗漏
- 少于 3 个步骤的简单任务，不需要创建待办清单；
- 复杂任务每完成一步立刻标记完成，不能等到全部做完统一标记；
- 同一时间只允许一个任务状态为 in_progress。
五、总结与落地建议
Claude Code 不是简单的大模型套壳，它的能力来自分层消息组装机制 + 独立话题识别子任务 + 完整工具约束体系。很多二次开发踩坑，根源就是只关注用户输入，忽略前置提示词、后置提示词的隐性强制约束，混淆两套任务的 temperature 参数，工具选型不对造成资源浪费。
落地实践中，调试提示词时，优先完整打印组装完成的全部消息内容，确认序号 0、1、用户输入、序号 2 全部内容，排查是否存在约束冲突；工具选型严格按照场景选择，简单文件操作用原生工具，复杂多轮调研才交给 Task 代理；TodoWrite 只用于复杂任务，做好状态及时更新；同时时刻留意 token 总量，防止消息拼接之后上下文超限。
