harper-best-practices

Harper のベストプラクティス

Harper 上でスケーラブルかつ安全で高性能なアプリケーションを構築するためのガイドラインです。初期のスキーマ設計から高度なデプロイ戦略まで、あらゆる内容を扱います。

使用するタイミング

次の作業を行う際に、これらのガイドラインを参照してください。

• データベーススキーマを定義または変更する
• REST／WebSocket API を実装または拡張する
• 認証とセッション管理を扱う
• カスタムリソースと拡張機能を扱う
• データの保存と取得（Blob、ベクトルインデックス作成）を最適化する
• アプリケーションを Harper Fabric にデプロイする

仕組み

1. タスクの要件（スキーマ設計、API のニーズ、またはインフラストラクチャのセットアップ）を確認します。
2. 「優先度別のルールカテゴリ」で該当するカテゴリを参照し、判断がもたらす影響を理解します。
3. 以下の「クイックリファレンス」セクションから該当するルールを選び、詳細なルールファイルを読んで適用します。
4. 新しいテーブルを作成する場合は、schema- ルールを優先します。
5. 機能を拡張する場合は、logic- と api- のルールを参照します。
6. デプロイ前に、実装が ops- ルールに準拠していることを確認します。

例

各ルールの小節に記載されている具体例（GraphQL スキーマ、REST クエリパターン、デプロイワークフローのスニペット）を参照してください。

優先度別のルールカテゴリ

優先度	カテゴリ	影響	プレフィックス
1	スキーマとデータ設計	高	schema-
2	API と通信	高	api-
3	ロジックと拡張	中	logic-
4	インフラストラクチャと運用	中	ops-

クイックリファレンス

1. スキーマとデータ設計（高）

• adding-tables-with-schemas — GraphQL スキーマを使用して Harper データベースにテーブルを追加するためのガイドラインです。
• schema-design-tooling — コアディレクティブや GraphQL ツール設定など、Harper のスキーマ設計に関するベストプラクティスです。
• defining-relationships — GraphQL を使用して Harper のテーブル間のリレーションシップを定義し、使用する方法です。
• vector-indexing — Harper で類似性検索用のベクトルインデックスを有効にし、クエリする方法です。
• using-blob-datatype — Harper で効率的にバイナリデータを保存するために Blob データ型を使用する方法です。
• handling-binary-data — Harper で画像や音声などのバイナリデータを保存し、提供する方法です。

2. API と通信（高）

• automatic-apis — Harper が自動生成する REST API と WebSocket API の使用方法です。
• querying-rest-apis — クエリパラメーターを使用して Harper REST API のデータをフィルタリング、並べ替え、ページネーションする方法です。
• real-time-apps — WebSocket と Pub/Sub を使用して Harper でリアルタイム機能を構築する方法です。
• checking-authentication — Harper リソースでユーザー認証とセッションを扱う方法です。

3. ロジックと拡張（中）

• custom-resources — Harper で JavaScript または TypeScript を使用してカスタム REST エンドポイントを定義する方法です。
• extending-tables — Harper で自動生成されたテーブルリソースにカスタムロジックを追加する方法です。
• programmatic-table-requests — tables オブジェクトを使用して Harper のテーブルをプログラムから操作する方法です。
• typescript-type-stripping — ビルド手順なしで Harper 上で TypeScript ファイルを直接実行する方法です。
• caching — 外部ソースのデータを Harper に統合してキャッシュする方法です。

4. インフラストラクチャと運用（中級）

• deploying-to-harper-fabric — CLI を使用して Harper アプリケーションを Harper Fabric にデプロイする方法、リリースが認定されたことを確認する方法、および以前のリリースの deployment_id を有効にしてロールバックする方法です。
• deploying-from-ci — OIDC トラステッドパブリッシングを使用して GitHub Actions から Harper アプリケーションをデプロイし、CI に Harper の認証情報を保存しない方法です。harper deploy setup=true provider=github-actions を使ったワンコマンドでのセットアップも含まれます。
• creating-a-fabric-account-and-cluster — Harper Fabric のアカウント、組織、クラスターを作成する方法です。
• creating-harper-apps — CLI を使用して新しい Harper アプリケーションを初期化する方法です。
• serving-web-content — Harper で静的ファイルと統合された Vite/React アプリケーションを配信する方法です。
• logging — コンソールキャプチャ、詳細なロガーインターフェース、プログラムによるログ取得など、Harper でのロギングのベストプラクティスです。
• load-env — loadEnv プラグインを使用して、.env ファイルから環境変数を Harper アプリケーションに読み込む方法です。
• v5-upgrade — Harper アプリケーションを v5 に移行する際の破壊的変更と推奨される更新内容です。
• delegating-to-the-built-in-agent — CLI とエージェント操作 API を通じて、Harper の組み込みエージェントにタスクを委任する方法です。

使用方法

詳しい説明とコード例については、各ルールファイルをお読みください。

rules/adding-tables-with-schemas.md
rules/schema-design-tooling.md
rules/automatic-apis.md
rules/creating-harper-apps.md
rules/logging.md

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

すべてのルールを展開した完全なガイドについては、AGENTS.md をご覧ください。