global-standards

プロジェクト標準

このスキルでは、言語やフレームワークを問わず、コードベース全体に適用されるプロジェクト全体のコーディング標準、規約、ベストプラクティスについて、包括的なガイダンスを提供します。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください。

• コードを書く場合 - プロジェクト標準との一貫性を確保する
• アーキテクチャ上の判断を行う場合 - 確立されたパターンに従う
• オンボーディング時 - プロジェクトの規約を理解する
• コードレビュー時 - 標準に準拠しているか確認する
• リファクタリング時 - 変更中も一貫性を維持する
• 新機能を設定する場合 - プロジェクトの規約に従う

中核となる標準分野

1. コーディングスタイル

適用するタイミング：

• 変数、関数、クラス、モジュール、ファイルに名前を付けるとき
• 読みやすさと保守性を考慮してコードを構成するとき
• 関数のサイズや単一責任について判断するとき
• 未使用コード、コメントアウトされたブロック、不要なインポートを削除するとき
• 重複を避けるために再利用可能なロジックを抽出するとき
• 一貫したフォーマットとインデントを適用するとき
• 明瞭さと簡潔さを高めるためにコードをリファクタリングするとき

原則：

• 意図が伝わる、明確で説明的な名前
• DRY（Don't Repeat Yourself）原則
• 単一責任の原則
• 構造によって自己説明するコード
• コードベース全体で一貫したフォーマット

適用対象： すべてのコードファイル（.py,.js, .ts,.jsx, .tsx,.vue, .rb,.go, .java,.rs, .cpp,.c, .swift,.kt）

2. コメントの標準

適用するタイミング：

• コードにコメントが必要かどうかを判断するとき
• 複雑なアルゴリズムや自明でないビジネスロジックを文書化するとき
• docstringや関数の説明を書くとき
• 既存のコメントが適切かどうかレビューするとき
• 古くなったコメントや誤解を招くコメントを削除するとき
• 自明でないコード上の判断や回避策を説明するとき

原則：

• 最小限で役立つコメント
• 何をするかではなく、なぜそうするかを説明する
• 明確な命名によって、コードを自己説明的に保つ
• コメントでは複雑なロジックやビジネスルールを説明する
• コードの動作を言い換えるだけのコメントは避ける
• コメントを常に有効で関連性のある状態に保つ

適用対象： コードベース全体のすべてのコードファイル

3. エラー処理

適用するタイミング：

• コードをtry-catchまたはtry-exceptブロックで囲むとき
• カスタム例外クラスまたはエラークラスを作成するとき
• エラーバウンダリー（Reactなど）を実装するとき
• API呼び出しによるHTTPエラーを処理するとき
• ユーザーにわかりやすいエラーメッセージを表示するとき
• 指数バックオフによる再試行ロジックを実装するとき
• finallyブロックでリソースをクリーンアップするとき
• エラーを捕捉するか、伝播させるか判断するとき
• 適切な重大度レベルでエラーをログに記録するとき
• 外部サービス向けにサーキットブレーカーを実装するとき
• 構造化されたレスポンスで検証エラーを処理するとき

原則：

• ユーザーにわかりやすいエラーメッセージ
• 適切な例外の型と階層
• グレースフルデグラデーション
• コンテキストを含む包括的なログ記録
• finallyブロックでのリソースのクリーンアップ
• 適切なエラー伝播
• 一時的な障害に対する再試行ロジック

適用対象： エラーが発生する可能性のあるすべてのコード（APIハンドラー、サービス関数、データ処理、ファイル操作、外部連携、ネットワークリクエスト、データベース操作）

4. 入力検証

適用する場面：

• フロントエンドでフォーム入力を検証する
• API リクエスト本文、クエリパラメーター、ヘッダーを検証する
• サーバーサイドの検証ロジックを実装する
• 検証スキーマ（Zod、Yup、Pydantic、Joi）を作成する
• XSS や SQL インジェクションを防ぐため、ユーザー入力をサニタイズする
• データ型、形式、範囲、必須フィールドを検証する
• ビジネスルールの検証を実装する
• 検証エラーメッセージを表示する
• ドメイン固有のルールに対するカスタムバリデーターを作成する
• ファイルアップロードの検証を処理する

原則：

• クライアント側とサーバー側の両方で検証する
• 一貫性を保つため、検証ライブラリを使用する
• セキュリティ上の脆弱性を防ぐため、入力をサニタイズする
• 明確で、具体的な対処方法がわかるエラーメッセージを提供する
• システム境界で検証する
• ブロックリストではなく、許可リストを使用する

対象： フォームコンポーネント、API ハンドラー、リクエストバリデーター、入力サニタイザー、スキーマ定義、検証ミドルウェア、ファイルアップロード、Webhook、外部 API との連携

5. 技術スタックの一貫性

適用する場面：

• 新しい機能に使用するライブラリやパッケージを選ぶ
• フレームワーク固有のパターンを使って機能を実装する
• 新しいサービス、連携、サードパーティ API を設定する
• データベース接続、ORM 設定、クエリビルダーを設定する
• 認証、認可、セキュリティ機能を追加する
• テストフレームワーク、ツール、テストユーティリティを設定する
• デプロイ、CI/CD パイプライン、インフラストラクチャを設定する
• 新しい依存関係を追加するかどうかを評価する
• キャッシュ、監視、ロギング、オブザーバビリティを実装する
• 複数のアプローチから選択する

原則：

• 既存の技術選択との一貫性を保つ
• フレームワーク固有のパターンと慣用表現に従う
• 新しい依存関係を追加するより、既存のツールを優先する
• 技術的な決定を文書化する
• アーキテクチャの一貫性を維持する

対象： フロントエンド、バックエンド、データベース、インフラストラクチャ、テスト、デプロイ、サードパーティとの連携

6. プロジェクトの規約

適用する場面：

• ファイルとディレクトリ構造を整理する
• Git のコミットメッセージや PR の説明を書く
• 環境変数、設定、シークレットを管理する
• プロジェクトの依存関係を追加または更新する
• CI/CD ワークフローを設定または変更する
• フィーチャーフラグを実装する
• README ファイルやプロジェクトのドキュメントを更新する
• コードレビューのプロセスを確立する
• 変更履歴やリリースノートを管理する
• リンター、フォーマッター、コミット前フックを設定する
• 開発環境を設定する
• モノレポや複数パッケージの構成を管理する

原則：

• ファイルとディレクトリの構成に一貫性を持たせる
• コミットメッセージの規約に従う
• ドキュメントを明確にする
• 依存関係を適切に管理する
• 品質チェックを自動化する
• 開発ワークフローを明確にする

対象： 設定ファイル（.env、package.json、requirements.txt、pyproject.toml、Dockerfile、docker-compose.yml、Makefile）、ディレクトリ（.github/、.gitlab-ci/、scripts/、docs/）、ドキュメントファイル（README.md、CHANGELOG.md、CONTRIBUTING.md）

参照ファイル

詳細な標準ドキュメントを確認するには、必要に応じて参照ファイルを読み込んでください。

• references/coding-style.md - 詳細なコーディングスタイルガイドライン、命名規則、書式設定の標準
• references/commenting.md - コメント作成のベストプラクティス、docstring の標準、コメントを付ける場面
• references/error-handling.md - エラー処理のパターン、例外の階層、ロギング戦略
• references/validation.md - 検証パターン、スキーマ定義、セキュリティに関する考慮事項
• references/tech-stack.md - 技術スタックのリファレンス、フレームワークのパターン、依存関係のガイドライン
• references/conventions.md - プロジェクトの規約、ファイル構造、Git ワークフロー、CI/CD の標準

特定の領域で作業する際は、詳細なガイダンスを得るために適切な参照ファイルを読み込んでください。

ベストプラクティス

一貫性を最優先する

• コードベース内の既存のパターンに従う
• 判断に迷った場合は、周囲のコードのスタイルに合わせる
• すべてのファイルで一貫性を保つ

段階的な拡張

• シンプルで明確なコードから始めます
• 必要な場合にのみ複雑さを加えます
• 明確さと保守性を高めるためにリファクタリングします

ドキュメント

• ドキュメントを最新の状態に保ちます
• 判断とトレードオフを記録します
• ドキュメントに例を含めます

品質ゲート

• リンターとフォーマッターを使用します
• コミット前にテストを実行します
• コードが標準に準拠しているか確認します

他のスキルとの連携

• code-review：標準への準拠を確認するためにコードレビューを行う際に使用します
• dead-code-removal：コードを整理する際はコーディングスタイルに従います
• debugging：エラーを分析する際はエラー処理の標準を適用します
• dependency-management：依存関係を管理する際は技術スタックの標準に従います