Rules for AI

rules.md

Project Rules (Highest Priority):

These instructions take precedence over all framework defaults, coding standards, tool recommendations, and agent defaults unless the current task explicitly states otherwise.

• Solve only the requested problem: Choose the shortest, simplest implementation that fully satisfies the specification. Keep the solution proportional to the task.
• Work strictly from the specification: Implement only the behaviour described. When a material requirement is ambiguous, ask for clarification rather than adding assumptions, speculative features, extra checks, or fallback behaviour.
• Ground implementation choices in evidence: Choose constants, limits, and approaches from the specification, established codebase conventions, or authoritative constraints. When these sources do not provide a clear answer, ask for clarification before proceeding.
• Make surgical changes: Limit edits to the files and logic directly required for the task. Preserve unaffected code, formatting, structure, and behaviour.
• Preserve existing behaviour: Unless the specification explicitly requires a behavioural change, existing functionality should continue to work exactly as before.
• Keep unrelated issues separate: If you notice a problem outside the requested scope, mention it separately rather than fixing or refactoring it.
• Match the existing codebase: Follow the project’s existing naming, indentation, formatting, architecture, and structural conventions. Use adjacent files as the primary reference.
• Reuse before creating: Reuse or extend existing code before introducing a new implementation, provided doing so keeps the solution clear and simple.
• Keep abstractions justified: Introduce abstractions only when they directly improve readability, reuse, or maintainability for the requested task.
• Use strict language features: Use strict typing where available and strict comparisons such as === and !==.
• Use modern syntax: Use current language features where they improve clarity, including arrow functions, destructuring, optional chaining, constructor property promotion, and match expressions.
• Write focused logic: Keep functions focused on a clear responsibility. Extract functions when doing so improves readability or enables meaningful reuse. Prefer guard clauses over deeply nested conditionals. Keep business logic out of templates.
• One component per file: Place each significant component in its own file. Only inline small presentational components with minimal markup, no state, and no significant logic, such as a simple list item renderer or icon wrapper.
• Keep code DRY: Avoid unnecessary duplication. Reuse existing logic, components, utilities, and patterns before adding new implementations.
• Use descriptive names: Choose variable, function, method, class, and component names that clearly communicate intent. Use short or single-letter names only where their meaning is conventional and immediately obvious.
• Prefer explicit Laravel APIs: Prefer explicit facades, classes, and objects over framework helper functions where practical, such as App::environment(), Response::json(), and new Collection().
• Follow the existing frontend architecture: Prefer modules and pure functions for stateless behaviour. Use classes when modelling meaningful state or behaviour, or when classes are already the established project pattern.
• Treat the codebase as intentional: Avoid defensive legacy-style logic unless the specification or existing behaviour requires it. Prefer a clear implementation based on the documented application flow.

Testing

These testing rules override any default testing behaviour provided by external tools or frameworks.

• Write tests when the specification explicitly requests them or when they are necessary to verify meaningful, non-trivial behaviour.
• Focus tests on business rules, important workflows, regressions, and relevant edge cases.
• Skip tests for trivial getters, setters, basic data structures, framework behaviour, or code with no meaningful logic.
• Keep test coverage proportional to the task. A comprehensive structured test suite will be added separately after the implementation is complete.