Communitygithub.com

AlizHarb/agent-skills

AIコーディングアシスタント向けの高品質なAgent Skillsコレクションです。Laravel、ソフトウェアアーキテクチャ、デバッグ、テスト、セキュリティ、コード品質、ドキュメント、エンジニアリングのベストプラクティスに関する専門知識を、Codex、Claude Code、Cursor、Gemini CLI、および互換性のあるエージェントに提供します。

agent-skills とは?

このスキルは、Laravelプロジェクトにおいてデータ転送オブジェクト(DTO)を作成するための包括的なガイドラインを提供します。データが境界を越える場合や、Web、API、Livewire、ジョブ、コマンド、統合などで再利用される必要がある場合に使用します。 Spatie Laravel Dataパッケージがインストールされていることを前提に、`final readonly class`とコンストラクタプロパティプロモーションを使用した不変DTOを推奨しています。また、`#[MapInputName]`、`#[WithCast]`、`#[ValidationAttribute]`などのSpatie Data属性を適宜使用し、列挙型や型付きクラス定数を活用してクライアントに依存しないDTOを実現します。 このスキルは、コードアシスタントが一貫したアーキテクチャルールに従ってDTOを作成・修正できるように設計されており、テスト要件やセキュリティ要件も含まれています。Codex、Claude Code、Cursor、Gemini CLIなど、スキルファイル(SKILL.md)をサポートする任意のAIエージェントプラットフォームで動作します。

対応✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add AlizHarb/agent-skills

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

DTOまたはデータオブジェクトの作成

使用すべきタイミング

データが境界を越える場合、またはWeb、API、Livewire、ジョブ、コマンド、統合で再利用する必要がある場合にこのスキルを使用します。

必要な入力

  • フィールド、型、バリデーションルール、ソース境界、出力コンシューマ、デフォルト値、シリアライゼーション要件。

ワークフロー

  1. 既存のデータオブジェクトの規約を確認します。
  2. デフォルトでは、Spatie Laravel Data(インストール済み)を使用します。近くのモジュールに異なるデータスタイルがすでに存在する場合は、ローカルの規約に従います。
  3. 不変DTOには、コンストラクタプロパティプロモーションを使用した final readonly class を推奨します。
  4. プロパティに適したSpatie Data属性を使用します。
    • #[MapInputName]
    • #[MapOutputName]
    • #[WithCast]
    • #[WithTransformer]
    • #[Computed]
    • #[ValidationAttribute] またはパッケージのバリデーション属性
    • #[DataCollectionOf]
    • #[Lazy]
    • #[Hidden]
    • #[LoadRelation] および #[LoadMissing]
    • #[Inject] またはパッケージやプロジェクトの規約で使用する場合のプロパティインジェクション属性
  5. 閉じた集合には列挙型を、再利用可能なスカラー契約には型付きクラス定数を使用します。
  6. DTOをクライアントから独立させておきます。
  7. fromArray、fromRequest、fromModel などの名前付きコンストラクタは、有用な場合にのみ追加します。
  8. プロジェクトの規約がサポートしている場合は、バリデーションルールをDTOの近くに配置します。
  9. 永続化、認可、ワークフローロジックは避けます。
  10. 構築、バリデーションルール、シリアライゼーション、エッジケースのテストを追加します。

作成される可能性のあるファイル

  • app/Data/*.php、app/DTOs/*.php、または既存のローカル同等のもの。
  • DTOテスト。

修正される可能性のあるファイル

  • フォームリクエスト、アクション、リソース、Livewireコンポーネント、コントローラ、ジョブ、テスト。

アーキテクチャルール

  • DTOは入力または出力の契約を表します。
  • DTOはAPIとUIの両方での再利用をサポートします。
  • DTOはLivewire、Blade、コントローラ、レスポンスに依存してはなりません。
  • DTOは、実用的な場合は常に非構造化配列ではなく、最新のPHP型付けを使用する必要があります。
  • ネスト、変換、または再利用可能なデータ形状が必要な機能には、Spatie Dataコレクション/リソースを使用します。
  • 再利用可能なコード内でのアドホックな配列バリデーションよりも、Spatie Dataバリデーション属性を優先します。

テスト要件

  • 必須フィールド、型変換、デフォルト値、無効なデータ、および公開されている場合はシリアライゼーションをテストします。

セキュリティ要件

  • DTOの構築を認可として信頼しないでください。
  • 明示的に意図されていない限り、機密フィールドを出力DTOに含めないでください。

レビューチェックリスト

  • DTOは安定しており、クライアントから独立していますか?
  • フィールドは型付けされていますか?
  • バリデーションルールは十分に近くにあり、同期を維持できますか?

例

良い例

namespace App\Data;

use Spatie\LaravelData\Data;
use Spatie\LaravelData\Attributes\Validation\Email;
use Spatie\LaravelData\Attributes\Validation\Required;
use Spatie\LaravelData\Attributes\Validation\Max;

final readonly class RegisterUserData extends Data
{
    public function __construct(
        #[Required, Max(255)]
        public string $name,

        #[Required, Email]
        public string $email,
    ) {}
}

悪い例

// ❌ 型安全性が低く、バリデーションコンテキストがなく、バックグラウンドジョブでの再利用が困難。
class RegisterController extends Controller
{
    public function store(Request $request)
    {
        $this->action->handle($request->all());
    }
}

関連スキル