AGENTS

Overview

This repository is a minimal starter project. Agents interacting with it should follow the conventions below for building, linting, testing, and coding style. The guidelines are intentionally generic to accommodate future language or framework additions. If new tools are added, update this file accordingly.

1. Build / Lint / Test Commands

Tool	Command	Purpose
npm	`npm run build`	Transpile / bundle the source code (if applicable). No default script is currently defined; add only when a build process emerges.
npm	`npm run lint`	Run ESLint + Prettier checks. Ensure that `lint` script is configured in `package.json`.
npm	`npm test`	Run the full test suite using Jest / Mocha / any test runner configured.
npm	`npm test -- <pattern>`	Run a single test or a set of tests matching the glob `<pattern>`. Example: `npm test -- src/__tests__/*.spec.js`.
npm	`npm run format`	Auto‑format the code base using Prettier. Helpful after manual edits.
npm	`npm run type-check`	Run TypeScript type checking (if the project uses TypeScript).

Tip: Agents should prefer the single‑test form when debugging to avoid slow test runs.

2. Code Style Guidelines

2.1 Import Order

External packages (npm modules) alphabetically.
Internal modules (relative imports) sorted by path depth.
Side‑effect imports ("./setup") placed last.

Use the ESLint import/order rule to enforce this.

2.2 Formatting

Use Prettier with the repository’s .prettierrc configuration.
Prefer single quotes for strings, unless a string contains a single quote.
Trailing commas are mandatory in multiline arrays, objects, and function parameter lists.
Max line width: 100 characters.

2.3 Types

If TypeScript is used, prefer explicit types over any.
For function parameters, use named types (Array<string>, Record<string, number>, etc.).
Avoid type inference when the type becomes unclear.
Export type aliases and interfaces from types/index.ts where appropriate.

2.4 Naming Conventions

Element	Style	Example
Variables / constants	`snake_case` for constants, `camelCase` for others	`MAX_RETRIES`, `userName`
Functions	`camelCase`	`fetchData()`
Classes / Interfaces	`PascalCase`	`UserService`
Enums	`UPPER_SNAKE_CASE`	`UserStatus`
React Components	`PascalCase`	`MyComponent`
Redux Actions / Reducers	`lower_kebab-case`	`fetch-users`

2.5 Error Handling

Use try/catch blocks around async operations.
Wrap errors in custom error classes (e.g., ApiError) to provide rich context.
Never swallow errors; always either re‑throw or log with sufficient detail.
When interacting with external services, use exponential back‑off and timeouts.

2.6 Testing

Tests should be in __tests__ directories mirroring the source tree.
Use descriptive describe/it blocks.
Avoid global state; reset mocks before each test.
A test file must be covered by a single public API surface.

3. Cursor / Copilot Rules

No cursor or copilot configuration files currently exist in the repository. If these are added in the future:

Place cursor rules under .cursor/rules/.
Copilot instructions should be kept in .github/copilot-instructions.md.
Agents should respect any allowlist or blocklist directives.

4. Miscellaneous

All commits must pass linting and tests before merging.
Use descriptive commit messages following the Conventional Commits spec.
Document major decisions in the CONTRIBUTING.md (once created).

If additional tooling or standards are added, update this file and communicate changes to all agents.