create-command

コマンドの作成

code-forge アプリケーション用のコマンドを作成、管理します。コマンドは、特定のタスクを実行するために呼び出せるモジュール式のワークフローです。

ファイルの配置場所

重要：すべてのコマンドファイルは、code-forge プロジェクトの現在の作業ディレクトリである <cwd>/.forge/commands ディレクトリに作成する必要があります。

• ディレクトリ：<cwd>/.forge/commands
• ファイル形式：{command-name}.md
• 例：プロジェクトが /home/user/my-project にある場合、コマンドは /home/user/my-project/.forge/commands/ に配置します。

forge がカスタムコマンドを検出して読み込む場所はここだけです。

コマンドファイルの構造

各コマンドファイルには、次の項目が必要です。

1. YAML フロントマター（必須）：

   • 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

完全なコマンドのサンプル

このサンプルでは、3 種類すべてのタグを紹介します。

---
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> の <cwd>/.forge/commands に必ず配置してください。それ以外の場所に配置したコマンドは、forge に検出されません。

フロントマター

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

コマンド本文

ステップには Markdown のリストを使用します。各ステップは次の要件を満たす必要があります。

• 明確な動作を表す動詞で始める
• 具体的で実行可能な内容にする
• 実行内容に関するコンテキストを含める

特殊なコマンドタグ

自動化されたワークフローには、次のタグを使用します。

<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>rm -rf target/debug</shell>

タグの使用方法

タグは、ステップの説明の後に、独立した行として配置します。

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

コマンドの種類

シンプルなコマンド

1 つのステップ、または指示のみで構成されるコマンドです。

---
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 frontmatter が --- 区切りを使用している

Frontmatter

• name フィールドが存在する
• name が小文字を使用している
• name が複数単語の場合にハイフンを使用している
• name が動詞ベース（命令形）である
• description フィールドが存在する
• description が明確かつ簡潔である
• description が「どのように」ではなく「何を」を説明している

コマンド本体

• 少なくとも 1 つのステップが定義されている
• ステップが箇条書き（-）を使用している
• 各ステップが動作動詞で始まっている
• ステップが具体的で実行可能である
• 複雑なステップにはコンテキストが含まれている
• ステップが論理的な順序になっている

特殊タグ

• タグがステップの説明の後の独立した行にある
• 有効なタグのみを使用している（<lint>、<test>、<shell>）
• タグのコマンドが完全で実行可能である
• タグのコマンドが適切なフラグを使用している
• タグのコマンドが正しくフォーマットされている

コンテンツの品質

• コマンド名が説明的である
• ステップが明確で曖昧さがない
• 冗長または重複したステップがない
• ステップが論理的な順序に従っている
• 特別な要件が文書化されている
• エラー処理が考慮されている

テスト

• コマンドが正常に実行できる
• すべてのステップが期待どおりに完了する
• 特殊タグが正しく機能する
• 出力が期待どおりである
• エッジケースが処理されている
• コマンドが forge に認識される: forge list command --custom（または forge list cmd）を実行して、コマンドが一覧に表示されることを確認してください

避けるべきよくある間違い

Frontmatter の間違い

悪い例: 誤った区切り:

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

（閉じる --- が欠落）

良い例: 正しい:

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

悪い例: 必須フィールドの欠落:

---
name: my-command
---

（description が欠落）

良い例: 正しい:

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

命名の間違い

悪い例: CamelCase の名前:

---
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> - lint/フォーマットのコマンド用
• <test> - テストのコマンド用
• <shell> - 一般的なシェルコマンド用

命名規則

• 小文字のみ
• 複数単語の名前にはハイフンを使用
• 動詞ベース（命令形）
• 短くても説明的にする

ステップのガイドライン

• 動作動詞で始める
• 具体的にする
• 複雑なステップにはコンテキストを含める
• 現在形を使用する
• ステップを焦点を絞ったものにする

タグを使う場面

• フォーマッタやリンターを実行する場合は <lint> を使う
• テストスイートを実行する場合は <test> を使う
• その他のシェルコマンドには <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 のフロントマターが有効であることを確認します（区切り文字 --- を使用します）

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 ディレクトリに置いてください（最もよくある問題です）
• ファイル名がフロントマターの name フィールドと一致している
• YAML のフロントマターが区切り文字 --- で正しく書式設定されている
• name フィールドと description フィールドの両方がある

ヘルプを得る

不明な点がある場合は、次の方法をお試しください。

• このスキルの例を確認する
• 検証チェックリストに従う
• 最終確定する前にコマンドをテストする