最佳实践
提示词工程
编写高效提示词的最佳实践
高效的提示词是 AI 辅助开发成功的基础。清晰、具体并附带恰当上下文的请求，能让 Verdent 交付准确、相关的结果。
你将学到什么
- 编写高效提示词的最佳实践
- 如何提供上下文并避免常见错误
- @-提及和子智能体委派等进阶技巧
- 结构良好的提示词示例
- 迭代优化策略
什么样的提示词才高效
高效的提示词清晰、具体，并提供必要的上下文，让 Verdent 理解你的意图并交付准确结果。
关键原则：
- 具体明确 - 准确说明你的需求，而非含糊的请求
- 包含细节 - 当你有偏好时提供技术规格
- 明确范围 - 说明涉及哪些文件/组件
- 提供上下文 - 帮助 Verdent 理解你的架构
- 说明预期结果 - 描述成功的样子
- 使用自然语言 - 无需特殊语法
示例转换：
糟糕：
Fix the code良好：
Add input validation to the email field in ContactForm.js to reject invalid email formats糟糕：
Add authentication良好：
Add JWT authentication using the same middleware pattern as auth.js, store tokens in httpOnly cookies常见的提示词错误
示例提示词：
Make the app betterFix the bugs| 问题 | 解决方案 |
|---|---|
| Verdent 不知道你想要哪些改进，或要处理哪些 bug | 准确说明需要改进什么或要修复哪个 bug |
示例提示词：
Add authentication| 问题 | 解决方案 |
|---|---|
| 你使用 OAuth 时 Verdent 可能实现 JWT，反之亦然 | 明确实现方式、现有模式和技术要求 |
示例提示词：
Build the entire user management system with authentication, authorization, profiles, settings, and admin dashboard| 问题 | 解决方案 |
|---|---|
| 复杂的多系统请求难以一次性正确执行 | 拆分成更小的任务——先认证，再授权，然后是用户资料 |
示例提示词：
Update the validation logic| 问题 | 解决方案 |
|---|---|
| 不清楚要修改哪些文件或验证 | 明确范围："在 UserController.js 中更新验证，要求强密码" |
示例提示词：
Expecting Verdent to know your specific business rules or constraints| 问题 | 解决方案 |
|---|---|
| Verdent 在没有你具体需求的情况下实现通用方案 | 明确陈述所有约束、业务规则和需求 |
示例提示词：
Referencing files without including them in context| 问题 | 解决方案 |
|---|---|
| Verdent 可能无法访问你所讨论的文件 | 使用 @filename.js 显式包含相关文件 |
示例提示词：
Repeatedly asking for the same thing when Verdent encounters errors| 问题 | 解决方案 |
|---|---|
| 相同的方法产生相同的错误 | 阅读错误信息，根据失败原因调整提示词 |
示例提示词：
Requesting large refactorings or multi-file changes without using Plan Mode first| 问题 | 解决方案 |
|---|---|
| 直到文件已被修改你才看到完整范围 | 对复杂任务切换到 Plan Mode，在执行前审查方案 |
对于复杂改动，启用 Plan Mode 在执行前审查方案，这能尽早发现理解偏差。
示例提示词：
Using Auto-Run or Skip Permission Mode without Git initialized| 问题 | 解决方案 |
|---|---|
| 如果 Verdent 做了不想要的改动则没有安全网 | 在使用宽松模式前，始终初始化 Git 并提交 |
示例提示词：
Providing incomplete requirements and expecting Verdent to guess correctly| 问题 | 解决方案 |
|---|---|
| Verdent 基于可能不符合你需求的假设进行实现 | 要求 Verdent 访谈你："在创建方案前，先就需求向我提出澄清问题" |
结构良好的提示词示例
以清晰的需求和约束创建新功能：
Create a POST /api/tasks endpoint that:
- Accepts task title (required), description (optional), and category_id (required)
- Validates that the category exists in the database
- Returns 400 if validation fails with descriptive error messages
- Saves the task to the database and returns the created task with 201 status
- Add this to the existing tasks router in routes/tasks.js
- Create the controller method in controllers/taskController.js
- Use the existing error handling pattern from other controllers这为何有效：
- 对输入和验证有清晰的需求
- 明确的实现文件位置
- 引用现有模式以保持一致性
- 预期的 HTTP 状态码和错误处理
带上下文和建议方案地描述问题：
Fix the race condition in payment processing at checkout. When multiple users submit payments simultaneously, some transactions fail with "duplicate order ID" errors. The issue appears to be in PaymentController.js around line 45 where we generate order IDs. Implement proper locking or use UUID generation to ensure unique IDs even under concurrent load.这为何有效：
- 清晰的问题描述及症状
- 问题的具体位置（文件和行号）
- 何时发生的上下文（并发用户）
- 建议的解决方案
在保留行为的同时更改实现：
Refactor the authentication middleware in middleware/auth.js to use JWT tokens instead of session cookies. Keep the same authorization logic, but:
- Replace session validation with JWT verification
- Store tokens in httpOnly cookies
- Maintain the existing user object structure that routes expect
- Update only the authentication mechanism, don't change authorization rules
- Ensure all existing routes continue to work without modification这为何有效：
- 清晰的目标（用 JWT 替代 session）
- 要重构的具体文件
- 明确的约束（什么不应改变）
- 向后兼容要求
编写覆盖全面的测试：
Write comprehensive unit tests for the UserService class in services/UserService.js. Cover:
- User creation with valid and invalid data
- Email validation edge cases (empty, malformed, duplicate)
- Password hashing verification
- User lookup by ID and email
- Error handling for database failures
Use Jest and follow the testing patterns in existing service tests这为何有效：
- 要测试的具体类/文件
- 要覆盖的完整场景列表
- 指定测试框架
- 引用现有测试模式
以详细规格构建 UI 组件：
Create a reusable SearchBar component for the product catalog with:
- Text input with real-time debounced search (300ms delay)
- Category dropdown filter (fetch options from /api/categories)
- Price range slider (min $0, max $1000)
- Clear filters button
- Use Material-UI components to match existing design
- Emit search parameters via onChange callback to parent
- Include PropTypes for all props这为何有效：
- 带具体细节的完整功能列表
- 技术规格（300ms 防抖、价格区间）
- 指定 UI 库（Material-UI）
- 集成方式（回调给父组件）
进阶提示技巧
引用特定文件、组件或子智能体：
@auth.js @UserController.js Refactor authentication to use the same validation pattern优势：
- 通过显式包含特定文件，确保 Verdent 拥有准确的上下文
- 在文件名相似的大型代码库中避免歧义
- 保证所有相关代码同时可见，以实现准确的重构和模式匹配
- 在引用某文件的实现模式以应用到另一文件时必不可少
在执行大型改动前切换到 Plan Mode：
Switch to Plan Mode
Refactor the entire API layer to use TypeScript with strict type checking优势：
- 在任何文件被修改前审查 Verdent 的完整方案
- 防止大型重构或架构变更中的高昂错误
- 在执行开始前迭代方案、添加约束或彻底改变方向
- 要求 Verdent 通过澄清问题访谈你，以预先收集所有需求
将专门任务委派给内置或自定义子智能体：
@Code-reviewer Review the security vulnerabilities in authentication flow
@Explorer Find all files that import the deprecated API client
@Verifier Validate the authentication logic in the middleware优势：
- 利用针对特定任务（探索、验证、代码审查）优化的专门智能体
- 比通用处理更专注的专长和更快的结果
- 并行执行多个分析，大幅缩短总执行时间
- 为项目独特需求创建具备领域知识的自定义子智能体
内置默认子智能体：
@Verifier- 快速代码检查和验证@Explorer- 快速代码库探索和文件查找@Code-reviewer- 代码质量评估
用 @Explorer 处理代码库问题，用 @Code-reviewer 进行安全分析，有针对性的委派比主智能体路由更快。
为复杂挑战启用扩展推理：
Think: Design the optimal database schema for a multi-tenant SaaS application优势：
- 激活扩展推理，从多个角度更深入地分析复杂问题
- 更彻底地评估替代方案和边界情况
- 在正确性至关重要时产出稳健的解决方案
- 响应更慢、积分消耗更高，但能避免因仓促、次优方案带来的高昂返工
Think Hard Mode 擅长架构决策、复杂调试和需要深度分析的算法问题。
在之前的回应基础上逐步优化：
Initial: "Create a dashboard component"
Follow-up: "Add real-time data updates using WebSockets"
Follow-up: "Now add filtering and sorting capabilities"优势：
- 支持增量开发，在增加复杂度前对每一步进行测试
- 在叠加之前先验证每一层正确工作，降低风险
- 若迭代产生意外结果可立即纠正
- 由于每次迭代都小而独立，更容易定位是哪个具体改动引入了 bug
迭代优化能降低风险，从小范围开始，验证结果，然后逐步扩展。
在指定要更改什么的同时，说明不要更改什么：
Add caching to the API endpoints, but:
- Don't modify the authentication middleware
- Keep the existing error handling unchanged
- Maintain backward compatibility with mobile clients优势：
- 显式定义边界，防止修改关键系统（认证、支付）
- 保护因合规或风险要求必须保持不变的稳定系统
- 避免实现改动、发现功能损坏、返工方案的高昂循环
- 保持向后兼容，保护久经考验的代码免于不必要的重构
指向现有代码作为实现示例：
Implement the new ProductService following the same pattern as UserService.js, including error handling, validation, and database transaction management优势：
- 确保新实现与既定约定保持一致
- 让代码库更易维护、更可预测
- 大幅减少所需的解释——指向示例而非详细描述方法
- 利用经过验证、久经考验的模式，而非重新发明方案
- 减少 bug 并确保与现有系统无缝集成
创建 todos.md 文件来跟踪复杂的多步骤任务：
Create a todos.md file with these tasks:
1. Refactor authentication to use JWT tokens
2. Update all controllers to use new auth middleware
3. Add tests for authentication flow
4. Update API documentation优势：
- 创建清晰的书面路线图，可供审查、优化并与团队成员共享
- 随项目需求演进而轻松调整
- 跨会话持久化，便于暂停工作、稍后恢复并立即了解进度
- 作为项目工件，记录已规划、已完成和待完成的内容，便于未来维护和上手
在不同 todo 之间开启新会话以获得全新上下文：
After completing todo #1: "Start a new session"
Then: "Let's work on todo #2 from todos.md"优势：
- 防止上下文污染，即之前任务的细节不当地影响当前工作
- 确保只专注于当前 todo，不带前序任务的包袱
- 通过不加载不必要的对话历史，减少 token 使用
- 让响应更快、更节省积分
- 为测试和提交改动创造自然的检查点，保持干净的 git 历史并更易隔离问题
使用 MCP (Model Context Protocol) 服务器注入专门的上下文：
- 项目专属文档
- API 规范（OpenAPI、GraphQL schema）
- 框架专属知识
优势：
- 增强 Verdent 对其训练数据中没有的自定义框架、内部工具和专门领域的理解
- 直接注入组织专属的 API 规范和文档，无需反复解释自定义系统
- 让原本无法仅通过提示词传达的内部 API 和专有系统得以正确使用
在提示词中包含上下文
显式将相关文件纳入上下文：
@models/User.js @controllers/UserController.js Add password reset functionality何时使用：
- 处理紧密耦合的文件时（模型与控制器、服务与测试）
- 引用某文件的实现模式以应用到另一文件
- 协调跨多个相关文件的改动
- 在文件名相似的大型代码库中，自动检测可能遗漏上下文
- 当要求 Verdent "遵循与……相同的模式" 时，始终使用以确保它拥有准确的代码
包含关于你技术栈的高层上下文：
This is a MERN stack application (MongoDB, Express, React, Node.js) with JWT authentication. Add role-based access control following our existing middleware pattern.何时使用：
- 实现需要与现有技术栈集成的功能时
- 首次在某代码库中工作，或功能跨越多个层级（前端到数据库）
- 当你的技术栈有强烈倾向（GraphQL 与 REST、Redux 与 Context API）影响实现选择时
- 当你需要 Verdent 选择契合你系统的方法，而非通用方案时
指向展示你约定的代码：
Follow the same error handling pattern used in ProductController.js - return consistent error objects with status codes and descriptive messages何时使用：
- 当你希望新代码与既定约定（错误处理、验证、日志、测试）保持一致时
- 在代码库的新区域实现类似功能
- 上手代码库中不熟悉的部分，想学习并复制现有模式
- 当你想避免详细描述模式，需要 Verdent 捕捉难以表述的细微差别时
陈述限制或要求：
We're using TypeScript with strict mode enabled, React 18 with hooks only (no class components), and Material-UI v5 for styling何时使用：
- 当你的项目有特定技术要求（TypeScript strict 模式、仅用 React hooks、无外部依赖）时
- 处理遗留约束（IE11 支持、Node.js 14 兼容）
- 当合规要求决定选择时（WCAG 无障碍、GDPR 数据处理）
- 使用版本间有破坏性变更的特定库版本
- 当你需要防止 Verdent 提出违反项目技术边界的方案时
解释领域专属规则：
Users can only view tasks assigned to them or their team. Managers can view all tasks in their department. Admins can view everything.何时使用：
- 当实现 Verdent 无法仅从代码推断出的领域专属规则的功能时
- 授权逻辑（谁能访问什么）、业务工作流（审批流程、状态机）
- 验证规则（密码策略、数据约束）、领域约束（库存上限、定价规则）
- 构建需要解释实体关系和基数的数据模型
- 实现计算（折扣规则、税费计算、佣金结构）
- 当你需要 Verdent 正确执行你组织的业务规则，而不只是功能性代码时
调试时分享错误信息或日志：
Getting "TypeError: Cannot read property 'id' of undefined" at UserController.js:42 when trying to update user profiles. The req.user object exists but doesn't have an id property after the recent auth middleware changes.何时使用：
- 修复 bug 时始终包含完整的错误信息、堆栈跟踪和日志
- 运行时错误（异常、崩溃）、构建失败（编译错误、lint 违规）
- 测试失败（断言错误、超时问题）、意外行为（错误输出、数据缺失）
- 当你有带行号的准确错误信息和显示调用链的完整堆栈跟踪时
- 当你能提供关于何时发生的上下文时（总是、间歇性、特定条件）
- 当你想大幅提升 Verdent 识别根因而非猜测的能力时
Verdent 会根据你的请求自动加载相关文件：
- 提示词中按名提及的文件
- 同一目录中的相关文件
- 常被访问的项目文件
何时依赖它：
- 对于关系明显的标准文件引用
- 按名提及组件且 Verdent 需要加载该特定文件
- 处理同一目录中常一起工作的文件
- 访问常用项目文件（package.json、配置文件）
- 在组织良好的代码库中，对于直接明了的场景效果很好
- 对于复杂的多文件重构、相距较远的代码库部分或含糊的文件名，请改用显式 @-提及
通过规则文件配置持久上下文（设置 → 规则）：
用户规则（VERDENT.md）： 应用于所有项目的全局偏好
项目规则（AGENTS.md）： 项目专属标准——架构模式、编码标准
方案规则（plan_rules.md）： 自定义 Plan Mode 中的方案格式和内容
何时使用：
- 当跨会话反复提供相同上下文时
- 用户规则用于个人偏好（编码风格、偏好的库、你青睐的模式）
- 项目规则用于团队标准（架构决策、命名约定、测试要求）
- 对新团队成员上手很有价值（将团队默会知识编入文档）
- 在大型团队中保持一致性并减少提示词冗余
- 当你的项目成熟到拥有值得记录的既定模式时，投入规则文件
包含截图、原型图或图表：
@screenshot.png Implement this UI design with React components何时使用：
- 当视觉信息比文字更有效地传达需求时
- UI/UX 实现（设计原型、线框图、用户流程）
- 调试视觉问题（损坏布局的截图、渲染问题）
- 理解复杂架构（系统图、数据库 schema、流程图）
- 对响应式设计、无障碍分析和错误复现必不可少
- 将 Figma 或 Sketch 等工具的设计转化为代码
- 一张拍得好的截图往往能传达需要数段文字才能描述的细节
引用外部文档或示例：
Ultrathink: Read this API documentation at https://api-docs.example.com/v1/endpoints and implement the authentication flow何时使用：
- 当实现与有官方在线文档的外部 API 或库的集成时
- 当库有复杂的配置选项或认证流程时尤其有价值
- 使用 "Ultrathink:" 前缀指示 Verdent 在生成代码前抓取并分析网页内容
- 对于文档比训练数据更新的快速演进 API 必不可少
- 当遵循框架专属模式时（Next.js App Router、Vue Composition API）
- 确保实现与当前 API 版本一致并遵循官方建议
迭代优化策略
初始提示词：
Add authentication to the APIVerdent 的回应可能比较通用。优化：
Use JWT tokens stored in httpOnly cookies, implement refresh token rotation, and follow the authentication pattern from our existing UserController何时使用： 从一般请求开始，然后根据初始回应添加细节
如果 Verdent 的实现不符合预期：
The validation logic is good, but use Joi schema validation instead of manual checks. Match the validation pattern in ProductController.js何时使用： 在审查输出并识别具体改进后
增量构建：
Initial: "Create a UserProfile component"
Follow-up: "Add an avatar upload feature with image preview"
Follow-up: "Add validation - max 5MB, only jpg/png formats"
Follow-up: "Show upload progress with a progress bar"何时使用： 在同一会话中逐步构建功能
如果实现看起来意外：
Why did you use Redux instead of Context API? Can you explain the trade-offs for this use case?然后根据理解进行优化：
Actually, use Context API for consistency with the rest of our application何时使用： 在请求更改前理解推理过程
对于复杂改动：
Switch to Plan Mode
Show me how you would refactor the authentication system to support OAuth providers审查方案、提问、在执行前迭代方法。
何时使用： 需要审查的重大架构变更
如果 Verdent 的风格与你的不符：
The component structure is close, but use this pattern instead:
[paste example of your preferred structure]
Apply this same pattern to the remaining components何时使用： 建立或强化代码风格偏好
如果输出违反了未说明的约束：
Good approach, but don't modify the database schema - work within the existing User table structure何时使用： 在看到初始实现后添加发现的约束
从核心功能开始，迭代地添加特性：
Step 1: "Create basic CRUD endpoints for tasks"
Step 2: "Add pagination to the GET endpoint"
Step 3: "Add filtering by status and priority"
Step 4: "Add full-text search across title and description"何时使用： 增量构建复杂功能，在每一步进行测试
常见问题
我的提示词应该多具体？
具体到足以消除歧义，但不要过度解释显而易见的细节。包含：准确的文件路径、实现方式、预期结果和约束。糟糕："修复代码"——太含糊。良好："在 ContactForm.js 中为 email 字段添加输入验证以拒绝无效的邮箱格式"——清晰的范围和目标。拿不准时，宁可更具体。
@-提及和自动文件加载有什么区别？
Verdent 会自动加载提示词中按名提及的文件及同一目录中的相关文件。@-mentions（@filename.js）显式保证文件在上下文中，这在处理紧密耦合的文件、引用某文件模式以应用到另一文件、或自动检测可能在大型代码库中遗漏上下文时至关重要。当要求 Verdent "遵循与……相同的模式" 时，始终使用 @-mentions 以确保准确的代码引用。
我应该什么时候用 Plan Mode 而非普通模式？
在以下情况使用 Plan Mode：大型重构或架构变更、想在执行前审查范围的多文件修改、对需求不确定的复杂任务，或当你希望 Verdent 在实现前通过澄清问题访谈你时。跳过 Plan Mode 的情况：简单、明确定义的任务，快速 bug 修复，或常规操作。Plan Mode 增加了开销，但能防止复杂工作中的高昂错误。
如果 Verdent 没有正确理解或遵循我的提示词怎么办？
使用迭代优化：审查输出，识别错在哪里，然后在后续提示词中提供纠正。示例："验证逻辑不错，但请用 Joi schema 验证替代手动检查。匹配 ProductController.js 中的验证模式。" 你也可以要求解释："你为什么用 Redux 而非 Context API？" 然后根据理解优化。不要重复相同的提示词——根据失败原因进行调整。
会话期间我需要在每条提示词中重复项目上下文吗？
不需要——Verdent 在会话内维护对话上下文，所以你无需重复已讨论过的架构细节或约定。然而，对于关键约束，或当会话变长（100+ 条消息）时，请重述重要上下文。更好的方法：使用项目规则（AGENTS.md）记录持久上下文，如技术栈、编码标准和模式——这样你就永远不必重复它们。
意图清晰、上下文相关、约束具体的结构良好的提示词，能持续产出更好的结果。