mcpField
L
laravel:debugging-prompts

laravel:debugging-prompts

github.com/jpcaparasAgent 工作流157111 次安装18 周前更新
代码仓库

关于 laravel:debugging-prompts

面向 Laravel AI 调试的提示词编写技能，说明如何提供错误、预期与实际结果、日志、状态和已尝试方案，为 Agent 提供具体诊断背景。

主要功能

  1. 01详细错误与堆栈模板
  2. 02预期与实际结果示例
  3. 03日志和状态说明指南
  4. 04假设与证据结构
  5. 05常见调试问题模板

适用场景

  1. 01整理数据库错误报告
  2. 02说明 API 响应异常
  3. 03提供队列故障和任务状态
  4. 04记录已尝试的性能优化

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jpcaparas/superpowers-laravel --skill laravel:debugging-prompts

安装后在 Claude Code 中输入/laravel:debugging-prompts确认已加载。

详细介绍

调试提示词

借助 AI 进行调试需要完整的信息。缺少上下文，只会得到无法解决你具体问题的通用建议。

错误消息和堆栈跟踪

信息不完整

"支付控制器报错了"

信息完整

"处理支付时出现错误：

错误：

Illuminate\Database\QueryException: SQLSTATE[23000]: 
Integrity constraint violation: 1452 Cannot add or update a child row: 
a foreign key constraint fails (`app`.`payments`, CONSTRAINT `payments_order_id_foreign` 
FOREIGN KEY (`order_id`) REFERENCES `orders` (`id`) ON DELETE CASCADE)

堆栈跟踪：

#0 app/Services/PaymentService.php(45): Payment::create()
#1 app/Http/Controllers/PaymentController.php(28): PaymentService->process()
#2 vendor/laravel/framework/src/Illuminate/Routing/Controller.php(54)

上下文：

  • Laravel 13.x、MySQL 8.0
  • 当 order_id 在 orders 表中不存在时发生
  • 支付数据：['order_id' => 999, 'amount' => 5000, 'status' => 'pending']
  • 数据库中不存在订单 999"

**有效原因：**包含完整的错误、堆栈跟踪、上下文，以及导致问题的具体数据。

预期行为与实际行为

含糊

"API 返回的数据不对"

具体

"Product API 返回的数据不正确：

预期行为：

{
  "data": {
    "id": 1,
    "name": "Widget",
    "price": "29.99",
    "category": {
      "id": 5,
      "name": "Tools"
    }
  }
}

实际行为：

{
  "data": {
    "id": 1,
    "name": "Widget",
    "price": 2999,
    "category": null
  }
}

问题：

  1. 价格以分为单位（2999），而不是格式化后的美元金额（"29.99"）
  2. 尽管产品的 category_id = 5，但类别仍为 null

代码：

// ProductController@show
return new ProductResource($product);

数据库中产品的 category_id = 5，但关联数据没有加载。"

**有效原因：**展示准确的预期输出与实际输出，指出具体问题，并包含相关代码。

日志条目和状态

信息不足

"队列好像出问题了"

信息充足

"队列中的任务失败：

日志条目：

[2024-01-15 10:30:15] local.ERROR: Job failed: ProcessOrderJob
{"order_id":123,"exception":"Stripe\\Exception\\InvalidRequestException: 
No such customer: cus_invalid","attempts":3}

[2024-01-15 10:30:15] local.INFO: Order state before job
{"id":123,"status":"pending","stripe_customer_id":"cus_invalid"}

任务代码：

public function handle()
{
    $customer = $this->stripe->customers->retrieve(
        $this->order->stripe_customer_id
    );
    // ...
}

状态：

  • 订单 123 的 stripe_customer_id = "cus_invalid"
  • Stripe 中不存在该客户
  • 任务已重试 3 次，现在位于 failed_jobs 表中
  • 使用 Laravel 13.x 和 Horizon"

**有效原因：**包含日志、状态信息、相关代码，以及有关重试的上下文。

假设和证据

较弱

"我觉得是缓存问题"

较强

"怀疑 Redis 缓存已过期：

**假设：**产品价格已缓存，但更新时没有使缓存失效。

证据：

  1. 在数据库中更新了产品价格：UPDATE products SET price = 3999 WHERE id = 1
  2. 数据库显示：SELECT price FROM products WHERE id = 1 → 3999
  3. API 返回旧价格：GET /api/products/1 → "price": "29.99"
  4. 执行 php artisan cache:clear 后，API 返回了正确价格："price": "39.99"

缓存代码：

public function show(Product $product)
{
    $cached = Cache::remember("product.{$product->id}", 3600, function () use ($product) {
        return new ProductResource($product);
    });
    return $cached;
}

**问题：**产品更新时，缓存键没有失效。需要在 ProductObserver 中使缓存失效，或从 show 方法中移除缓存。"

**有效原因：**假设明确、证据具体、代码相关，并提出了建议的解决方案。

已尝试的解决方案

没有帮助

"我试了一些办法，但都没用"

有帮助

"尝试过的解决方案及结果：

**尝试 1：**添加预加载

$products = Product::with('category')->get();

**结果：**仍然出现 N+1 查询。Debugbar 显示 101 次查询（1 次查询产品，100 次查询类别）。

**尝试 2：**获取数据后使用 load()

$products = Product::all();
$products->load('category');

**结果：**问题依旧，仍然是 101 次查询。

**尝试 3：**检查关联定义

// In Product model
public function category()
{
    return $this->belongsTo(Category::class);
}

**结果：**关联看起来正确。products 表中存在外键 category_id。

**当前状态：**预加载语法看起来正确，但没有生效。使用 Laravel 13.x。我遗漏了什么？"

**有效原因：**说明尝试过哪些方法、使用的准确代码和观察到的结果，有助于避免推荐已经尝试过的方案。

调试模板

模板：错误报告
**Error:** [Full error message]
**Stack trace:** [Complete stack trace]
**File/Line:** [Where error occurs]
**Context:** [Laravel version, packages, environment]
**Data:** [Input data causing error]
**Expected:** [What should happen]
模板：异常行为
**Expected:** [Describe expected behavior with example]
**Actual:** [Describe actual behavior with example]
**Code:** [Relevant code snippet]
**State:** [Database state, variable values]
**Environment:** [Laravel version, Sail/host, packages]
模板：性能问题
**Problem:** [Describe slow operation]
**Metrics:** [Response time, query count, memory usage]
**Query log:** [Slow queries from Debugbar/Telescope]
**Code:** [Code causing performance issue]
**Dataset size:** [Number of records involved]
**Attempted:** [Optimizations already tried]

速查

借助 AI 高效调试：

  • 提供完整错误信息——完整消息、堆栈跟踪、文件和行号
  • 展示两方面的信息——预期行为与实际行为
  • 包含日志——错误日志、信息日志、状态转储
  • 分享证据——数据库查询、API 响应、变量转储
  • 记录尝试过程——尝试过什么、准确代码、结果
  • 提供上下文——Laravel 版本、环境、软件包

信息越多，解决问题越快。调试时，请尽可能提供更多信息。

评论

支持 Markdown