terminal-ui

DevEx 開発者エクスペリエンス 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 - ターミナル出力を 1 回の書き込みにまとめる
• render-overwrite-dont-clear - クリアして再描画するのではなく、コンテンツを上書きする
• render-synchronized-output - アニメーションには同期出力プロトコルを使用する
• 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 - レイアウトには Flexbox を使用する Box コンポーネントを使う
• 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. 堅牢性と互換性（低〜中）

• robust-tty-detection - TTY を検出し、それに応じて動作を調整する
• robust-signal-handling - プロセスシグナルを適切に処理する
• robust-exit-codes - 意味のある終了コードを使用する
• robust-terminal-restore - 終了時に必ずターミナルの状態を復元する
• robust-graceful-degradation - 機能が限られたターミナルでも適切に動作する

使用方法

詳しい説明とコード例については、各リファレンスファイルを参照してください。

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

コンパイル済みドキュメント全体

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