Communitygithub.com

AlizHarb/agent-skills

一份不断增长的高质量AI智能体技能集合,旨在增强Codex、Claude Code、Cursor、Gemini CLI等兼容代理的Laravel开发、软件架构、调试、测试、安全、代码质量、文档及工程最佳实践能力。

agent-skills 是什么?

该技能集合为AI编码助手提供了专业且可复用知识库,覆盖Laravel框架、软件架构设计、调试策略、测试方法、安全实践、代码质量提升、文档编写及工程最佳实践。它支持Codex、Claude Code、Cursor、Gemini CLI等多种主流AI编码代理,帮助开发者通过结构化提示和预定义工作流高效完成常见开发任务。技能以Markdown文件形式组织,包含明确的输入要求、分步工作流程、架构规则、安全要求和评审清单,确保AI代理能生成符合项目规范和最佳实践的代码。无论是创建数据对象、编写测试还是重构代码,该集合都能提供一致且高质量的指导。

兼容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add AlizHarb/agent-skills

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

创建数据传输对象(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());
    }
}

相关技能