Writing Rules System

A skill for creating and managing Claude Code writing rules — markdown files with YAML frontmatter that define patterns to watch for and messages to display when matches are detected. Writing Rules System helps you build consistent code quality guardrails that activate automatically as you work.

When to Use This Skill

Choose Writing Rules System when:

• Setting up automated code quality reminders for your project
• Creating pattern-based warnings for common mistakes or anti-patterns
• Building team-wide coding standards that Claude enforces during development
• Designing rules that trigger on specific file patterns or code content

Consider alternatives when:

• You need runtime linting (use ESLint, Pylint, or similar tools)
• You want Git pre-commit hooks (use husky or pre-commit framework)
• You need CI/CD pipeline checks (use GitHub Actions or similar)

Quick Start

Copy
claude "Create a writing rule that warns about console.log in production code"

Copy
# .claude/rules/no-console-log.md
---
name: no-console-log
description: Warns about console.log statements in production code
pattern:
  files:
    - "src/**/*.{ts,tsx}"
  content: "console\\.log"
  exclude:
    - "**/*.test.*"
    - "**/*.spec.*"
    - "src/utils/logger.ts"
message: |
  ⚠️ Avoid `console.log` in production code.
  Use the structured logger instead:
  ```typescript
  import { logger } from '@/utils/logger';
  logger.info('message', { context });

---

## Core Concepts

### Rule File Structure

| Field | Type | Purpose |
|-------|------|---------|
| `name` | string | Unique rule identifier |
| `description` | string | Human-readable explanation |
| `pattern.files` | glob[] | File paths where rule applies |
| `pattern.content` | regex | Content pattern to match |
| `pattern.exclude` | glob[] | Files to skip |
| `message` | string | Warning shown when pattern matches |

### Rule Categories

```markdown
## Security Rules
- no-hardcoded-secrets: Detect API keys, passwords in source
- no-eval: Warn about eval() and Function() usage
- sanitize-inputs: Remind about input validation

## Quality Rules
- no-console-log: Use structured logging
- no-any-type: Avoid TypeScript `any`
- max-function-length: Flag functions over 50 lines

## Convention Rules
- import-order: Enforce import grouping
- naming-conventions: Check variable/function naming
- file-structure: Validate module organization

Pattern Examples

Copy
# Match specific function calls
pattern:
  content: "document\\.getElementById"
  files: ["src/components/**/*.tsx"]

# Match import patterns
pattern:
  content: "import.*from ['\"]lodash['\"]"
  files: ["src/**/*.ts"]

# Match multiple patterns (any match triggers)
pattern:
  content: "(TODO|FIXME|HACK|XXX)"
  files: ["src/**/*"]
  exclude: ["**/*.test.*"]

Configuration

Parameter	Description	Default
rules_directory	Where rule files are stored	.claude/rules/
severity	Warning level: info, warning, error	warning
enabled	Whether rule is active	true
auto_fix	Suggest automatic fix when possible	false
suppress_in_tests	Don't trigger in test files	true

Best Practices

1. Start with high-value rules. Begin with rules that catch actual bugs or security issues your team encounters regularly. Rules about style preferences can come later — prioritize rules that prevent production incidents.

2. Write clear, actionable messages. Don't just say "bad pattern detected." Explain why it's a problem and show the correct alternative with a code example. A developer should be able to fix the issue just by reading the rule's message.

3. Use precise file patterns. A rule matching **/* creates noise. Target the specific directories and file types where the pattern matters — src/api/**/*.ts catches API routes without flagging test files or config.

4. Exclude legitimate uses. Every rule has exceptions. If your logger module needs console.log internally, exclude src/utils/logger.ts rather than disabling the rule everywhere. Exclude patterns prevent false positives.

5. Document rule rationale in the description. Six months from now, someone will ask why the rule exists. Include the context: "Added after incident #123 where hardcoded API key was committed to main branch."

Common Issues

Rules trigger too frequently and become noise. Narrow the file patterns and content regex. If a rule fires on every file, it's too broad. Consider splitting into multiple specific rules or adding exclude patterns for intentional uses.

Regex patterns miss variations of the same issue. Test your regex against real code samples. console\.log catches console.log() but misses console.warn() and console.error(). Use console\.(log|warn|error|debug) for comprehensive matching.

Team members disable rules instead of following them. This usually means the rule is too strict or the fix is too cumbersome. Review disabled rules to understand the pain point — maybe the rule needs better exclude patterns, or the codebase needs a utility that makes the correct pattern easier to use.