Claude 应用设计
让同一条指令在五种界面上仍有明确边界

Claude Code、Desktop、claude.ai、API 与 SDKs 都能承接自然语言需求，但它们接收的上下文、可用工具、持久配置与状态责任并不相同。本章不做产品导览，而是训练一个 developer 判断：同一项业务意图进入不同界面时，应用 contract 应怎样改写。

一、先选执行边界，再写提示词

「让 Claude 检查退款工单并修复问题」不是一个可直接搬运到所有界面的 instruction。它至少混合了四件事：读取工单、读取代码、提出判断、改变生产或仓库状态。界面只决定交互入口；真正的应用设计要回答：

1. 内容从哪里来：用户粘贴、项目知识、工作区文件，还是应用检索？
2. 动作在哪里执行：模型只返回文本，还是调用由宿主暴露的工具？
3. 状态由谁持有：当前 chat、项目配置、仓库文件，还是应用数据库？
4. 什么必须强制：schema 校验、权限、审批与副作用闸门由哪一层执行？

因此，跨界面迁移不是复制同一段 prompt，而是保持业务不变量，再重建该界面的 instruction source → content boundary → tool contract → state owner → validation 链。若先写 prompt、后补边界，最常见的结果就是把某个界面的隐式能力误当成所有界面的共同能力。

二、五种界面对照：同一句话进入了不同 contract

API 与 SDKs 容易被误画成两个能力层：前者像「底层」、后者像「自动 agent」。正确区分是，API 定义服务 contract，client SDK 提供语言侧调用接口；若要循环调用工具、保存状态或执行业务动作，仍须由应用明确实现。Claude Code、Desktop 与 claude.ai 则由各自宿主组装一部分上下文与能力，但 developer 仍不能越过可见边界做假设。

三、Content boundary：把「模型能看到什么」写成清单

系统里存在的数据，不等于本次推理可见的数据。一个可靠的 content boundary 至少包含五栏：

这张清单在不同界面落点不同：claude.ai Project 要区分单个 chat 与 project knowledge；API 应用要在每次 request 明确组装完整 conversation history 与本轮检索内容；Claude Code 要区分仓库内任务文件与机器上无关路径；Desktop 要以实际启用的 extension / connector 为准。共同原则是：显式提供才算上下文，授权可读也不代表应该读取。

四、Instruction source：稳定政策与本次任务分层

同一条规则放在不同位置，会得到不同的作用域与维护方式。设计时先按寿命分层，而不是把所有文字粘成一个超长 prompt：

在 Messages API 中，从开始就适用的 instruction 放在顶层 system 字段，不把它伪装成 messages 的第一条 system message；用户输入与后续对话属于 messages。在 Claude Code 中，仓库级约定可以落到根目录 CLAUDE.md，但本次 change 的范围、数据与完成条件仍要随当前请求说明。claude.ai 则要区分 Project instructions 与单个 chat 的任务内容。

分层的价值是可替换：业务政策变化时不必改 tool schema；换界面时可以保留同一组不变量，只把它们映射到新界面的 instruction source。若把审批、访问控制或金额上限只写进自然语言层，迁移时看似「提示词还在」，真正的控制却从未存在。

五、Schema design：把自由语言限制在合适的位置

在 API / SDK 应用中，tool definition 位于请求顶层 tools；input_schema 用 JSON Schema 描述预期参数，而 description 说明工具做什么、何时使用、如何表现。以只读工单查询为例：

{
  "name": "get_refund_case",
  "description": "Read one refund case after tenant authorization; never modify it.",
  "input_schema": {
    "type": "object",
    "properties": {
      "case_id": { "type": "string", "pattern": "^case-[0-9]+$" }
    },
    "required": ["case_id"],
    "additionalProperties": false
  }
}

一个好 schema 让合法形状窄而明确：required field、类型、枚举、格式与是否允许额外字段都有决定。description 补充 schema 难以表达的语义，例如「只读」「何时调用」「不存在时返回什么」。两者分工，不把可机器验证的约束全塞进 prose，也不指望 schema 说明全部业务语义。

但 schema 仍不是授权系统。Claude 返回结构化调用后，client tool 由应用执行；所以应用必须在执行点再次验证 tenant、actor、资源状态与审批证据。若工具会产生退款，较稳的 contract 是拆成 propose_refund 与受审批保护的 execute_refund，并让后者要求不可伪造的 approval token。模型选择哪个工具，不能替应用决定它是否有权成功。

六、Session hygiene：延续是选择，不是默认事实

Session hygiene 的目标不是「上下文越少越好」，而是防止旧假设、旧权限与旧数据悄悄进入新任务。恢复一个 session 前应核对：目标是否仍相同、输入是否过期、工具权限是否变化、先前未完成动作是否可能重放。新 session 也不等于删除外部系统记录；对话边界、业务状态与审计保留是三件不同的事。

1. 把长期真相外部化到可版本化、可审计的来源；
2. 把本次选择过的上下文与来源版本记入 trace；
3. 对具有副作用的 tool result 使用稳定 operation ID，恢复时先查状态再决定是否重试；
4. 在 tenant、仓库、目标或 operator 改变时建立清晰的新边界。

七、Plugin 与 connector 管理：安装是供应链决定

Claude Code plugin 可以包含 skills、agents、hooks 与 MCP servers。它不是一段孤立提示词，而是可能同时改变 instruction、tool surface 与运行时行为的扩展包。因此管理对象至少要记录：来源、版本、包含组件、可访问资源、启用范围、owner、升级验证与撤销路径。

Marketplace 是发现渠道，不是自动授权渠道：把 marketplace 加入 Claude Code 只登记 catalog，尚未安装其中的 plugin。应用设计应保留这两个独立决策——先决定信任哪个 catalog，再逐个审查和安装所需 plugin。把「能浏览」误当「已安装」，或把「已安装」误当「可无条件执行」，都会把可见性、部署状态与权限混成一层。

Desktop extension 运行在本机，并只在 Claude Desktop 与 Claude Code 可用；这使它适合承接明确需要本机资源的能力，也意味着它的本地访问面必须被单独审查。跨界面方案不能写成「所有 Claude 界面都调用这个 desktop extension」；若同一业务还要支持 claude.ai 或 API，应另行设计可用的远程服务或 client tool contract，并保持相同授权规则。

八、迁移演练：保留不变量，重写界面适配

考虑一条跨界面需求：「读取退款工单与 policy，判断是否需要代码修复；任何资金动作都必须人工批准。」不变量是内容按 tenant 隔离、结论可追溯、代码变更可审查、资金执行有强制审批。五种界面的落法不同：

做题时可以按四问裁决：需要宿主文件系统吗？需要可强制的工具动作吗？状态要跨请求或跨 chat 吗？稳定指令应由谁维护？答案决定界面与适配层。若一个选项只是把原 prompt 原样复制到新界面，却没有重建内容、schema、session 与 plugin 边界，它通常只保留了文字，没有保留应用 contract。

本章题组