An example of an AI context file (claude.md or gemini.md)

claude.md

Project Context

This is a LLM app using Python/FastAPI, langchain and langgraph.

Constraints

• Use data in memory for cache, storage, and queue.

Code Standards

• Max 50 lines per function
• Use descriptive variable names
• Use the latest stable versions of all libraries.
• Follow good practices and design patterns.

🚫 AI Code Generation Guidelines - AVOID THESE PATTERNS

Code Anti-Patterns to Avoid

1. NO excessive logging - Only log essential information at appropriate levels
2. NO generic error handling - Catch specific exceptions with recovery strategies
3. NO TODO/FIXME comments - Complete implementations before committing
4. NO functions with 5+ parameters - Use dataclasses/Pydantic models instead
5. NO dict[str, Any] everywhere - Use proper type hints and domain models
6. NO redundant code - Follow DRY principle, extract common functionality
7. NO magic numbers - Use named constants with clear documentation
8. NO unvalidated inputs - Always validate external data with Pydantic/schemas
9. NO inefficient algorithms - Consider O(n) complexity, use appropriate data structures
10. NO copy-paste code blocks - Create reusable functions and utilities
11. NO sequential awaits - Use asyncio.gather() for parallel async operations
12. NO untestable code - Design with dependency injection and separation of concerns

Mermaid Diagram Best Practices

1. Keep diagrams focused - One concept per diagram, max 15-20 nodes
2. Use consistent visual semantics - Same colors/shapes for same types across all diagrams
3. Always include legends - Explain what colors, shapes, and arrows mean
4. Avoid redundancy - Don't repeat same information in multiple diagrams
5. Progressive disclosure - Start with high-level overview, link to detailed diagrams
6. Clear flow direction - Make data/control flow obvious with arrows and labels
7. Purpose-specific diagrams - Separate diagrams for data flow, deployment, auth, etc.

🎯 Production-Ready Code Requirements

Make Code Review-Friendly

1. Small, atomic changes - Break large features into multiple small PRs (max 200 lines)
2. Clear context - Always explain WHY the change is needed, not just WHAT changed
3. Self-documenting code - Code should be readable without extensive comments
4. Complete implementations - Never submit partial solutions that "work but need cleanup"
5. Test coverage with meaning - Tests must validate behavior, not just increase coverage metrics

Security-First Development

1. Use only approved libraries - Check project's package.json/requirements.txt before adding dependencies
2. No experimental patterns - Stick to established, battle-tested approaches
3. Security validation - Always validate inputs, sanitize outputs, use parameterized queries
4. Compliance check - Follow existing authentication/authorization patterns in codebase
5. Never bypass security - Don't disable linters, skip tests, or ignore security warnings

Incremental Development Rules

1. Start minimal - Begin with the simplest working solution
2. Iterate with purpose - Each iteration should be reviewable and deployable
3. No "big bang" commits - Avoid massive single commits that change everything
4. Progressive enhancement - Add complexity only when requirements demand it
5. Maintain working state - Code should always be runnable after each change

Maintain Code Context

1. Preserve existing patterns - Match the style and structure of surrounding code
2. Respect architecture - Don't introduce new architectural patterns without discussion
3. Follow naming conventions - Use the project's established naming patterns
4. Keep dependencies minimal - Reuse existing utilities before creating new ones
5. Document deviations - If you must deviate from patterns, explain why clearly

Performance Considerations

1. Optimize for readability first - Clear code over clever code
2. Profile before optimizing - Don't guess about performance bottlenecks
3. Consider scale - Think about how code performs with 10x current data
4. Resource management - Always close connections, clear timeouts, free resources
5. Batch operations - Use bulk operations for database/API calls when possible

Testing Standards

1. Test behavior, not implementation - Tests should survive refactoring
2. Edge cases matter - Test error paths, boundary conditions, null/empty inputs
3. Meaningful assertions - Don't just check that functions execute
4. Independent tests - Each test should run in isolation
5. Fast feedback - Unit tests should run in milliseconds, not seconds

Code Review Mindset

1. Write for the reviewer - Assume the reviewer has no context
2. Self-review first - Review your own code before submitting
3. Explain non-obvious decisions - Add comments for complex business logic
4. Consider future maintainers - Code is read 10x more than written
5. Address feedback constructively - All review comments deserve thoughtful responses

🤖 AI Code Generation Specific Rules

NEVER Generate:

• Entire features in one response - break into logical chunks
• Code without understanding existing patterns
• Tests that only increase coverage metrics
• Complex abstractions for simple problems
• Code that bypasses existing validation/security
• Verbose or duplicated code.

ALWAYS Generate:

• Code that matches existing style guides
• Comprehensive error handling
• Meaningful variable/function names
• Tests that validate actual behavior
• Documentation for public APIs
• Production-ready and PR ready code that is easy to review and understand by human.

Before Generating Code:

1. Analyze existing codebase patterns
2. Understand the full context of the change
3. Consider security implications
4. Think about maintenance burden
5. Evaluate if simpler solution exists

Focus on Quality Metrics

• Review time < 30 minutes per PR
• Review iterations < 3 rounds
• Change failure rate < 5%
• Time to production < 1 day for small changes
• Post-deployment issues = 0 for standard features

Definition of "Done"

• Code follows project style guide
• All tests pass locally
• New tests cover new functionality
• Error scenarios handled gracefully
• Performance impact assessed
• Security implications reviewed
• Documentation updated if needed
• Code self-reviewed before submission
• PR description explains the "why"
• Breaking changes clearly marked