fcode-agent

Factorial Code — エージェントのワークフロー

Factorial Code MCP ツールを使って、反復的かつ確認を重ねながら Factorial Code のプロセスやモジュールを構築する方法です。fcode-core-concepts、fcode-javascript／fcode-python、fcode-cli と併せてご利用ください。

基本原則

• 実行前に説明する — 何をするのか、なぜ行うのかを説明します。
• 変更前に確認する — 重要な変更や破壊的な変更（リファクタリング、依存関係の変更、変数の変更など）を行う前に、明示的な承認を得ます。
• 小さな手順で反復する — 動作する単位で実装し、検証してから範囲を広げます。
• デフォルトで安全にする — シークレットをハードコードしたり、ログに出力したりしないでください。

ワークフロー

フェーズ 1 — 計画と確認

コードを記述したりツールを使ったりする前に、短い計画を提示して確認を得ます。

1. 現在の状況を分析します。 プロセスの言語（index.js → JS、main.py → Python。新しいコードは既存の言語に合わせる必要があります）、現在のスクリプトの動作、既存の変数／依存関係／モジュールを確認します（削除したり上書きしたりしないでください）。
2. 代替案を特定します。 よくあるニーズ（メール、SMS、決済、ストレージ）について、サードパーティサービスと直接プロトコルを使う方法、ライブラリの選択肢などを簡潔に比較し、ユーザーに選んでもらいます。複数の選択肢がある場合、方法を決めつけないでください。
3. 必要なコンポーネントを特定します。 設定変数、シークレット（ユーザーが作成する必要があります）、入力パラメーター（および型）、依存関係（存在を確認し、安定版のうち新しいものを優先します）、再利用できるモジュールを確認します。
4. 入力パラメーターの要件を定義します（フィールド、型、検証、API 呼び出しが必要な動的フィールドなど）。fcode-json-schema を参照してください。
5. 計画を提示します（構築するもの、作成する変数とユーザーが作成する変数、入力パラメーター、依存関係、再利用可能なモジュール、想定される動作）。「進めてもよいですか？」と確認します。
6. 明示的な確認を得るまで待ちます。

フェーズ 2 — 反復的な開発

小さな手順で作業し、各手順で確認を得ます。

• イテレーション 1（セットアップと調査）： 設定変数を作成し、機密性の高い変数はユーザーに作成してもらいます。必要に応じて調査用スクリプトを作成し、run_code で実行して接続を検証し、API やデータの形状を確認します。結果を共有します。
  • 調査やテストでシークレットの値が必要な場合は、ユーザーに提供を依頼します。共有したくない場合は、ユーザー自身で variables.local.env に設定してもらいます。FACTORIAL_TOKEN については、fcode-cli の OAuth 手順に従います。
  • ローカルのシークレット値はプッシュされないため、リモートのデモ環境でこれらの変数を手動で作成する必要があることをユーザーに伝えます（FACTORIAL_TOKEN はリモート環境に自動入力されるため除きます）。
• イテレーション 2 以降： 各手順で、内容を説明して確認を得てから、言語別のコード規則（検証、エラー処理、ログ記録）に従って実装します。run_code で各部分を検証してから、プロセス（コード、パラメーター、説明）を作成または更新します。変更内容をユーザーに伝え、次のイテレーションに進む前に確認してもらいます。

フェーズ 3 — テストと改善（CLI を使用）

fcode CLI（fcode-cli を参照）を使った一連の実行テストを提案し、確認を得てからテストパラメーターで実行します。結果を一緒に確認し、反復して改善します。その後、次のステップとして、スケジュール設定、Webhook（パブリック、ワークスペースの webhookAuth 設定を継承するもの、または独自のヘッダーとチーム変数を使うもの）、フォーム（Factorial 経由で開き、ユーザーを認証します）、Factorial UI 内のボタン（fcode-ui-triggers）、またはその他の Factorial Action のエントリーポイント（fcode-factorial-actions）を提示します。プロセスを MCP ツールとして公開する方法や、準備ができたらクラウドにプッシュする方法も提示します。プッシュしても stable エイリアスに固定された利用側には影響しません（モデルについては fcode-core-concepts を参照）。明示的な依頼がない限り、ワークスペースのバージョンを作成したり、stable を移動したりしないでください。

MCP ツールの作成

スタンドアロンの MCP サーバーコードは作成しないでください。 Factorial Code のプロセスはすべて MCP ツールになります。（1）ロジックを実装するプロセスを作成し、（2）parametersSchema.json で入力パラメーターを定義すると（ツールのパラメーターになります）、（3）プロセスにタグ（例：mcp-tool）を付けます。これで、Factorial Code MCP サーバーに接続されたすべての MCP クライアントから自動的に利用できるようになります。タグを付けるだけです。

利用可能な MCP ツール

• run_code — プロセスファイルを更新する前に、検証やテストのために JS／Python を実行します。
• yc_api_<method> — Factorial Code のリソースを管理します（例：yc_api_create_process、yc_api_update_process、yc_api_delete_process）。
• get_locales / get_locale / save_locale / delete_locale — ワークスペースの翻訳ファイルを管理します。save_locale はファイル全体を置き換えるため、キーを追加する場合は読み取り・変更・書き込みの手順で行ってください。fcode-i18n を参考にしてください。
• 必要に応じて、他の Factorial Code MCP ツールも使用してください。

コードの品質とセキュリティ

• 意味のあるメッセージを含む try/catch（try/except）を使用します。外部からの入力も含め、すべての入力を冒頭で検証し、重要な手順をログに記録し、再利用可能なロジックはモジュールに切り出し、リソースをクリーンアップします。
• fcode-core-concepts にあるモジュールの命名規則と variables.env に関する注意点を確認してください。

エラー処理

何が問題だったのかを説明し、修正案を提示して、確認を得てください。黙って再試行したり、試行錯誤を繰り返したりしないでください。要件が曖昧な場合、情報（認証情報、エンドポイント、パッケージ名など）が不足している場合、失敗が繰り返される場合、アーキテクチャやトレードオフに関する判断が必要な場合、セキュリティ上の懸念がある場合、または根本原因が不明確な場合は、推測せずにユーザーに確認してください。

例

このワークフローを最初から最後まで実演した例（Shopify からメールへの連携）については、references/example-interaction.md を参照してください。