Grading Claude Agents Md

Grading CLAUDE.md and AGENTS.md

Grade agent configuration files, generate improvement plans, and implement fixes.

Workflow

┌─────────────────────────────────────────────────────────────┐
│  1. GRADE          2. PLAN           3. IMPLEMENT          │
│  ─────────         ─────────         ─────────────         │
│  Auto-detect       Show issues       Apply fixes           │
│  files → Score     with fixes →      on approval →         │
│  against rubric    prioritized       verify result         │
└─────────────────────────────────────────────────────────────┘

Quick Start

1. Detect config files: Look for CLAUDE.md and/or AGENTS.md in project 2. Grade each file: Apply rubric from references/rubric.md 3. Generate report: Score card + prioritized issues + improvement plan 4. On approval: Implement changes using references/improvement-patterns.md 5. Verify: Re-grade to confirm improvements

Grading Checklist

Copy and track progress:

Evaluation Progress:
- [ ] Step 1: Detect CLAUDE.md and AGENTS.md files
- [ ] Step 2: Measure size (lines, bytes, tokens)
- [ ] Step 3: Score Structure (25 pts)
- [ ] Step 4: Score Content Quality (25 pts)
- [ ] Step 5: Score PDA Implementation (25 pts)
- [ ] Step 6: Score Maintainability (25 pts)
- [ ] Step 7: Apply modifiers (±10 pts)
- [ ] Step 8: Generate report with grade
- [ ] Step 9: List improvements with priority
- [ ] Step 10: Ask: "Implement these improvements?"

Score Summary

Base: Structure (25) + Content (25) + PDA (25) + Maintainability (25) = 100 pts Modifiers: ±10 pts for bonuses/penalties Final: Capped at 0-100

Reference Files

Implementation Workflow

After grading, if user approves improvements:

1. Backup: Copy original to CLAUDE.md.backup 2. Create structure: Add subdirectory configs if needed 3. Extract content: Move sections to reference files 4. Add TOC: Generate table of contents for files >100 lines 5. Update imports: Add @imports for extracted content 6. Validate: Run size check on new structure 7. Report: Show before/after comparison

What Gets Fixed Automatically

Output Format

Grade report structure:

# Config Grade Report: [filename]

## Score: XX/100 (Grade: X)

| Pillar | Score | Max |
|--------|-------|-----|
| Structure | XX | 25 |
| Content Quality | XX | 25 |
| PDA Implementation | XX | 25 |
| Maintainability | XX | 25 |
| Modifiers | ±X | ±10 |

## Top Issues (prioritized)

1. **[Issue]**: [Description] → [Fix]
   Impact: +X pts if fixed

2. **[Issue]**: [Description] → [Fix]
   Impact: +X pts if fixed

## Recommended Actions

- [ ] Action 1
- [ ] Action 2
- [ ] Action 3

---
**Implement these improvements? (y/n)**

When Not to Use

Do not use this skill for:

• Creating new skills (use skill-creator)
• General markdown editing
• README.md or documentation files
• System prompts or prompt engineering
• MCP server configuration

Improvement Patterns

Patterns for fixing common issues found during grading.

Contents

• Size Reduction
• Adding TOC
• Extracting to References
• Fixing Anti-Patterns
• Monorepo Splitting
• Cross-Platform Support

---

Size Reduction

When to Apply

• File > 300 lines
• Token count > 1,200
• AGENTS.md > 15KB

Pattern: Extract by Topic

Before:

# Project

## Commands
...20 lines...

## API Patterns
...150 lines of API documentation...

## Database
...100 lines of schema docs...

## Testing
...80 lines of test patterns...

After:

# Project

## Commands
npm run build | npm test | npm lint

## Documentation
- API Patterns: @docs/api-patterns.md
- Database: @docs/database.md
- Testing: @docs/testing.md

Pattern: Extract Code Examples

Before:

## Example API Handler

// 50+ lines of code example import express from 'express'; import { validateInput } from './validation'; ...

After:

## Example API Handler
See @examples/api-handler.ts for complete example.

Key points:
- Validate inputs with Zod
- Use async/await
- Return consistent error format

---

Adding TOC

When to Apply

• File > 100 lines
• No existing ## Contents section

Pattern: Simple TOC

Insert after title, before first section:

# Project Name

Brief description.

## Contents

- [Commands](#commands)
- [Structure](#structure)
- [Conventions](#conventions)
- [Documentation](#documentation)

---

## Commands
...

Pattern: Detailed TOC (>300 lines)

## Contents

### Getting Started
- [Commands](#commands)
- [Setup](#setup)

### Development
- [Code Style](#code-style)
- [Testing](#testing)
- [Debugging](#debugging)

### Reference
- [API](#api)
- [Database](#database)

Anchor Generation Rules

Convert header to anchor: 1. Lowercase 2. Remove punctuation (except hyphens) 3. Replace spaces with hyphens 4. Remove duplicate hyphens

Examples:

• ## Quick Start → #quick-start
• ## API v2.0 → #api-v20
• ## What's New? → #whats-new

---

Extracting to References

When to Apply

• Section > 50 lines
• Content not used in every session
• Detailed documentation inline

Pattern: @import (CLAUDE.md)

Step 1: Create reference file

# docs/api-patterns.md

## REST Conventions
...detailed content...

## Error Handling
...detailed content...

Step 2: Replace inline content

## API Development
Quick reference: POST/GET/PUT/DELETE standard patterns.
Full guide: @docs/api-patterns.md

Pattern: Link (AGENTS.md)

## API Development
See [API Patterns](docs/api-patterns.md) for detailed conventions.

What to Extract

---

Fixing Anti-Patterns

Style Rules → Linters

Before:

## Code Style
- Use 2-space indentation
- Always use semicolons
- Prefer single quotes
- Max line length 80

After:

## Code Style
Enforced by ESLint and Prettier. Run `npm run lint` to check.
Config: `.eslintrc.json` and `.prettierrc`

Negative-Only → Alternatives

Before:

- Never use var
- Don't use console.log
- Avoid any type

After:

- Use `const` or `let` instead of `var`
- Use `logger.debug()` instead of `console.log`
- Use specific types; `unknown` if truly dynamic

Secrets → Environment Variables

Before:

## API Config
API_KEY=sk-abc123...
DATABASE_URL=postgres://user:pass@...

After:

## API Config
Credentials in environment variables (see `.env.example`).
Never commit secrets to this file.

Explaining Obvious → Assume Knowledge

Before:

## JSON
JSON (JavaScript Object Notation) is a lightweight
data-interchange format that is easy for humans to
read and write...

After:

## Data Format
API uses JSON. See @docs/api-schema.md for response shapes.

Vague → Specific

Before:

- Be careful with the database
- Make sure tests pass
- Keep code clean

After:

- Use transactions for multi-table operations
- Run `npm test` before committing; CI blocks failures
- Run `npm run lint:fix` before committing

---

Monorepo Splitting

When to Apply

• Project has packages/ or apps/ directory
• Root CLAUDE.md > 300 lines
• Different packages have different conventions

Pattern: Root + Package Configs

Step 1: Create lean root

# Monorepo

## Workspace Commands
pnpm build    # Build all
pnpm test     # Test all
pnpm --filter <pkg> <cmd>  # Single package

## Packages
- web/: React frontend
- api/: Express backend
- shared/: Common utilities

Each package has its own CLAUDE.md.

Step 2: Create package configs

# packages/web/CLAUDE.md

## Commands (local to this package)
pnpm dev      # Start dev server
pnpm build    # Production build

## Patterns
- Components in src/components/
- Use React hooks, no class components
- Tailwind for styling

Step 3: Move shared patterns

# packages/shared/CLAUDE.md

## Usage
Shared utilities for all packages.
Import: `import { x } from '@project/shared'`

## Adding New Utils
1. Create in src/
2. Export from src/index.ts
3. Add tests

---

Cross-Platform Support

When to Apply

• Team uses both Claude Code and Codex/OpenCode
• Want consistent guidance across tools

Pattern: Shared + Platform-Specific

project/
├── CLAUDE.md           # Claude Code specific
├── AGENTS.md           # Codex/OpenCode specific
└── docs/
    └── shared-rules.md # Common content

CLAUDE.md:

# Claude Code Config
@docs/shared-rules.md

## Claude-Specific
Use /compact when context is large.
Use # to add session notes.

AGENTS.md:

# Codex Config
See docs/shared-rules.md for common guidelines.

## Codex-Specific
Prefer explicit file paths in responses.

docs/shared-rules.md:

# Shared Development Rules

## Commands
- Build: `npm run build`
- Test: `npm test`

## Conventions
- TypeScript strict mode
- Prettier for formatting

---

Implementation Checklist

When implementing improvements:

Pre-Implementation:
- [ ] Backup original: cp CLAUDE.md CLAUDE.md.backup

Structure Changes:
- [ ] Create docs/ directory if extracting content
- [ ] Create package CLAUDE.md files if splitting monorepo
- [ ] Move extracted content to new files

Content Updates:
- [ ] Add TOC if file > 100 lines
- [ ] Replace inline content with @imports
- [ ] Fix all identified anti-patterns
- [ ] Add alternatives to negative rules

Validation:
- [ ] All @imports resolve to existing files
- [ ] File size reduced to target
- [ ] Commands still accurate
- [ ] Structure is navigable

Post-Implementation:
- [ ] Re-run grading to verify improvement
- [ ] Show before/after comparison
- [ ] Commit changes with descriptive message

Config File Grading Rubric

Score each criterion, then sum for pillar total. Final score = sum of pillars + modifiers.

Contents

• Pillar 1: Structure (25 pts)
• Pillar 2: Content Quality (25 pts)
• Pillar 3: PDA Implementation (25 pts)
• Pillar 4: Maintainability (25 pts)
• Modifiers (±10 pts)
• Quick Scoring Guide

---

Pillar 1: Structure (25 pts)

File Size (0-8 pts)

Quick check:

wc -l CLAUDE.md  # Lines
wc -c AGENTS.md  # Bytes

Organization (0-8 pts)

Good structure:

# Project Name
## Commands (first - most used)
## Structure (second - orientation)
## Conventions (third - rules)
## Documentation (last - links to details)

Navigation (0-9 pts)

Check: Does file >100 lines have ## Contents or ## Table of Contents?

---

Pillar 2: Content Quality (25 pts)

Relevance (0-8 pts)

Red flags (deduct points for each):

• Explaining what JSON/REST/Git is (-1 each)
• Multi-paragraph introductions (-2)
• Duplicating content from README (-2)
• Including full API documentation inline (-3)

Actionability (0-9 pts)

Good actionability:

Build: `npm run build`
Test: `npm test -- --watch`
Deploy: `./scripts/deploy.sh production`

Poor actionability:

The build process involves several steps including
compilation, bundling, and optimization...

Accuracy (0-8 pts)

Check:

• Do referenced files exist?
• Do commands work?
• Are tool versions current?

---

Pillar 3: PDA Implementation (25 pts)

Reference Usage (0-10 pts)

Good example:

## API Development
Quick patterns: POST/GET/PUT/DELETE endpoints
Detailed guide: @docs/api-patterns.md
Error handling: @docs/error-codes.md

Hierarchy Depth (0-8 pts)

Check: Trace any @import - is it more than 1 hop from CLAUDE.md?

Subdirectory Configs (0-7 pts)

For monorepos/multi-package projects:

N/A for single-package projects (give 7 pts).

---

Pillar 4: Maintainability (25 pts)

Freshness (0-7 pts)

Check: Any references to deprecated tools, old versions, or moved files?

Anti-Pattern Avoidance (0-10 pts)

Deduct points for each anti-pattern found:

Start at 10, apply deductions.

Consistency (0-8 pts)

Check:

• Same term for same concept throughout
• Consistent header capitalization
• Consistent list formatting

---

Modifiers (±10 pts)

Bonuses (max +10)

Penalties (max -10)

---

Quick Scoring Guide

Instant Grade Estimates

Grade A (90+):

• File < 200 lines
• TOC present
• All @imports resolve
• No anti-patterns
• Recently updated

Grade B (80-89):

• File < 400 lines
• Some @imports
• Minor anti-patterns
• Mostly organized

Grade C (70-79):

• File < 600 lines
• Few @imports
• Several anti-patterns
• Needs reorganization

Grade D (60-69):

• File > 600 lines
• No @imports
• Many anti-patterns
• Poor organization

Grade F (<60):

• File > 800 lines
• No structure
• Severe anti-patterns
• Largely unmaintained

Scoring Worksheet

STRUCTURE (25 pts)
├── File Size:        __/8
├── Organization:     __/8
└── Navigation:       __/9
                      ──────
                      __/25

CONTENT QUALITY (25 pts)
├── Relevance:        __/8
├── Actionability:    __/9
└── Accuracy:         __/8
                      ──────
                      __/25

PDA IMPLEMENTATION (25 pts)
├── Reference Usage:  __/10
├── Hierarchy Depth:  __/8
└── Subdirectory Use: __/7
                      ──────
                      __/25

MAINTAINABILITY (25 pts)
├── Freshness:        __/7
├── Anti-Patterns:    __/10
└── Consistency:      __/8
                      ──────
                      __/25

MODIFIERS
├── Bonuses:          +__
└── Penalties:        -__
                      ──────
                      ±__/10

TOTAL: __/100  GRADE: __

Size Guide

Thresholds and targets for CLAUDE.md and AGENTS.md files.

Contents

• Size Thresholds
• Token Budgets
• Measuring Size
• Performance Impact

---

Size Thresholds

CLAUDE.md Thresholds

AGENTS.md Thresholds

Important: Codex truncates at 32KB by default. Content beyond this limit is silently dropped.

---

Token Budgets

Context Window Allocation

Why Size Matters

Every token in CLAUDE.md: 1. Loads every message - Processed with each interaction 2. Competes for context - Less room for actual work 3. Costs money - API charges per token 4. Reduces quality - More tokens = worse instruction following

The 150-200 Rule

Research shows models reliably follow ~150-200 instructions:

• Claude Code system prompt uses ~50
• MCP servers consume additional slots
• Your CLAUDE.md competes for the rest

Implication: Every unnecessary instruction reduces adherence to important ones.

---

Measuring Size

Quick Commands

# Line count
wc -l CLAUDE.md

# Byte count
wc -c CLAUDE.md

# Word count (rough token estimate: words × 1.3)
wc -w CLAUDE.md

# Human-readable size
ls -lh CLAUDE.md

Token Estimation

Tokens ≈ Words × 1.3
Tokens ≈ Bytes / 4
Tokens ≈ Characters / 4

Claude Code Commands

/context    # Shows token breakdown
/memory     # Shows loaded CLAUDE.md files
/cost       # Shows session token usage

---

Performance Impact

Context Length vs. Quality

"Lost in the Middle" Effect

Information in the middle of long contexts is poorly retained:

• Beginning: Well-retained
• Middle: Significantly degraded
• End: Well-retained

Implication: Put critical instructions at the START of CLAUDE.md.

Recommended Order

# Project Name

## Commands (FIRST - most used, best retained)
...

## Structure (SECOND - orientation)
...

## Conventions (THIRD - rules)
...

## Documentation (LAST - links to details)
...

---

Target Sizes by Project Type

Simple Project

Target: 50-100 lines
Tokens: 200-400
Structure: Single CLAUDE.md, no references

Medium Project

Target: 100-200 lines
Tokens: 400-800
Structure: CLAUDE.md + 1-3 reference files

Large Project / Monorepo

Target: 100-150 lines (root)
Tokens: 400-600 (root)
Structure: Root CLAUDE.md + package CLAUDE.md files + docs/

Enterprise Project

Target: 100-200 lines (root)
Tokens: 400-800 (root)
Structure: Enterprise policy + user memory + project + local

---

Quick Reference Card

┌────────────────────────────────────────┐
│         SIZE QUICK REFERENCE           │
├────────────────────────────────────────┤
│ CLAUDE.md Targets:                     │
│   Lines:  < 150 optimal, < 400 max     │
│   Tokens: < 600 optimal, < 2000 max    │
│   Bytes:  < 6KB optimal, < 16KB max    │
├────────────────────────────────────────┤
│ AGENTS.md Targets:                     │
│   Per-file: < 5KB optimal, < 15KB max  │
│   Combined: < 16KB optimal, < 32KB MAX │
├────────────────────────────────────────┤
│ Token Estimation:                      │
│   Tokens ≈ Words × 1.3                 │
│   Tokens ≈ Bytes / 4                   │
├────────────────────────────────────────┤
│ Commands:                              │
│   wc -l CLAUDE.md    (lines)           │
│   wc -c AGENTS.md    (bytes)           │
│   /context           (token breakdown) │
└────────────────────────────────────────┘

Grade Report Template

Use this template when generating grade reports.

---

Report Structure

# Config Grade Report: [CLAUDE.md / AGENTS.md]

**Graded:** [YYYY-MM-DD]
**File:** [path/to/file]
**Size:** [X lines, Y bytes, ~Z tokens]

---

## Score: XX/100 (Grade: X)

| Pillar | Score | Max |
|--------|-------|-----|
| Structure | XX | 25 |
| Content Quality | XX | 25 |
| PDA Implementation | XX | 25 |
| Maintainability | XX | 25 |
| Modifiers | ±X | ±10 |

---

## Detailed Scores

### Structure (XX/25)

| Criterion | Score | Max | Notes |
|-----------|-------|-----|-------|
| File Size | X | 8 | [X lines, Y tokens] |
| Organization | X | 8 | [assessment] |
| Navigation | X | 9 | [TOC present/missing] |

### Content Quality (XX/25)

| Criterion | Score | Max | Notes |
|-----------|-------|-----|-------|
| Relevance | X | 8 | [assessment] |
| Actionability | X | 9 | [assessment] |
| Accuracy | X | 8 | [assessment] |

### PDA Implementation (XX/25)

| Criterion | Score | Max | Notes |
|-----------|-------|-----|-------|
| Reference Usage | X | 10 | [X @imports found] |
| Hierarchy Depth | X | 8 | [flat/nested] |
| Subdirectory Use | X | 7 | [N/A or assessment] |

### Maintainability (XX/25)

| Criterion | Score | Max | Notes |
|-----------|-------|-----|-------|
| Freshness | X | 7 | [assessment] |
| Anti-Patterns | X | 10 | [X found] |
| Consistency | X | 8 | [assessment] |

### Modifiers Applied (±X)

**Bonuses:** [list or "None"]
**Penalties:** [list or "None"]

---

## Issues Found (Priority Order)

### 🔴 Critical Issues

1. **[Issue Title]**
   - Problem: [description]
   - Fix: [specific action]
   - Impact: +X points if fixed

### 🟡 Important Issues

2. **[Issue Title]**
   - Problem: [description]
   - Fix: [specific action]
   - Impact: +X points if fixed

### 🟢 Minor Issues

3. **[Issue Title]**
   - Problem: [description]
   - Fix: [specific action]
   - Impact: +X points if fixed

---

## Improvement Plan

### If Implemented:

| Action | Current → Target | Score Impact |
|--------|-----------------|--------------|
| [Action 1] | [before → after] | +X pts |
| [Action 2] | [before → after] | +X pts |
| [Action 3] | [before → after] | +X pts |

**Projected Score After Fixes:** XX/100 (Grade: X)

---

## Recommended Actions

- [ ] [Specific action 1]
- [ ] [Specific action 2]
- [ ] [Specific action 3]

---

**Implement these improvements? (y/n)**

---

Grade Descriptions

Use these descriptions in reports:

---

Example Reports

Example: Grade A Report

# Config Grade Report: CLAUDE.md

**Graded:** 2026-01-03
**File:** ./CLAUDE.md
**Size:** 87 lines, 3,421 bytes, ~342 tokens

---

## Score: 94/100 (Grade: A)

| Pillar | Score | Max |
|--------|-------|-----|
| Structure | 24 | 25 |
| Content Quality | 23 | 25 |
| PDA Implementation | 23 | 25 |
| Maintainability | 22 | 25 |
| Modifiers | +2 | ±10 |

...

**Implement these improvements? (y/n)**
Minor tweaks available but not required.

Example: Grade D Report

# Config Grade Report: CLAUDE.md

**Graded:** 2026-01-03
**File:** ./CLAUDE.md
**Size:** 847 lines, 34,521 bytes, ~8,630 tokens

---

## Score: 62/100 (Grade: D)

| Pillar | Score | Max |
|--------|-------|-----|
| Structure | 12 | 25 |
| Content Quality | 18 | 25 |
| PDA Implementation | 8 | 25 |
| Maintainability | 16 | 25 |
| Modifiers | -6 | ±10 |

## Issues Found (Priority Order)

### 🔴 Critical Issues

1. **File Severely Oversized**
   - Problem: 847 lines, ~8,630 tokens (target: <150 lines, <600 tokens)
   - Fix: Extract 80% of content to reference files
   - Impact: +12 points if fixed

2. **No @imports Used**
   - Problem: All content inline, no progressive disclosure
   - Fix: Create docs/ folder, move detailed sections
   - Impact: +8 points if fixed

...

**Projected Score After Fixes:** 88/100 (Grade: B)

**Implement these improvements? (y/n)**
Strongly recommended.