CLAUDE.md Quality Criteria

Scoring Rubric

1. Commands/Workflows (20 points)

20 points: All essential commands documented with context

• Build, test, lint, deploy commands present
• Development workflow clear
• Common operations documented

15 points: Most commands present, some missing context

10 points: Basic commands only, no workflow

5 points: Few commands, many missing

0 points: No commands documented

2. Architecture Clarity (20 points)

20 points: Clear codebase map

• Key directories explained
• Module relationships documented
• Entry points identified
• Data flow described where relevant

15 points: Good structure overview, minor gaps

10 points: Basic directory listing only

5 points: Vague or incomplete

0 points: No architecture info

3. Non-Obvious Patterns (15 points)

15 points: Gotchas and quirks captured

• Known issues documented
• Workarounds explained
• Edge cases noted
• "Why we do it this way" for unusual patterns

10 points: Some patterns documented

5 points: Minimal pattern documentation

0 points: No patterns or gotchas

4. Conciseness (15 points)

15 points: Dense, valuable content

• No filler or obvious info
• Each line adds value
• No redundancy with code comments

10 points: Mostly concise, some padding

5 points: Verbose in places

0 points: Mostly filler or restates obvious code

5. Currency (15 points)

15 points: Reflects current codebase

• Commands work as documented
• File references accurate
• Tech stack current

10 points: Mostly current, minor staleness

5 points: Several outdated references

0 points: Severely outdated

6. Actionability (15 points)

15 points: Instructions are executable

• Commands can be copy-pasted
• Steps are concrete
• Paths are real

10 points: Mostly actionable

5 points: Some vague instructions

0 points: Vague or theoretical

Assessment Process

1. Read the CLAUDE.md file completely
2. Cross-reference with actual codebase:
   • Run documented commands (mentally or actually)
   • Check if referenced files exist
   • Verify architecture descriptions
3. Score each criterion
4. Calculate total and assign grade
5. List specific issues found
6. Propose concrete improvements

Rules Quality Criteria

For .claude/rules/*.md files:

Frontmatter Validity

• paths: uses comma-separated format (NOT YAML array)
• Path patterns match existing files in codebase
• No overlapping rules with conflicting instructions

Content Quality

• Clear, specific instructions for the targeted paths
• No duplication with main CLAUDE.md
• Appropriate scope (not too broad, not too narrow)

Example Valid Rule

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

# API Development Rules

- Use dependency injection pattern
- All endpoints must have OpenAPI docs

Common Rule Issues

• Using YAML array syntax: paths: [a, b] (wrong)
• Paths that don't match any files
• Overly broad rules that should be in CLAUDE.md
• Conflicting instructions between rules

Red Flags

• Commands that would fail (wrong paths, missing deps)
• References to deleted files/folders
• Outdated tech versions
• Copy-paste from templates without customization
• Generic advice not specific to the project
• "TODO" items never completed
• Duplicate info across multiple CLAUDE.md files
• Rules with invalid paths: frontmatter syntax