tech-preferences

技術スタックの好み

James の個人ソフトウェアプロジェクトでは、以下をデフォルトとして使用してください。このスキルは何を使って構築するかについてのものであり、engineering-principles は設計方法について、verifiable-trust は AI の検証と実行リスクについて扱います。

適用方法

1. まず、リポジトリの状態、関連する AGENTS.md の指示、文書化された決定事項を確認してください。既存の技術は根拠にはなりますが、自動的に永続的なアーキテクチャ上の決定となるわけではありません。
2. 新規作業では、以下のデフォルトに従ってください。既存のプロジェクトでは、重要な逸脱があれば早めに指摘し、有用な場合は標準への準拠を推奨してください。トレードオフを説明し、移行前に確認してください。移行を別の作業に便乗させてはいけません。
3. James が逸脱を維持することを選んだ場合は、その決定と理由を適切なリポジトリのドキュメントに記録してください。依頼された場合や、再検討に値する重要な新たな根拠がある場合を除き、再び議論に持ち出さないでください。
4. 大きな改善や学習の機会につながる場合は、新しい選択肢を積極的に提案してください。実績のある技術と実験的な技術を明確に区別し、リスク、運用コスト、元に戻せるかどうかを説明してください。なじみのない技術を導入する前に確認してください。 寿命の短い流行は避けてください。
5. 「検討する」は関心を示すものであり、採用の承認ではありません。記録されたプロジェクトの決定事項と明示的な除外事項は、一般的な好みより優先されます。既存の規約やインフラを再利用することを優先してください。

言語とフロントエンド

分類	指針
推奨	新しいバックエンド、CLI、開発者向けツールには Go を使用してください。まず Go 標準ライブラリを使い、有用な場合は小規模で特化したライブラリを採用してください。
Go CLI	ヘッドレス実行可能ファイルやシンプルなコマンドには、標準ライブラリの引数解析を優先してください。保守されているユーザー向け CLI で、構造化されたコマンドツリー、フラグ、ヘルプ、補完が役立つ場合は Cobra を使用し、その CLI のひな形は cobra-cli で作成してください。設定が複雑な場合に限り、Viper を追加してください。
推奨	フロントエンドには React + TypeScript + Vite、パッケージマネージャーには npm、リンターとフォーマッターには ESLint と Prettier を使用してください。共有状態には Zustand を使用してください。
許容	Tailwind CSS は許容します。コンポーネント、ルーティング、クエリ、フォーム、バリデーションの各ライブラリは、個別の状況に応じて選んでください。必須のデザインシステムはありません。
強く非推奨	React + Vite を使うよりも非常に強力で具体的な理由がない限り、Next.js は避けてください。導入する前に確認してください。
回避	明示的に必要とされない限り、Redux、Java、C#/.NET、PHP、重量級のエンタープライズフレームワークは避けてください。
スクリプト	タスクランナーには Just を使用してください。Bash は開発用のごく小さな補助に限り、実質的な Bash スクリプトは作成しないでください。再利用可能なツールには Go を使用してください。Python は主に機械学習に使用し、一般的なスクリプトには使わないでください。
検討	マイクロフロントエンドと Module Federation は検討対象であり、デフォルトではありません。
品質	プロジェクトの成熟度に応じて、レスポンシブでアクセシブルな UI を実現してください。

Go CLI の規約

• 実行ファイルの数ではなく、コマンドの契約に基づいて選びます。 Kubernetes の init プロセス、デーモン、または単純な 1 コマンドのツールには、通常、標準ライブラリの flag だけで十分です（パーサーが不要な場合もあります）。それ自体を目的として Cobra、Viper、生成されたコマンドパッケージ、補完コードを導入しないでください。
• Cobra は、保守されている対話型またはユーザー向けの CLI で、コマンド数、フラグの動作、補完、ヘルプの要件により実質的なメリットがある場合に使用します。新しい Cobra コマンドは、既存のモジュール内で cobra-cli init／add を使ってひな形を作成します。コマンドのファイルは解析とディスパッチに専念させ、動作は役割を絞った internal/<capability> パッケージに実装します。
• 既存の CLI では、パーサーの選択や移行を行う前に、実際の呼び出し元と動作を調べます。文書化されたフラグ、位置引数、標準入力、シグナル、終了ステータスを維持し、既存ファイルを上書きせず、破棄可能な場所に生成します。
• Viper は、複数のソースからの設定が実際に必要な場合にのみ使用します。設定項目が少数なら、通常の環境変数や単純なフラグを優先します。
• 独創的または規範を押し付けるようなスタイル変換より、慣用的で明示的な Go を優先します。Go Code Review Comments と Google Go Style Guide を実用的な参考資料として使用します。外部のスキルや恣意的な数値によるスタイル基準が、可読性や文書化されたプロジェクトの決定に優先することはありません。

アプリケーション、インターフェース、データ

• リポジトリとデプロイの構成： サイドプロジェクト、製品、または自己完結したコンセプトごとに 1 つのモノレポを使用します。小規模なプロジェクトでも、バックエンドのドメインは独立してデプロイできる小規模なマイクロサービスとして分けることを優先します。フロントエンドとバックエンドを 1 つのモノリシックなアプリケーションにまとめないでください。独立してデプロイできることは、リポジトリやインフラストラクチャスタックを分けることを意味しません。
• API： デフォルトでは gRPC + Protobuf を使用し、ブラウザーや外部クライアント向けには REST/JSON ゲートウェイを用意します。Buf と gRPC のライブラリ／フレームワークは歓迎します。デフォルトでは、REST ゲートウェイの OpenAPI コントラクトからフロントエンドの TypeScript API クライアントを生成します。Protobuf 生成クライアントを使う場合も、ブラウザーから直接 gRPC を使う必要はありませんが、OpenAPI はブラウザー連携の推奨方式に適合します。gRPC をバックエンドとする GraphQL は、意図的に検討する場合に限り、探求すべき領域です。
• データベース： デフォルトは PostgreSQL です。真に小規模なケースや組み込み用途には SQLite を使用します。MongoDB は使い慣れており、適している場合は問題なく使用できます。GORM は使い慣れた選択肢です。sqlc は評価を検討する価値のある代替手段ですが、必須のデフォルトではありません。ストアドプロシージャは避けます。
• 通信： 即時の一貫性が必要な場合は同期フローを、意図的に結果整合性とする場合は非同期フローを使用します。適切な場合は、コマンド形式のメッセージングよりも、事実／イベント駆動型の連携を優先します。不要な間接化を招かずに、役立つ場合は Dapr の pub/sub、サービス呼び出しなどの機能を使用します。
• ID 管理： 自前の認証ではなく、ホスト型の OIDC/OAuth を使用します。Auth0 は使い慣れた選択肢です。許可が得られる場合は Stytch の検討も有望です。認可は明示的に行います。

インフラストラクチャ、運用、セキュリティ

• ホスティング： 既存の Rackspace Spot Kubernetes のみを使用します。小規模なプロジェクトでも Kubernetes を使用し、承認なしに新しいクラウドやホスティングプラットフォームを導入しないでください。
• GitOps： ファーストパーティサービスには Argo CD + Kustomize、サードパーティアプリケーションには Helm を使用します。Terraform は避けてください。現在のインフラストラクチャとデプロイの規約を再利用します。
• 開発： Devcontainers、Just、Docker/Compose を使用し、ツールを再現可能にし、ローカル環境のセットアップを文書化します。
• CI/CD： ビルド、リリース、デプロイ／昇格のワークフローを分けた GitHub Actions を使用します。既存のフローを再利用します。一度だけビルドし、不変のアーティファクトにバージョンを付けて、同じアーティファクトを昇格させます。マルチステージの最小コンテナイメージ、固定されたベースイメージ、非 root のランタイム、不変のイメージタグを使用します。
• 構成： 環境固有の設定には環境変数を、認証情報には Kubernetes Secrets を使用します。必要な場合に限り、適切な追加のシークレット管理ソリューションを使用します。レビュー可能なアプリケーションポリシーは、バージョン管理された構造化構成に含めてもかまいません。シークレットは決して埋め込まないでください。
• テレメトリー： OpenTelemetry による計装、構造化ログ、メトリクス、分散トレースを使用します。Prometheus、Loki、Tempo を含む Grafana エコシステムを使用します。
• レジリエンス： 明示的なエラー、妥当なタイムアウト、上限のある再試行、Kubernetes のヘルス／レディネスプローブ、グレースフルシャットダウン、リソース制限を設定します。独自の連携処理を減らせる場合は Dapr を使用します。高度なレジリエンスパターンは、正当な理由がある場合にのみ追加します。
• セキュリティ： 実験段階でもセキュリティをデフォルトで確保します。最小権限、制限された権限、非 root コンテナ、入力の検証、セキュリティ／依存関係スキャンを実施します。

検証、依存関係、ドキュメント

• 動作の実装とバグ修正では、TDD をデフォルトとします。 Matt Pocock の implement → tdd ワークフローに従います。有用な公開テスト境界について合意し、実装前に動作を検証する失敗テストを 1 つ作成して（red）、それを通すために必要な最小限の実装を行い（green）、小さな垂直スライスで繰り返します。外部から観測可能な成功、失敗、復旧をテストします。コードを単に言い換えただけのテストではなく、独立して導き出した期待結果を使用します。動作を伴わない作業やテストが現実的でない作業では、価値の低いテストを作成するのではなく、明確な理由に基づく例外を設けます。
• 統合テストには Go の testing パッケージと Testcontainers を使用します。フロントエンドには Vitest + React Testing Library + Playwright を使用します。
• CI でフォーマッター、リンター、型チェック、セキュリティスキャンを必須にします。チェックは実際の不変条件を検証するものでなければなりません。
• 目的を絞った依存関係を使用し、現代的なツールを避けるのではなく、本当に有用な改善を取り入れます。マイナー／パッチ更新は自動化します。メジャーアップグレードには承認が必要です。使い慣れていない依存関係も、バージョンにかかわらず承認が必要です。
• 簡潔な README、アーキテクチャと運用のドキュメント、明確なビルド／テストコマンドを維持し、重要で自明でない判断について ADR を作成します。

技術を推奨する際は、デフォルト、重要な逸脱、トレードオフ、明示的な承認が必要な事項、記録に値する判断を明確にしてください。すでに決着した選択肢を何度も議論しないでください。