create-command

创建命令

为 code-forge 应用创建和管理命令。命令是模块化工作流，可调用以执行特定任务。

文件位置

重要：所有命令文件都必须创建在 <cwd>/.forge/commands 目录中，其中 <cwd> 是 code-forge 项目的当前工作目录。

• 目录：<cwd>/.forge/commands
• 文件格式：{command-name}.md
• 示例：如果项目位于 /home/user/my-project，命令文件应放在 /home/user/my-project/.forge/commands/

这是 forge 发现和加载自定义命令的唯一位置。

命令文件结构

每个命令文件都必须包含：

1. YAML Frontmatter（必需）：

   • name：命令标识符（多词名称使用连字符）
   • description：命令的功能

2. 命令正文（必需）：

   • 要执行的步骤列表
   • 用于自动化工作流的特殊标签
   • 每个步骤的明确说明

命令文件示例

---
name: check
description: Checks if the code is ready to be committed
---

- Run the `lint` and `test` commands and verify if everything is fine.
  <lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>
  <test>cargo insta test --accept --unreferenced=delete</test>
- Fix every issue found in the process

完整命令示例

此示例展示了全部三种标签类型：

---
name: sample-command
description: Sample command demonstrating the command file structure
---

This is a sample command that demonstrates the structure of command files.

- First step: Perform an initial action
  <lint>echo "Running linting..."</lint>
- Second step: Execute tests
  <test>echo "Running tests..."</test>
- Third step: Complete the workflow
  <shell>echo "Workflow complete!"</shell>
- Final step: Verify everything worked correctly

创建新命令

第 1 步：确定命令用途

确定命令应完成什么任务：

• 它要执行什么任务？
• 涉及哪些步骤？
• 是否需要自动检查或测试？
• 用户应如何处理结果？

第 2 步：选择命令名称

使用动词形式的名称；多词命令使用连字符：

• 推荐：check、fixme、pr-description、run-tests
• 不推荐：checker、fixing、PRdescription

第 3 步：编写命令文件

在 <cwd>/.forge/commands 目录中创建文件，格式为：{command-name}.md

重要：文件必须位于 <cwd>/.forge/commands 中，其中 <cwd> 是当前工作目录。放在其他位置的命令不会被 forge 发现。

Frontmatter

---
name: your-command-name
description: Clear, concise description of what this command does
---

命令正文

使用 Markdown 列表列出步骤。每个步骤都应：

• 以明确的动作动词开头
• 具体且可执行
• 包含要执行操作的背景信息

特殊命令标签

将这些标签用于自动化工作流：

<lint> 标签

用于 lint/格式化命令：

<lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>

<test> 标签

用于测试命令：

<test>cargo insta test --accept --unreferenced=delete</test>

<shell> 标签

用于一般 shell 命令（非 lint 或测试命令）：

<shell>rm -rf target/debug</shell>

使用标签

标签应放在步骤说明之后的单独一行：

- Run linting and testing
  <lint>your-lint-command</lint>
  <test>your-test-command</test>

命令类型

简单命令

单步命令或仅包含说明的命令：

---
name: fixme
description: Looks for all the fixme comments in the code and attempts to fix them
---

Find all the FIXME comments in source-code files and attempt to fix them.

多步骤命令

包含多个连续步骤的命令：

---
name: pr-description
description: Updates the description of the PR
---

- I have created a Pull Request with all the accepted changes
- Understand the current PR deeply using the GH CLI and update the PR title and description
- Make sure the title follows conventional commits standard
- Top-level summary should contain 2-3 lines about the core functionality improvements

自动化工作流命令

包含自动检查的命令：

---
name: check
description: Checks if the code is ready to be committed
---

- Run the `lint` and `test` commands and verify if everything is fine.
  <lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>
  <test>cargo insta test --accept --unreferenced=delete</test>
- Fix every issue found in the process

命令模板

简单命令模板

---
name: simple-command
description: Does one specific thing
---

Single clear instruction or description.

自动化工作流模板

---
name: automated-workflow
description: Runs automated checks and performs follow-up actions
---

- Run automated checks
  <lint>your-lint-command</lint>
  <test>your-test-command</test>
- Review and fix any issues found
- Complete the workflow

多步骤工作流模板

---
name: multi-step-workflow
description: Performs multiple sequential steps
---

- First step with clear action
- Second step with context
- Third step with specific requirements
- Final step with verification

Git 工作流模板

---
name: git-workflow
description: Performs git operations
---

- Stage changes
  <shell>git add .</shell>
- Run pre-commit checks
  <lint>cargo fmt --all</lint>
  <test>cargo test</test>
- Commit with message
  <shell>git commit -m "your commit message"</shell>
- Push to remote
  <shell>git push</shell>

最佳实践

命名

• 使用小写字母
• 使用连字符分隔单词
• 使用动词形式的名称（祈使形式）
• 名称应简短且具有描述性

描述

• 清晰简洁
• 描述命令的功能，而非实现方式
• 说明主要用途和关键结果
• 避免实现细节

命令步骤

• 连续步骤使用编号列表
• 每个步骤都以动作动词开头
• 明确说明要执行的操作
• 复杂步骤应包含背景信息
• 使用现在时

特殊标签

• 将标签放在步骤之后的单独一行
• 仅使用 <lint>、<test> 和 <shell> 标签
• 包含可执行的完整命令
• 使用适合工作流的标志

常见模式

Git 工作流命令

---
name: commit-check
description: Verifies code is ready to commit
---

- Run linting and tests
  <lint>cargo fmt --all; cargo clippy --fix --allow-staged</lint>
  <test>cargo test</test>
- Review and fix any issues
- Stage all changes

文档命令

---
name: update-docs
description: Updates documentation for recent changes
---

- Review recent code changes
- Identify functions or modules that need documentation
- Update inline documentation comments
- Regenerate any auto-generated docs
- Verify documentation builds successfully

清理命令

---
name: cleanup
description: Cleans up temporary files and artifacts
---

- Remove build artifacts
  <shell>rm -rf target/debug</shell>
- Remove temporary files
  <shell>find . -name "*.tmp" -delete</shell>
- Clean up dependency caches if needed
- Verify the project still builds

构建和部署命令

---
name: build-deploy
description: Builds the project and deploys to staging
---

- Build the project in release mode
  <shell>cargo build --release</shell>
- Run integration tests
  <test>cargo test --test integration</test>
- Build Docker image
  <shell>docker build -t myapp:latest .</shell>
- Tag image for staging
  <shell>docker tag myapp:latest myapp:staging</shell>
- Push to registry
  <shell>docker push myapp:staging</shell>
- Deploy to staging environment
  <shell>kubectl set image deployment/myapp myapp=myapp:staging</shell>

验证清单

使用此清单验证命令是否完整且正确：

文件结构

• 文件位于 <cwd>/.forge/commands 目录中（重要）
• 文件名与命令名称匹配（例如，name: check 对应 check.md）
• 文件扩展名为 .md
• YAML 前置元数据使用 --- 分隔符

前置元数据

• 存在 name 字段
• name 使用小写字母
• 多词名称的 name 使用连字符
• name 以动词为基础（祈使形式）
• 存在 description 字段
• description 清晰简洁
• description 描述做什么，而非如何做

命令正文

• 至少定义一个步骤
• 步骤使用项目符号（-）
• 每个步骤都以动作动词开头
• 步骤具体且可执行
• 复杂步骤包含上下文
• 步骤按逻辑顺序排列

特殊标签

• 标签单独占一行，位于步骤描述之后
• 仅使用有效标签（<lint>、<test>、<shell>）
• 标签命令完整且可执行
• 标签命令使用适当的标志
• 标签命令格式正确

内容质量

• 命令名称具有描述性
• 步骤清晰明确
• 没有多余或重复的步骤
• 步骤按逻辑顺序排列
• 已记录特殊要求
• 已考虑错误处理

测试

• 命令可以成功执行
• 所有步骤都按预期完成
• 特殊标签正常工作
• 输出符合预期
• 已处理边缘情况
• forge 能识别命令：运行 forge list command --custom（或 forge list cmd），并确认命令出现在列表中

应避免的常见错误

前置元数据错误

错误：分隔符错误：

---
name: my-command
description: My command

（缺少结束的 ---）

正确：正确示例：

---
name: my-command
description: My command
---

错误：缺少必填字段：

---
name: my-command
---

（缺少 description）

正确：正确示例：

---
name: my-command
description: Does something useful
---

命名错误

错误：驼峰式名称：

---
name: myCommand
description: Does something
---

正确：正确示例：

---
name: my-command
description: Does something
---

错误：使用名词而非动词：

---
name: checker
description: Checks something
---

正确：正确示例：

---
name: check
description: Checks something
---

步骤错误

错误：没有动作动词：

---
name: test
description: Runs tests
---

- The tests
- The code

正确：正确示例：

---
name: test
description: Runs tests
---

- Run all tests
- Verify code quality

错误：步骤含糊：

---
name: deploy
description: Deploys application
---

- Do the deployment
- Make sure it works

正确：正确示例：

---
name: deploy
description: Deploys application to production
---

- Build the Docker image
  <shell>docker build -t myapp:latest .</shell>
- Push to registry
  <shell>docker push myapp:latest</shell>
- Deploy to production
  <shell>kubectl set image deployment/myapp myapp=myapp:latest</shell>
- Verify deployment is healthy

标签错误

错误：标签与正文在同一行：

- Run tests <test>cargo test</test>

正确：正确示例：

- Run tests
  <test>cargo test</test>

错误：无效标签：

- Run checks
  <check>cargo clippy</check>

正确：正确示例：

- Run checks
  <lint>cargo clippy</lint>

错误：命令不完整：

- Format code
  <lint>cargo fmt</lint>

（缺少 --all 标志）

正确：正确示例：

- Format code
  <lint>cargo fmt --all</lint>

快速参考

文件位置

• 目录：<cwd>/.forge/commands（其中 <cwd> 是当前工作目录）
• 格式：{command-name}.md
• 重要：命令必须位于此确切位置，才能被 forge 发现

有效标签

• <lint> - 用于代码检查／格式化命令
• <test> - 用于测试命令
• <shell> - 用于常规 Shell 命令

命名规则

• 仅使用小写字母
• 多词名称使用连字符
• 以动词为基础（祈使形式）
• 名称应简短且具有描述性

步骤指南

• 以动作动词开头
• 内容具体
• 为复杂步骤提供上下文
• 使用现在时
• 步骤聚焦于单一事项

何时使用标签

• 运行格式化工具或代码检查工具时，使用 <lint>
• 运行测试套件时，使用 <test>
• 其他 Shell 命令使用 <shell>
• 将标签单独放在步骤描述之后的一行
• 如果步骤只是说明，则不要使用标签

测试命令

创建命令后，请按以下步骤进行测试：

1. 语法检查：验证 YAML 是否有效

   # If you have yamllint installed
   yamllint path/to/your-command.md
   

2. 手动审查：通读命令

   • 每个步骤是否合理？
   • 顺序是否合乎逻辑？
   • 所有命令是否完整？

3. 执行测试：运行命令

   • 每个步骤是否都能成功执行？
   • 输出是否符合预期？
   • 是否存在错误？

4. Forge 识别测试：验证 forge 是否能识别该命令

   # Option 1: List all commands (custom commands marked as type: custom)
   forge list command
   
   # Option 2: List only custom commands
   forge list cmd
   
   # Option 3: List only custom commands (newer versions)
   forge list command --custom
   

   • 列表中是否显示了你的命令？
   • 名称是否正确？
   • 描述是否正确？

5. 边缘情况：考虑不常见的场景

   • 如果某个步骤失败，会发生什么？
   • 如果环境不同，会发生什么？
   • 如果缺少文件，会发生什么？

验证

创建命令后：

1. 验证文件位置：确保文件位于 <cwd>/.forge/commands 目录中（至关重要——其他位置的命令都无法被找到）

2. 检查 YAML frontmatter 是否有效（使用 --- 分隔符）

3. 确保命令名称与文件名一致（不含 .md）

4. 验证 forge 是否能识别该命令：

   # Option 1: List all commands (custom commands marked as type: custom)
   forge list command
   
   # Option 2: List only custom commands
   forge list cmd
   
   # Option 3: List only custom commands (newer versions)
   forge list command --custom
   

   新命令应以名称和描述的形式显示在列表中

5. 测试命令，确保其按预期运行

6. 验证特殊标签的格式是否正确

如果你的命令没有显示在列表中，请检查：

• 文件位置：文件必须位于 <cwd>/.forge/commands 目录中（这是最常见的问题）
• 文件名是否与 frontmatter 中的 name 字段一致
• YAML frontmatter 是否使用 --- 分隔符正确格式化
• 是否同时包含 name 和 description 字段

获取帮助

如果你对某些内容不确定：

• 查看此技能中的示例
• 遵循验证清单
• 定稿前测试你的命令