diff --git a/AGENTS.md b/AGENTS.md index a4ac967..0babfbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,41 @@ These instructions apply to any automated or semi-automated agent working in this repository. -## Core delivery standards +## 1. Non-negotiable engineering principles + +- Follow repository-specific conventions first. When the repository does not define a convention, always follow the most common globally accepted conventions for the language, framework, platform, and tooling you are working in. +- Write code that is clean, well structured, readable, and maintainable by default. Treat this as a hard requirement, not a preference. +- Prefer idiomatic, ecosystem-native solutions over clever, surprising, or custom patterns. +- Choose designs that a strong maintainer in that technology would expect on first read. +- Keep implementations cohesive, predictable, and easy to reason about. Avoid unnecessary abstraction, indirection, or complexity. + +## 2. Technology convention rules + +- Always apply the dominant conventions of the specific technology you touch. Do not mix patterns from one ecosystem into another when they are not idiomatic there. +- Use official language and framework guidance as the default source of truth when repository conventions are absent. +- Match the naming, file organization, error-handling style, typing model, testing style, and architectural patterns that are most commonly used by mature projects in that ecosystem. +- If a repository convention conflicts with a global convention, follow the repository convention unless it would clearly reduce correctness or maintainability. + +### Examples + +- **TypeScript / JavaScript**: prefer idiomatic modern TypeScript and standard JavaScript conventions, clear module boundaries, strong typing, descriptive names, `camelCase` for values and functions, `PascalCase` for types and components, and avoidance of `any` unless genuinely unavoidable. +- **C# / .NET**: follow standard .NET conventions, `PascalCase` for public types and members, `camelCase` for locals and parameters, clear class and namespace organization, proper async/await usage with `Async` suffixes, and nullable-aware, type-safe code. +- **SQL / database code**: write explicit, readable queries; use clear naming; prefer maintainable schema and query structure over compact but opaque statements. +- **Tests**: use the testing patterns most natural to the framework in use, keep tests behavior-focused and readable, and favor clear setup/action/assertion flow. +- **Other technologies**: default to the mainstream conventions most widely used by that ecosystem's official documentation and production-grade projects. + +## 3. Code quality and structure + +- Code must always be clean and well structured. +- Keep files, modules, classes, and functions focused on a single responsibility. +- Separate concerns clearly and maintain sensible boundaries between UI, domain logic, data access, infrastructure, and tests where applicable. +- Prefer simple control flow, explicit intent, and low cognitive overhead. +- Avoid duplication when a shared abstraction improves clarity and maintainability. +- Prefer composition and small reusable units over sprawling functions, deep inheritance, or tightly coupled code. +- Make invalid states difficult to represent through types, structure, or APIs whenever the technology supports it. +- Add comments only when they explain intent, reasoning, or non-obvious behavior that the code itself cannot communicate clearly. + +## 4. Core delivery standards - Keep commits atomic. Each commit should represent one logical change and use a Conventional Commit message such as `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, or `chore:`. - Treat tests as part of the implementation, not as follow-up work. Every fix, behavior change, and new feature must be covered by tests, and the relevant test suite must pass before the work is considered complete. @@ -10,7 +44,7 @@ These instructions apply to any automated or semi-automated agent working in thi - Apply the same quality bar to feature work. Think through scope, edge cases, integration points, and long-term maintainability before implementing. - When adding or updating dependencies, use the latest stable version available. If a non-latest version is required for compatibility, document the reason explicitly in the change. -## Repository workflow expectations +## 5. Repository workflow expectations - Use Bun for dependency management and script execution. - Prefer repository-local tooling over global machine state whenever possible.