How to Include Code Examples in Rules

Show, Do Not Tell: Why Examples Are Powerful

A description: 'Use structured error responses with a code, message, and optional details field.' The AI interprets this and generates: something that might match what you had in mind, or might not. An example: 'Error responses: { success: false, error: { code: "VALIDATION_ERROR", message: "Email is required", details: [{ field: "email", issue: "missing" }] } }.' The AI: generates responses that match the exact shape shown in the example. No interpretation needed. No ambiguity. The example IS the specification.

When examples beat descriptions: complex data structures (the shape is easier to show than to describe), specific formatting patterns (how imports are grouped, how components are structured), before-and-after transformations (showing the wrong pattern and the right pattern side by side), and multi-part patterns (a function with specific parameter ordering, return type, and error handling). These: are easier to understand from an example than from a paragraph of prose.

When descriptions beat examples: simple rules that do not need examples ('use camelCase for variable names' — every developer knows what camelCase looks like), rules that apply to many different code structures (an example shows one case; a description covers all cases), and rules about intent rather than structure ('prefer composition over inheritance' — the implementation varies too much for one example to cover). AI rule: 'Use examples for structure and shape. Use descriptions for intent and principles. Many rules benefit from both: a description of the principle plus an example of the pattern.'

Step 1: Formatting Examples for AI Consumption

Code blocks: use fenced code blocks with language tags. The AI parses code blocks more accurately than inline code. Format: three backticks + language (typescript, python, go), then the example code, then three closing backticks. The language tag: helps the AI understand the context. A TypeScript example with the typescript tag: generates TypeScript. Without the tag: the AI may not recognize the language.

Good-vs-bad examples: the most effective example format shows both the wrong and right patterns. Format: '### Error Handling\nDo NOT do this:\n```typescript\ntry { const user = await getUser(id); } catch (e) { console.log(e); return null; }\n```\nDo this instead:\n```typescript\nconst result = await getUser(id);\nif (!result.success) { logger.error(result.error); return Result.err(result.error); }\nreturn Result.ok(result.data);\n```.' The contrast: makes the difference immediately clear. The AI: avoids the first pattern and follows the second.

Keep examples concise: the example should show the minimum code needed to demonstrate the pattern. A 50-line example: buries the pattern in boilerplate. A 5-line example: highlights exactly the pattern the AI should follow. If more context is needed: add a brief comment above the example explaining what to focus on. AI rule: 'Examples: 3-10 lines. Show the pattern, not the entire function. The AI extracts the pattern from the example and applies it in the larger context of the code it generates.'

Step 2: Types of Examples and When to Use Each

Pattern example: shows the correct pattern for a common task. Use when: the pattern is specific and you want the AI to generate it exactly. Example: '### API Response Format\n```typescript\nreturn { success: true, data: { id: user.id, email: user.email }, meta: { timestamp: new Date().toISOString() } };\n```.' The AI: generates responses matching this exact shape. Pattern examples: the most common and most useful type.

Anti-pattern example: shows what NOT to do, paired with the correct version. Use when: the AI frequently generates a specific wrong pattern. Example: '### Database Queries\nWRONG: db.query("SELECT * FROM users WHERE id = " + userId)\nRIGHT: db.query("SELECT * FROM users WHERE id = $1", [userId]).' The anti-pattern: explicitly shown so the AI recognizes and avoids it. Without the anti-pattern: the AI might generate the wrong version because it has seen it in training data.

Template example: shows a complete template for a recurring code structure. Use when: you want the AI to generate a specific file structure. Example: '### New API Route Template\n```typescript\nimport { z } from "zod";\nconst inputSchema = z.object({ /* params */ });\nexport async function GET(request: Request) {\n const params = inputSchema.parse(/* parsed input */);\n const result = await service.getData(params);\n return Response.json({ success: true, data: result });\n}\n```.' The template: a complete starting point that the AI fills in with specific business logic. AI rule: 'Template examples: the highest-impact example type. They show the complete structure for a recurring task. The AI: uses the template as a skeleton and fills in the specifics.'

Step 3: Balancing Examples with File Size

The trade-off: examples make rules clearer but increase file size. A rule file with 50 rules and code examples for each: could be 5,000+ words, pushing the limits of effective context for some AI tools. The balance: use examples for the 10-15 rules that benefit most (complex patterns, frequently misinterpreted rules, anti-patterns). Use descriptions only for the remaining rules (simple conventions, self-explanatory patterns).

The external example strategy: for rules that need long examples (multi-file patterns, complex architectural examples), keep a short version in the main rules file and link to a detailed example in a docs/ file. The main file: '### Service Pattern\nServices use constructor injection and return Result types. See: docs/examples/service-pattern.ts for a complete example.' The AI reads the short description. The developer: references the detailed example when needed. This keeps the main file lean while providing depth.

Measuring example effectiveness: if a rule has an example and the AI still generates the wrong pattern: the example may be too short (does not show enough context), too complex (the AI cannot extract the pattern from the noise), or contradicted by another rule (the example shows one approach, another rule describes a different one). Test: remove the example and use only a description. If the description works better: the example was misleading, not helpful. AI rule: 'Not every rule needs an example. Add examples when: the AI consistently generates the wrong pattern without them. Remove examples when: they increase file size without improving AI output quality.'

Code Examples in Rules Summary

Summary of including code examples in AI rules.

• Power: examples eliminate ambiguity. The AI generates code matching the exact pattern shown
• When to use: complex data structures, specific formats, before/after transformations, templates
• When to skip: simple rules (camelCase), intent rules (composition over inheritance), self-explanatory patterns
• Format: fenced code blocks with language tags. 3-10 lines. Show the pattern, not the whole function
• Good-vs-bad: show the wrong pattern AND the right pattern. Contrast makes the difference clear
• Template examples: complete file templates. Highest impact. AI uses as skeleton, fills in specifics
• Balance: examples for 10-15 most important rules. Descriptions for the rest. Keep file under 3,000 words
• External examples: short version in main file + link to detailed example in docs/