Adding a Rule
Relevant source files
The following files were used as context for generating this wiki page:
A rule is a single-concern best practice stored in a skill's rules/ directory. Rules provide AI assistants with specific guidance for tasks such as schema design, object creation, or generator implementation. Every new rule requires a corresponding evaluation task and a deterministic grader check to ensure the AI follows the guidance accurately. Sources: dev/guides/adding-a-rule.md:3-10, dev/knowledges/skill-writing-guide.md:73-75
Rule Definition and Structure
Rules must focus on exactly one concern to remain independently addressable by AI models. A rule file answers why the concern matters, how to apply the pattern, and provides examples of compliant and non-compliant implementations. Sources: dev/knowledges/skill-writing-guide.md:73-88, dev/guides/adding-a-skill.md:126-136
Mandatory Components
Each rule file follows a standardized format to provide clarity to the AI:
| Component | Description |
|---|---|
| Title | A concise name for the rule. |
| Summary | A one-sentence summary of the rule. |
| Reasoning | The "Why": explains consequences like validation errors or data loss. |
| Pattern | Specific instructions or checks to apply. |
| Examples | Separate code blocks for compliant and non-compliant patterns. |
| Common Mistakes | Typical errors the AI or user might make. |
Sources: dev/knowledges/skill-writing-guide.md:78-88, dev/guides/adding-a-skill.md:131-136, skills/infrahub-common/rules/_template.md:9-30
Example Separation
You must place compliant and non-compliant examples in two separate fenced markdown blocks. If they are in one block, the AI may read the wrong implementation as part of the valid artifact. Sources: dev/knowledges/skill-writing-guide.md:83-88, dev/guidelines/skill-authoring.md:57-61
Implementation Workflow
The process of adding a rule involves writing the prose, registering categories, and creating automated verification tests.
The diagram shows the sequential steps required to integrate a new rule into the project and its testing framework. Sources: dev/guides/adding-a-rule.md:21-170
1. File Placement and Registration
Place the new file at skills/<skill>/rules/<category>-<concern>.md. You must use existing category prefixes found in the skill's rules/_sections.md. If a new prefix is required, you must register it in:
rules/_sections.md- The
Rule Categoriestable inSKILL.md - Any severity or ladder legends maintained by the skill.
Sources: dev/guides/adding-a-rule.md:28-40
2. Linking in SKILL.md
Link the rule within the SKILL.md file at the specific workflow step where the AI needs the information. State when to read the rule rather than just what it covers. A rule only reachable from an index may be read after a mistake has already occurred. Sources: dev/guides/adding-a-rule.md:44-54
Automated Verification
Every rule must be testable via deterministic graders and evaluation tasks.
Deterministic Graders
Grader code lives in graders/<skill>/lib.py. These functions must inspect the parsed YAML or AST of the AI's output and return a pass/fail tuple. You must avoid substring matching; instead, use yaml.safe_load for YAML or the ast module for Python code. Sources: dev/guides/adding-a-rule.md:58-95
Evaluation Tasks
Evaluation tasks are added to the root eval.yaml. A task should simulate a realistic user request that naturally triggers the rule without explicitly telling the AI to "follow the rule." Sources: dev/guides/adding-a-rule.md:118-137
Grader Verification Fixtures
To prevent false passes or failures, you should verify the grader against four specific fixtures:
- Compliant: Written exactly as the rule shows.
- Compliant Variant: Refactored in a way the check's traversal might miss.
- Violating: An obvious breach of the rule.
- Near-Miss: Satisfies keyword checks but breaks the underlying rule.
Sources: dev/guides/adding-a-rule.md:162-187
Summary of Best Practices
- One Fact, One Home: State a command or claim in only one file and link to it to prevent documentation drift. Sources: dev/knowledges/skill-writing-guide.md:92-95
- Imperative Voice: Use direct instructions like "Check the namespace" instead of "You should check...". Sources: dev/knowledges/skill-writing-guide.md:65
- Verified Claims: Only include claims you have tested against a specific Infrahub version. Sources: dev/knowledges/skill-writing-guide.md:104-108
- Stand-alone Examples: Ensure every code snippet includes all necessary kind and attribute definitions to be executable. Sources: dev/knowledges/skill-writing-guide.md:126-130