directive-synthesis

Claude Code 命令构建器

目的

引导用户创建结构合理的 Claude Code 斜杠命令，并妥善处理参数和工作流设计。当用户想要创建或修改自定义命令时自动调用。

何时使用

在用户提到以下内容时自动调用：

• 创建命令——“创建命令”“制作命令”“新建斜杠命令”
• 命令结构——“命令模板”“命令格式”“命令 frontmatter”
• 参数——“$ARGUMENTS”“$1”“$2”“命令参数”“位置参数”
• 工作流——“命令工作流”“命令步骤”“命令流程”
• Bash 执行——“!command”“在命令中执行 bash”“带 bash 的命令”

知识库

• 官方文档：.claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md
• 项目指南：.claude/docs/creating-components.md
• 仓库中的示例：.claude/commands/

流程

1. 收集需求

询问用户：

Let me help you create a Claude Code slash command! I need a few details:

1. **Command name** (lowercase-with-hyphens):
   Example: deploy, review-pr, commit, analyze-tokens
   This will be invoked as: /your-command-name

2. **What does this command do?**
   Describe the workflow in 1-2 sentences.

3. **Does it need arguments?**
   - None (simple prompt)
   - All arguments: $ARGUMENTS
   - Positional: $1, $2, $3, etc.

4. **Does it need bash execution?**
   Commands that run before the slash command (e.g., !`git status`)

5. **Scope:**
   - Personal (`~/.claude/commands/`) - just for you
   - Project (`.claude/commands/`) - shared with team

6. **Namespace/subdirectory?**
   Example: git/, deploy/, testing/
   Helps organize related commands

2. 验证输入

检查命令名称：

• 必须是有效的文件名（不能包含空格，除连字符外不能包含特殊字符）
• 描述清晰且易于记忆
• 不与内置命令冲突
• 使用连字符（而非下划线）

验证参数：

• 定义预期参数
• 按需提供默认值
• 说明参数顺序

3. 确定命令类型

简单提示词（无 frontmatter）：

Analyze this code for performance issues and suggest optimizations.

带参数：

---
argument-hint: [file-path]
description: Analyze file for performance issues
---

Analyze the file at $1 for performance issues and suggest optimizations.

带 Bash 执行：

---
allowed-tools: Bash(git status:*), Bash(git diff:*)
description: Create a git commit
---

## Current State

- Git status: !`git status`
- Staged changes: !`git diff --staged`
- Recent commits: !`git log --oneline -5`

## Your Task

Based on the above changes, create a git commit with a clear, conventional commit message.

功能齐全：

---
allowed-tools: Bash(npm run:*), Bash(git add:*), Bash(git commit:*)
argument-hint: [component-name]
description: Create a new React component with tests
model: sonnet
---

# Create React Component

Component name: $1

Execute the following workflow:

1. **Validate Input**
   !`test -n "$1" && echo "Creating component: $1" || echo "Error: Component name required"`

2. **Check Existing Files**
   !`ls src/components/$1.tsx 2>/dev/null || echo "Component does not exist"`

3. **Create Files**
   Create the following files:
   - `src/components/$1.tsx`
   - `src/components/$1.test.tsx`
   - `src/components/$1.module.css`

4. **Run Tests**
   After creation, run: !`npm run test -- $1`

4. 生成命令文件

根据复杂程度创建命令结构：

简单命令模板：

Brief description of what the command does.

[Prompt instructions for Claude]

带 frontmatter 的命令模板：

---
argument-hint: [arg1] [arg2]
description: Brief description shown in /help
allowed-tools: Bash(command:*), Read, Write
model: sonnet
disable-model-invocation: false
---

# Command Name

Usage: /command-name [args]

[Detailed instructions]

5. 构建命令工作流

将工作流组织成清晰的步骤：

Execute the following workflow:

1. **Step Name**
   ```bash
   # Bash command (if needed)
   command arg1 arg2

• 此步骤的作用
• 验证检查
• 错误处理

2. 下一步 [给 Claude 的指令]

   • 检查什么
   • 如何继续
   • 输出什么

3. 最后一步

   • 结果摘要
   • 用户接下来的操作
   • 成功标准

### 6. Add Argument Handling

**All Arguments ($ARGUMENTS):**
```markdown
Fix issue #$ARGUMENTS following our coding standards.

用户运行：/fix-issue 123 high-priority 变为：“按照我们的编码标准修复问题 #123 high-priority。”

位置参数（$1、$2、$3）：

Review PR #$1 with priority $2 and assign to $3.
Focus on: $4

用户运行：/review-pr 456 high alice security 这些参数会分别传入，可单独引用。

带默认值：

---
argument-hint: [environment] [branch]
---

Deploy to environment: ${1:-staging}
From branch: ${2:-main}

7. 添加 Bash 执行（如有需要）

使用 ! 前缀，在处理前执行命令：

---
allowed-tools: Bash(git:*)
---

## Context

- Current branch: !`git branch --show-current`
- Status: !`git status --short`
- Recent commits: !`git log --oneline -5`

## Your Task

[Instructions based on the above context]

重要：

• 必须通过 allowed-tools 指定具体的 Bash 权限
• 输出会包含在命令上下文中
• 命令会在 Claude 处理提示词之前运行

8. 添加文件引用

使用 @ 前缀引用文件：

Review the implementation in @src/utils/helpers.js

Compare @src/old-version.js with @src/new-version.js

Analyze all files in @src/components/

9. 配置思考模式（如有需要）

对于复杂问题，触发扩展思考：

Carefully analyze the following code and think through...

Let's approach this step by step...

Consider all edge cases before implementing...

这些关键词可以触发扩展思考模式。

10. 创建文件

将文件保存到正确的位置：

个人命令：

~/.claude/commands/command-name.md
~/.claude/commands/category/command-name.md  # With namespace

项目命令：

.claude/commands/command-name.md
.claude/commands/category/command-name.md  # With namespace

11. 测试命令

提供测试说明：

To test your command:
1. Restart Claude Code or start a new session
2. Type: /help
3. Find your command in the list
4. Try: /your-command-name [args]
5. Verify it behaves as expected

测试用例：

# No arguments
/your-command

# With arguments
/your-command arg1
/your-command arg1 arg2

# Edge cases
/your-command ""
/your-command "with spaces"

Frontmatter 参考

字段	用途	示例
argument-hint	在自动补全中显示预期参数	[pr-number] [priority]
description	在 /help 菜单中显示简短说明	Review pull request
allowed-tools	命令可使用的工具	Bash(git:*), Read, Write
model	指定要使用的模型	claude-sonnet-4-5-20250929
disable-model-invocation	阻止 SlashCommand 工具调用此命令	true

Bash 工具权限

使用 ! 前缀或需要执行 bash 时：

---
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git push:*)
---

权限模式：

• Bash(git:*)——所有 git 命令
• Bash(npm run:*)——所有 npm run 脚本
• Bash(git add:*), Bash(git commit:*)——特定 git 命令

参数模式

模式 1：所有参数

Run tests for: $ARGUMENTS

用法：/test users api database 变为：“运行以下内容的测试：users api database”

模式 2：位置参数

Deploy $1 to $2 environment with tag $3

用法：/deploy my-app staging v1.2.3 变为：“将 my-app 部署到 staging 环境，使用标签 v1.2.3”

模式 3：混合

---
argument-hint: <file> [rest of args]
---

Analyze file $1 for: $ARGUMENTS

用法：/analyze src/app.js performance security 结果："Analyze file src/app.js for: src/app.js performance security" 注意：$ARGUMENTS 包含所有参数，因此 $1 会重复

更好的方法：

Analyze file $1 for: ${2:+${@:2}}

此方法单独使用 $1，其余参数从 $2 开始

模式 4：带默认值

Environment: ${1:-production}
Verbose: ${2:-false}

命令大小指南

• ✅ 良好： 少于 100 行
• ⚠️ 警告： 100-150 行
• ❌ 过大： 超过 250 行（必须重构）

如果过大：

• 提取到外部脚本
• 拆分为多个命令
• 使用子命令模式

常见命令类型

1. Git 工作流

---
allowed-tools: Bash(git:*)
description: Create conventional commit
---

## Context
- Status: !`git status --short`
- Diff: !`git diff HEAD`

Create a conventional commit message.

2. 代码生成器

---
argument-hint: [component-name]
description: Generate React component
---

Create a new React component named $1:
- Component file
- Test file
- Storybook story

3. 分析工具

---
argument-hint: [file-path]
description: Analyze code complexity
---

Analyze @$1 for:
- Cyclomatic complexity
- Code smells
- Improvement suggestions

4. 部署助手

---
allowed-tools: Bash(npm:*), Bash(git:*)
argument-hint: [environment]
description: Deploy to environment
---

Deploy to ${1:-staging}:
1. Run tests: !`npm test`
2. Build: !`npm run build`
3. Deploy: !`npm run deploy:$1`

5. 文档生成器

---
argument-hint: [file-pattern]
description: Generate API documentation
---

Generate documentation for: $1
Include:
- Function signatures
- Parameters
- Return types
- Examples

TOON Formatter 示例

简单版本：

# Convert to TOON

Convert the specified JSON file to TOON v2.0 format with automatic optimization and show token savings.

Usage: /convert-to-toon <file>

使用 bash 的高级版本：

---
allowed-tools: Bash(jq:*), Bash(.claude/utils/toon/zig-out/bin/toon:*)
argument-hint: <file> [--delimiter comma|tab|pipe]
description: Convert JSON to TOON format
---

# Convert to TOON

File: $1
Delimiter: ${2:-comma}

1. **Validate**: !`test -f "$1" && jq empty "$1" 2>&1`
2. **Analyze**: !`jq 'if type == "array" then length else 0 end' "$1"`
3. **Convert**: !`.claude/utils/toon/zig-out/bin/toon encode "$1"`
4. Show savings comparison

故障排除

找不到命令

检查：

# List all commands
ls ~/.claude/commands/*.md
ls .claude/commands/*.md

# Verify filename
ls .claude/commands/your-command.md

请记住：

• 文件名（不含 .md）会成为命令名称
• 文件名中的连字符会保留为命令中的连字符
• 在 Linux/Mac 上区分大小写

参数不起作用

调试：

Debug: $ARGUMENTS
Debug $1: "$1"
Debug $2: "$2"

运行命令并检查输出，查看传入了哪些内容。

Bash 命令未执行

检查：

1. allowed-tools 包含正确的 Bash 权限
2. 使用 ! 前缀：!command``
3. 反引号正确：`command`，而不是 'command'
4. 权限允许执行该命令

命令未显示在 /help 中

可能的原因：

• 文件不在正确的位置
• 文件没有 .md 扩展名
• frontmatter 中存在语法错误
• 需要重启 Claude Code

最佳实践

应该：

✅ 提供清晰的参数提示 ✅ 包含用法示例 ✅ 妥善处理错误 ✅ 为耗时操作显示进度 ✅ 说明预期行为 ✅ 使用各种输入进行测试 ✅ 使用描述性命令名称

不应该：

❌ 让命令过于复杂（超过 250 行） ❌ 忘记为 Bash 指定 allowed-tools ❌ 使用含义不清的参数名称 ❌ 跳过错误处理 ❌ 对值进行硬编码（使用参数） ❌ 忘记测试边缘情况

对比：Commands 与 Skills

在以下情况下使用 Commands：

• 需要明确控制（手动调用）
• 简单、重复的提示词
• 特定工作流步骤
• 常用模板

在以下情况下使用 Skills：

• Claude 应自动检测需求
• 复杂的多文件工作流
• 全面的领域知识
• 团队需要标准化的专业知识

两者可以同时使用：

• Command 显式调用 skill
• Skill 自动激活
• Command 提供快速访问
• Skill 提供深度能力

资源

• 官方 Command 文档： .claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md
• 项目组件指南： .claude/docs/creating-components.md
• Command 示例： .claude/commands/ 目录
• Skills 与 Commands： slash-commands.md 中的章节