CLAUDE.md

1# Project: Megarepo - AI Setup Repository
2 
3## Overview
4Megarepo is a minimal repository template designed for AI-related projects and development. It serves as a foundational setup repository that provides basic configuration files and structure for Node.js/Next.js AI applications. The repository is currently in a minimal state and is intended to be expanded with AI-specific tooling, configurations, and project scaffolding.
5 
6## Architecture
7- **Current Structure**: Minimal setup with basic configuration files
8- **Target Architecture**: Node.js/Next.js based AI applications
9- **Key Directories** (when populated):
10  - `src/` - Main source code directory
11  - `src/pages/` - Next.js pages (if Next.js project)
12  - `src/components/` - React components for AI interfaces
13  - `src/utils/` - Utility functions and AI helpers
14  - `public/` - Static assets and files
15- **Configuration Files**:
16  - `.gitignore` - Pre-configured for Node.js/Next.js projects
17  - `LICENSE` - MIT license
18  - `.github/copilot-instructions.md` - Detailed AI agent instructions
19 
20## Technology Stack
21- **Frontend**: Next.js, React (intended)
22- **Runtime**: Node.js
23- **Package Manager**: npm
24- **License**: MIT
25- **AI Integrations**: To be determined based on project needs (OpenAI, LangChain, Hugging Face, etc.)
26 
27## Coding Preferences
28 
29### General Guidelines
30- Follow existing patterns established in the repository
31- Prioritize minimal, surgical changes over large refactors
32- Maintain consistency with the existing file structure
33- Use TypeScript when adding JavaScript code (based on .gitignore patterns)
34 
35### AI Development Specific
36- Use environment variables for API keys and sensitive configuration
37- Never commit API keys or secrets to the repository
38- Structure AI-related code in logical, modular components
39- Document AI model dependencies and version requirements
40- Include error handling for AI service failures
41 
42### Code Style
43- Follow standard Node.js/Next.js conventions
44- Use meaningful variable and function names, especially for AI-related functionality
45- Include JSDoc comments for complex AI algorithms or integrations
46- Organize imports: external dependencies first, then internal modules
47 
48### File Organization
49- Keep configuration files in the root directory
50- Place source code in `src/` directory when added
51- Use clear, descriptive file names
52- Group related functionality together
53 
54## Instructions for Claude
55 
56### Project Understanding
57- This repository is currently minimal and serves as a template/setup for AI projects
58- No build system or source code exists yet - do not attempt to build, test, or run code
59- The repository is pre-configured for Node.js/Next.js development patterns
60- Focus on the intended AI setup purpose when making recommendations
61 
62### When Adding New Code
631. **Always check for existing package.json before running npm commands**
642. **Follow the patterns established in `.github/copilot-instructions.md`**
653. **Set appropriate timeouts for long-running operations** (builds: 60+ minutes, installs: 10+ minutes)
664. **Validate changes don't break existing minimal structure**
67 
68### AI-Specific Considerations
69- When adding AI dependencies, verify compatibility with the intended Node.js/Next.js stack
70- Create `.env.example` files to document required environment variables
71- Consider rate limiting and error handling for AI service integrations
72- Document AI model requirements, versions, and expected behavior
73 
74### Testing Strategy
75- When source code is added, include tests for AI functionality
76- Test error scenarios (API failures, rate limits, invalid responses)
77- Include integration tests for AI service connections
78- Document how to run tests with mock AI services for CI/CD
79 
80### Documentation Requirements
81- Update README.md when adding significant functionality
82- Document AI service setup and configuration steps
83- Include examples of AI integrations and usage
84- Maintain this claude.md file as the project evolves
85 
86### Constraints and Limitations
87- Repository is currently minimal - respect this intentional simplicity
88- Do not add unnecessary complexity or dependencies prematurely
89- Maintain compatibility with the existing MIT license
90- Follow the existing .gitignore patterns for Node.js/Next.js projects
91- Respect the established minimal change philosophy outlined in copilot-instructions.md
92 
93## Development Workflow
94 
95### Initial Setup (when code is added)
96```bash
97# Verify package.json exists before running commands
98test -f package.json && echo "Node.js project detected" || echo "No package.json found"
99 
100# Install dependencies if package.json exists
101npm install
102 
103# Check for environment variables
104ls .env* || echo "No environment files found"
105```
106 
107### AI Service Integration
108```bash
109# Check for AI-related packages
110grep -E "(openai|langchain|tensorflow|pytorch|huggingface)" package.json
111 
112# Validate environment configuration
113test -f .env.example && echo "Environment template found" || echo "Create .env.example for required variables"
114```
115 
116### Before Committing
117```bash
118# Run linting if configured
119npm run lint 2>/dev/null || echo "No lint script found"
120 
121# Run tests if configured  
122npm run test 2>/dev/null || echo "No test script found"
123 
124# Check for secrets in staged files
125git diff --cached --name-only | xargs grep -l "api.*key\|secret\|token" || echo "No potential secrets found"
126```
127 
128## Notes
129- This configuration file should be updated as the repository evolves from its current minimal state
130- The repository is designed to be a foundation for AI projects, so expect significant expansion
131- Always refer to `.github/copilot-instructions.md` for additional context and detailed workflows
132- Maintain the minimal, focused approach that characterizes this repository template