95 lines
3.1 KiB
Markdown
95 lines
3.1 KiB
Markdown
# Agent Guidelines for Light Chat
|
|
|
|
This document outlines the rules and principles for AI agents (or developers) working on the light_chat codebase.
|
|
|
|
## Core Principles
|
|
|
|
1. **Simplicity** - Keep the codebase simple and easy to understand
|
|
2. **Modularity** - Separate concerns; each module has a single responsibility
|
|
3. **Reusability** - Abstract common functionality for multiple use cases
|
|
4. **Test Coverage** - All functions and components must have unit tests
|
|
|
|
## Git Practices
|
|
|
|
### Commit Standards
|
|
- Write clear, descriptive commit messages (imperative mood: "Add feature" not "Added feature")
|
|
- Use conventional commits format: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`
|
|
- Make atomic commits - each commit should represent a single logical change
|
|
- Reference issue numbers in commit messages when applicable
|
|
|
|
### Branch Strategy
|
|
- Use `main` as the stable branch
|
|
- Create feature branches: `feature/description` or `feat/description`
|
|
- Use bugfix branches: `fix/description`
|
|
- Delete branches after merging to keep repository clean
|
|
|
|
### Pull Requests
|
|
- Keep PRs small and focused
|
|
- Include a clear description of changes and rationale
|
|
- Ensure all tests pass before requesting review
|
|
- Request code review for all changes (unless trivial)
|
|
- Address review feedback promptly
|
|
|
|
### Before Committing
|
|
- Run tests locally to verify functionality
|
|
- Check for unnecessary files (node_modules, build artifacts, env files)
|
|
- Verify no secrets or sensitive data are committed
|
|
- Rebase/squash commits if needed for clean history
|
|
|
|
### Code History
|
|
- Avoid force pushes to shared branches
|
|
- Regularly pull latest changes from main to avoid conflicts
|
|
- Use `git status` to verify what you're committing
|
|
|
|
## Coding Standards
|
|
|
|
### Function Design
|
|
- Before creating a new function, check if a similar one exists that can be extended
|
|
- Abstract shared logic into utility functions
|
|
- Keep functions focused on a single task
|
|
|
|
### Component Architecture
|
|
- Components should be small and composable
|
|
- Separate UI from business logic
|
|
- Use custom hooks for shared stateful logic
|
|
|
|
### Testing Requirements
|
|
- Every new component needs test coverage
|
|
- Mock external dependencies (API calls, storage, etc.)
|
|
- Test both success and error cases
|
|
- Use descriptive test names
|
|
|
|
## API Communication Pattern
|
|
|
|
The LLM API integration should be minimal:
|
|
- Simple GET/POST requests
|
|
- Extract "content" from responses
|
|
- Handle errors gracefully
|
|
- Allow custom endpoint configuration
|
|
|
|
## State Management
|
|
|
|
- Use React hooks (useState, useContext) for simplicity
|
|
- Session data should be persistable
|
|
- Maintain connection state (connected/disconnected)
|
|
|
|
## File Structure
|
|
|
|
```
|
|
src/
|
|
components/ # Reusable UI components
|
|
hooks/ # Custom React hooks
|
|
utils/ # Utility functions and API clients
|
|
services/ # Business logic and API services
|
|
stores/ # State management (if needed)
|
|
tests/ # Unit tests
|
|
```
|
|
|
|
## Workflow for New Features
|
|
|
|
1. Identify existing similar functionality
|
|
2. Abstract common patterns if applicable
|
|
3. Implement with test-driven development
|
|
4. Write tests first, then code
|
|
5. Keep it simple - avoid over-engineering
|