Writing Project Rules

Overview

Project rules provide context-specific instructions to Claude. This skill covers creating file-scoped rules that minimize token usage by only loading when relevant files are touched.

When to Use

• Creating new project rules
• Adding .claude/rules/*.md files
• Scoping rules to specific files with globs
• Setting up doc-sync reminders (update X when Y changes)

Rule File Locations

Workflow

1. Choose Scope

• Project-wide (commits, general info) → .claude/CLAUDE.md
• File-specific (component rules, doc sync) → .claude/rules/*.md with globs

2. Create File-Scoped Rule

---
globs: src/api/**/*.ts
---

# API Rules

- Use Result types for errors
- Validate inputs at boundaries

3. Use Appropriate Glob Patterns

*.ts                    # All .ts files anywhere
src/**/*.ts             # All .ts in src tree
fish/config.fish        # Exact file match
{src,lib}/**/*.ts       # Multiple directories

Multiple globs:

---
globs:
  - src/api/**/*.ts
  - src/services/**/*.ts
---

Example: Doc Sync Rule

When modifying a file should trigger doc updates:

---
globs: fish/config.fish
---

# Git Dashboard

When modifying `_git_*` functions:

- Update `fish/GIT_DASHBOARD_DESIGN.md` after visible changes

Rules vs Skills

Consider a skill instead of a rule when:

• Content applies to operations (git push, running tests) not file edits
• Guidance is on-demand rather than always needed
• The glob pattern doesn't match when the rule would actually help

Gotcha: A rule with globs: ".github/**" containing "never push to main" won't load during git push - it only loads when editing .github files. Use a skill or hook instead.

Key Principles

1. Prefer globs over project-wide - reduces token usage
2. Keep rules concise - they consume context tokens
3. One concern per rule file - easier to maintain
4. Multiple rules can match - all matching rules apply
5. Match globs to trigger - ensure glob fires when rule is needed