Rules Organizer

Skill for organizing Claude Code instructions into modular .claude/rules/ files.

When to Use

This skill activates when you:

• Set up coding standards for a project area
• Create team conventions for specific domains
• Add security or compliance rules
• Share rules across projects via symlinks
• Organize a large CLAUDE.md into focused files

Keywords: rules, standards, conventions, guidelines, organize instructions, coding style, team rules

Quick Reference

Directory Structure

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main instructions (keep concise)
│   └── rules/
│       ├── code-style.md   # General coding style
│       ├── security.md     # Security requirements
│       ├── testing.md      # Testing conventions
│       ├── frontend/
│       │   ├── react.md    # React patterns
│       │   └── tailwind.md # Tailwind conventions
│       └── backend/
│           ├── api.md      # API route patterns
│           └── database.md # Database conventions

Rule File Format

Each rule file is a simple markdown file (no frontmatter required):

# Code Style Rules

## General
- Use 2-space indentation
- No semicolons in TypeScript
- Prefer functional components

## Naming
- Components: PascalCase
- Functions: camelCase
- Constants: SCREAMING_SNAKE_CASE

## Examples

### Good
```typescript
const UserProfile = ({ user }: Props) => {
  return <div>{user.name}</div>
}

Bad

function user_profile(props: any) {
  return <div>{props.user.name}</div>;
}

## CircleTel Rules Organization

### Recommended Structure

.claude/rules/ ├── general/ │ ├── code-style.md # TypeScript, naming conventions │ ├── error-handling.md # try/catch patterns │ └── security.md # OWASP, input validation ├── frontend/ │ ├── react-patterns.md # Hooks, components, state │ ├── tailwind.md # Utility classes, responsive │ └── forms.md # Validation, submission ├── backend/ │ ├── api-routes.md # Next.js 15 patterns │ ├── supabase.md # Client usage, RLS │ └── webhooks.md # Signature verification ├── domain/ │ ├── payments.md # NetCash, billing rules │ ├── coverage.md # MTN, provider APIs │ └── b2b-kyc.md # KYC workflow rules └── testing/ ├── unit.md # Jest patterns └── e2e.md # Playwright patterns

## Creating Rule Files

### Step 1: Identify the Category
- Is it general coding style? → `general/`
- Is it framework-specific? → `frontend/` or `backend/`
- Is it business logic? → `domain/`
- Is it about testing? → `testing/`

### Step 2: Create the File
```bash
# Create directory if needed
mkdir -p .claude/rules/backend

# Create rule file
touch .claude/rules/backend/api-routes.md

Step 3: Write Clear Rules

• Start with a heading
• Use bullet points for rules
• Include code examples
• Show both good and bad patterns

Example Rule Files for CircleTel

.claude/rules/backend/api-routes.md

# API Route Conventions

## Next.js 15 Async Params (CRITICAL)

Always await params in dynamic routes:

```typescript
// CORRECT
export async function GET(
  request: NextRequest,
  context: { params: Promise<{ id: string }> }
) {
  const { id } = await context.params
}

// WRONG - Will cause type errors
export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const { id } = params
}

Supabase Client Selection

// Server-side (API routes)
import { createClient } from '@/lib/supabase/server'
const supabase = await createClient()

// Client-side (components)
import { createClient } from '@/lib/supabase/client'
const supabase = createClient()

Error Response Format

Always use consistent error responses:

// Success
return NextResponse.json({ data, success: true })

// Error
return NextResponse.json(
  { error: 'Description', code: 'ERROR_CODE', success: false },
  { status: 400 }
)

Authentication Check Pattern

export async function GET(request: NextRequest) {
  // Check authorization header first
  const authHeader = request.headers.get('authorization')

  if (authHeader?.startsWith('Bearer ')) {
    const token = authHeader.split(' ')[1]
    const { data: { user }, error } = await supabase.auth.getUser(token)
    if (error || !user) {
      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
    }
  }

  // Continue with authenticated request...
}

### `.claude/rules/domain/payments.md`
```markdown
# Payment System Rules

## NetCash Integration

### Environment Variables
- `NETCASH_SERVICE_KEY` - Never expose in client code
- `NETCASH_WEBHOOK_SECRET` - For signature verification

### Webhook Signature Verification (REQUIRED)
```typescript
import crypto from 'crypto'

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

// Always verify first
if (!verifyWebhookSignature(payload, signature, secret)) {
  return NextResponse.json({ error: 'Invalid signature' }, { status: 401 })
}

Payment Statuses

eMandate Flow

1. Create mandate request via API
2. Redirect customer to NetCash authorization
3. Receive webhook confirmation
4. Store mandate reference for future debits

### `.claude/rules/frontend/react-patterns.md`
```markdown
# React Patterns for CircleTel

## Loading States (CRITICAL)

Always use try/catch/finally to prevent infinite loading:

```typescript
// CORRECT
useEffect(() => {
  const fetchData = async () => {
    try {
      setLoading(true)
      const data = await api.getData()
      setData(data)
    } catch (error) {
      console.error('Failed:', error)
      setError(error)
    } finally {
      setLoading(false)  // ALWAYS executes
    }
  }
  fetchData()
}, [])

// WRONG - Loading never stops on error
useEffect(() => {
  const fetchData = async () => {
    setLoading(true)
    const data = await api.getData()  // Error here = stuck loading
    setData(data)
    setLoading(false)
  }
  fetchData()
}, [])

Component Organization

components/
├── ui/           # Reusable UI primitives
├── forms/        # Form components
├── layout/       # Layout components
├── dashboard/    # Dashboard-specific
├── admin/        # Admin-specific
└── checkout/     # Checkout flow

Props Interface Pattern

interface UserCardProps {
  user: User
  onEdit?: (user: User) => void
  className?: string
}

export const UserCard = ({ user, onEdit, className }: UserCardProps) => {
  // Component implementation
}

Custom Hooks Pattern

// hooks/use-customer.ts
export function useCustomer(customerId: string) {
  const [customer, setCustomer] = useState<Customer | null>(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<Error | null>(null)

  useEffect(() => {
    // Fetch logic with try/catch/finally
  }, [customerId])

  return { customer, loading, error }
}

## Symlink Shared Rules

### Share Rules Across Projects
```bash
# Create shared rules directory
mkdir -p ~/shared-claude-rules

# Create shared security rules
cat > ~/shared-claude-rules/security.md << 'EOF'
# Security Standards

- Never log sensitive data (passwords, tokens, PII)
- Always validate user input
- Use parameterized queries
- Verify webhook signatures
EOF

# Symlink to project
cd /path/to/project
ln -s ~/shared-claude-rules/security.md .claude/rules/security.md

Company-Wide Standards

# Clone company rules repo
git clone git@github.com:company/claude-rules.git ~/company-claude-rules

# Symlink entire directory
ln -s ~/company-claude-rules .claude/rules/company

User-Level Rules

Personal rules that apply to ALL your projects:

~/.claude/rules/
├── preferences.md    # Your coding preferences
├── workflows.md      # Your preferred workflows
└── communication.md  # How you like Claude to respond

Example: ~/.claude/rules/preferences.md

# My Coding Preferences

## Communication
- Be concise, avoid over-explanation
- Use code examples over lengthy descriptions
- Include file:line references

## Code Style
- Prefer early returns
- Use optional chaining (?.)
- Avoid nested ternaries
- Prefer const over let

## When I Ask "Fix This"
1. Read the file first
2. Make minimal changes
3. Explain what changed

Migration from Large CLAUDE.md

Step 1: Identify Sections

Review your CLAUDE.md and categorize content:

• General coding → rules/general/
• Framework-specific → rules/frontend/ or rules/backend/
• Domain logic → rules/domain/
• Keep in CLAUDE.md: Project overview, commands, file structure

Step 2: Extract to Files

# Create directories
mkdir -p .claude/rules/{general,frontend,backend,domain,testing}

# Create rule files
touch .claude/rules/general/code-style.md
touch .claude/rules/frontend/react.md
touch .claude/rules/backend/api.md
touch .claude/rules/domain/payments.md

Step 3: Slim Down CLAUDE.md

Keep only:

• Project overview
• Quick start commands
• File organization
• Environment setup
• Links to rule files

Best Practices

1. Keep rules focused - One topic per file
2. Use examples - Show don't just tell
3. Include bad patterns - Show what to avoid
4. Update regularly - Rules evolve with project
5. Version control - Commit rule changes
6. Document purpose - Header explaining when rule applies
7. Use subdirectories - Group related rules

Troubleshooting

Rules not loading

• Ensure files have .md extension
• Check file is in .claude/rules/ directory
• Restart Claude Code after adding rules

Too many rules

• Consolidate related rules into fewer files
• Use subdirectories for organization
• Consider what's truly essential

Conflicting rules

• More specific rules (deeper paths) take priority
• Project rules override user rules
• CLAUDE.md has highest priority

Version: 1.0.0 Last Updated: 2025-12-10 For: Claude Code v2.0.64+