Add Rule — Capture a Team Convention

Purpose

Formalize a convention, best practice, or correction into the project's .claude/rules/ or .claude/agents/ files so it applies automatically for all team members.

Input

The user provides a convention in natural language. Examples:

• /add-rule "prefer require.NoError over t.Fatal for error assertions"
• /add-rule "use context.Background() in tests, not context.TODO()"
• /add-rule "CLI commands must support --format json"

If no argument is provided, ask: "What convention would you like to add?"

Instructions

1. Understand the Convention

Parse the user's input to identify:

• The rule: What should or should not be done
• The scope: Which files or areas it applies to (Go code, tests, CLI, operator, etc.)
• The reason: Why this convention exists (ask if not provided — the "why" is critical for future developers to judge edge cases)

2. Find the Right Target File

Rules vs Agents — key principle: Rules define conventions; agents reference rules. Never duplicate rule content in agent files.

• Rules files (.claude/rules/): Auto-loaded based on paths: frontmatter globs when Claude touches matching files. These define the canonical conventions (style, testing patterns, error handling, etc.).
• Agent files (.claude/agents/): Define agent-specific behavior — persona, review checklist, output format, workflow steps. Agents inherit the full conversation context (including CLAUDE.md), so they already have access to all loaded rules. Agent files should reference rules (e.g., "Follows conventions in .claude/rules/testing.md"), never restate them.

Match the convention to an existing file based on scope:

If no existing file fits, propose creating a new rule file with appropriate paths: frontmatter. New rule files need a glob pattern that determines when they auto-load.

If the convention is about code (how to write Go, test patterns, error handling), it belongs in a rules file — even if it's most relevant to a specific agent. The agent can reference the rule.

3. Draft the Addition

Read the target file and draft the new content:

• Match the style and formatting of existing rules in the file
• Place the rule in the most logical section (or propose a new section if needed)
• Keep it concise — one to three lines is ideal
• Include a brief rationale if the "why" isn't obvious from the rule itself
• Use code examples for conventions that benefit from showing good vs bad patterns

Format examples:

Simple rule:

- Use `context.Background()` in tests, not `context.TODO()` — tests have no caller to propagate cancellation from

Rule with example:

## Prefer Table-Driven Tests

Use table-driven tests over repeated test functions:
` ``go
// Good
tests := []struct{ name string; input int; want int }{...}

// Avoid: separate TestFoo1, TestFoo2, TestFoo3 functions
` ``

4. Present the Change

Show the user:

1. Target file and the section where the rule will be added
2. The exact edit — the lines being added in context
3. A one-line confirmation prompt: "Add this rule to .claude/rules/testing.md? (y/n)"

5. Apply on Confirmation

Use the Edit tool to add the rule to the target file. After applying:

• Verify the file is still well-structured
• If the rule was added to a rules file, mention that agents already pick it up automatically — rules are auto-loaded when matching files are touched, and agents inherit the full context. No agent file edits are needed unless the agent needs to explicitly reference the rule in a checklist.

Edge Cases

• Duplicate rule: If a similar rule already exists, show it to the user and ask whether to update the existing rule or skip
• Contradicts existing rule: If the new convention contradicts an existing one, highlight the conflict and ask the user to resolve it
• Too broad for one file: If the convention spans multiple scopes, suggest adding it to CLAUDE.md instead or splitting into multiple rule additions
• Personal preference vs team convention: If the rule sounds personal (e.g., "I prefer tabs"), ask: "Is this a team-wide convention or a personal preference? Personal preferences go in your ~/.claude/ memory instead."