Claude-Code-Workflow/COMMAND_FLOW_STANDARD.md

Command Flow Expression Standard

用途：规范命令文档中Task、SlashCommand、Skill和Bash调用的标准表达方式

版本：v2.1.0

---

核心原则

1. 统一格式 - 所有调用使用标准化格式
2. 清晰参数 - 必需参数明确标注，可选参数加方括号
3. 减少冗余 - 避免不必要的echo命令和管道操作
4. 工具优先 - 优先使用专用工具（Write/Read/Edit）而非Bash变通
5. 可读性 - 保持缩进和换行的一致性

---

1. Task调用标准（Agent启动）

标准格式

Task(
  subagent_type="agent-type",
  description="Brief description",
  prompt=`
FULL TASK PROMPT HERE
  `
)

规范要求

• subagent_type: Agent类型（字符串）
• description: 简短描述（5-10词，动词开头）
• prompt: 完整任务提示（使用反引号包裹多行内容）
• 参数字段缩进2空格

正确示例

// CLI执行agent
Task(
  subagent_type="cli-execution-agent",
  description="Analyze codebase patterns",
  prompt=`
PURPOSE: Identify code patterns for refactoring
TASK: Scan project files and extract common patterns
MODE: analysis
CONTEXT: @src/**/*
EXPECTED: Pattern list with usage examples
  `
)

// 代码开发agent
Task(
  subagent_type="code-developer",
  description="Implement authentication module",
  prompt=`
GOAL: Build JWT-based authentication
SCOPE: User login, token validation, session management
CONTEXT: @src/auth/**/* @CLAUDE.md
  `
)

---

2. SlashCommand调用标准

标准格式

SlashCommand(command="/category:command-name [flags] arguments")

规范要求

单行调用 | 双引号包裹 | 完整路径/category:command-name | 参数顺序: 标志→参数值

正确示例

// 无参数
SlashCommand(command="/workflow:status")

// 带标志和参数
SlashCommand(command="/workflow:session:start --auto \"task description\"")

// 变量替换
SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"description\"")

// 多个标志
SlashCommand(command="/workflow:plan --agent --cli-execute \"feature description\"")

---

3. Skill调用标准

标准格式

Skill(command: "skill-name")

规范要求

单行调用 | 冒号语法command: | 双引号包裹skill-name

正确示例

// 项目SKILL
Skill(command: "claude_dms3")

// 技术栈SKILL
Skill(command: "react-dev")

// 工作流SKILL
Skill(command: "workflow-progress")

// 变量替换
Skill(command: "${skill_name}")

---

4. Bash命令标准

核心原则：优先使用专用工具

工具优先级:

1. Write工具 → 创建/覆盖文件内容
2. Edit工具 → 修改现有文件内容
3. Read工具 → 读取文件内容
4. Bash命令 → 仅用于真正的系统操作（git, npm, test等）

标准格式

bash(command args)

合理使用Bash的场景

// ✅ Git操作
bash(git status --short)
bash(git commit -m "commit message")

// ✅ 包管理器和测试
bash(npm install)
bash(npm test)

// ✅ 文件系统查询和文本处理
bash(find .workflow -name "*.json" -type f)
bash(rg "pattern" --type js --files-with-matches)

避免Bash的场景

// ❌ 文件创建/写入 → 使用Write工具
bash(echo "content" > file.txt)  // 错误
Write({file_path: "file.txt", content: "content"})  // 正确

// ❌ 文件读取 → 使用Read工具
bash(cat file.txt)  // 错误
Read({file_path: "file.txt"})  // 正确

// ❌ 简单字符串处理 → 在代码中处理
bash(echo "text" | tr '[:upper:]' '[:lower:]')  // 错误
"text".toLowerCase()  // 正确

---

5. 组合调用模式（伪代码准则）

核心准则

直接写执行逻辑（无FUNCTION/END包裹）| 用#注释分段 | 变量赋值variable = value | 条件IF/ELSE | 循环FOR | 验证VALIDATE | 错误ERROR + EXIT 1

顺序调用（依赖关系）

# Phase 1-2: Session and Context
sessionId = SlashCommand(command="/workflow:session:start --auto \"description\"")
PARSE sessionId from output
VALIDATE: bash(test -d .workflow/{sessionId})

contextPath = SlashCommand(command="/workflow:tools:context-gather --session {sessionId} \"desc\"")
context_json = READ(contextPath)

# Phase 3-4: Conditional and Agent
IF context_json.conflict_risk IN ["medium", "high"]:
    SlashCommand(command="/workflow:tools:conflict-resolution --session {sessionId}")

Task(subagent_type="action-planning-agent", description="Generate tasks", prompt=`SESSION: {sessionId}`)

VALIDATE: bash(test -f .workflow/{sessionId}/IMPL_PLAN.md)
RETURN summary

并行调用（无依赖）

PARALLEL_START:
    check_git = bash(git status)
    check_count = bash(find .workflow -name "*.json" | wc -l)
    check_skill = Skill(command: "project-name")
WAIT_ALL_COMPLETE
VALIDATE results
RETURN summary

条件分支调用

IF task_type CONTAINS "test": agent = "test-fix-agent"
ELSE IF task_type CONTAINS "implement": agent = "code-developer"
ELSE: agent = "universal-executor"

Skill(command: "project-name")
Task(subagent_type=agent, description="Execute task", prompt=build_prompt(task_type))
VALIDATE output
RETURN result

---

6. 变量和占位符规范

上下文	格式	示例
Markdown说明	[variableName]	[sessionId], [contextPath]
JavaScript代码	${variableName}	${sessionId}, ${contextPath}
Bash命令	$variable	$session_id, $context_path

---

7. 快速检查清单

Task: subagent_type已指定 | description≤10词 | prompt用反引号 | 缩进2空格

SlashCommand: 完整路径 /category:command | 标志在前 | 变量用[var] | 双引号包裹

Skill: 冒号语法 command: | 双引号包裹 | 单行格式

Bash: 能用Write/Edit/Read工具吗？| 避免不必要echo | 真正的系统操作

---

8. 常见错误及修复

// ❌ 错误1: Bash中不必要的echo
bash(echo '{"status":"active"}' > status.json)
// ✅ 正确: 使用Write工具
Write({file_path: "status.json", content: '{"status":"active"}'})

// ❌ 错误2: Task单行格式
Task(subagent_type="agent", description="Do task", prompt=`...`)
// ✅ 正确: 多行格式
Task(subagent_type="agent", description="Do task", prompt=`...`)

// ❌ 错误3: Skill使用等号
Skill(command="skill-name")
// ✅ 正确: 使用冒号
Skill(command: "skill-name")