Dual-Use Tool Design

为人类与AI Agent分别构建工具会引发以下问题：

• 维护开销：需实现两套功能相近的方案
• 行为不一致：面向人类的工具与面向Agent的工具运作方式存在差异
• 学习成本：用户需学习一套界面，Agent则需适配另一套
• 功能漂移：人类工具与Agent工具的能力会随时间逐渐分化
• 测试负担：必须分别对两套界面进行验证

设计所有工具时遵循双用原则——对人类和AI Agent均保持同等的可访问性与实用性。当人类可以手动调用某一工具时，Agent应能通过编程方式调用它，反之亦然。

核心原则：「你能做的所有事，Claude都能做。二者之间没有中间地带。」

双用工具的关键特征：

1. 统一界面：人类与Agent使用完全相同的API/命令
2. 共享逻辑：一套实现同时服务两种使用场景
3. 可组合性：工具可由人类或Agent链式调用
4. 可观测性：双方能看到完全一致的输出（透明性）
5. 单次文档化：行为说明仅有单一事实来源

# 双用斜杠命令示例
define_slash_command("/commit") {
    steps: [
        "运行linters（代码检查工具）",
        "从git diff生成提交信息",
        "以标准格式创建提交"
    ],
    callable_by: ["human", "agent"],
    pre_allowed_tools: ["git add", "git commit"],
    model: "haiku"  # 人类与Agent共用同一模型
}

# 人类调用方式
$ /commit

# Agent调用方式
agent.call_slash_command("/commit")

设计原则：

1. 以人类易用性为核心：对人类而言合理的设计，通常对Agent同样合理
2. 所有功能可脚本化：人类能点击操作的功能，Agent也应能调用
3. 共享状态可见性：人类与Agent可查看相同的终端输出、文件变更等内容
4. 权限一致性：二者遵循相同的安全规则

Claude Code 实现示例：

• 斜杠命令：/commit、/pr、/feature-dev 既可手动执行，也可在Agent流程中运行
• 钩子（Hooks）：人类可手动触发钩子，Agent则可自动触发
• Bash模式：!command 命令在同一终端中对人类和Agent均可见
• 权限控制：预授权工具无论由人类还是Agent调用，工作机制完全一致

实践验证的优势：

“这种以人为中心的优雅设计，能很好地适配模型。”——鲍里斯·切尔尼（Boris Cherny）

优点：

• 维护成本降低：一套工具实现可同时服务两类受众
• 行为一致性：无论由人类还是Agent调用，行为完全一致
• 改进成果共享：优化升级可同时惠及两种使用场景
• 测试更简便：单一测试套件即可验证两条调用路径
• 用户体验提升：人类可手动复刻Agent的工作流
• 透明度增强：Agent使用的是人类所熟悉的同款可观测工具

缺点：

• 设计存在约束：必须同时兼顾人类使用的人机工程学要求与API的简洁性标准
• 可能制约优化空间：单独设计工具能够实现更精准的专业化
• 边缘场景处理复杂：部分行为可能需要添加条件逻辑
• 文档编写难度大：必须清晰说明工具的双重使用方式