Communitygithub.com

AlizHarb/agent-skills

AI 코딩 어시스턴트를 위한 고품질 Agent Skill 모음입니다. Codex, Claude Code, Cursor, Gemini CLI 및 호환 에이전트에 Laravel, 소프트웨어 아키텍처, 디버깅, 테스팅, 보안, 코드 품질, 문서화, 엔지니어링 모범 사례에 대한 전문 지식을 제공합니다.

agent-skills란 무엇인가요?

이 스킬은 AI 코딩 어시스턴트(Codex, Claude Code, Cursor, Gemini CLI 등)가 DTO(Data Transfer Object) 또는 데이터 객체를 생성할 때 따라야 할 일관되고 모범적인 워크플로우를 정의합니다. Spatie Laravel Data 패키지를 기본 도구로 사용하며, `final readonly class`와 생성자 프로퍼티 프로모션을 통해 불변 DTO를 권장합니다. 또한 `#[MapInputName]`, `#[WithCast]`, `#[ValidationAttribute]` 등 Spatie Data 속성을 적절히 활용하여 입력/출력 매핑, 캐스팅, 유효성 검사, 직렬화를 처리합니다. 이 스킬은 DTO가 웹, API, Livewire, 잡, 명령 등 여러 소비자에서 재사용될 수 있도록 클라이언트 중립성을 유지하고, 지속성, 인가, 워크플로 로직을 포함하지 않도록 강제합니다. 또한 DTO에 대한 테스트 작성(생성, 유효성 검사, 직렬화, 경계 조건)을 요구하며, 민감한 필드가 출력 DTO에 의도치 않게 포함되지 않도록 보안 요구사항을 명시합니다. Laravel 프로젝트에서 DTO를 체계적으로 관리하고자 하는 개발자에게 필수적인 스킬입니다.

지원 대상✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add AlizHarb/agent-skills

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

DTO 또는 데이터 객체 생성

사용 시점

데이터가 경계를 넘거나 웹, 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());
    }
}

관련 스킬