best-practices

# 命令最佳实践 本文档提供了创建有效斜杠命令的质量指南、写作风格建议、常见陷阱以及详细的模板结构。 ## 命令写作风格 命令由 AI 智能体执行，因此请针对自主执行进行优化。 ### 写作形式 **始终使用祈使句/不定式形式**（动词优先指令），不要使用第二人称。 markdown ✅ 正确： - "运行 git status 以检查当前分支" - "在继续之前检查 .PLAN.md 是否存在" - "将 Task 工具与 Bash 工具结合使用" ❌ 错误： - "你应该运行 git status" - "你需要检查 .PLAN.md 是否存在" - "你会想要使用 Task 工具" ### 具体性 要明确且具体，不要含糊。 markdown ✅ 正确： - "运行 make lint 以检查 lint 错误" - "读取 src/config.py 第 45-67 行以了解配置结构" - "使用 Edit 工具将 'List[str]' 替换为 'list[str]'" ❌ 错误： - "检查错误" - "查看配置文件" - "修复类型注解" ### 预期结果 包含每个操作后应该发生什么。 markdown ✅ 正确： - "运行 git status - 这应该显示 src/ 目录中已修改的文件" - "运行 make format 后，所有 Python 文件都应被格式化" - "输出应包含每个已提交分支的 PR URL" ❌ 错误： - "运行 git status" - "运行 make format" - "提交 PR" ### 具体示例 提供现实的示例，而不是 foo/bar 这样的占位符。 markdown ✅ 正确： - "示例：`git commit -m 'Add user authentication with OAuth2'`" - "示例：`/submit-stack 'Implement caching for API responses'`" - "如果显示错误：`src/erk/cli/commands/init.py:45: Type error`" ❌ 错误： - "示例：`git commit -m 'foo bar'`" - "示例：`/submit-stack 'something'`" - "如果显示错误：`file.py:123: Error message`" ## 模板结构 使用此模板结构来创建全面的命令： markdown --- description: [/help 输出的一行描述] argument-hint: [] 或 [[optional]] (如果没有参数则省略) --- # [命令标题] [1-2 句关于此命令功能的概述] ## 此命令的功能 [主要步骤的编号列表，面向用户的描述] 1. **[第一步操作]**: [功能描述] 2. **[第二步操作]**: [功能描述] 3. **[第三步操作]**: [功能描述] ## 用法 bash # [带参数的示例] /command-name "argument example" # [可选参数时不带参数的示例] /command-name ## 实现