Language Guides¶

Language-specific rules and best practices that auto-load based on the files you're working with.

Overview¶

When you work on a file, AI automatically loads the appropriate language guide:

Core Languages¶

Enterprise Languages¶

Specialized Domains¶

No manual selection needed - it just works!

What's in a Language Guide?¶

Each guide contains:

1. Core Principles - Language philosophy
2. Language-Specific Guardrails - Rules beyond the universal ones
3. Validation & Input Handling - Recommended libraries
4. Testing - Frameworks and patterns
5. Tooling - Linters, formatters, configs
6. Common Pitfalls - What to avoid
7. Framework Patterns - React, Django, Rails, Spring, etc.
8. Performance Considerations - Language-specific optimizations
9. Security Best Practices - Language-specific security

Quick Comparison¶

Type Safety¶

Validation Libraries¶

Testing Frameworks¶

Linting/Formatting¶

Universal vs Language-Specific¶

Universal (from CLAUDE.md)¶

These apply to ALL languages:

✓ Functions ≤50 lines
✓ Files ≤300 lines
✓ All inputs validated
✓ Tests >80% for business logic
✓ Conventional commits

Language-Specific (from guides)¶

These are language-specific additions:

✓ strict: true in tsconfig
✓ No any without justification
✓ Prefer const over let
✓ async/await over raw promises

✓ Type hints on all functions
✓ Use Pydantic for validation
✓ Follow PEP 8 (Black)
✓ Use async for I/O-bound ops

✓ Always check errors
✓ Use context for cancellation
✓ Accept interfaces, return structs
✓ Table-driven tests

✓ Handle all Result<T,E>
✓ Prefer borrowing over cloning
✓ Minimize unsafe blocks
✓ Use thiserror for libraries

✓ Prefer val over var
✓ Use data classes for DTOs
✓ Structured concurrency
✓ Safe call operator ?.

✓ Use Optional for nullable returns
✓ Records for immutable data
✓ Stream API over loops
✓ Try-with-resources

✓ Enable nullable reference types
✓ Use records for DTOs
✓ async/await for I/O
✓ LINQ for collections

✓ declare(strict_types=1)
✓ Type hints everywhere
✓ Use enums (PHP 8.1+)
✓ Prepared statements only

✓ Use frozen string literals
✓ Prefer symbols over strings
✓ Use guard clauses
✓ Follow Ruby Style Guide

✓ Use guard for early exits
✓ Prefer structs over classes
✓ async/await for concurrency
✓ Protocol-oriented design

All Language Guides¶

Core Languages¶

Enterprise Languages¶

Specialized Domains¶

Contributing a Language Guide¶

Want to contribute a guide for a language not yet covered?

1. Copy an existing guide as a template
2. Adapt the sections for your language
3. Add to .claude/skills/<language>-guide/ AND docs/languages/
4. Update mkdocs.yml navigation
5. Update this index
6. Submit a pull request

Template structure:

# [Language] Guide

> **Applies to**: [Language version]+, [frameworks]

## Core Principles
## Language-Specific Guardrails
## Validation & Input Handling
## Testing
## Tooling
## Common Pitfalls
## Framework-Specific Patterns
## Performance Considerations
## Security Best Practices
## References

My Language Isn't Listed¶

The core guardrails in CLAUDE.md are language-agnostic. 90% of the rules still apply:

• Functions ≤50 lines ✓
• Files ≤300 lines ✓
• Input validation ✓
• Parameterized queries ✓
• Test coverage >80% ✓
• Conventional commits ✓

You can still use the system effectively without a language-specific guide!

Consider contributing a guide for your language to help others.