DevEx Developer Experience TUI ベストプラクティス

Ink (CLI 用の React) と Clack プロンプトを使用して TypeScript ターミナルユーザーインターフェースを構築するための包括的な開発者体験ガイドです。8 つのカテゴリにわたる 42 のルールを含み、自動リファクタリングとコード生成を導くために影響度順に優先順位付けされています。

適用タイミング

以下の場合にこれらのガイドラインを参照してください：

• @clack/prompts を使用してインタラクティブプロンプト付きの CLI ツールを構築する
• Ink で React ベースのターミナル UI を作成する
• キーボード入力とユーザーインタラクションを処理する
• ターミナルレンダリングを最適化してちらつきを防ぐ
• 開発者向けの CLI 体験を設計する

ルールカテゴリ（優先度順）

優先度	カテゴリ	インパクト	プリフィックス
1	レンダリング & 出力	CRITICAL	render-
2	入力 & キーボード	CRITICAL	input-
3	コンポーネントパターン	HIGH	tuicomp-
4	ステート & ライフサイクル	HIGH	tuistate-
5	プロンプト設計	MEDIUM-HIGH	prompt-
6	UX & フィードバック	MEDIUM	ux-
7	設定 & CLI	MEDIUM	tuicfg-
8	ロバストネス & 互換性	LOW-MEDIUM	robust-

クイックリファレンス

1. レンダリング & 出力 (CRITICAL)

• render-single-write - ターミナル出力をシングルライトでバッチ処理
• render-overwrite-dont-clear - クリアして再描画する代わりにコンテンツを上書き
• render-synchronized-output - アニメーション用に Synchronized Output Protocol を使用
• render-60fps-baseline - スムーズなアニメーションのために 60fps を目指す
• render-partial-updates - 変更されたリージョンのみを更新
• render-escape-sequence-batching - ANSI エスケープコード生成を最終出力に遅延

2. 入力 & キーボード (CRITICAL)

• input-useinput-hook - キーボード処理に useInput フックを使用
• input-immediate-feedback - 入力に対して即座にビジュアルフィードバックを提供
• input-modifier-keys - 修飾キーを正しく処理
• input-isactive-focus - フォーカス管理に isActive オプションを使用
• input-escape-routes - 常にエスケープルートを提供

3. コンポーネントパターン (HIGH)

• tuicomp-box-flexbox - レイアウトに Box コンポーネントと Flexbox を使用
• tuicomp-text-styling - すべての表示コンテンツに Text コンポーネントを使用
• tuicomp-measure-element - 動的サイジング用に measureElement を使用
• tuicomp-static-for-logs - ログ出力に Static コンポーネントを使用
• tuicomp-percentage-widths - レスポンシブレイアウトにパーセンテージ幅を使用
• tuicomp-border-styles - ビジュアル構造にボーダースタイルを使用

4. ステート & ライフサイクル (HIGH)

• tuistate-useapp-exit - アプリケーションライフサイクルに useApp フックを使用
• tuistate-cleanup-effects - アンマウント時に常にエフェクトをクリーンアップ
• tuistate-functional-updates - 古いクロージャを避けるため関数型ステート更新を使用
• tuistate-usecallback-stable - useCallback でコールバックを安定化
• tuistate-usememo-expensive - useMemo で高コストな計算をメモ化

5. プロンプト設計 (MEDIUM-HIGH)

• prompt-group-flow - 複数ステップのプロンプトに Clack の group() を使用
• prompt-validation - 説明的なメッセージを含む早期入力検証
• prompt-cancellation - isCancel でキャンセルを優雅に処理
• prompt-spinner-tasks - 長時間の操作に Spinner と Tasks を使用
• prompt-custom-render - @clack/core でカスタムプロンプトを構築

6. UX & フィードバック (MEDIUM)

• ux-progress-indicators - 1 秒以上かかる操作に進捗インジケータを表示
• ux-color-semantics - セマンティックで一貫性のある色を使用
• ux-error-messages - 実行可能なエラーメッセージを作成
• ux-next-steps - 完了後に次のステップを表示
• ux-intro-outro - セッションフレーミング用に Intro と Outro を使用

7. 設定 & CLI (MEDIUM)

• tuicfg-sensible-defaults - すべてのオプションに合理的なデフォルトを提供
• tuicfg-env-vars - 標準環境変数をサポート
• tuicfg-flags-over-args - 位置指定引数よりもフラグを優先
• tuicfg-help-system - 包括的なヘルプシステムを実装
• tuicfg-json-output - マシン可読出力形式をサポート

8. ロバストネス & 互換性 (LOW-MEDIUM)

• robust-tty-detection - TTY を検出して動作を適切に調整
• robust-signal-handling - プロセスシグナルを優雅に処理
• robust-exit-codes - 意味のある終了コードを使用
• robust-terminal-restore - 終了時に常にターミナルの状態をリストア
• robust-graceful-degradation - 制限されたターミナル用に優雅にデグレード

使い方

詳細な説明とコード例については、個別のリファレンスファイルを参照してください：

• セクション定義 - カテゴリ構造とインパクトレベル
• ルールテンプレート - 新しいルールを追加するためのテンプレート
• render-single-write - ルールファイル例
• input-useinput-hook - ルールファイル例

完全なコンパイルドキュメント

すべてのルールを展開した完全なガイド: AGENTS.md