Codebase overview generator for AI code editors

codebase_overview_prompt_ai_agents.txt

Please analyze this codebase thoroughly and create a comprehensive `CODEBASE_OVERVIEW.md` file that will serve as context for future AI coding sessions. This document should capture all the essential information needed for an AI assistant to understand how to work with this codebase effectively.

## Analysis Framework

### 1. Project Overview
- **Technology Stack**: Identify all major technologies, frameworks, languages, and versions used
- **Project Type**: (web app, API, library, CLI tool, mobile app, etc.)
- **Main Purpose**: What does this application do? What problem does it solve?
- **Target Environment**: (browser, Node.js, mobile, desktop, cloud, etc.)

### 2. Architecture Analysis
- **Overall Architecture Pattern**: (MVC, microservices, layered, component-based, etc.)
- **Key Components**: Identify main modules/components and their responsibilities
- **Data Flow**: How does data move through the application?
- **External Dependencies**: APIs, databases, third-party services
- **Build System**: How is the project built and deployed?

### 3. Code Organization & Structure
- **Directory Structure**: Map out the folder hierarchy and explain the purpose of each major directory
- **File Naming Conventions**: Patterns used for naming files and folders
- **Module Organization**: How are related functionalities grouped?
- **Import/Export Patterns**: How modules are connected

### 4. Coding Standards & Style
- **Naming Conventions**: Variables, functions, classes, constants
- **Code Formatting**: Indentation, spacing, line length preferences
- **Comment Style**: How and when comments are used
- **Function/Method Structure**: Preferred patterns for organizing code within functions
- **Error Handling**: How errors are typically handled and propagated

### 5. Development Patterns & Best Practices
- **Common Design Patterns**: Identify recurring patterns in the codebase
- **State Management**: How application state is handled
- **Testing Approach**: Testing philosophy, patterns, and tools used
- **Configuration Management**: How settings and environment variables are handled
- **Logging/Debugging**: Preferred approaches for logging and debugging

### 6. Key Files & Entry Points
- **Main Entry Points**: Primary files that start the application
- **Configuration Files**: Important config files and their purposes
- **Critical Utilities**: Commonly used utility functions or modules
- **Types/Interfaces**: If using TypeScript, key type definitions

### 7. Development Workflow
- **Adding New Features**: Typical steps and patterns for adding functionality
- **Code Review Guidelines**: What to look for in code reviews
- **Testing Requirements**: When and how to write tests
- **Documentation Requirements**: When and how to update documentation

### 8. Do's and Don'ts
- **Preferred Approaches**: What patterns and practices are encouraged
- **Anti-Patterns**: What should be avoided
- **Performance Considerations**: Important performance guidelines
- **Security Considerations**: Security practices to follow

## Output Format

Create a markdown file with the following structure:

```markdown
# Codebase Overview

## Project Summary
[Brief overview of what this project does]

## Technology Stack
[List of technologies and versions]

## Architecture
[High-level architecture description]

## Directory Structure
```
/src
  /components     # [Purpose]
  /utils         # [Purpose]
  /types         # [Purpose]
```

## Coding Standards
### Naming Conventions
- Variables: [convention]
- Functions: [convention]
- Files: [convention]

### Code Style
[Key style guidelines]

### Patterns to Follow
[Important patterns used in this codebase]

## Key Development Rules
1. [Rule 1]
2. [Rule 2]
3. [Rule 3]

## Common Tasks
### Adding a New Feature
[Step-by-step process]

### Testing
[Testing requirements and patterns]

## Important Files
- `[file]` - [purpose]
- `[file]` - [purpose]

## Do's and Don'ts
### ✅ Do
- [Guideline]
- [Guideline]

### ❌ Don't
- [Anti-pattern]
- [Anti-pattern]

## Notes for AI Assistants
[Specific instructions for AI tools working with this codebase]
```

## Analysis Instructions

1. **Scan the entire codebase** - Look at file structure, package.json/requirements.txt, config files, and source code
2. **Identify patterns** - Look for repeated patterns in naming, organization, and code structure
3. **Extract implicit rules** - Notice conventions that aren't explicitly documented
4. **Focus on consistency** - Highlight what makes this codebase unique
5. **Be specific** - Include actual examples from the codebase when possible
6. **Think like a new developer** - What would someone need to know to contribute effectively?

## Additional Context Questions to Address

- How are components/modules typically structured?
- What's the preferred way to handle async operations?
- How are types/interfaces organized (if applicable)?
- What's the approach to error handling?
- How are external APIs typically integrated?
- What's the testing philosophy?
- Are there any domain-specific rules or constraints?

Please analyze the codebase thoroughly and create a comprehensive overview that will eliminate the need to re-explain the project structure and conventions in future AI conversations.