develop-app

使用するタイミング

既存の Twenty アプリで何ができるか（データモデル、UI、ロジック、ワークフロー）を変更したい場合に、このスキルを選択してください。代表的な例：

• 「Twenty アプリに新しいオブジェクトを追加して」
• 「レコードの作成時に実行されるロジック関数を作成して」
• 「会社オブジェクトにカスタムフィールドを追加して」
• 「商談ページ用のフロントコンポーネントを作成して」
• 「既存のエンティティ／オブジェクト／フィールドを変更して」
• 「手動トリガーのワークフローを追加して」
• 「アプリにロールと権限を追加して」
• 「アプリにスタンドアロンページを作成して」

新しいアプリを一から作成する場合（create-app を使用）、同期／デプロイ／トラブルシューティングを行う場合（manage-app を使用）、マーケットプレイス用アセットを準備する場合（publish-app を使用）、またはワークスペースのレコードを照会する場合（use-twenty-mcp を使用）は、このスキルを使用しないでください。

適用範囲

Twenty アプリの仕組み（SDK パッケージ、リモート、同期のライフサイクル、レンダリングモデル）の概要については、../../references/concepts/how-apps-work.md を読んでください。すべての Twenty アプリのタスクに適用される、スキル横断の運用ルールは ../../references/concepts/operating-rules.md に記載されています。このルールは正式な指針であり、各スキルで繰り返し説明されていません。

ここで新しいアプリを一から作成しないでください。アプリが存在しない場合は、まず create-app を使用してください。

ワークフロー

エンティティを変更する前に、まずセットアップが適切であることを確認してください。現在のディレクトリは、既存の Twenty アプリのルートである必要があります。

test -f package.json
test -f src/application-config.ts

どちらかのファイルが見つからない場合は、確認せずに編集しないでください。近くのフォルダーを調べてアプリのルートを探すか、アプリが存在しない場合は create-app を使用してください。

セットアップ、依存関係、リモート、認証、同期、ビルド、デプロイ、ログ、CI/CD に問題がある場合は、エンティティの作業を続ける前に manage-app に切り替えてください。

アプリの構成とエンティティファイルの構造については、../../references/develop-app/app-structure.md を読んでください。

編集前に計画する

複数のエンティティに関わる変更では、編集前に計画を3〜6行で提示してください。拡張するオブジェクト、追加するフィールド、宣言するロジック関数とインストール後フック、アプリに UI が必要かどうかを記載します。実質的な選択肢がある場合は、ユーザーに確認してください。

単一エンティティの編集、名前の変更、文言の修正では省略してください。

コードの構成

ロジック関数、インストール後フック、フロントコンポーネントは小さく保ちます。トリガー、入力、書き込み、レンダリングの枠組み、外部呼び出し以外はすべて切り出します。

• src/utils/<name>.util.ts — 純粋なヘルパー（パーサー、マッパー、フォーマッター）。
• src/front-components/utils/<name>.util.ts — 再利用可能でテスト可能な、フロントコンポーネントのランタイムヘルパー。
• src/types/<name>.ts — 外部 API および内部 DTO の型（ファイルごとに PascalCase の型を 1 つ）。
• src/<service>-client/<name>.ts — 外部 SDK または共有 HTTP クライアントのラッパー。Twenty の *-client 規約に合わせ、サービスごとにフォルダーを 1 つ作成します。

ファイル名にはケバブケースを使用します。src/ 内のヘルパー、型、クライアントファイルでは、ファイルごとにエクスポートを 1 つだけにする必要があります。1 つのファイルから複数の関数をエクスポートしてはいけません。このルールではエクスポートを数えます。ローカルの（エクスポートされていない）型はユーティリティと同じファイルに置けますが、型をエクスポートするか再利用する場合は、src/utils/<name>.util.ts とは別の src/types/<name>.ts ファイルに分けます。標準ルールとサフィックスの規約全体については、app-structure.md を参照してください。

次の場合はリファクタリングします。

• *.logic-function.ts または *.post-install.ts ファイルがソフト上限を超えている場合（../../references/develop-app/logic.md を参照）。
• フロントコンポーネントに、コマンドの実行、レコードの読み込み、ロジック関数の検索、ペイロードの構築、結果の解析、スナックバーの整形の重複がある場合。
• 同じ解析またはマッピングのロジックが、複数のオブジェクト型で使われている場合。
• フィールドファイルが名前と識別子だけ異なる場合 — src/fields/ のファクトリーを使用します。

追加または変更するユーティリティ／関数ごとに、必ず隣接する __tests__/ フォルダーに *.spec.ts のテストファイルを作成します。ソースファイルごとに spec ファイルを 1 つ作成してください。../../references/develop-app/tests.md を参照してください。

フロントコンポーネントから選択されたレコードのロジック関数を呼び出す場合、ユーザーがその関数は 1 件のレコード専用と明示していない限り、必ず一括処理に対応したロジック関数を優先します。既定のペイロード形式は records: Array<{ id: string; ...fields }> です。records の内部では、配列名によってすでにレコードのコンテキストが示されているため、Twenty のレコード ID には id を使用します。既存の単一レコード API の維持をユーザーが明示的に求めていない限り、単一レコード用のフラットな互換ペイロードを追加しないでください。

新しいエンティティの追加

CLI を使用して新しいエンティティを追加します。適切なファイル構造、UUID、SDK のインポート、ボイラープレートが生成されます。まず、ターミナルなしで使えるスタンドアロン CLI があるか確認してください。

command -v twenty && twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input

スタンドアロン CLI がない場合はインストールします。対応している種類には twenty app add を使用し、それ以外のエンティティには、上記でリンクされている運用ルールのルール 3 と、対応する SDK 定義に従ってください。

フロントコンポーネントの既定値

表示されるすべてのフロントコンポーネントでは、既定で twenty-ui のコンポーネントと個別のアイコンを使用します。カスタムコントロールを作成したり、別の UI ライブラリを追加したりする前に、同等の Twenty UI コンポーネントを再利用してください。レイアウト用のコンテナーや、Twenty UI に同等のものがないコンテンツには、プレーンな HTML を使用できます。

フロントコンポーネントの UI を新規作成または編集する前に、インポートとレンダラーの制約については ../../references/develop-app/front-components.md を、コンポーネントの選択、テーマトークン、アクセシビリティ、表示状態については ../../references/design/front-component-ui.md を読んでください。これは最初の実装にも、その後の見た目の調整にも適用されます。API を推測したり、ドキュメント全文をアプリにコピーしたりせず、リンクされている公式コンポーネントのページで最新の props と構成方法を確認してください。

エンティティ変更後

変更に関するすべての編集が完了したら、最後に一度だけ lint と typecheck を実行し（個々の編集の後には実行しません）、その後、アプリを現在のリモートに同期します。

twenty app typecheck
yarn lint
twenty app apply

twenty app typecheck は生成されたアプリの型をチェックし、yarn lint はローカルの lint ルールをチェックし、twenty app apply はエンティティ定義を現在のリモートに同期します。すべての編集が完了した後に、3つすべてを一度だけ実行してください。各ステップの後に繰り返し実行しないでください。ユーザーから明示的にテストの実行を依頼された場合は、../../references/develop-app/tests.md に従ってください。

エンティティのフィールド、インポート、設定の形式を正確に確認する必要がある場合は、Twenty の公式ドキュメントまたはローカルの SDK ソースを参照してください。

開発リファレンス

依頼されたエンティティ作業に合致する、最小限のリファレンスを読んでください。

• オブジェクト、フィールド、リレーション、ロール、権限：../../references/develop-app/data-model.md
• ビュー、ナビゲーション、ページレイアウト、ページレイアウトのタブ、フロントコンポーネントの登録、設定メニュー項目：../../references/develop-app/layout.md
• 全ページのカスタム UI とスタンドアロンページのパターン：../../references/develop-app/standalone-pages.md
• フロントコンポーネントのソース、Twenty UI のインポート、データフック、ランタイムのインポート、ブラウザーでの検証：../../references/develop-app/front-components.md
• ロジック関数、スキル、エージェント、インストール後のフック、接続プロバイダー：../../references/develop-app/logic.md
• ワークフロー、手動トリガー、ドラフト／有効化のライフサイクル、シーダーの注意点：../../references/develop-app/workflows.md
• テスト — 対象とファイルの配置場所：../../references/develop-app/tests.md
• アプリのファイル構造とエンティティ検証チェックリスト：../../references/develop-app/app-structure.md
• フロントコンポーネントの UI デザインの詳細：../../references/design/front-component-ui.md

フロントコンポーネントを実装する前に、front-components.md を読んでください。配置には layout.md、全ページのカスタム UI には standalone-pages.md、ビジュアルデザインと Twenty UI コンポーネントの選定には front-component-ui.md を使用してください。

引き継ぎ

初回の実装を含め、画面に表示されるすべてのフロントコンポーネントには ../../references/design/front-component-ui.md を使用してください。

タスクが README、マーケットプレイスの紹介文、スクリーンショット、ロゴ、または掲載用アセットに関するものになった場合は、publish-app を使用してください。