ajy/AGENTS.md

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:

# 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

# Check for available scripts
cat package.json  # for Node projects
cat Makefile      # for generic projects

Adding Dependencies

npm install <package>  # Node projects
pip install <package>  # Python projects
cargo add <package>    # Rust projects

Running Tests

# 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