zhongwei/gh-cskiro-claudex-claude-code-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:16:51 +08:00
commit 4e8a12140c
88 changed files with 17078 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
skills/claude-md-auditor/reference/anti-patterns.md Normal file
View File

@@ -0,0 +1,215 @@
# CLAUDE.md Anti-Patterns
Catalog of common mistakes organized by severity.
## Critical Violations (Fix Immediately)
### Exposed Secrets
```markdown
# BAD - Never do this
API_KEY=sk-abc123...
DATABASE_URL=postgres://user:password@host:5432/db
```
**Detection patterns**:
- `password`, `secret`, `token`, `api_key`
- `postgres://`, `mysql://`, `mongodb://`
- `-----BEGIN.*PRIVATE KEY-----`
- `sk-`, `pk_`, `AKIA` (API key prefixes)
**Fix**: Remove immediately, rotate credentials, clean git history
### Exposed Infrastructure
```markdown
# BAD
Internal API: http://192.168.1.100:8080
Database: 10.0.0.50:5432
```
**Fix**: Use environment variables or secrets management
## High Severity (Fix This Sprint)
### Generic Content
```markdown
# BAD - Claude already knows this
## JavaScript Best Practices
- Use const instead of var
- Prefer arrow functions
- Use async/await over callbacks
```
**Fix**: Remove generic content, keep only project-specific deviations
### Excessive Verbosity
```markdown
# BAD - Too wordy
When you are writing code for this project, it is important that you
remember to always consider the implications of your changes and how
they might affect other parts of the system...
```
**Fix**: Be direct and concise
```markdown
# GOOD
Check integration test impacts before modifying shared utilities.
```
### Vague Instructions
```markdown
# BAD
Write good, clean code following best practices.
```
**Fix**: Be specific
```markdown
# GOOD
- Max function length: 50 lines
- Max file length: 300 lines
- All public functions need JSDoc
```
### Conflicting Guidance
```markdown
# BAD - Contradictory
## Testing
Always write tests first (TDD).
## Development Speed
Skip tests for quick prototypes.
```
**Fix**: Resolve conflicts, specify when each applies
## Medium Severity (Schedule for Next Quarter)
### Outdated Information
```markdown
# BAD
Run: npm run test (uses Jest) # Actually switched to Vitest 6 months ago
```
**Fix**: Regular audits, add last-updated dates
### Duplicated Content
```markdown
# BAD - Same info twice
## Build Commands
npm run build
## Getting Started
Run `npm run build` to build the project.
```
**Fix**: Single source of truth, reference don't repeat
### Missing Context
```markdown
# BAD - Why this pattern?
Always use repository pattern for data access.
```
**Fix**: Explain reasoning
```markdown
# GOOD
Use repository pattern for data access (enables testing with mocks,
required for our caching layer).
```
### Broken Import Paths
```markdown
# BAD
@docs/old-standards.md # File was moved/deleted
```
**Fix**: Validate imports exist, update or remove stale references
## Low Severity (Backlog)
### Poor Organization
```markdown
# BAD - No structure
Here's how to build. npm run build. Tests use vitest. We use TypeScript.
The API is REST. Database is Postgres. Deploy with Docker.
```
**Fix**: Use headers, lists, logical grouping
### Inconsistent Formatting
```markdown
# BAD - Mixed styles
## Build Commands
- npm run build
## Testing
Run `npm test` for unit tests
npm run test:e2e runs e2e tests
```
**Fix**: Consistent formatting throughout
### Missing Priority Markers
```markdown
# BAD - What's critical vs nice-to-have?
Use TypeScript strict mode.
Add JSDoc to public functions.
Never use any type.
Format with Prettier.
```
**Fix**: Add priority markers
```markdown
# GOOD
**CRITICAL**: Never use `any` type
**IMPORTANT**: TypeScript strict mode enabled
**RECOMMENDED**: JSDoc on public functions
```
## Structural Anti-Patterns
### Circular Imports
```
CLAUDE.md -> @a.md -> @b.md -> @CLAUDE.md # Infinite loop
```
**Fix**: Flatten structure, avoid circular references
### Deep Nesting
```
CLAUDE.md -> @a.md -> @b.md -> @c.md -> @d.md -> @e.md # 5 hops max!
```
**Fix**: Maximum 3 levels recommended, 5 is hard limit
### Monolithic Files
```markdown
# BAD - 800 lines in one file
[Everything crammed together]
```
**Fix**: Split into imports by category
```markdown
# GOOD
@standards/typescript.md
@standards/testing.md
@patterns/api.md
```
## Detection Commands
```bash
# Check for secrets
grep -rE "password|secret|token|api_key" CLAUDE.md
# Check file length
wc -l CLAUDE.md # Should be < 300
# Check for broken imports
grep "^@" CLAUDE.md | while read import; do
path="${import#@}"
[ ! -f "$path" ] && echo "Broken: $import"
done
# Check for vague words
grep -iE "good|clean|proper|best|appropriate" CLAUDE.md
```

691
skills/claude-md-auditor/reference/anti_patterns.md Normal file
View File

@@ -0,0 +1,691 @@
# CLAUDE.md Anti-Patterns and Common Mistakes
> **Purpose**: Catalog of common mistakes, violations, and anti-patterns to avoid when creating CLAUDE.md files
This document identifies problematic patterns frequently found in CLAUDE.md files, explains why they're problematic, and provides better alternatives.
---
## Critical Violations (Security & Safety)
### 🚨 CRITICAL-01: Secrets in Memory Files
#### Problem
```markdown
# CLAUDE.md
## API Configuration
- API Key: sk-1234567890abcdefghijklmnop
- Database Password: MySecretPassword123
- AWS Secret: AKIAIOSFODNN7EXAMPLE
```
#### Why It's Dangerous
- ❌ CLAUDE.md files are typically committed to source control
- ❌ Exposes credentials to entire team and git history
- ❌ Can leak through PR comments, logs, or backups
- ❌ Violates security best practices
#### Correct Approach
```markdown
# CLAUDE.md
## API Configuration
- API keys stored in: .env (see .env.example for template)
- Database credentials: Use AWS Secrets Manager
- AWS credentials: Use IAM roles, never hardcode
## Environment Variables Required
- API_KEY (get from team lead)
- DB_PASSWORD (from 1Password vault)
- AWS_REGION (default: us-east-1)
```
**Severity**: CRITICAL
**Action**: Immediate removal + git history cleanup + key rotation
---
### 🚨 CRITICAL-02: Exposed Internal URLs/IPs
#### Problem
```markdown
## Production Servers
- Production Database: postgres://admin:pass@10.0.1.42:5432/proddb
- Internal API: https://internal-api.company.net/v1
- Admin Panel: https://admin.company.net (password: admin123)
```
#### Why It's Dangerous
- ❌ Exposes internal infrastructure
- ❌ Provides attack surface information
- ❌ May violate security policies
#### Correct Approach
```markdown
## Production Access
- Database: Use connection string from AWS Parameter Store
- API: See deployment documentation (requires VPN)
- Admin Panel: Contact DevOps for access (SSO required)
```
**Severity**: CRITICAL
**Action**: Remove immediately + security review
---
## High-Severity Issues
### ⚠️ HIGH-01: Generic Programming Advice
#### Problem
```markdown
## React Best Practices
React is a JavaScript library for building user interfaces. It was created
by Facebook in 2013. React uses a virtual DOM for efficient updates.
### What is a Component?
A component is a reusable piece of UI. Components can be class-based or
functional. Functional components are preferred in modern React...
[200 lines of React documentation]
```
#### Why It's Problematic
- ❌ Wastes context window space
- ❌ Claude already knows this information
- ❌ Not project-specific
- ❌ Duplicates official documentation
#### Correct Approach
```markdown
## React Standards (Project-Specific)
- Use functional components only (no class components)
- Custom hooks in: /src/hooks
- Component co-location pattern: Component + test + styles in same directory
- Props interface naming: [ComponentName]Props
Example:
/src/features/auth/LoginForm/
├── LoginForm.tsx
├── LoginForm.test.tsx
├── LoginForm.styles.ts
└── index.ts
```
**Severity**: HIGH
**Action**: Remove generic content, keep only project-specific standards
---
### ⚠️ HIGH-02: Excessive Verbosity
#### Problem
```markdown
# CLAUDE.md (1,200 lines)
## Introduction
Welcome to our project. This document contains comprehensive information...
[50 lines of introduction]
## History
This project started in 2019 when our founder...
[100 lines of history]
## Git Basics
To use git, first you need to understand version control...
[200 lines of git tutorial]
## TypeScript Fundamentals
TypeScript is a typed superset of JavaScript...
[300 lines of TypeScript basics]
[500 more lines of generic information]
```
#### Why It's Problematic
- ❌ Consumes excessive context (> 18,000 tokens ≈ 9% of 200K window)
- ❌ "Lost in the middle" degradation
- ❌ Difficult to maintain
- ❌ Hard to find relevant information
#### Correct Approach
```markdown
# CLAUDE.md (250 lines)
## Project: MyApp
Enterprise CRM built with React + TypeScript + PostgreSQL
## CRITICAL STANDARDS
[20 lines of must-follow rules]
## Architecture
[30 lines of project-specific architecture]
## Development Workflow
[40 lines of team process]
## Code Standards
[50 lines of project-specific rules]
## Common Tasks
[40 lines of commands and workflows]
## Detailed Documentation (Imports)
@docs/architecture.md
@docs/git-workflow.md
@docs/typescript-conventions.md
```
**Severity**: HIGH
**Action**: Reduce to < 300 lines, use imports for detailed docs
---
### ⚠️ HIGH-03: Vague or Ambiguous Instructions
#### Problem
```markdown
## Code Quality
- Write good code
- Make it clean
- Follow best practices
- Be consistent
- Keep it simple
- Don't be clever
```
#### Why It's Problematic
- ❌ Not actionable
- ❌ Subjective interpretation
- ❌ Doesn't provide measurable criteria
- ❌ Claude won't know what "good" means in your context
#### Correct Approach
```markdown
## Code Quality Standards (Measurable)
- Function length: Maximum 50 lines (warning) / 100 lines (error)
- Cyclomatic complexity: Maximum 10 (warning) / 20 (error)
- Test coverage: Minimum 80% for new code
- No `console.log` in src/ directory (use /src/lib/logger.ts)
- No `any` types (use `unknown` if type truly unknown)
- TypeScript strict mode: Enabled (no opt-outs)
```
**Severity**: HIGH
**Action**: Replace vague advice with specific, measurable standards
---
## Medium-Severity Issues
### ⚠️ MEDIUM-01: Outdated Information
#### Problem
```markdown
## Build Process
- Use Webpack 4 for bundling
- Node 12 required
- Run tests with Jest 25
## Deployment
- Deploy to Heroku using git push
- Use MongoDB 3.6
```
#### Why It's Problematic
- ❌ Misleads developers
- ❌ May cause build failures
- ❌ Indicates unmaintained documentation
- ❌ Conflicts with actual setup
#### Correct Approach
```markdown
## Build Process (Updated 2025-10-26)
- Vite 5.0 for bundling (migrated from Webpack)
- Node 20 LTS required
- Run tests with Vitest 2.0
## Deployment (Updated 2025-10-26)
- Deploy to AWS ECS using GitHub Actions
- Use PostgreSQL 16
## Update History
- 2025-10-26: Migrated to Vite, PostgreSQL
- 2024-05-15: Upgraded to Node 20
```
**Severity**: MEDIUM
**Action**: Regular audits, include update dates
---
### ⚠️ MEDIUM-02: Duplicate or Conflicting Information
#### Problem
```markdown
## Code Style (Line 50)
- Use 2-space indentation
- Prefer single quotes
## TypeScript Standards (Line 150)
- Use 4-space indentation
- Prefer double quotes
## React Guidelines (Line 250)
- Indentation: Use tabs
- Quotes: Use backticks for strings
```
#### Why It's Problematic
- ❌ Conflicting instructions
- ❌ Claude may follow the wrong standard
- ❌ Team confusion
- ❌ Indicates poor maintenance
#### Correct Approach
```markdown
## Code Style (Single Source of Truth)
### Formatting (Enforced by Prettier)
- Indentation: 2 spaces
- Quotes: Single quotes for strings, backticks for templates
- Line length: 100 characters
- Trailing commas: Always
### Config Location
- .prettierrc.json (root directory)
- Auto-format on save (VS Code: editor.formatOnSave)
```
**Severity**: MEDIUM
**Action**: Consolidate all style rules in one section
---
### ⚠️ MEDIUM-03: Missing Context for Standards
#### Problem
```markdown
## Standards
- Never use `useState` hook
- All API calls must use POST method
- No files over 200 lines
- Must use Redux for all state
```
#### Why It's Problematic
- ❌ Standards seem arbitrary without context
- ❌ May be outdated after architecture changes
- ❌ Hard to question or update
- ❌ New team members don't understand "why"
#### Correct Approach
```markdown
## State Management Standards
### useState Hook (Avoid for Complex State)
- ❌ DON'T: Use useState for complex/shared state
- ✅ DO: Use useState for simple local UI state (toggles, input values)
- ✅ DO: Use Zustand for shared application state
- WHY: useState causes prop drilling; Zustand avoids this
### API Call Methods
- Use POST for: Mutations, large request bodies
- Use GET for: Queries, cached responses
- WHY: RESTful conventions, better caching
### File Length (Soft Limit: 200 Lines)
- Preference: Keep files under 200 lines
- Exception: Generated files, large data structures
- WHY: Maintainability, easier code review
```
**Severity**: MEDIUM
**Action**: Add context/rationale for standards
---
## Low-Severity Issues
### ⚠️ LOW-01: Poor Organization
#### Problem
```markdown
# CLAUDE.md
Random information...
## Testing
More random stuff...
### Security
Back to testing...
## API
### More Security
## Testing Again
```
#### Why It's Problematic
- ❌ Hard to navigate
- ❌ Information scattered
- ❌ Difficult to maintain
- ❌ Poor user experience
#### Correct Approach
```markdown
# Project Name
## 1. CRITICAL STANDARDS
[Must-follow rules]
## 2. PROJECT OVERVIEW
[Context and architecture]
## 3. DEVELOPMENT WORKFLOW
[Git, PRs, deployment]
## 4. CODE STANDARDS
[Language/framework specific]
## 5. TESTING REQUIREMENTS
[Coverage, strategies]
## 6. SECURITY REQUIREMENTS
[Authentication, data protection]
## 7. COMMON TASKS
[Commands, workflows]
## 8. REFERENCE
[File locations, links]
```
**Severity**: LOW
**Action**: Reorganize with clear hierarchy
---
### ⚠️ LOW-02: Broken Links and Paths
#### Problem
```markdown
## Documentation
- See architecture docs: /docs/arch.md (404)
- Import types from: /src/old-types/index.ts (moved)
- Run deploy script: ./scripts/deploy.sh (deleted)
```
#### Why It's Problematic
- ❌ Misleads developers
- ❌ Causes frustration
- ❌ Indicates stale documentation
#### Correct Approach
```markdown
## Documentation (Verified 2025-10-26)
- Architecture: /docs/architecture/system-design.md ✅
- Types: /src/types/index.ts ✅
- Deployment: npm run deploy (see package.json scripts) ✅
## Validation
Links verified: 2025-10-26
Next check: 2026-01-26
```
**Severity**: LOW
**Action**: Periodic validation, date stamps
---
### ⚠️ LOW-03: Inconsistent Formatting
#### Problem
```markdown
## Code Standards
some bullet points without dashes
* Others with asterisks
- Some with dashes
- Inconsistent indentation
* Mixed styles
Headers in Title Case
Headers in sentence case
Headers in SCREAMING CASE
```
#### Why It's Problematic
- ❌ Unprofessional appearance
- ❌ Harder to parse
- ❌ May affect rendering
- ❌ Poor user experience
#### Correct Approach
```markdown
## Code Standards
### Formatting Rules
- Consistent bullet style (dashes)
- 2-space indentation for nested lists
- Title Case for H2 headers
- Sentence case for H3 headers
### Example List
- First item
- Nested item A
- Nested item B
- Second item
- Nested item C
```
**Severity**: LOW
**Action**: Adopt consistent markdown style guide
---
## Structural Anti-Patterns
### 📋 STRUCTURE-01: No Section Hierarchy
#### Problem
```markdown
# CLAUDE.md
Everything at the top level
No organization
No hierarchy
Just a wall of text
```
#### Correct Approach
```markdown
# Project Name
## Section 1
### Subsection 1.1
### Subsection 1.2
## Section 2
### Subsection 2.1
```
---
### 📋 STRUCTURE-02: Circular Imports
#### Problem
```markdown
# CLAUDE.md
@docs/standards.md
# docs/standards.md
@docs/guidelines.md
# docs/guidelines.md
@CLAUDE.md
```
#### Correct Approach
- Maintain acyclic import graph
- Use unidirectional imports
- CLAUDE.md → detailed docs (not reverse)
---
### 📋 STRUCTURE-03: Deep Import Nesting
#### Problem
```markdown
# CLAUDE.md
@docs/level1.md
@docs/level2.md
@docs/level3.md
@docs/level4.md
@docs/level5.md
@docs/level6.md (exceeds 5-hop limit)
```
#### Correct Approach
- Maximum 5 import hops
- Flatten structure when possible
- Use fewer, comprehensive documents
---
## Detection and Prevention
### Automated Checks
```markdown
## Checklist for CLAUDE.md Quality
### Security (CRITICAL)
- [ ] No API keys, tokens, or passwords
- [ ] No database credentials
- [ ] No internal URLs or IPs
- [ ] No private keys
- [ ] Git history clean
### Content Quality (HIGH)
- [ ] No generic programming tutorials
- [ ] Under 300 lines (or using imports)
- [ ] Specific, actionable instructions
- [ ] No vague advice ("write good code")
- [ ] Project-specific context
### Maintainability (MEDIUM)
- [ ] No outdated information
- [ ] No conflicting instructions
- [ ] Context provided for standards
- [ ] All links functional
- [ ] Last update date present
### Structure (LOW)
- [ ] Clear section hierarchy
- [ ] Consistent formatting
- [ ] No circular imports
- [ ] Import depth ≤ 5 hops
- [ ] Logical organization
```
---
## Anti-Pattern Summary Table
| ID | Anti-Pattern | Severity | Impact | Fix Effort |
|----|-------------|----------|---------|------------|
| CRITICAL-01 | Secrets in memory files | 🚨 CRITICAL | Security breach | Immediate |
| CRITICAL-02 | Exposed internal infrastructure | 🚨 CRITICAL | Security risk | Immediate |
| HIGH-01 | Generic programming advice | ⚠️ HIGH | Context waste | High |
| HIGH-02 | Excessive verbosity | ⚠️ HIGH | Context waste | High |
| HIGH-03 | Vague instructions | ⚠️ HIGH | Ineffective | Medium |
| MEDIUM-01 | Outdated information | ⚠️ MEDIUM | Misleading | Medium |
| MEDIUM-02 | Duplicate/conflicting info | ⚠️ MEDIUM | Confusion | Medium |
| MEDIUM-03 | Missing context for standards | ⚠️ MEDIUM | Poor adoption | Low |
| LOW-01 | Poor organization | ⚠️ LOW | UX issue | Low |
| LOW-02 | Broken links/paths | ⚠️ LOW | Frustration | Low |
| LOW-03 | Inconsistent formatting | ⚠️ LOW | Unprofessional | Low |
| STRUCTURE-01 | No section hierarchy | 📋 STRUCTURAL | Poor navigation | Low |
| STRUCTURE-02 | Circular imports | 📋 STRUCTURAL | Load failure | Medium |
| STRUCTURE-03 | Deep import nesting | 📋 STRUCTURAL | Complexity | Low |
---
## Real-World Examples
### Example 1: The "Documentation Dump"
**Before** (Anti-Pattern):
```markdown
# CLAUDE.md (2,500 lines)
[Complete React documentation copy-pasted]
[Complete TypeScript handbook]
[Complete git tutorial]
[Complete testing library docs]
```
**After** (Fixed):
```markdown
# CLAUDE.md (200 lines)
## Project-Specific React Standards
- Functional components only
- Co-location pattern
- Custom hooks in /src/hooks
## TypeScript Standards
- Strict mode enabled
- No `any` types
- Explicit return types
@docs/react-architecture.md
@docs/typescript-conventions.md
```
---
### Example 2: The "Secret Leaker"
**Before** (Anti-Pattern):
```markdown
## API Configuration
API_KEY=sk-1234567890
DB_PASSWORD=MySecret123
```
**After** (Fixed):
```markdown
## API Configuration
- Use .env file (see .env.example)
- API_KEY: Get from team lead
- DB_PASSWORD: In 1Password vault
```
---
### Example 3: The "Vague Advisor"
**Before** (Anti-Pattern):
```markdown
## Standards
- Write clean code
- Be professional
- Follow best practices
```
**After** (Fixed):
```markdown
## Code Quality Standards
- Max function length: 50 lines
- Max cyclomatic complexity: 10
- Min test coverage: 80%
- No console.log in production
```
---
**Document Version**: 1.0.0
**Last Updated**: 2025-10-26
**Purpose**: Anti-pattern catalog for CLAUDE.md auditing
**Status**: Comprehensive reference for audit validation

121
skills/claude-md-auditor/reference/best-practices.md Normal file
View File

@@ -0,0 +1,121 @@
# Community Best Practices
Field-tested recommendations from practitioners. These are suggestions, not requirements.
## Size Recommendations
### Target Range
- **Optimal**: 100-300 lines
- **Acceptable**: Up to 500 lines with @imports
- **Warning**: > 500 lines indicates need for splitting
### Token Budget
- **Recommended**: < 3,000 tokens
- **Maximum**: 5,000 tokens before significant context cost
- **Measure**: Use `wc -w` as rough estimate (tokens ≈ words × 1.3)
## Content Organization
### 80/20 Rule
- 80% essential, immediately-applicable guidance
- 20% supporting context and edge cases
### Section Priority
1. **Critical** (MUST follow): Security, breaking patterns
2. **Important** (SHOULD follow): Core standards, conventions
3. **Recommended** (COULD follow): Optimizations, preferences
### Header Hierarchy
```markdown
# Project Name
## Build Commands (most used first)
## Architecture Overview
## Coding Standards
## Testing Requirements
## Common Patterns
```
## Import Strategies
### When to Import
- Detailed documentation > 50 lines
- Shared standards across projects
- Frequently updated content
### Import Organization
```markdown
## Core Standards
@standards/typescript.md
@standards/testing.md
## Project-Specific
@docs/architecture.md
@docs/api-patterns.md
```
## Version Control Practices
### Commit Discipline
- Commit CLAUDE.md changes separately
- Use descriptive messages: "docs: update testing standards in CLAUDE.md"
- Review in PRs like any other code
### Change Tracking
```markdown
---
**Last Updated**: 2025-10-26
**Version**: 1.2.0
**Changes**: Added memory retrieval patterns
---
```
## Maintenance Cadence
### Regular Reviews
- **Weekly**: Check for outdated commands
- **Monthly**: Review against actual practices
- **Quarterly**: Full audit and optimization
### Staleness Indicators
- Commands that no longer work
- References to removed files
- Outdated dependency versions
- Patterns no longer used
## Multi-Project Strategies
### Shared Base
```
~/.claude/CLAUDE.md # Personal defaults
~/.claude/standards/ # Shared standards
├── typescript.md
├── testing.md
└── security.md
```
### Project Override
```markdown
# Project CLAUDE.md
## Override user defaults
@~/.claude/standards/typescript.md
## Project-specific additions
...
```
## Anti-Pattern Avoidance
### Don't Duplicate
- If it's in official docs, don't repeat it
- If it's in your codebase comments, reference don't copy
### Don't Over-Specify
- Trust Claude's knowledge
- Focus on YOUR project's quirks
- Specify deviations from standards, not standards themselves
### Don't Neglect Updates
- Outdated CLAUDE.md is worse than none
- Schedule regular maintenance
- Delete rather than leave stale

544
skills/claude-md-auditor/reference/best_practices.md Normal file
View File

@@ -0,0 +1,544 @@
# Community Best Practices for CLAUDE.md Configuration
> **Source**: Community wisdom, practitioner experience, and field-tested recommendations (not official Anthropic guidance)
This document contains best practices derived from the Claude Code community, real-world usage, and practical experience. While not officially mandated by Anthropic, these practices have proven effective across many projects.
---
## Size Recommendations
### Target Length: 100-300 Lines
**Rationale**:
- Represents approximately 1,500-4,500 tokens
- Accounts for roughly 1-2.5% of a 200K context window
- Small enough to avoid attention issues
- Large enough to be comprehensive
- Balances detail with context efficiency
**Community Consensus**:
- ✅ **Under 100 lines**: Potentially too sparse, may miss important context
- ✅ **100-300 lines**: Sweet spot for most projects
- ⚠️ **300-500 lines**: Acceptable for complex projects, but consider splitting
- ❌ **Over 500 lines**: Too verbose, consider using imports
**Note**: This is community-derived guidance, not an official Anthropic recommendation. Official guidance simply says "keep them lean."
### Token Budget Analysis
| CLAUDE.md Size | Tokens | % of 200K Context | Recommendation |
|----------------|--------|-------------------|----------------|
| 50 lines | ~750 | 0.4% | Too sparse |
| 100 lines | ~1,500 | 0.75% | Minimum viable |
| 200 lines | ~3,000 | 1.5% | Ideal |
| 300 lines | ~4,500 | 2.25% | Maximum recommended |
| 500 lines | ~7,500 | 3.75% | Consider splitting |
| 1000 lines | ~15,000 | 7.5% | Excessive |
---
## Content Organization
### Priority Positioning Strategy
Based on LLM research (not official Anthropic guidance), organize content by priority:
#### TOP Section (Highest Attention)
Place **mission-critical** standards here:
```markdown
# CRITICAL STANDARDS
## Security Requirements (MUST FOLLOW)
- Never commit secrets or API keys
- All authentication must use MFA
- Input validation required for all user inputs
## Code Quality Gates (MUST PASS)
- TypeScript strict mode enforced
- 80% test coverage minimum before PR merge
- No console.log in production code
```
#### MIDDLE Section (Lower Attention)
Place **nice-to-have** context and supporting information:
```markdown
## Nice-to-Have Practices
- Prefer functional components over class components
- Use meaningful variable names
- Keep functions under 50 lines when possible
```
#### BOTTOM Section (High Attention)
Place **important reference** information:
```markdown
## Key Commands (REFERENCE)
- npm run build: Build production bundle
- npm test: Run test suite
- npm run lint: Run linter
## Critical File Locations
- Config: /config/app.config.ts
- Types: /src/types/global.d.ts
```
**Rationale**: "Lost in the middle" research shows LLMs have U-shaped attention curves, with highest attention at the start and end of context.
---
## The 80/20 Rule for CLAUDE.md
### 80% Essential, 20% Supporting
**Essential (80%)** - Must-have information:
- Project-specific development standards
- Security requirements
- Testing requirements
- Critical file locations
- Common commands
- Non-obvious architectural decisions
**Supporting (20%)** - Nice-to-have context:
- Historical context
- Optional style preferences
- General best practices
- Team conventions
### Example Structure (200-line CLAUDE.md)
```markdown
# Project: MyApp
## CRITICAL STANDARDS (30 lines)
- Security requirements
- Must-follow coding standards
- Quality gates
## PROJECT CONTEXT (40 lines)
- Tech stack overview
- Architecture patterns
- Key dependencies
## DEVELOPMENT WORKFLOW (40 lines)
- Git workflow
- Testing requirements
- Deployment process
## CODE STANDARDS (30 lines)
- Language-specific rules
- Framework conventions
- Naming patterns
## COMMON ISSUES & SOLUTIONS (20 lines)
- Known gotchas
- Troubleshooting tips
## REFERENCE (40 lines)
- Common commands
- File locations
- Useful links
```
---
## Import Strategy
### When to Use Imports
#### Use Imports For:
- ✅ Lengthy architecture documentation (> 100 lines)
- ✅ Detailed API documentation
- ✅ Testing strategy documentation
- ✅ Deployment procedures
- ✅ Historical ADRs (Architecture Decision Records)
#### Keep in Main CLAUDE.md:
- ✅ Critical standards that must always be in context
- ✅ Common commands and workflows
- ✅ Project overview and tech stack
- ✅ Essential file locations
### Example Import Structure
```markdown
# CLAUDE.md (main file - 200 lines)
## Critical Standards (always in context)
- Security requirements
- Quality gates
- Testing requirements
## Project Overview
- Tech stack summary
- Architecture pattern
## Import Detailed Documentation
@docs/architecture/system-design.md
@docs/testing/testing-strategy.md
@docs/deployment/deployment-guide.md
@docs/api/api-documentation.md
@~/.claude/personal-preferences.md
```
**Benefits**:
- Keeps main CLAUDE.md lean
- Loads additional context on demand
- Easier to maintain separate documents
- Can reference external documentation
---
## Category Organization
### Recommended Section Structure
#### 1. Header & Overview (5-10 lines)
```markdown
# Project Name
Brief description of the project
Tech stack: React, TypeScript, Node.js, PostgreSQL
```
#### 2. Critical Standards (20-30 lines)
```markdown
## MUST-FOLLOW STANDARDS
- Security requirements
- Quality gates
- Non-negotiable practices
```
#### 3. Architecture (20-40 lines)
```markdown
## Architecture
- Patterns used
- Key decisions
- Module structure
```
#### 4. Development Workflow (20-30 lines)
```markdown
## Development Workflow
- Git branching strategy
- Commit conventions
- PR requirements
```
#### 5. Code Standards (30-50 lines)
```markdown
## Code Standards
- Language-specific rules
- Framework conventions
- Testing requirements
```
#### 6. Common Tasks (20-30 lines)
```markdown
## Common Tasks
- Build commands
- Test commands
- Deployment commands
```
#### 7. Reference Information (20-40 lines)
```markdown
## Reference
- File locations
- Environment setup
- Troubleshooting
```
---
## Version Control Best Practices
### Project-Level CLAUDE.md
#### Commit to Source Control
- ✅ **DO** commit `./CLAUDE.md` or `./.claude/CLAUDE.md` to git
- ✅ **DO** include in code reviews
- ✅ **DO** update alongside code changes
- ✅ **DO** document major changes in commit messages
#### Review Standards
```markdown
## PR Checklist for CLAUDE.md Changes
- [ ] Removed outdated information
- [ ] Added context for new features/patterns
- [ ] Updated commands if changed
- [ ] Verified no secrets committed
- [ ] Kept file under 300 lines
- [ ] Used imports for lengthy docs
```
### User-Level CLAUDE.md
#### Keep Personal Preferences Separate
- ✅ **DO** use `~/.claude/CLAUDE.md` for personal preferences
- ✅ **DO NOT** commit user-level files to project repos
- ✅ **DO** share useful patterns with team (move to project-level)
---
## Naming Conventions
### Section Headers
Use clear, action-oriented headers:
#### Good Examples:
```markdown
## MUST FOLLOW: Security Requirements
## How to Build and Deploy
## Common Troubleshooting Solutions
## File Structure Overview
```
#### Avoid:
```markdown
## Miscellaneous
## Other
## Notes
## TODO
```
### Emphasis Techniques
Use consistent emphasis for priority levels:
```markdown
## CRITICAL: [thing that must never be violated]
## IMPORTANT: [thing that should be followed]
## RECOMMENDED: [thing that's nice to have]
## REFERENCE: [lookup information]
```
---
## Maintenance Cadence
### When to Update CLAUDE.md
#### Update Immediately:
- New critical security requirements
- Major architecture changes
- New must-follow standards
- Breaking changes in workflow
#### Update During Sprint Planning:
- New features that introduce patterns
- Updated dependencies with new conventions
- Deprecated practices to remove
#### Update Quarterly:
- Remove outdated information
- Consolidate duplicate guidance
- Optimize length and structure
- Review for clarity
### Staleness Detection
Signs your CLAUDE.md needs updating:
- ⚠️ References to deprecated tools or frameworks
- ⚠️ Outdated command examples
- ⚠️ Broken file paths
- ⚠️ Conflicting instructions
- ⚠️ Information duplicated in multiple sections
---
## Multi-Project Strategies
### User-Level Patterns
For developers working across multiple projects:
```markdown
# ~/.claude/CLAUDE.md
## Personal Development Standards
- TDD approach required
- Write tests before implementation
- No console.log statements
## Preferred Tools
- Use Vitest for testing
- Use ESLint with recommended config
- Use Prettier with 2-space indent
## Communication Style
- Be concise and direct
- Provide context for decisions
- Flag breaking changes prominently
```
### Project-Level Focus
Each project's CLAUDE.md should:
- ✅ Override user-level preferences where needed
- ✅ Add project-specific context
- ✅ Define team-wide standards
- ❌ Avoid duplicating user-level preferences
---
## Testing Your CLAUDE.md
### Validation Checklist
#### Structure Test
- [ ] Under 300 lines (or using imports)
- [ ] Clear section headers
- [ ] Bullet points for lists
- [ ] Code blocks formatted correctly
#### Content Test
- [ ] No secrets or sensitive information
- [ ] Specific instructions (not generic)
- [ ] Project-specific context
- [ ] No outdated information
- [ ] No broken file paths
#### Effectiveness Test
- [ ] Start a new Claude Code session
- [ ] Verify standards are followed without re-stating
- [ ] Test that Claude references CLAUDE.md correctly
- [ ] Confirm critical standards enforced
---
## Advanced Techniques
### Conditional Instructions
Use clear conditions for context-specific guidance:
```markdown
## Testing Standards
### For New Features
- Write tests BEFORE implementation (TDD)
- Integration tests required for API endpoints
- Accessibility tests for UI components
### For Bug Fixes
- Add regression test that would have caught the bug
- Update existing tests if behavior changed
- Ensure fix doesn't break other tests
```
### Progressive Disclosure
Organize from high-level to detailed:
```markdown
## Architecture
### Overview
- Clean Architecture pattern
- Feature-based modules
- Hexagonal architecture for API layer
### Module Structure
├── features/ # Feature modules
│ ├── auth/ # Authentication feature
│ ├── dashboard/ # Dashboard feature
│ └── settings/ # Settings feature
├── lib/ # Shared libraries
└── infrastructure/ # Infrastructure layer
### Detailed Patterns
(Include or import detailed documentation)
```
---
## Anti-Patterns to Avoid
### Common Mistakes
#### ❌ Copy-Paste from Documentation
```markdown
## React Hooks
React Hooks allow you to use state and other React features
without writing a class...
[200 lines of React documentation]
```
**Problem**: Claude already knows this. Wastes context.
#### ❌ Excessive Detail
```markdown
## Git Workflow
1. First, open your terminal
2. Navigate to the project directory using cd
3. Type git status to see your changes
4. Type git add to stage files...
[50 lines of basic git commands]
```
**Problem**: Claude knows git. Be specific about YOUR workflow only.
#### ❌ Vague Instructions
```markdown
## Code Quality
- Write good code
- Make it clean
- Follow best practices
```
**Problem**: Not actionable. Be specific.
#### ✅ Better Approach
```markdown
## Code Quality Standards
- TypeScript strict mode: no `any` types
- Function length: max 50 lines
- Cyclomatic complexity: max 10
- Test coverage: minimum 80%
- No console.log in src/ directory (use logger instead)
```
---
## Success Metrics
### How to Know Your CLAUDE.md is Effective
#### Good Signs:
- ✅ Claude consistently follows your standards without prompting
- ✅ New team members onboard faster
- ✅ Fewer "why did Claude do that?" moments
- ✅ Code reviews show consistent patterns
- ✅ Standards violations caught early
#### Bad Signs:
- ❌ Constantly repeating yourself in prompts
- ❌ Claude ignores your standards
- ❌ Instructions are ambiguous
- ❌ Team members confused about standards
- ❌ CLAUDE.md conflicts with actual practices
---
## Real-World Examples
### Startup/Small Team (150 lines)
- Focus on essential standards
- Include critical workflows
- Prioritize speed over perfection
### Enterprise Project (250 lines + imports)
- Comprehensive security standards
- Detailed compliance requirements
- Links to additional documentation
- Multi-environment considerations
### Open Source Project (200 lines)
- Contribution guidelines
- Code review process
- Community standards
- Documentation requirements
---
**Document Version**: 1.0.0
**Last Updated**: 2025-10-26
**Status**: Community best practices (not official Anthropic guidance)
**Confidence**: Based on field experience and practitioner reports

272
skills/claude-md-auditor/reference/ci-cd-integration.md Normal file
View File

@@ -0,0 +1,272 @@
# CI/CD Integration Examples
Ready-to-use configurations for automated CLAUDE.md validation.
## Pre-Commit Hook
### Basic Validation
```bash
#!/bin/bash
# .git/hooks/pre-commit
if git diff --cached --name-only | grep -q "CLAUDE.md"; then
echo "Validating CLAUDE.md..."
FILE=$(git diff --cached --name-only | grep "CLAUDE.md" | head -1)
# Check file length
LINES=$(wc -l < "$FILE")
if [ "$LINES" -gt 500 ]; then
echo "ERROR: CLAUDE.md is $LINES lines (max 500)"
exit 1
fi
# Check for secrets
if grep -qE "password|secret|token|api_key|-----BEGIN" "$FILE"; then
echo "ERROR: Potential secrets detected in CLAUDE.md"
echo "Run: grep -nE 'password|secret|token|api_key' $FILE"
exit 1
fi
# Check for broken imports
grep "^@" "$FILE" | while read -r import; do
path="${import#@}"
if [ ! -f "$path" ]; then
echo "ERROR: Broken import: $import"
exit 1
fi
done
echo "CLAUDE.md validation passed"
fi
```
### Installation
```bash
chmod +x .git/hooks/pre-commit
```
## GitHub Actions
### Basic Workflow
```yaml
# .github/workflows/claude-md-audit.yml
name: CLAUDE.md Audit
on:
pull_request:
paths:
- '**/CLAUDE.md'
- '**/.claude/CLAUDE.md'
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Find CLAUDE.md files
id: find
run: |
files=$(find . -name "CLAUDE.md" -type f)
echo "files=$files" >> $GITHUB_OUTPUT
- name: Check file lengths
run: |
for file in ${{ steps.find.outputs.files }}; do
lines=$(wc -l < "$file")
if [ "$lines" -gt 500 ]; then
echo "::error file=$file::File is $lines lines (max 500)"
exit 1
fi
echo "OK: $file ($lines lines)"
done
- name: Check for secrets
run: |
for file in ${{ steps.find.outputs.files }}; do
if grep -qE "password|secret|token|api_key|-----BEGIN" "$file"; then
echo "::error file=$file::Potential secrets detected"
grep -nE "password|secret|token|api_key" "$file" || true
exit 1
fi
done
echo "No secrets detected"
- name: Check imports
run: |
for file in ${{ steps.find.outputs.files }}; do
dir=$(dirname "$file")
grep "^@" "$file" | while read -r import; do
path="${import#@}"
if [ ! -f "$dir/$path" ]; then
echo "::error file=$file::Broken import: $import"
exit 1
fi
done
done
echo "All imports valid"
```
### With PR Comment
```yaml
- name: Post audit summary
if: always()
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
// Collect results
const results = {
files: 0,
passed: 0,
failed: 0,
warnings: []
};
// Post comment
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `## CLAUDE.md Audit Results
- Files checked: ${results.files}
- Passed: ${results.passed}
- Failed: ${results.failed}
${results.warnings.length > 0 ? '### Warnings\n' + results.warnings.join('\n') : ''}
`
});
```
## VS Code Task
### tasks.json
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "Audit CLAUDE.md",
"type": "shell",
"command": "bash",
"args": [
"-c",
"echo 'Auditing CLAUDE.md...' && wc -l CLAUDE.md && grep -c '^##' CLAUDE.md && echo 'Done'"
],
"group": "test",
"presentation": {
"reveal": "always",
"panel": "new"
},
"problemMatcher": []
},
{
"label": "Check CLAUDE.md secrets",
"type": "shell",
"command": "bash",
"args": [
"-c",
"if grep -qE 'password|secret|token|api_key' CLAUDE.md; then echo 'WARNING: Potential secrets found:' && grep -nE 'password|secret|token|api_key' CLAUDE.md; else echo 'No secrets detected'; fi"
],
"group": "test",
"problemMatcher": []
}
]
}
```
### Keyboard Shortcut
```json
// keybindings.json
{
"key": "ctrl+shift+a",
"command": "workbench.action.tasks.runTask",
"args": "Audit CLAUDE.md"
}
```
## Husky + lint-staged
### Installation
```bash
npm install -D husky lint-staged
npx husky init
```
### package.json
```json
{
"lint-staged": {
"**/CLAUDE.md": [
"bash -c 'wc -l \"$0\" | awk \"{if (\\$1 > 500) {print \\\"ERROR: \\\" \\$1 \\\" lines\\\"; exit 1}}\"'",
"bash -c 'grep -qE \"password|secret|token\" \"$0\" && exit 1 || true'"
]
}
}
```
### .husky/pre-commit
```bash
npx lint-staged
```
## GitLab CI
```yaml
# .gitlab-ci.yml
claude-md-audit:
stage: test
rules:
- changes:
- "**/CLAUDE.md"
script:
- |
for file in $(find . -name "CLAUDE.md"); do
echo "Checking $file"
lines=$(wc -l < "$file")
if [ "$lines" -gt 500 ]; then
echo "ERROR: $file is $lines lines"
exit 1
fi
done
- echo "CLAUDE.md audit passed"
```
## Makefile Target
```makefile
.PHONY: audit-claude-md
audit-claude-md:
@echo "Auditing CLAUDE.md files..."
@find . -name "CLAUDE.md" -exec sh -c '\
lines=$$(wc -l < "{}"); \
if [ "$$lines" -gt 500 ]; then \
echo "ERROR: {} is $$lines lines"; \
exit 1; \
fi; \
echo "OK: {} ($$lines lines)"' \;
@echo "Checking for secrets..."
@! grep -rE "password|secret|token|api_key" --include="CLAUDE.md" . || \
(echo "ERROR: Secrets detected" && exit 1)
@echo "Audit complete"
```
## Best Practices
1. **Fail fast**: Check secrets before anything else
2. **Clear errors**: Include file path and line numbers
3. **PR feedback**: Post results as comments
4. **Gradual adoption**: Start with warnings, then enforce
5. **Skip when needed**: Allow `[skip audit]` in commit message

92
skills/claude-md-auditor/reference/official-guidance.md Normal file
View File

@@ -0,0 +1,92 @@
# Official Anthropic Guidance
Complete compilation of official documentation from docs.claude.com (verified 2025-10-26).
## Memory Hierarchy
**Precedence Order** (highest to lowest):
1. Enterprise policy (managed by admins)
2. Project instructions (.claude/CLAUDE.md)
3. User instructions (~/.claude/CLAUDE.md)
**Loading Behavior**:
- All tiers loaded and merged
- Higher precedence overrides conflicts
- Enterprise can restrict user/project capabilities
## File Locations
| Tier | Location | Scope |
|------|----------|-------|
| Enterprise | Managed centrally | Organization-wide |
| Project | `.claude/CLAUDE.md` or `CLAUDE.md` in project root | Per-repository |
| User | `~/.claude/CLAUDE.md` | All user sessions |
## Import Functionality
**Syntax**: `@path/to/file.md`
**Limitations**:
- Maximum 5 import hops
- Only markdown files
- Relative paths from CLAUDE.md location
- No circular imports
**Example**:
```markdown
## Coding Standards
@docs/coding-standards.md
## API Guidelines
@docs/api-guidelines.md
```
## Official Best Practices
### Keep Them Lean
- Avoid verbose documentation
- Focus on project-specific information
- Claude already knows general programming
### Be Specific
- Concrete examples over vague guidance
- Actual commands, not descriptions
- Real patterns from your codebase
### Use Structure
- Clear markdown headers
- Organized sections
- Priority markers for critical items
## What NOT to Include
### Security Risks
- API keys, tokens, secrets
- Database credentials
- Private keys
- Internal infrastructure details
### Redundant Content
- Generic programming best practices
- Language documentation
- Framework tutorials
- Content Claude already knows
### Problematic Content
- Conflicting instructions
- Vague guidance ("write good code")
- Outdated information
## Validation Methods
### /memory Command
Shows what Claude currently has loaded from all CLAUDE.md files.
### /init Command
Generates or updates CLAUDE.md based on project analysis.
## Official Documentation Links
- Memory Files: https://docs.claude.com/en/docs/memory
- Best Practices: https://docs.claude.com/en/docs/claude-md-best-practices
- Import Syntax: https://docs.claude.com/en/docs/imports

368
skills/claude-md-auditor/reference/official_guidance.md Normal file
View File

@@ -0,0 +1,368 @@
# Official Anthropic Guidance for CLAUDE.md Configuration
> **Source**: Official Anthropic documentation from docs.claude.com (verified 2025-10-26)
This document compiles all official guidance from Anthropic for creating and maintaining CLAUDE.md memory files in Claude Code.
## Memory Hierarchy
### Three-Tier System
Claude Code uses a hierarchical memory system with clear precedence:
1. **Enterprise Policy Memory** (Highest Priority)
- **Locations**:
- macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`
- Linux: `/etc/claude-code/CLAUDE.md`
- Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md`
- **Purpose**: Organization-wide instructions managed by IT/DevOps
- **Access**: Typically managed centrally, not by individual developers
2. **Project Memory** (Medium Priority)
- **Locations**:
- `./CLAUDE.md` (project root)
- `./.claude/CLAUDE.md` (hidden directory in project root)
- **Purpose**: Team-shared project instructions committed to source control
- **Access**: All team members can edit, checked into git
3. **User Memory** (Lowest Priority)
- **Location**: `~/.claude/CLAUDE.md`
- **Purpose**: Personal preferences that apply across all projects
- **Access**: Individual developer only
### Precedence Rules
- **Higher-level memories load first** and provide a foundation that more specific memories build upon
- **Settings are merged**: More specific settings add to or override broader ones
- **Recursive discovery**: Claude Code starts in the current working directory and recurses up to (but not including) the root directory, reading any CLAUDE.md files it finds
**Source**: [Memory Management Documentation](https://docs.claude.com/en/docs/claude-code/memory)
---
## File Loading Behavior
### Launch-Time Loading
- **CLAUDE.md files are loaded at startup** when Claude Code is launched
- Memory files in **parent directories** are loaded at startup
- Memories in **subdirectories** load dynamically when Claude accesses files in those locations
- This loading happens **separately from conversation history**
**Source**: [Memory Lookup Documentation](https://docs.claude.com/en/docs/claude-code/memory)
---
## Import Functionality
### Syntax
CLAUDE.md files can import additional files using the `@path/to/import` syntax:
```markdown
# Project Standards
@docs/coding-standards.md
@docs/testing-guidelines.md
@~/.claude/my-personal-preferences.md
```
### Limitations
- **Maximum import depth**: 5 hops
- **Prevents circular imports**: Claude Code detects and prevents infinite loops
- **Purpose**: Allows you to include documentation without bloating the main memory file
**Source**: [Memory Imports Documentation](https://docs.claude.com/en/docs/claude-code/memory)
---
## Official Best Practices
### Keep Memory Files Lean
> "Memory files are read at the beginning of each coding session, which is why it's important to keep them lean as they take up context window space."
**Key Principle**: Concise and human-readable
### Be Specific
- ✅ **Good**: "Use 2-space indentation"
- ❌ **Bad**: "Format code properly"
**Rationale**: Specific instructions are more actionable and less ambiguous
### Use Structure to Organize
- **Format**: Each individual memory as a bullet point
- **Group**: Related memories under descriptive headings
- **Example**:
```markdown
## Code Style
- Use 2-space indentation
- Use ES modules syntax
- Destructure imports when possible
## Testing
- Run tests with: npm test
- Minimum 80% coverage required
```
### Strike a Balance
- Avoid wasting tokens on too many details
- Don't include generic information Claude already understands
- Focus on project-specific context and requirements
**Source**: [Memory Best Practices Documentation](https://docs.claude.com/en/docs/claude-code/memory), [Best Practices Blog](https://www.anthropic.com/engineering/claude-code-best-practices)
---
## What NOT to Include
### ❌ Basic Programming Concepts
Claude already understands fundamental programming principles. Don't include:
- Language syntax basics
- Common design patterns
- Standard library documentation
- General programming advice
### ❌ Information Covered in Official Documentation
Don't duplicate content from official docs that Claude has been trained on:
- Framework documentation (React, Vue, etc.)
- Language specifications (JavaScript, TypeScript, etc.)
- Standard tool documentation (npm, git, etc.)
### ❌ Changing Details
Avoid information that changes frequently:
- Current sprint tasks (use issue trackers instead)
- Temporary project status
- Time-sensitive information
- Specific bug references
### ❌ Secret Information
**Never include**:
- API keys or tokens
- Passwords or credentials
- Private keys
- Connection strings
- Any sensitive information
**Note**: .env files should be in .gitignore, and CLAUDE.md should never contain secrets
**Source**: [Memory Best Practices](https://docs.claude.com/en/docs/claude-code/memory), [Security Standards](https://docs.claude.com/en/docs/claude-code/settings)
---
## Context Management
### Auto-Compaction
- **Behavior**: "Your context window will be automatically compacted as it approaches its limit"
- **Purpose**: Allows you to continue working indefinitely
- **Customization**: You can add summary instructions to CLAUDE.md to customize compaction behavior
- **Hook**: PreCompact hook runs before compaction operation
### Memory Persistence Across Sessions
- CLAUDE.md files persist across sessions (loaded at launch)
- Memory files maintain their content through compaction
- You can customize how compaction summarizes conversations via CLAUDE.md
**Source**: [Cost Management Documentation](https://docs.claude.com/en/docs/claude-code/costs), [Hooks Reference](https://docs.claude.com/en/docs/claude-code/hooks)
---
## Validation Methods
### Official Commands
#### `/memory` Command
- **Purpose**: View and edit CLAUDE.md memory files
- **Usage**: Type `/memory` in Claude Code to see all loaded memory files
- **Features**:
- Shows file paths for each memory location
- Allows direct editing of memory files
- Confirms which files are loaded
#### `/init` Command
- **Purpose**: Bootstrap CLAUDE.md file for your project
- **Usage**: Run `/init` in a new project
- **Features**:
- Analyzes your codebase
- Generates initial CLAUDE.md with project information
- Includes conventions and frequently used commands
**Source**: [Slash Commands Reference](https://docs.claude.com/en/docs/claude-code/slash-commands)
### CLI Debug Flags
While there is no `/debug` slash command, Claude Code offers CLI flags:
- `--debug`: Enable debug mode with detailed output
- `--mcp-debug`: Debug MCP server connections
- `--verbose`: Enable verbose logging
**Source**: Claude Code CLI documentation
---
## Content Recommendations
### What TO Include
#### Project-Specific Context
```markdown
# Project Overview
- Monorepo using npm workspaces
- TypeScript strict mode enforced
- Testing with Vitest
## Architecture
- Feature-based folder structure
- Clean Architecture pattern
- API layer in /src/api
```
#### Development Standards
```markdown
## Code Quality
- TypeScript strict mode required
- No `any` types allowed
- 80% test coverage minimum
- No console.log in production code
## Git Workflow
- Branch pattern: feature/{name}
- Conventional commit messages
- Pre-commit hooks enforced
```
#### Common Commands
```markdown
## Bash Commands
- npm run build: Build the project
- npm test: Run tests with coverage
- npm run typecheck: Run TypeScript compiler checks
```
#### Important File Locations
```markdown
## Key Files
- Config: /config/app.config.ts
- Constants: /src/constants/index.ts
- Types: /src/types/global.d.ts
```
**Source**: [Best Practices Blog](https://www.anthropic.com/engineering/claude-code-best-practices)
---
## Integration with Settings
### Relationship to settings.json
While CLAUDE.md provides instructions and context, `settings.json` provides programmatic control:
#### Settings Hierarchy
1. Enterprise managed policies (highest)
2. Command line arguments
3. Local project settings (`.claude/settings.local.json`)
4. Shared project settings (`.claude/settings.json`)
5. User settings (`~/.claude/settings.json`)
#### Complementary Usage
- **CLAUDE.md**: Instructions, context, standards, preferences
- **settings.json**: Permissions, hooks, tool access, environment variables
**Example** of settings.json:
```json
{
"permissions": {
"allow": ["Bash(npm run test:*)"],
"deny": ["Write(./.env)", "Write(./production.config.*)"]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write(*.py)",
"hooks": [{"type": "command", "command": "python -m black $file"}]
}
]
}
}
```
**Source**: [Settings Documentation](https://docs.claude.com/en/docs/claude-code/settings)
---
## Iterative Improvement
### Living Document Philosophy
- **Use `#` shortcut**: Quickly add instructions during conversations
- **Iterate and refine**: Test what produces the best instruction following
- **Share with team**: Commit improvements to source control
- **Add emphasis**: Use keywords like "IMPORTANT" or "YOU MUST" for critical standards
### Optimization Techniques
Consider using a "prompt improver" to enhance instructions:
- Make vague instructions more specific
- Add context where needed
- Improve clarity and organization
**Source**: [Best Practices Blog](https://www.anthropic.com/engineering/claude-code-best-practices)
---
## Summary of Official Guidelines
### ✅ DO
1. Keep CLAUDE.md files **lean and concise**
2. Be **specific** in instructions (not generic)
3. Use **structured markdown** with headings and bullets
4. Use **imports** for large documentation
5. Focus on **project-specific** context
6. **Iterate and refine** based on effectiveness
7. Use **hierarchy** appropriately (Enterprise → Project → User)
### ❌ DON'T
1. Include basic programming concepts
2. Duplicate official documentation
3. Add changing/temporary information
4. Include secrets or sensitive information
5. Make memory files excessively long
6. Use vague or generic instructions
7. Create circular import loops
---
## Validation Checklist
When auditing a CLAUDE.md file, verify:
- [ ] Proper file location (Enterprise/Project/User tier)
- [ ] No secrets or sensitive information
- [ ] Specific (not generic) instructions
- [ ] Structured with headings and bullets
- [ ] No duplicated official documentation
- [ ] Import syntax correct (if used)
- [ ] Maximum 5-hop import depth
- [ ] No circular imports
- [ ] Lean and concise (not excessively verbose)
- [ ] Project-specific context (not generic advice)
- [ ] Can be validated via `/memory` command
---
**Document Version**: 1.0.0
**Last Updated**: 2025-10-26
**Based On**: Official Anthropic documentation from docs.claude.com
**Verification Status**: All claims verified against official sources

115
skills/claude-md-auditor/reference/research-insights.md Normal file
View File

@@ -0,0 +1,115 @@
# Research-Based Optimization
Academic findings on LLM context utilization and attention patterns.
## Lost in the Middle Phenomenon
**Source**: Liu et al., 2023 - "Lost in the Middle: How Language Models Use Long Contexts"
### Key Finding
LLMs perform best when relevant information is positioned at the **beginning or end** of context, not the middle.
### Performance Curve
```
Performance
^
100%|* *
| * *
75%| * *
| * *
50%| * **** *
| ** **
+----------------------------> Position
Start Middle End
```
### Implications for CLAUDE.md
- **Critical information**: First 20% of file
- **Reference material**: Last 20% of file
- **Supporting details**: Middle sections
## Optimal Structure
Based on research findings:
```markdown
# Project Name
## CRITICAL (Top 20%)
- Build commands
- Breaking patterns to avoid
- Security requirements
## IMPORTANT (Next 30%)
- Core architecture
- Main conventions
- Testing requirements
## SUPPORTING (Middle 30%)
- Detailed patterns
- Edge cases
- Historical context
## REFERENCE (Bottom 20%)
- Links and resources
- Version history
- Maintenance notes
```
## Token Efficiency Research
### Context Window Utilization
- **Diminishing returns** after ~4K tokens of instructions
- **Optimal range**: 1,500-3,000 tokens
- **Beyond 5K**: Consider splitting into imports
### Information Density
- Prefer lists over paragraphs (better attention)
- Use code blocks (higher signal-to-noise)
- Avoid redundancy (wastes attention budget)
## Attention Calibration (MIT/Google Cloud AI, 2024)
### Finding
Recent models (Claude 3.5+) show improved but not eliminated middle-position degradation.
### Recommendations
1. **Chunking**: Group related information together
2. **Explicit markers**: Use headers and formatting
3. **Repetition**: Critical items can appear twice (top and bottom)
## Claude-Specific Performance Data
### Context Awareness in Claude 4/4.5
- Better at tracking multiple requirements
- Still benefits from positional optimization
- Explicit priority markers help attention allocation
### Effective Markers
```markdown
**CRITICAL**: Must follow exactly
**IMPORTANT**: Strongly recommended
**NOTE**: Additional context
```
## Practical Applications
### Audit Criteria Based on Research
**Check positioning of**:
- Security requirements (should be top)
- Build commands (should be top)
- Error-prone patterns (should be top or bottom)
- Reference links (should be bottom)
**Flag as issues**:
- Critical info buried in middle
- Long unstructured paragraphs
- Missing headers/structure
- No priority markers
## References
- Liu et al. (2023). "Lost in the Middle: How Language Models Use Long Contexts"
- MIT/Google Cloud AI (2024). "Attention Calibration in Large Language Models"
- Anthropic (2024). "Claude's Context Window Behavior"

464
skills/claude-md-auditor/reference/research_insights.md Normal file
View File

@@ -0,0 +1,464 @@
# Research-Based Insights for CLAUDE.md Optimization
> **Source**: Academic research on LLM context windows, attention patterns, and memory systems
This document compiles findings from peer-reviewed research and academic studies on how Large Language Models process long contexts, with specific implications for CLAUDE.md configuration.
---
## The "Lost in the Middle" Phenomenon
### Research Overview
**Paper**: "Lost in the Middle: How Language Models Use Long Contexts"
**Authors**: Liu et al. (2023)
**Published**: Transactions of the Association for Computational Linguistics, MIT Press
**Key Finding**: Language models consistently demonstrate U-shaped attention patterns
### Core Findings
#### U-Shaped Performance Curve
Performance is often highest when relevant information occurs at the **beginning** or **end** of the input context, and significantly degrades when models must access relevant information in the **middle** of long contexts, even for explicitly long-context models.
**Visualization**:
```
Attention/Performance
High | ██████ ██████
| ██████ ██████
| ██████ ██████
Medium | ██████ ██████
| ███ ███
Low | ████████████████
+------------------------------------------
START MIDDLE SECTION END
```
#### Serial Position Effects
This phenomenon is strikingly similar to **serial position effects** found in human memory literature:
- **Primacy Effect**: Better recall of items at the beginning
- **Recency Effect**: Better recall of items at the end
- **Middle Degradation**: Worse recall of items in the middle
The characteristic U-shaped curve appears in both human memory and LLM attention patterns.
**Source**: Liu et al., "Lost in the Middle" (2023), TACL
---
## Claude-Specific Performance
### Original Research Results (Claude 1.3)
The original "Lost in the Middle" research tested Claude models:
#### Model Specifications
- **Claude-1.3**: Maximum context length of 8K tokens
- **Claude-1.3 (100K)**: Extended context length of 100K tokens
#### Key-Value Retrieval Task Results
> "Claude-1.3 and Claude-1.3 (100K) do nearly perfectly on all evaluated input context lengths"
**Interpretation**: Claude performed better than competitors at accessing information in the middle of long contexts, but still showed the general pattern of:
- Best performance: Information at start or end
- Good performance: Information in middle (better than other models)
- Pattern: Still exhibited U-shaped curve, just less pronounced
**Source**: Liu et al., Section 4.2 - Model Performance Analysis
### Claude 2.1 Improvements (2023)
#### Prompt Engineering Discovery
Anthropic's team discovered that Claude 2.1's long-context performance could be dramatically improved with targeted prompting:
**Experiment**:
- **Without prompt nudge**: 27% accuracy on middle-context retrieval
- **With prompt nudge**: 98% accuracy on middle-context retrieval
**Effective Prompt**:
```
Here is the most relevant sentence in the context: [relevant info]
```
**Implication**: Explicit highlighting of important information overcomes the "lost in the middle" problem.
**Source**: Anthropic Engineering Blog (2023)
---
## Claude 4 and 4.5 Enhancements
### Context Awareness Feature
**Models**: Claude Sonnet 4, Sonnet 4.5, Haiku 4.5, Opus 4, Opus 4.1
#### Key Capabilities
1. **Real-time Context Tracking**
- Models receive updates on remaining context window after each tool call
- Enables better task persistence across extended sessions
- Improves handling of state transitions
2. **Behavioral Adaptation**
- **Sonnet 4.5** is the first model with context awareness that shapes behavior
- Proactively summarizes progress as context limits approach
- More decisive about implementing fixes near context boundaries
3. **Extended Context Windows**
- Standard: 200,000 tokens
- Beta: 1,000,000 tokens (1M context window)
- Models tuned to be more "agentic" for long-running tasks
**Implication**: Newer Claude models are significantly better at managing long contexts and maintaining attention throughout.
**Source**: Claude 4/4.5 Release Notes, docs.claude.com
---
## Research-Backed Optimization Strategies
### 1. Strategic Positioning
#### Place Critical Information at Boundaries
**Based on U-shaped attention curve**:
```markdown
# CLAUDE.md Structure (Research-Optimized)
## TOP SECTION (Prime Position)
### CRITICAL: Must-Follow Standards
- Security requirements
- Non-negotiable quality gates
- Blocking issues
## MIDDLE SECTION (Lower Attention)
### Supporting Information
- Nice-to-have conventions
- Optional practices
- Historical context
- Background information
## BOTTOM SECTION (Recency Position)
### REFERENCE: Key Information
- Common commands
- File locations
- Critical paths
```
**Rationale**:
- Critical standards at TOP get primacy attention
- Reference info at BOTTOM gets recency attention
- Supporting context in MIDDLE is acceptable for lower-priority info
---
### 2. Chunking and Signposting
#### Use Clear Markers for Important Information
**Research Finding**: Explicit signaling improves retrieval
**Technique**:
```markdown
## 🚨 CRITICAL: Security Standards
[Most important security requirements]
## ⚠️ IMPORTANT: Testing Requirements
[Key testing standards]
## 📌 REFERENCE: Common Commands
[Frequently used commands]
```
**Benefits**:
- Visual markers improve salience
- Helps overcome middle-context degradation
- Easier for both LLMs and humans to scan
---
### 3. Repetition for Critical Standards
#### Repeat Truly Critical Information
**Research Finding**: Redundancy improves recall in long contexts
**Example**:
```markdown
## CRITICAL STANDARDS (Top)
- NEVER commit secrets to git
- TypeScript strict mode REQUIRED
- 80% test coverage MANDATORY
## Development Workflow
...
## Pre-Commit Checklist (Bottom)
- ✅ No secrets in code
- ✅ TypeScript strict mode passing
- ✅ 80% coverage achieved
```
**Note**: Use sparingly - only for truly critical, non-negotiable standards.
---
### 4. Hierarchical Information Architecture
#### Organize by Importance, Not Just Category
**Less Effective** (categorical):
```markdown
## Code Standards
- Critical: No secrets
- Important: Type safety
- Nice-to-have: Naming conventions
## Testing Standards
- Critical: 80% coverage
- Important: Integration tests
- Nice-to-have: Test names
```
**More Effective** (importance-based):
```markdown
## CRITICAL (All Categories)
- No secrets in code
- TypeScript strict mode
- 80% test coverage
## IMPORTANT (All Categories)
- Integration tests for APIs
- Type safety enforcement
- Security best practices
## RECOMMENDED (All Categories)
- Naming conventions
- Code organization
- Documentation
```
**Rationale**: Groups critical information together at optimal positions, rather than spreading across middle sections.
---
## Token Efficiency Research
### Optimal Context Utilization
#### Research Finding: Attention Degradation with Context Length
Studies show that even with large context windows, attention can wane as context grows:
**Context Window Size vs. Effective Attention**:
- **Small contexts (< 10K tokens)**: High attention throughout
- **Medium contexts (10K-100K tokens)**: U-shaped attention curve evident
- **Large contexts (> 100K tokens)**: More pronounced degradation
#### Practical Implications for CLAUDE.md
**Token Budget Analysis**:
| Context Usage | CLAUDE.md Size | Effectiveness |
|---------------|----------------|---------------|
| < 1% | 50-100 lines | Minimal impact, highly effective |
| 1-2% | 100-300 lines | Optimal balance |
| 2-5% | 300-500 lines | Diminishing returns start |
| > 5% | 500+ lines | Significant attention cost |
**Recommendation**: Keep CLAUDE.md under 3,000 tokens (≈200 lines) for optimal attention preservation.
**Source**: "Lost in the Middle" research, context window studies
---
## Model Size and Context Performance
### Larger Models = Better Context Utilization
#### Research Finding (2024)
> "Larger models (e.g., Llama-3.2 1B) exhibit reduced or eliminated U-shaped curves and maintain high overall recall, consistent with prior results that increased model complexity reduces lost-in-the-middle severity."
**Implications**:
- Larger/more sophisticated models handle long contexts better
- Claude 4/4.5 family likely has improved middle-context attention
- But optimization strategies still beneficial
**Source**: "Found in the Middle: Calibrating Positional Attention Bias" (MIT/Google Cloud AI, 2024)
---
## Attention Calibration Solutions
### Recent Breakthroughs (2024)
#### Attention Bias Calibration
Research showed that the "lost in the middle" blind spot stems from U-shaped attention bias:
- LLMs consistently favor start and end of input sequences
- Neglect middle even when it contains most relevant content
**Solution**: Attention calibration techniques
- Adjust positional attention biases
- Improve middle-context retrieval
- Maintain overall model performance
**Status**: Active research area; future Claude models may incorporate these improvements
**Source**: "Solving the 'Lost-in-the-Middle' Problem in Large Language Models: A Breakthrough in Attention Calibration" (2024)
---
## Practical Applications to CLAUDE.md
### Evidence-Based Structure Template
Based on research findings, here's an optimized structure:
```markdown
# Project Name
## 🚨 TIER 1: CRITICAL STANDARDS
### (TOP POSITION - HIGHEST ATTENTION)
- Security: No secrets in code (violation = immediate PR rejection)
- Quality: TypeScript strict mode (no `any` types)
- Testing: 80% coverage on all new code
## 📋 PROJECT OVERVIEW
- Tech stack: [summary]
- Architecture: [pattern]
- Key decisions: [ADRs]
## 🔧 DEVELOPMENT WORKFLOW
- Git: feature/{name} branches
- Commits: Conventional commits
- PRs: Require tests + review
## 📝 CODE STANDARDS
- TypeScript: strict mode, explicit types
- Testing: Integration-first (70%), unit (20%), E2E (10%)
- Style: ESLint + Prettier
## 💡 NICE-TO-HAVE PRACTICES
### (MIDDLE POSITION - ACCEPTABLE FOR LOWER PRIORITY)
- Prefer functional components
- Use meaningful variable names
- Extract complex logic to utilities
- Add JSDoc for public APIs
## 🔍 TROUBLESHOOTING
- Common issue: [solution]
- Known gotcha: [workaround]
## 📌 REFERENCE: KEY INFORMATION
### (BOTTOM POSITION - RECENCY ATTENTION)
- Build: npm run build
- Test: npm run test:low -- --run
- Deploy: npm run deploy:staging
- Config: /config/app.config.ts
- Types: /src/types/global.d.ts
- Constants: /src/constants/index.ts
```
---
## Summary of Research Insights
### ✅ Evidence-Based Recommendations
1. **Place critical information at TOP or BOTTOM** (not middle)
2. **Keep CLAUDE.md under 200-300 lines** (≈3,000 tokens)
3. **Use clear markers and signposting** for important sections
4. **Repeat truly critical standards** (sparingly)
5. **Organize by importance**, not just category
6. **Use imports for large documentation** (keeps main file lean)
7. **Leverage Claude 4/4.5 context awareness** improvements
### ⚠️ Caveats and Limitations
1. Research is evolving - newer models improve constantly
2. Claude specifically performs better than average on middle-context
3. Context awareness features in Claude 4+ mitigate some issues
4. Your mileage may vary based on specific use cases
5. These are optimization strategies, not strict requirements
### 🔬 Future Research Directions
- Attention calibration techniques
- Model-specific optimization strategies
- Dynamic context management
- Adaptive positioning based on context usage
---
## Validation Studies Needed
### Recommended Experiments
To validate these strategies for your project:
1. **A/B Testing**
- Create two CLAUDE.md versions (optimized vs. standard)
- Measure adherence to standards over multiple sessions
- Compare effectiveness
2. **Position Testing**
- Place same standard at TOP, MIDDLE, BOTTOM
- Measure compliance rates
- Validate U-shaped attention hypothesis
3. **Length Testing**
- Test CLAUDE.md at 100, 200, 300, 500 lines
- Measure standard adherence
- Find optimal length for your context
4. **Marker Effectiveness**
- Test with/without visual markers (🚨, ⚠️, 📌)
- Measure retrieval accuracy
- Assess practical impact
---
## References
### Academic Papers
1. **Liu, N. F., et al. (2023)**
"Lost in the Middle: How Language Models Use Long Contexts"
_Transactions of the Association for Computational Linguistics, MIT Press_
DOI: 10.1162/tacl_a_00638
2. **MIT/Google Cloud AI (2024)**
"Found in the Middle: Calibrating Positional Attention Bias Improves Long Context Utilization"
_arXiv:2510.10276_
3. **MarkTechPost (2024)**
"Solving the 'Lost-in-the-Middle' Problem in Large Language Models: A Breakthrough in Attention Calibration"
### Industry Sources
4. **Anthropic Engineering Blog (2023)**
Claude 2.1 Long Context Performance Improvements
5. **Anthropic Documentation (2024-2025)**
Claude 4/4.5 Release Notes and Context Awareness Features
docs.claude.com
### Research Repositories
6. **arXiv.org**
[2307.03172] - "Lost in the Middle" paper
[2510.10276] - "Found in the Middle" paper
---
**Document Version**: 1.0.0
**Last Updated**: 2025-10-26
**Status**: Research-backed insights (academic sources)
**Confidence**: High (peer-reviewed studies + Anthropic data)