> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 优质指令 vs. 糟糕指令

> 哪些有效，哪些无效

<Note>请务必阅读 [何时使用 Devin](/zh/essential-guidelines/when-to-use-devin) 和 [如何有效指示 Devin](/zh/essential-guidelines/instructing-devin-effectively) 获取更多关键提示。</Note>

<CardGroup cols={1}>
  <Card title="添加新的 API 端点" icon="server">
    **良好做法**

    <Check>
      "创建一个新的端点 `/users/stats`，返回一个 JSON 对象，其中包含用户总数以及平均注册年龄。使用我们在 PostgreSQL 中现有的 users 表。你可以参考 `statsController.js` 中的 `/orders/stats` 端点了解响应结构。确保新的端点被纳入 `StatsController.test.js` 测试套件覆盖范围。"
    </Check>

    **为什么这种方式有效：**

    * 清晰指定了路由和预期响应格式
    * 引用了现有代码作为模板
    * 明确了数据源 (users 表)
    * 包含测试覆盖要求

    <br />

    ***

    <br />

    **糟糕做法**

    <Warning>
      "添加一个用户统计端点。"
    </Warning>

    **为什么这种方式失败：**

    * 未具体说明需要包含哪些统计信息
    * 未提及数据源
    * 未参考现有模式
    * 缺少测试要求
  </Card>

  <Card title="用于展示数据的前端功能" icon="window">
    **良好做法**

    <Check>
      "在 `UserProfileComponent` 中添加一个下拉框，展示用户角色列表 (admin、editor、viewer) 。使用 `DropdownBase` 的样式。当选择某个角色后，调用现有 API 设置该用户角色。通过检查选择结果是否更新了数据库中的用户角色来进行验证。有关如何正确编写测试，请参考你的知识库。"
    </Check>

    **为什么这种方式有效：**

    * 指明了具体组件
    * 列出了要包含的具体角色
    * 引用了已有样式组件
    * 定义了用户交互流程
    * 包含验证步骤

    <br />

    ***

    <br />

    **糟糕做法**

    <Warning>
      "让用户个人资料页面更“用户友好”。加一个方式让他们能修改角色，并确认功能正常。"
    </Warning>

    **为什么这种方式失败：**

    * “用户友好”是主观概念
    * 未提到具体 UI 组件
    * 用户交互流程不清晰
    * 验证标准含糊不清
  </Card>
</CardGroup>

<div id="more-examples">
  ## 更多示例
</div>

<div id="good">
  ### 良好示例
</div>

<CardGroup cols={1}>
  <Card title="编写单元测试" icon="vial">
    <Check>
      "为 AuthService 的 login 和 logout 方法添加 Jest 测试，确保这两个函数的测试覆盖率至少达到 80%。参考 `UserService.test.js` 作为示例。实现完成后，运行 `npm test -- --coverage`，并确认覆盖率报告中这两个函数的覆盖率都大于 80%。同时确认在有效和无效凭证情况下测试都能通过，并且 logout 能正确清除会话数据。"
    </Check>

    **为什么是良好示例？** 有清晰的成功指标 (80% 覆盖率) ，提供了可供 Devin 参考的示例 (`UserService.test.js`) ，并且范围明确，包含具体的验证步骤。
  </Card>

  <Card title="迁移或重构现有代码" icon="code-branch">
    <Check>
      "将 `logger.js` 从 JavaScript 迁移到 TypeScript。我们已经有 `tsconfig.json` 和用于验证的 `LoggerTest.test.js` 测试套件。确保能够无错误编译通过，并且不要修改现有配置！迁移完成后，通过以下方式验证：1) 运行 `tsc` 确认没有类型错误；2) 运行 `npm test LoggerTest.test.js` 执行测试套件，确保所有测试通过；3) 检查代码库中所有现有的 logger 方法调用在迁移后仍然可以正常工作且没有类型错误。"
    </Check>

    **为什么是良好示例？** 有清晰的模板 (`tsconfig.json`) 和测试套件用于即时反馈，还有具体的编译和验证步骤。
  </Card>

  <Card title="更新 API 或数据库查询" icon="database">
    <Check>
      "我们将从 pg 切换到 sequelize (请阅读 [https://sequelize.org/api/v6/identifiers](https://sequelize.org/api/v6/identifiers)) 。请将 UserModel 的查询更新为使用 Sequelize 方法。参考 `OrderModel` 了解在当前代码库中的实现方式。实现完成后，通过以下方式验证：1) 运行 `npm run test:integration UserModel.test.js`，检查所有集成测试是否通过；2) 在包含 1000 个用户的测试数据集上检查执行时间，确认查询性能没有下降；3) 运行 `npm run test:e2e user-flows.test.js`，验证所有 CRUD 操作在端到端流程中仍然保持数据完整性。"
    </Check>

    **为什么是良好示例？** Devin 可以模仿已知模式，并且有明确的参考 (`OrderModel.js`) 。提供了文档链接以便 Devin 知道需要查阅，同时包含具体的性能和功能验证步骤以及精确的测试命令。
  </Card>

  <Card title="根据设计实现功能" icon="paintbrush">
    <Check>
      "根据这个 Figma 文件实现定价页：[https://figma.com/file/abc123/Pricing-Page。重点关注“Pricing](https://figma.com/file/abc123/Pricing-Page。重点关注“Pricing) Section”这个画板。使用我们在 tailwind.config.ts 中定义的 Tailwind 配置来设置颜色和间距。复用 src/components/ui/ 中已有的 Card 和 Button 组件。实现完成后，启动开发服务器，并在桌面端 (1440px) 和移动端 (375px) 宽度下分别截图。在页面与设计完全吻合之前，不要打开 PR。"
    </Check>

    **为什么是良好示例？** 提供了具体的 Figma 文件链接，指出了精确的画板名称，引用了项目的设计系统和现有组件，并要求 Devin 在打开 PR 之前先通过视觉对比验证实现效果。在连接了 [Figma MCP](/zh/work-with-devin/mcp) 后，Devin 可以直接从该文件中读取设计 Token。
  </Card>

  <Card title="排查生产环境 Bug" icon="bug">
    <Check>
      "用户反馈在结账页面出现 500 错误。使用 Sentry MCP 拉取 payments-api 项目的最新堆栈跟踪。检查数据库中是否存在相关的数据问题。找到根因、修复问题，并添加回归测试。在 PR 描述中附上该 Sentry Issue 的链接。"
    </Check>

    **为什么是良好示例？** 将 Devin 指向正确的工具 ([MCP 集成](/zh/work-with-devin/mcp)) ，提供了清晰的排查路径，并明确了预期产出 (修复 + 回归测试 + PR) 。
  </Card>
</CardGroup>

<div id="bad">
  ### 不佳示例
</div>

<CardGroup cols={1}>
  <Card title="开放式代码审查" icon="magnifying-glass">
    <Warning>
      “找出我们代码库中的问题并修复它们”
    </Warning>

    **为什么不好？** 这个请求太模糊、太开放，没有任何成功标准，Devin 也不知道什么时候算完成。

    **可以这样做：** 对特定 PR 使用 [Devin Review](/zh/work-with-devin/devin-review) 进行自动代码审查，或者给 Devin 一个更有针对性的任务，比如“查找并修复 `src/services/` 中所有已弃用 `oldLogger` API 的使用。”
  </Card>

  <Card title="纯主观的视觉请求" icon="palette">
    <Warning>
      “让着陆页看起来更好”
    </Warning>

    **为什么不好？** “更好”是主观的，Devin 没有可以对齐的评判标准。Devin 能够构建功能性 UI，并根据设计规格实现界面，但它无法独立做出审美判断。

    **可以这样做：** 提供 Figma 设计稿、参考网站，或具体修改要求：“把首屏 (hero 区域) 字体大小增大到 48px，增加 32px 的内边距，并使用我们 Tailwind 配置中的 `indigo-500` 颜色。”
  </Card>

  <Card title="高度复杂且模糊的项目" icon="sitemap">
    <Warning>
      “为我们的应用构建一个新的微服务架构。”
    </Warning>

    **为什么不好？** 这是一个非常庞大且结构不清晰的任务，需要做大量架构决策、权衡取舍，并依赖许多不在提示中的上下文信息。

    **更好的方式是拆解它：**

    1. 使用 [Ask Devin](/zh/work-with-devin/ask-devin) 调查你的代码库并梳理依赖关系
    2. 让 Devin 提出具体的架构方案并分析各自的权衡
    3. 为实现每个服务创建单独的会话——使用 [managed Devins](/zh/work-with-devin/advanced-capabilities#managed-devins) 并行运行它们
  </Card>
</CardGroup>