# Agent Guidelines

This document provides guidelines for AI agents working in this repository.

## Project Overview

This is a minimal repository. When adding new projects, document their structure here.

## Build / Lint / Test Commands

Since the project currently has no build system, these are placeholder guidelines:

```bash
# Running a single test (example patterns - adjust per project)
npm test -- --testPathPattern=filename
pytest tests/test_file.py::TestClass::test_method
cargo test test_name
go test -run TestName ./...

# Linting
npm run lint
eslint src/
pylint src/
golangci-lint run

# Building
npm run build
npm run dev
cargo build
```

## Code Style Guidelines

### Imports

- Use absolute imports over relative imports when possible
- Group imports: standard library, third-party, local
- Sort alphabetically within groups
- Use explicit imports rather than wildcard imports

### Formatting

- Use 2 or 4 space indentation (match existing project style)
- Maximum line length: 80-120 characters (per project)
- Add trailing commas where appropriate
- Use consistent line endings (LF or CRLF per project)

### Types

- Prefer explicit type annotations for function parameters and return types
- Use interfaces/types for object shapes
- Avoid `any` type - use `unknown` if type is truly unknown
- Enable strict type checking where possible

### Naming Conventions

- **Files**: kebab-case or PascalCase (match project)
- **Classes**: PascalCase (e.g., `UserService`)
- **Functions/Variables**: camelCase (e.g., `getUserById`)
- **Constants**: SCREAMING_SNAKE_CASE (e.g., `MAX_RETRIES`)
- **Booleans**: Use `is`, `has`, `should` prefixes (e.g., `isActive`)

### Error Handling

- Use specific exception types rather than generic ones
- Include meaningful error messages with context
- Log errors with appropriate level (error, warning, debug)
- Handle async errors with try/catch or .catch()
- Never silently swallow errors unless explicitly intended

### General Practices

- Keep functions small and focused (single responsibility)
- Write comments for "why", not "what"
- Keep code DRY (Don't Repeat Yourself)
- Use meaningful variable and function names
- Write tests for new features
- Follow the existing code style of the project

## Testing Guidelines

- Test file naming: `filename.test.ts` or `filename_spec.ts`
- Use descriptive test names that explain the scenario
- Follow AAA pattern: Arrange, Act, Assert
- Mock external dependencies
- Test both success and error paths
- Aim for meaningful coverage, not just high percentage

## Git Conventions

- Write clear, concise commit messages
- Use feature branches for new work
- Keep commits atomic and focused
- Run linters before committing
- Review changes before pushing

## Documentation

- Update README.md for user-facing changes
- Add code comments for complex logic
- Document public APIs with docstrings/type hints
- Keep documentation close to the code it describes

## Cursor Rules

No Cursor rules found in this repository.

## Copilot Instructions

No Copilot instructions found in this repository.

## Working with This Repository

When working in this repository:

1. **Check existing structure** - Look at existing files and directories to understand the project layout before making changes
2. **Understand the domain** - Read README.md and any existing documentation
3. **Follow code style** - Match the existing code style in the project
4. **Test changes** - Run appropriate tests when available
5. **Commit responsibly** - Make meaningful commits with clear messages

## Common Tasks

### Running Development Server
```bash
# Check for available scripts
cat package.json  # for Node projects
cat Makefile      # for generic projects
```

### Adding Dependencies
```bash
npm install <package>  # Node projects
pip install <package>  # Python projects
cargo add <package>    # Rust projects
```

### Running Tests
```bash
# Identify test framework first
npm test               # Node/Jest
pytest                 # Python
cargo test             # Rust
```

## Best Practices for AI Agents

1. **Read first** - Always read existing files before editing
2. **Verify changes** - Check that changes work as expected
3. **Handle errors gracefully** - Provide meaningful error messages
4. **Ask for clarification** - When requirements are unclear, ask the user
5. **Be proactive** - Suggest improvements when obvious issues are found
6. **Respect user intent** - Don't make changes beyond what was asked unless clearly beneficial

## File Organization

- Keep related files together
- Use clear, descriptive file names
- Follow framework conventions (e.g., components in /components, tests in /tests)
- Maintain consistent directory structure across the project

## Performance Considerations

- Avoid unnecessary re-renders or computations
- Use appropriate data structures for the task
- Consider lazy loading for large modules
- Optimize database queries and API calls
- Profile before optimizing

## Security Guidelines

- Never commit secrets, API keys, or credentials
- Use environment variables for sensitive configuration
- Validate and sanitize all user inputs
- Follow OWASP security practices
- Keep dependencies updated for security patches