modular-rules-generator

name	modular-rules-generator
description	Generate Claude Code modular rules in .claude/rules/ that are short, succinct, and optimized for LLM coding agents with path-specific scoping support
license	MIT
metadata	{"version":"1.0.0","model":"claude-opus-4-5-20251101"}

Modular Rules Generator

Generate focused, path-specific rules for Claude Code in .claude/rules/ directory. Rules are short, succinct, and optimized for LLM coding agents.

---

Quick Start

generate modular rule

Claude will analyze your codebase, suggest relevant rule topics, and guide you through creating a modular rule with optional path-specific scoping.

---

Triggers

Trigger	Use Case
generate modular rule	Full interactive workflow
create claude rule	Alternative phrasing
add rule for {path/topic}	Path or topic-specific
suggest rules	Get rule suggestions only
modular rules	Generic invocation

---

Quick Reference

Feature	Example
Global rule	No frontmatter, applies everywhere
Path-scoped	paths: src/**/*.ts in frontmatter
Multiple patterns	paths: {src,lib}/**/*.{ts,tsx}
Subdirectories	frontend/, backend/, testing/
Rule length	5-15 bullet points (succinct)

---

Process

1. DISCOVERY
   └── Analyze codebase structure
   └── Detect file types, frameworks, directories
   └── Suggest relevant rule topics

2. CONFIGURATION
   └── Gather rule topic via AskUserQuestion
   └── Determine scope (global or path-specific)
   └── Collect and validate glob patterns

3. GENERATION
   └── Create directory structure if needed
   └── Generate markdown with frontmatter
   └── Write rule file
   └── Verify creation

---

Rule Structure

Global Rule (No Path Scoping)

# Testing Rules

- Run tests before committing
- Use descriptive test names
- Mock external dependencies
- Achieve >80% coverage on business logic

Path-Scoped Rule

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

# API Rules

- Validate all request inputs
- Use standard error response format
- Include OpenAPI documentation
- Log all errors with context

---

Glob Pattern Examples

Pattern	Matches
**/*.ts	All TypeScript files
src/**/*.{ts,tsx}	TypeScript/React in src/
{src,lib}/**/*.go	Go files in src/ or lib/
*.md	Markdown in project root
tests/**/*.test.js	Test files in tests/

See references/glob-patterns.md for comprehensive guide.

---

Suggested Topics (Auto-Detected)

Detected Pattern	Suggested Topic	Subdirectory
*.ts, *.tsx	typescript, react	frontend/
*.go	golang, backend	backend/
*_test.*, *.test.*	testing	testing/
.env*, config/	security, config	security/
*.css, *.scss	styling	frontend/
Dockerfile, *.yaml	docker, deployment	deployment/
*.sql, migrations/	database	backend/
src/api/**, routes/	api-design	backend/

---

Commands

Command	Action
generate modular rule	Full workflow
suggest rules	Analysis only (no generation)

---

Validation Checklist

After rule generation:

• .claude/rules/ directory exists
• Rule file has descriptive filename
• Frontmatter valid (if path-scoped)
• Glob patterns are syntactically correct
• Rule content is 5-15 bullet points
• No duplicate rule files
• Rules are succinct (no verbose prose)

---

Anti-Patterns

Avoid	Instead
Verbose paragraphs	Short bullet points
Generic advice	Project-specific rules
Overlapping rules	One topic per file
Overly broad paths (**/*)	Precise patterns (src/**/*.ts)
50+ line rules	5-15 focused points
Duplicate rules	Check existing first

---

Best Practices

Rule Content

• Succinct: 5-15 bullet points maximum
• Actionable: Clear, specific guidance
• Contextual: Relevant to the codebase
• Consistent: Match existing project patterns

File Organization

.claude/rules/
├── general.md              # Global rules (no frontmatter)
├── frontend/
│   ├── react.md           # paths: **/*.{tsx,jsx}
│   └── styling.md         # paths: **/*.{css,scss}
├── backend/
│   ├── api.md             # paths: src/api/**/*.ts
│   └── database.md        # paths: **/*.sql, migrations/**/*
└── testing/
    └── unit-tests.md      # paths: **/*.test.{ts,js}

Path Scoping

• Use specific patterns over broad ones
• Combine related extensions: {ts,tsx}
• Scope to actual file locations
• Test patterns match expected files

---

Examples

See references/rule-examples.md for complete examples organized by topic.

---

Deep Dive: Phase 1 - Discovery

Codebase Analysis

The skill analyzes your project to suggest relevant rules:

1. File Type Detection

# Detect file types
glob **/*.ts, **/*.tsx, **/*.go, **/*.py, etc.

# Count occurrences
typescript: 145 files → suggest typescript.md
go: 0 files → skip golang rules

2. Framework Detection

File Pattern	Framework	Suggested Rules
package.json + React	React	react.md, jsx-patterns.md
go.mod	Go	golang.md, error-handling.md
requirements.txt	Python	python.md, type-hints.md
Cargo.toml	Rust	rust.md, ownership.md

3. Directory Structure Analysis

Directory Pattern	Suggested Topic
src/api/, routes/	api-design.md
tests/, __tests__/	testing.md
components/, views/	react.md
models/, schemas/	database.md
middleware/, auth/	security.md

4. Existing Rules Detection

# Read existing .claude/rules/
ls -la .claude/rules/

# Prevent duplicates
existing: ["testing.md", "api.md"]
suggest: code-style.md, security.md (exclude existing)

Deep Dive: Phase 2 - Configuration

Interactive Configuration

Uses AskUserQuestion to gather rule details:

Question 1: Rule Topic

What topic should this rule cover?

Options:
1. Code Style
2. Testing Standards
3. API Design
4. Security Practices
5. [Custom - user input]

Question 2: Scope

Should this rule apply globally or to specific paths?

Options:
1. Global (applies to all files)
2. Path-specific (applies to matching files only)

Question 3: Target Paths (if path-specific)

Which files should this rule apply to?

Examples:
- src/**/*.ts (all TypeScript in src/)
- **/*.test.js (all test files)
- {src,lib}/**/*.go (Go files in src/ or lib/)

[User enters glob pattern]

Glob Pattern Validation

Before accepting patterns:

function validateGlobPattern(pattern) {
  // Check basic syntax
  - No spaces (use {a,b} not {a, b})
  - Balanced braces
  - Valid characters

  // Test against actual files
  matches = glob(pattern)

  if (matches.length === 0) {
    warn("Pattern matches no files. Continue anyway?")
  }

  return valid
}

Question 4: Subdirectory Organization

Where should this rule be stored?

Based on topic 'API Design':
1. .claude/rules/backend/api.md (Recommended)
2. .claude/rules/api.md
3. [Custom path]

Deep Dive: Phase 3 - Generation

Rule File Generation

Step 1: Create Directory Structure

# If subdirectory suggested
mkdir -p .claude/rules/backend/

# Ensure base directory exists
mkdir -p .claude/rules/

Step 2: Generate Frontmatter (if scoped)

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

Step 3: Generate Rule Content

Based on selected topic, use template or generate custom:

# API Development Rules

- Validate all request inputs using Zod schemas
- Use standard error response format: {error, message, code}
- Include OpenAPI documentation comments
- Version endpoints: /api/v1/resource
- Return 200 for success, 400 for client errors, 500 for server errors
- Log all errors with request context
- Implement rate limiting on public endpoints
- Use JWT for authentication
- Sanitize user inputs to prevent injection
- Return consistent data structures

Length constraint: 5-15 bullets (enforced)

Step 4: Write File

# Write to determined path
write .claude/rules/backend/api.md

# Verify creation
test -f .claude/rules/backend/api.md

Step 5: Confirmation

✓ Created .claude/rules/backend/api.md

Rule applies to: src/api/**/*.ts
Contains: 10 guidelines

Template Library

Available Templates

Pre-built templates for common rule topics:

Template	Path	Use Case
code-style.md	assets/templates/	General coding standards
testing.md	assets/templates/	Test conventions
security.md	assets/templates/	Security requirements
api-design.md	assets/templates/	API standards

Using Templates

1. User selects topic matching template
2. Load template from assets/templates/{topic}.md
3. Customize based on detected frameworks/languages
4. Apply path scoping if requested
5. Write customized rule

Custom Rules

When no template matches:

1. Generate rule structure
2. Provide 8-12 baseline bullets
3. User can edit after creation

---

Related Skills

Skill	Relationship
claude-authoring-guide	Writing effective Claude instructions
skill-composer	Orchestrating multiple skills

---

Extension Points

1. New Templates: Add templates to assets/templates/ for new topics
2. Framework Detection: Extend detection logic for new frameworks
3. Validation Scripts: Add glob pattern testing scripts
4. Migration Tools: (Future) Convert CLAUDE.md to modular rules
5. Rule Linting: (Future) Validate rule quality and duplication

---

Verification Criteria

A successful rule generation:

• File created at intended path
• Frontmatter valid (if path-scoped)
• Content is 5-15 bullet points
• Bullets are actionable and specific
• No duplicate rules for same topic
• Glob patterns match expected files
• File follows naming convention (lowercase, hyphens)

---

Changelog

v1.0.0

• Initial release
• Support for global and path-scoped rules
• Codebase analysis and suggestions
• Interactive configuration workflow
• Template library (4 templates)
• Glob pattern validation