斜杠命令设计与意图映射

斜杠命令设计与意图映射

学习目标

• 理解 7 个斜杠命令与开发阶段的映射关系
• 掌握 /ship 的并行扇出实现细节
• 理解 OpenCode 的意图映射如何替代斜杠命令
• 学会应用生命周期映射（Implicit Commands）

前置知识

本章涉及多 Agent 路由与编排模式的通用原理，建议先阅读：

• 多 Agent 路由与隔离

下文直接聚焦 agent-skills 的具体斜杠命令实现。

项目实践

7 个命令与开发阶段的映射

agent-skills 定义了 7 个斜杠命令，覆盖完整开发生命周期：

/
│
├── /spec          → Define 阶段
│                    规格文档：Objective, Commands, Structure, Style, Testing, Boundaries
│
├── /plan          → Plan 阶段
│                    将规格分解为可验证的任务块
│
├── /build         → Build 阶段
│                    incremental-implementation + test-driven-development
│
├── /test          → Verify 阶段
│                    test-driven-development + browser-testing-with-devtools
│
├── /review        → Review 阶段
│                    code-review-and-quality（五轴审查）
│
├── /code-simplify → Review 阶段
│                    code-simplification（保留行为减少复杂度）
│
└── /ship          → Ship 阶段
                     并行扇出 3 个角色 → 合并 → go/no-go 决策

每个命令的职责：

命令	包装的 Persona	包装的 Skill	一句话
/spec	无（直接执行）	spec-driven-development	写规格再写代码
/plan	无（直接执行）	planning-and-task-breakdown	将规格分解为任务
/build	无（直接执行）	incremental-implementation	薄垂直切片，逐片实现
/test	test-engineer	test-driven-development	先失败的测试
/review	code-reviewer	code-review-and-quality	五轴审查
/code-simplify	无（直接执行）	code-simplification	减少不必要的复杂度
/ship	3 个角色并行	shipping-and-launch	发布前全面审查

/ship 的并行扇出实现

/ship 是 agent-skills 中唯一的并行扇出命令。其实现关键点：

/ship
  ├── (parallel) code-reviewer    → 审查报告
  ├── (parallel) security-auditor → 安全审计报告
  └── (parallel) test-engineer    → 覆盖率报告
                  ↓
        合并阶段（主 Agent）
                  ↓
        go/no-go 决策 + 回滚计划

关键技术细节：在 Claude Code 中，平行扇出要求在单个 assistant turn 中多次调用 Agent tool call。顺序调用会序列化执行，失去并行性。

✅ 正确（并行）：
[Agent tool call: code-reviewer]
[Agent tool call: security-auditor]   ← 同一 turn 中
[Agent tool call: test-engineer]      ← 同一 turn 中

❌ 错误（序列化）：
Turn 1: [Agent tool call: code-reviewer] → 等待结果
Turn 2: [Agent tool call: security-auditor] → 等待结果
Turn 3: [Agent tool call: test-engineer] → 等待结果

成本期望：3 个并行子 Agent 上下文 + 1 次合并轮次。高于直接调用，但墙时钟更短（3 个角色同时工作），且每个子 Agent 保持在其单一视角上。

Gemini CLI 命令镜像

agent-skills 在 .gemini/commands/ 中提供了 7 个等价命令的 Gemini CLI 版本。这确保了使用 Gemini CLI 的用户也能获得相同的开发工作流。

OpenCode 的意图映射

OpenCode 不支持斜杠命令。agent-skills 通过 AGENTS.md 中的意图映射实现等价功能：

# AGENTS.md 中的意图映射

Feature / new functionality → spec-driven-development, then incremental-implementation, test-driven-development
Planning / breakdown → planning-and-task-breakdown
Bug / failure / unexpected behavior → debugging-and-error-recovery
Code review → code-review-and-quality
Refactoring / simplification → code-simplification
API or interface design → api-and-interface-design
UI work → frontend-ui-engineering

生命周期隐式映射（OpenCode 内部执行）：

DEFINE → spec-driven-development
PLAN   → planning-and-task-breakdown
BUILD  → incremental-implementation + test-driven-development
VERIFY → debugging-and-error-recovery
REVIEW → code-review-and-quality
SHIP   → shipping-and-launch

用户不需要输入 /spec 等命令——Agent 根据请求的意图自动映射到对应技能。

问题与规避

陷阱	表现	对策
顺序调用代替并行	/ship 变慢 3 倍	确保同一 turn 中多次 Agent tool call
命令职责重叠	用户不确定用哪个命令	每个命令对应唯一的开发阶段
命令体过重	命令文件变成另一个 Skill	命令只负责触发 Persona 和 Skill，不编码工作流
意图映射过宽	”任何文件修改”都触发 Skill	细化意图描述，如 “Feature / new functionality”

设计取舍

为什么 /ship 是唯一的并行扇出命令？

并行扇出的前提是子任务独立（无共享可变状态、无顺序依赖）。在开发生命周期中，只有发布前的审查满足这个条件——代码审查、安全审计和测试覆盖分析可以完全独立进行。其他命令（如 spec → plan → build）有严格的顺序依赖，不能并行。

为什么不是所有工具链都支持斜杠命令？

斜杠命令是 Claude Code 和 Gemini CLI 的特性。Cursor、Windsurf、Copilot 等工具使用不同的指令加载机制。agent-skills 通过提供适配指南（docs/ 目录）而非强制统一机制，确保了最大的兼容性。

参考来源

• 源码验证: .claude/commands/ship.md — 并行扇出的实现
• 源码验证: .claude/commands/*.md — 7 个斜杠命令的定义
• 源码验证: AGENTS.md — OpenCode 的意图映射和生命周期映射
• 源码验证: references/orchestration-patterns.md — 编排模式目录中的并行扇出模式