掌握Amazon Q Developer规则 | AWS DevOps与开发者生产力博客

当我开始使用Amazon Q Developer时，对其功能印象深刻，但很快发现自己陷入了一个熟悉的模式。使用AI助手的开发团队面临一个共同挑战：需要反复解释编码标准、工作流程偏好和既定模式。这种重复设置降低了生产力，并在团队成员之间造成了不一致的AI指导。听起来熟悉吗？

这就是我发现自定义规则力量的时候——它彻底改变了我与AI助手协作的方式。

什么是Amazon Q Developer规则？

Amazon Q Developer中的规则是构建编码标准和最佳实践库的一种方式，这些规则在与助手交互时会自动用作上下文。

这些规则定义在项目.amazonq/rules文件夹中存储的Markdown文件中。一旦创建，它们会自动成为开发者在项目中与Amazon Q Developer交互时的上下文部分，无论团队成员的经验水平如何，都能保持一致性。目前，规则在Amazon Q Developer IDE扩展和Amazon Q Developer CLI中受支持。

基于规则的AI辅助的力量

我发现基于规则的AI辅助最引人注目的是它如何最小化通常伴随AI交互而来的重复设置。您可以将偏好和标准定义为规则，而不是为每个请求反复指导AI助手。这创建了一个一致、可预测的AI体验，自动尊重您团队的约定和最佳实践。

对我来说，真正的改变游戏规则的是一致性。无论我是开发新功能、调试问题还是审查代码，Amazon Q Developer现在从一开始就理解我的上下文。这意味着我可以专注于实际的问题解决，而不是反复解释我喜欢的工作方式。

理解规则生命周期

一直让开发者感到惊讶的是规则如何无缝集成到Amazon Q Developer工作流程中。理解规则何时以及如何注入到上下文中有助于您充分利用此功能。以下是该过程的运作方式：

规则在几个关键时刻被注入：

1. 初始上下文加载：当您首次在项目中与Amazon Q Developer交互时，它会扫描.amazonq/rules目录并将适用的规则加载到其上下文中。
2. 请求处理：在生成响应之前，Amazon Q Developer会根据加载的规则评估您的请求，以确定哪些规则适用。
3. 响应生成：在构建响应时，Amazon Q Developer遵循适用规则的指令，根据其指定的优先级进行优先排序。
4. 动态更新：如果您在会话期间修改现有规则或添加新规则，Amazon Q Developer会检测这些更改并相应更新其行为。

这种持续集成确保Amazon Q Developer的响应始终符合您的标准，而无需您在每次对话中重复指令。

为什么基于规则的AI会带来不同？

我发现这种方法最有价值的是它如何将AI从通用助手转变为真正理解您团队工作方式的东西。以下是我经历的关键好处：

一致性：每个团队成员获得相同的AI指导体验，确保代码和文档保持一致性，无论谁编写它们。 知识保存：规则捕获您团队积累的智慧和最佳实践，使每个人都能访问它们。 减少认知负担：您可以专注于解决问题，而不是记住和执行标准。 更快上手：新团队成员自动接收与团队实践一致的指导。 适应性：规则可以随着项目的发展而演变，确保AI辅助随着需求的变化保持相关性。

通用AI辅助和规则引导辅助之间的区别很快变得清晰。通用AI可能建议任何有效的解决方案，而规则引导的AI建议适合您特定上下文和标准的解决方案。

构建有效规则：实用方法

既然您已经看到了规则的力量，让我带您了解如何创建它们。虽然没有Amazon Q Developer规则的"官方"格式（美妙之处在于灵活性！），但我即将分享的方法一直为我和我的团队带来出色的结果。

规则文件格式和位置

以下是我为Amazon Q Developer组织规则所学到的内容：

• 规则必须用Markdown格式编写（.md文件）
• 它们应放在项目的.amazonq/rules目录中
• 您可以使用您选择的文件名，但描述性名称有助于组织（例如：monitoring-rule.md、frontend-react.rule.md）
• 规则可以在子目录中组织以获得更好的结构（例如：.amazonq/rules/frontend/react.rule.md）
• 文件名本身是任意的——Amazon Q Developer将读取目录中的.md文件。但是，使用有意义的名称使您的规则系统在增长时更易于维护。

基本规则结构

我发现最有效的是一个精心制作的规则文件，包含以下关键部分：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 规则名称
## 目的
清晰、简洁地说明此规则存在的原因。
## 指令
- Amazon Q Developer要遵循的具体指令
- 带有自己标识符的附加指令
- 指令适用的条件
## 优先级
[关键/高/中/低]
## 错误处理
- 当发生异常时Amazon Q Developer应如何行为
- 当主要指令无法遵循时的回退策略

让我通过一个对我的团队特别有效的完整监控规则示例来展示这个结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 监控
## 目的
此规则确保在向项目添加主要功能时保持监控覆盖。
## 指令
- 当实施主要功能（新服务、API端点或核心功能）时，始终检查MONITORING_PLAN.md是否需要更新。
- 主要功能包括：新微服务、AI集成、WebSocket端点、数据库操作、外部API集成或面向用户的功能。
- 始终更新MONITORING_PLAN.md以包括新功能的相关指标、仪表板和警报。
- 更新监控计划时，包括：自定义指标、CloudWatch仪表板、警报和特定于新功能的日志记录要求。
- 更新MONITORING_PLAN.md后，始终输出"📊 更新了监控计划：[功能描述]"。
## 优先级
高
## 错误处理
- 如果MONITORING_PLAN.md不存在，使用基本监控结构创建它并记录创建
- 如果监控计划不可读，创建备份并重新开始当前功能要求
- 如果不确定某个功能是否 qualifies 为"主要"，宁可谨慎并更新监控计划

我将此保存为项目.amazonq/rules目录中的monitoring.rule.md。

有效的规则组件

现在让我分解每个组件，并向您展示为什么这种结构如此有效。

规则名称 将其视为规则的"类名"。它应该是描述性的和特定领域的，如"Frontend – React"或"Monitoring"。这有助于将规则组织到逻辑类别中，并随着规则集的增长使它们更易于维护。

目的 此部分至关重要，这是您解释规则背后"原因"的地方。我学到的是，清晰的目的有助于Amazon Q Developer理解您指令背后的意图，使其在面对边缘情况时能够做出更好的决策。例如：

1
2

## 目的
确保在向项目添加新功能时保持一致的监控覆盖。

这个简单的陈述指导Amazon Q Developer优先考虑监控考虑因素，即使它们在您的请求中没有明确提及。

指令 这是魔法发生的地方。指令是塑造Amazon Q Developer行为的具体指示。我发现最有效的是当每个指令：

• 清晰且可操作
• 专注于行为的单个方面
• 使用一致的格式以便轻松扫描

例如：

1
2
3
4

## 指令
- 当实施主要功能时，始终检查MONITORING_PLAN.md是否需要更新。
- 主要功能包括：新微服务、AI集成、WebSocket端点。
- 更新MONITORING_PLAN.md后，输出"📊 更新了监控计划：[功能]"。

这些清晰、重点突出的指令为Amazon Q Developer提供了在不同情况下如何行为的具体指导，在您的团队中保持一致的响应。

优先级 并非所有规则都是平等的。我发现优先级水平有助于Amazon Q Developer在多个规则可能适用于某个情况时解决冲突。我通常使用四个级别：

• 关键：必须毫无例外地遵循
• 高：除非与关键规则冲突，否则应遵循
• 中：塑造行为的重要指南
• 低：在必要时可以覆盖的偏好

错误处理 这个经常被忽视的部分是使规则在现实世界场景中健壮的原因。良好的错误处理指令告诉Amazon Q Developer当事情不按计划进行时该做什么：

1
2
3

## 错误处理
- 如果MONITORING_PLAN.md不存在，使用基本监控结构创建它
- 如果不确定某个功能是否 qualifies 为"主要"，宁可谨慎

这些回退策略确保Amazon Q Developer即使在面对意外情况时也能保持帮助性。

规则在行动中

为了向您展示这种结构有多么有效，让我给您一个简单的例子。没有规则时，要求Amazon Q Developer"为用户配置文件添加新的React组件"可能会导致一个不匹配项目模式的组件。

但有了精心制作的前端规则，Amazon Q Developer会自动：

• 检查现有组件结构
• 遵循您的命名约定
• 创建适当的prop接口
• 添加正确级别的文档
• 将文件放在您偏好的目录结构中

所有这些都无需您每次指定这些细节！

使规则透明：改变游戏规则的技术

我发现的一个特别强大的技术是教Amazon Q Developer明确承认它正在遵循哪些规则。这不是Amazon Q Developer的默认行为，而是您可以通过特定对话规则实现的自定义增强。

为可追溯性添加唯一标识符

此系统的关键是为规则中的每个指令添加唯一标识符（ID）。例如：

1
2
3
4

## 指令
- 当实施主要功能时，始终检查MONITORING_PLAN.md是否需要更新。（ID：CHECK_MONITORING_PLAN）
- 主要功能包括：新微服务、AI集成、WebSocket端点。（ID：MAJOR_FEATURE_CRITERIA）
- 更新MONITORING_PLAN.md后，输出"📊 更新了监控计划：[功能]"。（ID：ANNOUNCE_MONITORING_UPDATE）

这些ID作为"可追溯标记"，Amazon Q Developer在遵循规则时可以引用。

创建确认行为

接下来，您可以创建一个对话规则，指示Amazon Q Developer确认它正在遵循哪些规则。以下是此类规则的完整示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 对话
## 目的
此规则定义Amazon Q Developer在对话中应如何行为，包括它应如何确认它正在遵循的其他规则。
## 指令
- 在使用工具或响应之前，始终考虑您的规则。（ID：CHECK_RULES）
- 当基于规则行动时，始终在响应的最开始打印"Rule used: `filename` (ID)"。（ID：PRINT_RULES）
- 如果匹配多个规则，列出所有："Rule used: `file1.rule.md` (ID1), `file2.rule.md` (ID2)"。（ID：PRINT_MULTIPLE）
- 不要以关于使用规则或上下文的一般提及开始响应，但要按照上述规定打印特定的规则使用情况。（ID：NO_GENERIC_MENTIONS）
## 优先级
关键
## 错误处理
- 如果规则文件不可读，继续但注意问题
- 如果多个冲突规则适用，遵循最高优先级规则并注意冲突

将此保存为您的.amazonq/rules目录中的conversation.rule.md。

当Amazon Q Developer遵循规则时，它现在将明确说明哪个规则和标识符指导了其行动。

我发现这个简单添加最有价值的是它创造的显著好处：

透明度：团队成员可以立即看到哪些指南影响了Amazon Q Developer的响应 调试：当Amazon Q Developer行为意外时，您可以识别哪个规则导致了该行为 学习：新团队成员通过查看哪些规则被应用来发现相关规则 验证：您可以确认您的规则按预期工作 持续改进：识别哪些规则最常用，哪些可能需要改进

通过使规则可见，您将Amazon Q Developer转变为不仅遵循您的指南，而且帮助团队成员发现和参与您既定实践的协作伙伴。ID不仅仅是组织工具——它们是一个自文档化AI辅助工作流程的基础，随着规则系统的扩展而变得更有价值。

开始使用您自己的规则

我喜欢这种方法的是您可以从小处着手。从解决您最常见痛点的一两个规则开始，然后在看到好处时扩展。一些好的起点包括：

• 代码风格和组织规则
• 文档标准
• 测试要求
• Git提交消息格式

请记住，目标不是创建详尽的规则手册——而是捕获对团队生产力和代码质量最重要的开发过程方面。

实际示例：规则在行动中

为了向您展示规则的实际影响，让我带您了解一些具体场景，展示规则如何转变AI辅助体验。这些示例显示了通用AI帮助和规则引导辅助之间的区别。

场景1：基于时间的数据分析

此场景演示了规则如何帮助Amazon Q Developer理解您环境中与时间相关的操作和分析的上下文。以下是此规则在VS Code中实际操作的示例。

以下是我使用的一个规则，用于告知Amazon Q Developer在需要理解当前时间时如何行为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 时间
## 目的
此规则定义Amazon Q Developer（代理）如何处理与时间相关的操作和查询
## 指令
- 当确定当前时间时，始终使用带AEST时区的bash命令：`date`（ID：GET_AEST_TIME）
- 当需要时间戳进行日志记录或文档时，使用带AEST时区的ISO格式（ID：ISO_TIMESTAMP）
- 当比较时间或计算持续时间时，确保所有时间都在AEST中以保持一致性（ID：CONSISTENT_TIMEZONE）
- 对于时间敏感的操作，在继续之前始终验证当前AEST时间（ID：VERIFY_TIME）
## 优先级
中
## 错误处理
- 如果date命令失败，注意系统时间问题并继续使用可用信息
- 如果需要时区转换，使用适当的日期格式化命令

没有规则： 当Amazon Q Developer没有时间规则时，它缺乏基于时间查询所需的上下文。

如您所见，没有规则，Amazon Q Developer需要澄清时区上下文，不知道如何确定您环境中的当前时间。

有时间规则： 以下是带有时间规则的类似查询：

注意Amazon Q Developer如何立即使用date命令获取当前AEST时间，完全按照规则中的规定，无需澄清。

影响：

• 自动上下文：Amazon Q Developer立即知道使用date命令获取AEST时间
• 无需澄清：它理解"昨天"相对于当前AEST时间而无需询问
• 一致行为：相同的方法适用于团队成员之间的其他基于时间的查询
• 环境意识：它确切知道如何确定您特定系统环境中的时间
• 透明过程：您可以看到它正在按照指定使用bash date命令遵循规则

此示例显示了时间规则如何将潜在混乱的交互转变为流畅、上下文感知的分析，每次都一致工作。

场景2：前端组件开发

此场景演示了规则如何帮助防止技术债务积累并在团队中保持一致的组件架构。

没有规则： 当Amazon Q Developer没有前端特定指导时，不同的开发者可能获得不一致的组件创建建议。有些人可能立即创建可重用组件，其他人获得复制粘贴解决方案，组件组织基于个人偏好而变化。

有前端规则： 以下是我开发工作流程中的一个真实React规则，解决了这些一致性问题：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Frontend - React
## 目的
定义在编写React时如何行动
## 指令
- 始终使用这些标准评估新视觉元素的可重用性潜力：在2+个地方使用，具有可配置的props，或代表常见的UI模式。（ID：EVALUATE_REUSABILITY）
- 如果可重用性潜力高（满足2+个以上标准），在适当的文件夹（components/、shared/或ui/）中创建具有清晰prop接口和JSDoc注释的专用组件。（ID：CREATE_REUSABLE_COMPONENT）
- 当创建可重用组件时，包括明确的注释解释：目的、关键props、使用示例和任何重要行为。（ID：DOCUMENT_COMPONENTS）
- 遵循项目中components文件夹中找到的现有组件结构和命名约定。（ID：FOLLOW_CONVENTIONS）
- 偏好组合而非继承——创建可以组合的小型、重点突出的组件。（ID：PREFER_COMPOSITION）
## 优先级
中
## 错误处理
- 如果组件文件夹结构不清楚，将新组件放在src/components/中并询问用户偏好的组织
- 如果现有约定不一致，遵循最新或最常见的模式并注意不一致

影响：

• 一致架构：无论经验水平如何，团队成员获得相同的组件创建指导
• 减少技术债务：自动评估可重用性有助于防止重复的UI元素
• 更好的文档：组件自动包括适当的JSDoc注释和使用示例
• 可维护结构：跨项目的一致命名约定和文件夹组织
• 可扩展模式：以组合为中心的方法创建更灵活、可重用的组件

这确保无论是初级开发人员还是高级架构师与Amazon Q Developer合作，生成的组件都遵循相同的质量标准和架构模式。

场景3：版本控制工作流程

此场景演示了规则如何作为安全机制和工作流程控制器，促进围绕版本控制操作的一致实践。

没有规则： Amazon Q Developer可能建议git操作而不考虑团队的工作流程偏好或安全要求。它可能推荐立即推送、通用提交消息，或跳过有助于防止错误的确认步骤。

有Git规则： 以下是一个真实的git规则，改变了Amazon Q Developer处理版本控制操作的方式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Git
## 目的
此规则规定Amazon Q Developer（代理）与git相关的行为。
## 指令
- 在推送到git之前，始终询问用户的确认。（ID：GIT_PUSH）
- 始终确保提交消息有意义且详细，包括更改了什么以及为什么。（ID：GIT_COMMIT）
- 提交消息应准确但 playful 且不太正式，包含更改的全面细节。（ID：GIT_COMMIT_STYLE）
- 在提交消息中包括修改的特定文件/组件和更改的影响。（ID：GIT_COMMIT_DETAILS）
## 优先级
中
## 错误处理
N/A

以下是此规则在我要求Amazon Q Developer提交我们的更改时的实际操作：

注意Amazon Q Developer如何自动在其响应的开头显示"Rule used: git.rule.md (GIT_COMMIT), git.rule.md (GIT_COMMIT_STYLE), git.rule.md (GIT_COMMIT_DETAILS)"——这是我们之前讨论的规则透明度系统在行动中，显示确切哪个规则指令指导了提交消息的创建。

影响：

• 有助于防止事故：确认要求停止可能 disrupt 团队工作流程的意外推送
• 一致的提交质量：无论谁在工作，提交消息都遵循相同的详细、信息丰富的风格
• 团队个性：“playful但不太正式"的风格在保持专业性的同时维护团队文化
• 更好的Git历史：详细的提交消息使未来的代码考古更加直接
• 工作流程安全：作为尊重关键操作中人工监督的防护栏

此规则显示了Amazon Q Developer如何不仅仅是代码助手——它成为理解并执行团队操作偏好和安全要求的工作流程伙伴。

基于规则的开发的下一步

通过对Amazon Q Developer规则的探索，我们发现了一个简单概念——定义您的偏好一次而不是不断重复它们——如何转变您的开发工作流程。关键学习是清晰的：规则帮助您避免重复设置，促进团队一致性，保存机构知识，并创建随着时间推移变得更有价值的透明AI交互。

减少认知负担、更快上手、一致的代码质量，以及真正理解团队上下文的AI辅助——从重复解释的解决方案开始，已经演变为跨团队扩展开发实践的综合系统。

我的Amazon Q Developer规则系统继续发展，我对未来的可能性感到兴奋。随着更多团队采用这种方法，我期望看到社区共享的规则库和更复杂的自定义选项。

我发现最有希望的是规则如何为更高级的AI辅助创建基础。当您的AI助手深刻理解您的上下文时，它可以提供更复杂的建议，并在潜在问题成为问题之前捕获它们。

我鼓励您开始试验规则——选择一个您发现自己向AI助手重复指令的领域，并创建您的第一个规则。您会惊讶于这种方法多么快速地转变您的开发工作流程。

关键是记住规则不是关于约束创造力——它们是通过自动化常规决策，让您自由专注于有趣的问题。当Amazon Q Developer知道您喜欢如何做事时，您可以花更多时间在构建什么上，而更少时间在如何构建上。

准备好开始使用Amazon Q Developer规则了吗？查看Amazon Q Developer文档以获取设置说明和更多示例。