How to Write Rules
Learn how to format your markdown so AiRulesHub can detect and analyze your engineering standards correctly.
Best Practices
Do's
- •Start with a high-level overview: Briefly describe the goal of the rule set.
- •Be specific and actionable: Use clear instructions like "validate input" rather than "be safe".
- •Use negative constraints: Explicitly state what NOT to do (e.g., "Do not use inline styles").
- •Group related rules: Use headings like `## API Standards` to organize context.
Don'ts
- •Avoid vague language: Words like "clean", "maintainable", or "better" are hard to enforce.
- •Don't bury rules in text: Avoid long paragraphs. Use lists for detection.
- •Avoid conflicting instructions: Ensure rules don't contradict each other or global defaults.
What Is a Rule?
A rule is a clear, actionable instruction written in plain English meant to guide AI behavior or team standards.
"Do not put business logic inside UI components"
Actionable"UI should be clean"
VagueSupported Formats
AiRulesHub v1 detects rules when they are written in these specific formats.
Recommended: Bullet lists are the most reliable way to ensure rules are detected.
Where Rules Should Live
Rules are best detected when placed under clear headings. The analyzer prioritizes content under:
What Is Ignored
To reduce noise, the following content is ignored by the rule detector:
Common Detection Mistakes
"Do this" - Rules need enough context to be distinguished from normal text.
"Keep code clean" - Rules must be actionable and objective.
Buried inside long paragraphs without bullet points or action verbs.
"We believe in quality" - Statements of belief are not detected as rules.
- One instruction per rule: Don't combine multiple unrelated tasks.
- Avoid subjective words: Words like "better", "clean", "fast" are hard to validate.
- Be specific: Name specific patterns, paths, or file types.
- Prefer negative constraints: "Do not..." is often clearer than "You should...".
Still having issues? Checkout our GitHub Issues or join the discussion.