# Content Quality Metrics

## Quality Criteria

### Actionability
Rules should provide clear, actionable guidance. Descriptions alone are insufficient.

```markdown
<!-- BAD: Just a description -->
This project uses TypeScript.

<!-- GOOD: Actionable guidance -->
Use strict TypeScript. Enable `noImplicitAny` and `strictNullChecks`.
Prefer interfaces over type aliases for object shapes.
```

### Conciseness
Each rule file should be focused and concise (< 500 tokens typical).

### Non-Conflicting
Rules across files should not contradict each other.

### Single Topic
Each rule file should address one focused topic.

## Scoring (25 points, deductive)

Starts at 25, deducts for issues found:

| Issue | Deduction | Criteria |
|-------|-----------|----------|
| Empty content | -25 | Rule file has no body text |
| Too short | -5 | Fewer than 10 words |
| Too verbose | -5 | Exceeds 500 estimated tokens |

# Frontmatter Validation

## Valid Frontmatter Fields

Claude Code rules support these frontmatter fields:

| Field | Type | Required | Purpose |
|-------|------|----------|---------|
| `paths` | `list[string]` | No | Glob patterns for conditional loading |
| `description` | `string` | No | Brief description of rule purpose |

Rules without `paths` are unconditional (apply to all files).

## Common Errors

### YAML Syntax Errors
```yaml
# INVALID - unquoted glob starting with *
---
paths:
  - **/*.ts        # YAML parse error
---

# VALID - quoted glob
---
paths:
  - "**/*.ts"
---
```

### Wrong Field Names
```yaml
# INVALID - Cursor-specific fields
---
globs:             # Wrong! Use 'paths'
  - "*.ts"
alwaysApply: true  # Wrong! Cursor-only, not Claude Code
---
```

### Invalid Structure
```yaml
# INVALID - paths must be a list
---
paths: "**/*.ts"   # Should be a list
---

# VALID
---
paths:
  - "**/*.ts"
---
```

## Scoring (25 points, deductive)

Starts at 25, deducts for issues found:

| Issue | Deduction | Criteria |
|-------|-----------|----------|
| YAML parse error | -25 | Frontmatter fails to parse |
| Cursor-specific field | -5 each | `globs`, `alwaysApply`, etc. |
| Invalid `paths` type | -5 | `paths` is not a list |
| Unknown field | -2 each | Field not in valid set |
| Empty `paths` list | -1 | `paths: []` (likely unintended) |

# Glob Pattern Analysis

## Pattern Quality Assessment

### Good Patterns
```
"src/api/**/*.ts"       # Specific scope
"tests/**/*.test.ts"    # Clear intent
"{src,lib}/**/*.ts"     # Multiple dirs, quoted
"*.config.{js,ts}"      # Config files only
```

### Problem Patterns
```
"**/*"                  # Too broad - matches everything
"*"                     # Root only, usually too narrow
**/*.ts                 # Unquoted - YAML parse error
"."                     # Invalid glob
```

## Validation Rules

1. **Syntax validity**: Pattern must be valid glob syntax
2. **Quoting**: Patterns with `*`, `{`, `}`, `[`, `]` must be quoted
3. **Specificity**: Patterns should not match everything (`**/*`)
4. **Intent clarity**: Pattern should clearly indicate target files

## Scoring (20 points, deductive)

Starts at 20, deducts for issues found. Files without `paths` receive full score.

| Issue | Deduction | Criteria |
|-------|-----------|----------|
| Overly broad pattern | -5 each | Matches `**/*`, `*`, etc. |
| Empty pattern | -4 each | Blank or whitespace-only pattern |

# Organization Patterns

## Directory Structure

### Recommended Layout
```
.claude/rules/
  api-validation.md       # Descriptive names
  testing-standards.md    # Topic-based naming
  frontend/               # Subdirectories for grouping
    react-patterns.md
    css-conventions.md
```

### Anti-Patterns
```
.claude/rules/
  rules1.md              # Non-descriptive names
  misc.md                # Catch-all files
  RULES.md               # Shouting case
  my rules file.md       # Spaces in filenames
```

## Naming Conventions

- Use kebab-case: `api-validation.md`
- Be descriptive: name should indicate rule content
- Use subdirectories for 5+ rule files
- Avoid generic names: `rules.md`, `misc.md`, `todo.md`

## Symlink Support

Symlinks enable shared rules across projects:
```bash
ln -s ~/shared-rules/code-style.md .claude/rules/code-style.md
```

Validate that symlink targets exist and are readable.

## Scoring (15 points)

| Check | Points | Criteria |
|-------|--------|----------|
| Descriptive filenames | 5 | Names indicate content |
| Kebab-case naming | 4 | Consistent formatting |
| Logical grouping | 3 | Subdirectories when needed |
| No broken symlinks | 3 | All symlinks resolve |