Rule Authoring

Overview

AI coding rules are instructions that shape how AI assistants behave. Poorly written rules are ignored, misinterpreted, or cause inconsistent behavior across tools.

Core principle: Rules must be unambiguous, actionable, and testable. If an AI assistant can interpret a rule two different ways, it will choose the wrong one at the worst moment.

Iron Law:

EVERY RULE MUST HAVE A TESTABLE "DID IT WORK?" CRITERION

When to Use

• Writing new rules for .ai-rules/rules/
• Updating existing rules that produce inconsistent behavior
• Adapting rules for a new AI tool (cursor, codex, q, kiro)
• Auditing rules for ambiguity or overlap

Rule Quality Criteria

A good rule is:

Rule Structure

Core Rule Format

## [Rule Category]: [Rule Name]

**When:** [Trigger condition — when does this rule apply?]

**Do:** [Specific action to take]

**Don't:** [Specific anti-pattern to avoid]

**Example:**
\`\`\`typescript
// ✅ Good
function getUser(id: string): Promise<User>

// ❌ Bad
function getUser(id: any): any
\`\`\`

**Why:** [One-sentence rationale]

Rule File Structure

# [Category Name]

Brief description of what rules in this file govern.

## Rules

### Rule 1: [Name]
...

### Rule 2: [Name]
...

## Rationale

Why these rules exist for this project.

## Exceptions

Cases where these rules do not apply (keep this list short).

Writing Process

Phase 1: Identify the Rule Need

1. What behavior is inconsistent or incorrect?
   → "AI assistants sometimes use 'any' type in TypeScript"

2. What is the desired behavior?
   → "All variables must have explicit types"

3. What is the trigger condition?
   → "When writing TypeScript code"

4. Can an AI verify compliance?
   → "Yes: TypeScript compiler will error on 'any' in strict mode"

5. Is there already a rule covering this?
   → Check existing rules in .ai-rules/rules/

Phase 2: Write the Rule

Template:

### [Rule Name]

**When:** [Specific trigger condition]

**Do:** [Concrete action in imperative mood]

**Don't:** [Specific anti-pattern]

**Check:** [How to verify the rule was followed]

Good examples:

### No `any` Type

**When:** Writing TypeScript code

**Do:** Always specify explicit types for function parameters and return values

**Don't:** Use `any` type — use `unknown` for truly unknown types, then narrow

**Check:** TypeScript compiler passes with `noImplicitAny: true` in tsconfig

---

### Test Before Implement (TDD)

**When:** Implementing a new function or feature

**Do:** Write the failing test first, then write minimal implementation to pass it

**Don't:** Write implementation first and add tests after

**Check:** Running tests shows RED (failure) before GREEN (pass)

Phase 3: Test Multi-Tool Compatibility

Different AI tools parse rules differently. Test your rules with each tool:

Compatibility checklist for each new rule:

Claude Code:
- [ ] Rule triggers correctly from CLAUDE.md or custom-instructions.md
- [ ] Rule doesn't conflict with default Claude behavior

Cursor:
- [ ] Rule works in .cursorrules or .cursor/rules/
- [ ] Pattern matching works as expected

GitHub Copilot / Codex:
- [ ] Rule understandable from .github/copilot-instructions.md
- [ ] No Copilot-specific syntax required

Amazon Q:
- [ ] Compatible with .q/rules/ format

Kiro:
- [ ] Compatible with .kiro/ format

Phase 4: Anti-Ambiguity Review

Read each rule and ask: "Could this be interpreted two different ways?"

Ambiguity red flags:

❌ "appropriate" → What's appropriate? Define it.
❌ "when necessary" → When is that? Specify the condition.
❌ "best practices" → Which ones? List them.
❌ "avoid" → How strongly? Use "never" or "prefer X over Y".
❌ "clean code" → What does clean mean? Measurable criteria only.

Ambiguity fixes:

❌ "Use appropriate error handling"
✅ "Catch specific error types, never catch Exception or Error base class"

❌ "Write clean functions"
✅ "Functions must be ≤ 30 lines and have a single return type"

❌ "When necessary, add comments"
✅ "Add comments only for non-obvious logic. Self-documenting code needs no comments."

Rule Categories

Adapter-Specific Formatting

Claude Code (adapters/claude-code.md)

## Claude Code Specific Rules

- Use `parse_mode` for PLAN/ACT/EVAL detection
- Follow `dispatch_agents` pattern for parallel agents
- Context persists via `docs/codingbuddy/context.md`

Cursor (adapters/cursor.md)

## Cursor-Specific Rules

Rules in `.cursorrules` are parsed line-by-line.
Keep rules to one line each for Cursor compatibility.

Codex (adapters/codex.md)

## GitHub Copilot / Codex Rules

Place in `.github/copilot-instructions.md`.
Copilot prefers explicit examples over abstract rules.

Rule Maintenance

Auditing Existing Rules

# Find rules that haven't been updated recently
git log --since="6 months ago" -- packages/rules/.ai-rules/rules/

# Find duplicate rule concepts
grep -h "^###" packages/rules/.ai-rules/rules/*.md | sort | uniq -d

Quarterly audit questions:

1. Is this rule still relevant to our current stack?
2. Is this rule being followed consistently?
3. Does this rule conflict with any new tool defaults?
4. Are there new patterns that need new rules?

Quick Reference

Rule Strength Vocabulary:
─────────────────────────
MUST / ALWAYS     → Required, no exceptions
SHOULD / PREFER   → Default behavior, exceptions allowed
AVOID / PREFER NOT → Discouraged, explain if used
NEVER / MUST NOT  → Prohibited

Red Flags — STOP

Additional resources

• Rule template — Copy-and-adapt template with filled example and pre-commit checklist
• Trigger patterns — Catalog of clear trigger patterns, ambiguity antipatterns, and strength vocabulary