Rules

[dpyragas]

Hi all,

I've been using Amazon q cli for a bit now and created my dev agent which has a set of rules as well in .amazonq/rules, but unfortunately it quite often deviates from them, especially for UI. I've followed this blog post Mastering Amazon Q Developer with Rules. Does anyone have any good tips to share how to improve the consistency? Thank you!

[uldyssian-sh]

Amazon Q “rules” are context, not hard enforcement. So some drift (especially for UI/formatting) is expected unless you make the rules extremely explicit, non-conflicting, and easy to apply.

Here are practical ways to improve consistency (especially for UI):

1. Make UI rules concrete, testable, and example-driven
   Bad: “Use our UI style”
   Good: “For UI, always output React components using , , from @acme/ui. Never use raw / unless explicitly asked. Include a minimal example.”

Add a short “Do/Don’t” snippet in the rule file so the model can pattern-match.

2. Split rules by scope and keep each file focused
   Instead of one huge rules file, split into:

• frontend-ui.md (components, patterns, accessibility, CSS approach)
• backend.md (logging, error handling, style)
• testing.md (test style)
• output-format.md (how responses should be formatted)

Large mixed rules increase conflicts and “rule dilution”.

3. Add Priority + conflict resolution in the rule text (even if not required)
   Even if priority is informal, it helps. Example:

Priority: Critical

If any other instruction conflicts with this rule, follow this rule.

Also add:
“If you cannot follow this rule, state exactly which requirement cannot be met and why, then propose the closest alternative.”

4. Add rule IDs + force a self-check
   Add IDs to each instruction and a self-check requirement:

• Before responding, verify compliance with: UI-001, UI-002, UI-003.
• After responding, add a short “Compliance check: UI-001 OK, UI-002 OK …” line.

This is one of the most effective ways to reduce drift because it forces the model to “look back”.

5. Reduce “optional language” and ambiguity
   Words like “try”, “prefer”, “should”, “ideally” invite deviation.
   For UI rules, use:

• ALWAYS / NEVER / MUST
• clear fallbacks:
  “If component X is not available, use component Y; otherwise use semantic HTML with aria labels.”

6. Avoid contradictions across rules
   Common hidden conflict: one rule says “be concise”, another says “always provide complete code”.
   For UI: pick one:

• either “always provide complete working component code”
• or “provide minimal patch diff only”
  Not both.

7. Ensure Q is actually loading the updated rules
   Rules are loaded when the session/context is established. If you changed files and Q keeps deviating:

• restart the Q chat session / CLI session
• ensure you’re running from the project root where .amazonq/rules exists
• confirm there aren’t multiple repos / nested roots and you edited the wrong one

8. Keep “UI rules” near the top and short
   UI drift often happens because the model doesn’t retrieve long rule text reliably.
   Keep UI rules:

• first (or in a dedicated small file)
• ≤ 30–60 lines
• with examples

9. Add “output guardrails” specific to UI
   If your issue is “it talks about UI but doesn’t output it”, add:

• When asked for UI, ALWAYS output code first, then explanation.
• Output must include: component code, props interface/type, and usage example.
• Do not describe the solution without providing code.

10. Create a tiny “golden prompt” in the rules
    Include a canonical example request + ideal response pattern. Models imitate patterns extremely well.

Example snippet to include in the rules:

Example request:
“Create a settings dialog with Save/Cancel using our UI kit.”

Expected response:

• Full React component using @acme/ui Dialog/Button/Input
• Validation + disabled Save when invalid
• Accessibility notes

If you paste (or share) your current .amazonq/rules UI file, I can rewrite it into a tighter, enforcement-style version that tends to stick much better.

[uldyssian-sh]

Thanks! If this helps, please consider marking it as “Helpful” or “Accepted” 😊