fcode-core-concepts

Factorial Code のコアコンセプト

Factorial Code（fcode）は、エンタープライズ向けの統合・自動化プラットフォームです。 JavaScript または Python でプロセス（および再利用可能なモジュール）を記述します。サンドボックス化、依存関係、シークレット、スケジューリング、実行はプラットフォームが処理します。

このスキルでは基本的な考え方を説明します。実際にコードを書く場合は fcode-javascript または fcode-python も使用してください。CLI のワークフローについては fcode-cli を使用してください。

注意点

以下は一般的な想定に反する点です。間違えるとプロセスが動作しなくなります。

• データストアには文字列と数値のみを保存できます。 set の前に JSON.stringify / json.dumps でオブジェクトをシリアライズし、get の際にパースしてください。
• モジュールファイルの名前は index / main ではなく、スラッグにします。 モジュールは modules/<slug>/<slug>.js（または .py）に配置します。例： modules/shopify-client/shopify-client.js。決して modules/<slug>/index.js や main.py にしないでください（これらの名前はプロセスのエントリーファイル専用です）。また、専用フォルダーを作らずに modules/ 直下へモジュールファイルを置かないでください。
• variables.env 全体を上書きしないでください。 まず読み込み、対象の変数のみを追加・修正してください。ファイルを書き換えると、新しい内容に含まれないすべての変数が削除され、他のプロセスに影響する可能性があります。
• 継承したリソースを編集しないでください（variables.inherited.env、 i18n/<locale>.inherited.yaml、継承したプロセス／モジュール）。これらは親ワークスペースが所有し、pull のたびに再生成されます。変数やロケールキーを上書きするには、このワークスペース独自のファイルで定義してください。プロセスやモジュールは、それらを所有するワークスペースで編集してください。
• シークレットをハードコードしたり、ログに記録したりしないでください。 変数／環境変数を使用し、ログではシークレットをマスクするか省略してください。
• ランタイムのバージョンは固定されています： JavaScript = Node.js v22、Python = 3.13。
• 制限はワークスペースごとに固定されています — 実行あたり 12 h、同時実行数 50、50 req/s、戻り値 500 KB、データストアのエントリーあたり 50 KB です。上限を引き上げるには、プランを変更するのではなく、こちらにご依頼ください。Plans & limits をご覧ください。

主なコンセプト

コンセプト	内容	ポイント
プロセス	実行単位（ビジネスロジック）	入力パラメーターを定義し、構造化された結果を返します
モジュール	再利用可能なコードライブラリ	プロセス間で共有でき、バージョン管理できます
ワークスペースのバージョン	チームが所有するすべてのプロセスとモジュールに公開される 1 つのタグ（例：v1.0.0）	Web UI から公開します。同じタグで再試行しても問題ありません
バージョンエイリアス	バージョンを指す、移動可能なポインター	stable は常に存在します。利用側はこれに固定してください。移動するとロールアウト／ロールバックになります
変数	設定とシークレット	環境変数です。親ワークスペースから継承されます。シークレットは決してハードコードしないでください
データストア	永続的なキーと値のストア	文字列と数値のみです。リクエストに応じて値を保存時に暗号化できます
ストレージ	ファイルストレージ	バイナリファイル、ドキュメント、大容量データ
ロケール	言語ごとの翻訳ファイル（i18n/<locale>.yaml）	fcode.i18n が解決します。親からキー単位で継承されます。fcode-i18n をご覧ください
メール	組み込みのトランザクションメール	fcode.sendMail / send_mail を使用します。SMTP の設定は不要で、認証情報はマネージャーに保存されます

プロセス

JavaScript（index.js）または Python（main.py）で記述する基本的な実行単位です。 プロセスでは JSON Schema で入力パラメーターを宣言できます（parametersSchema.json、 fcode-json-schema を参照）。また、fcode.context.parameters からパラメーターを読み取れます。 構造化された JSON を返してください。Webhook 形式のレスポンスを返す場合は { status, headers, body } を使用してください。

モジュール

プロセス間で共有される再利用可能なライブラリです。重複を避け、API クライアントや統合をカプセル化し、プロセスのコードを簡潔に保ち、バージョン管理を可能にするために使用します。上記のモジュール名に関する注意点をご覧ください。

実行コンテキスト

各プロセスは分離された環境で実行され、以下にアクセスできます。

• 入力パラメーター：fcode.context.parameters
• 環境変数：process.env.* / os.getenv(...)（または fcode.env.*）
• 実行メタデータ：fcode.execution.*
• リクエストデータ（Webhook）：該当する場合、リクエスト本文／ヘッダー

変数（設定とシークレット）

ベース URL、タイムアウト、API キー、トークンは変数として保存します（ハードコードしないでください）。 variables.env にはチーム変数（KEY=VALUE）が格納され、variables.local.env にはローカル専用の上書きが格納されます。前述の上書きに関する注意点を参照してください。

variables.meta.json は、各変数の isSensitive フラグを示します。機密性の高い値がクラウドから出ることはありません。ローカルでは variables.env 内に ******** のプレースホルダーとして表示されます。実際の値は variables.local.env に設定してください。詳細は fcode-cli を参照してください。

ローカル実行でシークレットの実際の値が必要な場合は、ユーザーに値を尋ねてください。共有したくない場合は、ユーザー自身に variables.local.env へ設定してもらってください。FACTORIAL_TOKEN は Factorial Code アプリの詳細ページにある OAuth フローから取得し、ローカルでのみ必要です（リモートでは自動入力されます）。手順は fcode-cli を参照してください。

チーム変数を使って Webhook を保護することもできます。プロセスで期待するトークンを格納した変数名を指定し、呼び出し元はその値を Authorization: Bearer <token> として送信します。プロセスとともに保存されるのは変数名のみなので、トークンがエクスポートやコミット対象のファイルに含まれることはありません。

実行時には fcode.env.* を使って変数を読み取ります。プロセスからプログラムで変数を作成・更新・削除するには、fcode.variables ヘルパー（set／get／list／delete）を使います。チームのスコープ内で動作し、API トークンは不要です。fcode-javascript／fcode-python を参照してください。

親ワークスペースからの継承

ワークスペースでは、parentTeams の親が持つプロセス、モジュール、変数、i18n ロケール、依存関係を、自分自身のものとして利用できます。これらすべての解決順序は同じです。まずワークスペース自身を確認し、次に設定されている順に直接の親を確認します。親は最大 5 つで、推移的には適用されません（祖父母のリソースは孫に引き継がれません）。

• 継承されたリソースは自由に読み取り、呼び出し、インポートできます。継承されたモジュールも所有するモジュールと同じようにインポートでき、子のコードは親のプロセスに依存できます。ただし、継承されているリソースは読み取り専用です。ファイルの編集でも MCP ツール経由でも、変更、削除、再スケジュールはしないでください。所有元のワークスペースで編集してください。
• 変数、ロケール、依存関係は、ローカルで再定義すると上書きされます。子の variables.env、i18n/<locale>.yaml、または dependencies/package.json／requirements.txt にあるキーは、親の値より優先されます。キー単位で上書きされ、依存関係はパッケージ単位で上書きされます。同じパッケージの 2 つのバージョンを並行してインストールできないため、子の指定が親の指定を置き換えます。上書きを削除すると、親の値が再び有効になります。プロセスとモジュールには上書きの仕組みがないため、所有元で変更してください。
• **親から継承されるのは、インストール済みの依存関係のみです。**親が保存したものの、まだインストールしていないマニフェストの変更は子に反映されません。インストール後、子は次回の実行時にその依存関係を取得します。子側でインストールする必要はありません。親がすでに提供しているパッケージを、子で宣言する必要はありません。
• **親の変数を子で再作成しないでください。**子でもすでに解決されます。そのため、deploy-{installationId} ワークスペースにはその顧客固有の値だけを置き、共有のデフォルト値や認証情報は prod-{appId}／base-app に保持します。Web UI では、継承された変数に継承バッジが付き、ここで上書きを選択できます。
• **シークレットも継承され、実際の値がサンドボックスに渡されます。**子ワークスペースのプロセスは、実行時に親のシークレットを読み取れます。それ以外の場所ではマスクされたままです（GraphQL では null、REST では ******、CLI の継承されたファイルでは ********）。そのため、値を読み取れるのはプロセスのコードだけです。子ワークスペースのコードは、親の認証情報を信頼できるものとして扱ってください。ローカル実行ではプレースホルダーが取得されるため、実際の値は variables.local.env に設定してください。
• ワークスペースのバージョンでは、継承されたリソースは公開されません。タグが付くのは所有するリソースのみです（「バージョン管理とエイリアス」を参照してください）。

親チームをそのバージョンの 1 つに固定する

各親チームへのリンクには、任意のバージョン固定を設定できます。これは、その親チームのワークスペースバージョンのタグ、またはstableなどのエイリアスです。設定しない場合、親チームはライブで解決されます。つまり、現在のコードが使われ、動作は上記のとおりです。設定すると、親チームから提供されるのは作業コピーではなくリリースです。

• そのバージョンで公開された内容だけが、そのバージョンのコンテンツとともに使われます。 リリース後に親チームが追加したプロセスやモジュールは存在しないため、固定された親チームにそれがないものとして、次の親チームに解決が引き継がれます。親チームは編集や公開を続けても、子チームが実行する内容は変わりません。
• エイリアスによる固定では、エイリアスの参照先に追従します。 子チームをstableに固定し、親チームでstableの参照先を変更すると、そのエイリアスに固定されたすべての子チームが一度に切り替わります。これにより、ベースアプリからインストール先へ修正を展開できます。
• 依存関係も固定先に追従します。 子チームには、親チームが現在インストールしているパッケージではなく、固定されたリリースを作成したときのパッケージがインストールされます。
• 変数は、固定の有無にかかわらず常にライブで解決されます。 変数にはバージョン管理された形式がないためです。
• 子チームは、継承したリソースのバージョンを選択できません。 バージョンは固定によって決まります。Web UIでは、継承されたプロセス、モジュール、ロケールのバージョンは読み取り専用で表示されます（固定したタグ、またはライブ）。また、「Versions」タブもありません。リソースの公開とエイリアス設定は、そのワークスペースを所有する側で行います。

固定は、Web UI（チームの設定 → Details → 親チーム）またはワークスペースのsettings.jsonで、親チームごとに設定します。フィールドのリファレンスはfcode-cliにあります。明示的に依頼されない限り、固定を追加または変更しないでください。どのリリースをワークスペースで実行するかが決まるためです。

継承されたリソースのディスク上のレイアウト、Gitでの無視設定、プッシュ／プルの動作については、fcode-cliを参照してください。

スケジュール

cronまたは日時を指定して、プロセスを実行します。プロセスのコードから、fcode.scheduleヘルパー（create／list／get／update／pause／resume／delete／deleteForProcess）を使ってスケジュールを管理できます。他のヘルパーと同じ認証機能が標準で使えます。fcode-javascript／fcode-pythonを参照してください。

Datastore と Storage

• Datastore — 実行をまたいで保持されるキーと値の状態（最終実行時刻、カーソル、重複排除 ID、小規模なキャッシュなど）です。値は文字列または数値のみです。setの第 3 引数にtrueを渡すと、ワークスペースが所有するキーを使って保存時に値を暗号化できます。読み取り時には自動的に復号されます。プロセス自体が実行間で保持する必要のあるシークレット（取得した OAuth トークンなど）は、ここに保存します。fcode-javascript／fcode-pythonを参照してください。
• Storage — Datastore に保存するものではないファイル（レポート、エクスポート、画像、PDF、データ抽出ファイルなど）です。

メールの送信

組み込みのfcode.sendMail（Python ではfcode.send_mail）でメールを送信できます。認証済みのため、SMTP の設定は不要です。メールサーバーと認証情報はエグゼキューターマネージャーにあり、プロセス内に置くことはありません。デフォルトでは、各実行で最大 3 通のメールを送信できます。使い方はfcode-javascript／fcode-pythonを参照してください。

すべてのアプリは、固定の Factorial メールアドレスから送信します。そのため、1 つの不正なアプリが、受信者へのフィッシングの経路となり、他のすべてのアプリのメール到達性にも問題を引き起こす可能性があります。組み込みメーラーは、顧客の Factorial アカウントがすでに把握している相手へのトランザクションメールに限って使用できます。これ以外の用途では、アプリの検証（fcode-code-validation）によりリリースがブロックされます。

この範囲外のメール（顧客向けキャンペーン、大量送信、カスタム送信者など）には、アプリ独自の認証情報で呼び出す専用のメールプロバイダーが必要です（選択肢はfcode-agentを参照してください）。組み込みメーラーを使って送信上限を回避しないでください。

バージョン管理とエイリアス

プロセスとモジュールは個別にバージョン管理できます。また、ワークスペースバージョンを公開すると、チームが所有するすべてのプロセスとモジュールに1つのタグ（例：v1.0.0）を一度に付与します。parentTeams を通じて継承されるリソースには一切触れません。各エンティティの結果（作成済み／スキップ／失敗）はバージョンのマニフェストに記録されるため、一部失敗した後に同じタグを再作成すると、不足しているものだけが公開されます。

ワークスペースバージョンを公開すると、ワークスペースが所有するモジュールのタグなし fcode.import("mod") ／ fcode.import_module("mod") 呼び出しには、公開されたスナップショット内でのみタグが設定されます。作業コピーは変更されず、すでにタグまたはエイリアスが付いているインポートもそのままです。また、ワークスペースバージョンでは所有するロケールもすべて公開され、fcode.i18n 呼び出しにも同様にタグが設定されます。すでに version を指定している呼び出しはそのままにし、それ以外（タグなしの呼び出し、ロケールのみのオプション）にはタグを設定します。これにより、コードとフォームスキーマの両方でリリース時の翻訳が固定されます。詳細は fcode-i18n を参照してください。

バージョンエイリアスは、移動可能なバージョンへのポインターです。stable エイリアスは常に存在し、ワークスペースの安定版を指します。Webhook、フォーム、スケジュール、モジュールのインポートでは、タグを指定できる場所でエイリアスも指定できます。そのため、stable を別のバージョンに移動すれば、ワークスペース全体の参照先を1回の操作で切り替えられます。ロールアウトとロールバックは、エイリアスを1回変更するだけで完了します。利用側（Webhook URL、フォームの埋め込み）は常に stable に固定してください。方法については fcode-cli と fcode-forms を参照してください。

この仕組みには、次の2つの影響があります。

• fcode push は stable に固定された利用側に影響しません。 プッシュによって更新されるのは現在の（バージョン管理されていない）コードです。固定された利用側は、エイリアスが移動するまでリリース済みバージョンを引き続き実行します。
• ワークスペースバージョンを削除すると、関連するものもすべて削除されます。該当タグが付いた、所有するすべてのプロセス／モジュールのバージョンに加え、それらを参照するエイリアス、実行、スケジュールも削除されます。
• 別のワークスペースが固定しているバージョンまたはエイリアスは保護されます。 削除は拒否され、影響を受けるワークスペース名が表示されます。削除するには、先にそれらのワークスペースで固定を解除する必要があります。エイリアスの移動は引き続き可能です。リリースを昇格させる方法がこれです。

バージョンの公開とエイリアスの関連付けは、ウェブ UI（チーム設定 → Versions タブ）から行います。CLI での同等の操作（fcode settings:versions:* ／ settings:aliases:*）については fcode-cli に記載されています。明示的に依頼されていない限り、バージョンを作成したり stable を移動したりしないでください。

バージョンタグ（v1.0.0）は、metadata.json の tags とは無関係です。tags はプロセスラベルです（例：MCP ツールへの公開に使用されます。詳細は fcode-agent を参照してください）。

プランと上限

すべてのワークスペースは同じ固定プランで実行されるため、以下の上限はすべてのワークスペースに適用されます。選択できるプランはなく、セルフサービスでのアップグレードもできません。アプリはこれらの上限に収まるように設計してください。実際のニーズが上限に収まらない場合は、その上限の引き上げをワークスペースについて依頼してください（Factorial 社内ユーザー：Slack の #factorial-code-users、その他のユーザー：fcode-ama › エスカレーション）。上限を回避するために、1 つのジョブを多数の実行に分割したり、データストアのキーを連鎖させて上限をすり抜けたりしないでください。

上限	値	超過した場合
1 回の実行時間	12 時間	実行が終了します
ワークスペースあたりの同時実行数	50	新しい実行はキューに入ります
ワークスペースあたりのキュー内実行数	1,000	新しい実行は拒否されます
Webhook へのリクエスト	ワークスペースあたり 50 req/s	Retry-After を含む HTTP 429
フォームおよび OAuth エンドポイントへのリクエスト	プロセスおよび呼び出し元あたり 50 req/s	Retry-After を含む HTTP 429
入力パラメーター — テキスト	500 KB	HTTP 413、実行は作成されません
入力パラメーター — ファイル	合計 15 MB	HTTP 413、実行は作成されません
戻り値	500 KB	実行が失敗します。大きな結果はストレージに入れ、参照を返してください
実行ログ	500 行、500 KB	以降のログエントリーは破棄されます
データストアのエントリー	ワークスペースあたり 20,000 件	書き込みが失敗します（HTTP 403）
データストアのエントリーサイズ	50 KB	書き込みが失敗します（HTTP 413）
ストレージのファイル	1,000 ファイル、各 50 MB	アップロードが失敗します
1 回の実行あたりのメール	3 件（メールの送信を参照）	以降の送信は例外をスローします
1 日／1 か月あたりのプロセス、フォーム、依存関係、実行	無制限	—

判断の指針

モジュールとインラインコード

シナリオ	推奨事項
複数のプロセスで使用する API クライアント	モジュールを作成する
2 回以上使用するユーティリティヘルパー	モジュールを作成する
一度限りの変換／一度しか使わないロジック	インラインのままにする

データストア、Variables、Storage

必要なもの	使用するもの
ほとんど変更されない設定、シークレット／認証情報	Variables
実行間で変化する状態、キャッシュされた API レスポンス	Datastore
プロセスが取得し、実行間で保持する必要があるシークレット（OAuth トークン）	Datastore、set(key, value, true)
バイナリファイル／大規模なエクスポート	Storage

命名規則

リソース	規則	例
プロセスのスラッグ	kebab-case	order-sync-shopify
モジュールのスラッグ	kebab-case	shopify-client
Variables	SCREAMING_SNAKE_CASE	SHOPIFY_API_KEY
JavaScript の関数	camelCase	fetchOrders()
Python の関数	snake_case	fetch_orders()

ワークスペースの構成（CLI）

fcode CLI で管理されるローカルワークスペース（fcode-cli を参照）：

📦 <workspace-name>
┣ 📂 dependencies          # shared deps: package.json (JS) / requirements.txt (Py)
┃ ┗ 📜 package.inherited.json    # inherited deps (read-only, gitignored); .txt for Py
┣ 📂 i18n
┃ ┣ 📜 <locale>.yaml       #   translations this workspace owns (see fcode-i18n)
┃ ┗ 📜 <locale>.inherited.yaml  # inherited translations (read-only, gitignored)
┣ 📂 modules
┃ ┗ 📂 <module-slug>       # one folder per module
┃   ┗ 📜 <module-slug>.js  #   entry file named after the slug (NOT index.js)
┣ 📂 processes
┃ ┗ 📂 <process-slug>      # one folder per process
┃   ┣ 📜 index.js          #   or main.py — the process entry file
┃   ┣ 📜 parametersSchema.json   # input parameter schema (the form)
┃   ┣ 📜 parameters.json   #   default test parameters for `fcode run`
┃   ┣ 📜 metadata.json     #   name, description, tags, webhook + the `factorial` action block
┃   ┣ 📜 README.md
┃   ┗ 📜 package.json      #   optional process-scoped dependencies
┣ 📜 datastore.json
┣ 📜 settings.json         # workspace settings: inheritance, timezone, error handler, webhook auth
┣ 📜 variables.env         # team variables this workspace owns (KEY=VALUE)
┣ 📜 variables.inherited.env  # variables from parent workspaces (read-only, gitignored)
┣ 📜 variables.local.env   # local overrides (not shared)
┣ 📜 variables.meta.json   # per-variable isSensitive flags
┗ 📂 .fcode

開発チーム全体でチェックアウトする場合は、1 つ上の階層に移動し、アプリごとに 1 つのフォルダーを作成して、その中にワークスペースを配置します。fcode-cli の fcode team:clone を使用します：

acme-payroll/               # the development team
┣ 📂 .fcode/team.json       # the team and the Apps cloned into it
┣ 📂 .claude/skills/        # installed once, symlinked into every App
┗ 📂 payroll-sync/          # one folder per App — a future git repo
  ┣ 📜 settings.json        #   the App — name, description (mirror, read-only)
  ┣ 📜 README.md            #   the App's README (editable, `fcode app:push`)
  ┣ 📜 MARKETPLACE.md       #   the marketplace listing (editable, `fcode app:push`)
  ┣ 📜 CHANGELOG.md         #   generated from the App's releases (read-only)
  ┣ 📂 marketplace/logo.*   #   the App logo (read-only)
  ┗ 📂 app/                 #   the workspace laid out above

プロセスとモジュールには versions/<tag>/ サブフォルダー（例：versions/v1.0.0/）もあり、公開済みバージョンのスナップショットが格納されます。上記のバージョン管理のセクションを参照してください。dependencies/package.json には、内側の dependencies オブジェクトのみが格納されます（例：{ "axios": "^1.6.0" }）。

metadata.json では、プロセスの webhook トリガーとFactorial Actionを設定します。編集したら fcode push を実行してください。Webhook は公開（authMode: NONE）、settings.json のワークスペースの webhookAuth を継承（TEAM）、または独自のヘッダーとチーム変数を持つ（CUSTOM）ことができます。factorial ブロックでは、Factorial がプロセスにアクセスする方法を指定します。マスタースイッチ、Factorial が結果を待つかどうか、ユーザーに必要なポリシー、およびエントリーポイントごとのサブブロック（Factorial の UI 内のボタン（fcode-ui-triggers）、フォーム（fcode-forms）、コントラクトを備えた Factorial One ツール、バックエンドジョブ（fcode-factorial-actions））です。以前の form キーと uiTrigger キーはレガシーですが、これらとミラーされた状態に保たれています。アプリのライフサイクル用に、4 つのプロセススラッグ（install、settings、uninstall、sync）が予約されています。フィールドの完全なリファレンスは fcode-cli を参照してください。

一般的なルール

• 入力は早い段階で検証します。最初に必須パラメーターと型を確認してください。
• エラーを明示的に処理します。意味が明確で、対処方法の分かるエラーをスローし、捕捉したすべてのエラーを、コンテキスト（どの操作か、どの入力か）とともに、再スローする前にログに記録してください。
• 外部呼び出しにはタイムアウトと再試行を設定し、レート制限に注意してください。
• 共有の fcode-logs モジュールを使って十分にログを記録します。チーム変数 LOG_LEVEL（デフォルトは info）によるレベル制御付きのログを使用してください。開始・終了、主な判断、外部呼び出しは info で、詳細（ペイロード、中間状態）は debug で記録します（本番環境では無効です）。シークレットは記録しないでください。fcode-javascript / fcode-python での使用方法を参照してください。
• 出力は、利用やデバッグが容易な構造化形式（JSON）にしてください。