Global Rules for AI Coding Assistants

Follow these rules for every code-related task unless the project contains a more specific instruction that explicitly overrides a rule. Before making changes, inspect the existing project structure, conventions, configuration, documentation, and relevant files. Do not assume that a preferred pattern is already used by the project.

Match the existing style of every file you modify, including indentation, quotes, spacing, naming, import ordering, and surrounding conventions. Consistency within the existing file and codebase takes priority over introducing a different personal preference.

Keep all static imports at the top of the file. Do not place imports inside functions, conditions, or other execution paths unless dynamic loading is explicitly required for lazy loading, code splitting, runtime compatibility, or another documented reason.

Avoid hard-coded strings, numbers, URLs, identifiers, timeouts, limits, and configuration values when they represent reusable or environment-specific behaviour. Place reusable values in an appropriate constants, configuration, environment, or domain-specific module. Do not extract values that are genuinely local, obvious, and used only once when doing so would reduce readability.

Do not duplicate meaningful business logic, validation, data transformations, UI behaviour, or reusable components. Search for an existing implementation before creating another one. Extract shared code when duplication would create inconsistent behaviour or increase maintenance cost.

Keep source files focused and reasonably sized. Treat 500 lines as a warning threshold rather than permission to create oversized files. When a file exceeds this size, evaluate whether it contains multiple responsibilities that should be separated into smaller modules, components, hooks, services, utilities, or domain units. Do not split files mechanically if doing so would make the code harder to understand.

Treat UI layout stability as a hard requirement. Do not change page structure, panel placement, navigation hierarchy, responsive breakpoints, card sizing, list sizing, or interaction patterns unless the task explicitly requires it.

Before modifying a user interface, identify the existing layout primitive, shared shell, page template, grid, container, sidebar, split view, pane system, or reusable component responsible for the current behaviour. Reuse or improve the shared implementation instead of adding isolated page-specific patches.

Preserve established interaction models such as left navigation rails, right-side detail panes, split views, sticky sidebars, card grids, tables, drawers, and modal flows. Do not replace grid with flex, flex with grid, a horizontal split with a vertical stack, or one layout system with another unless the requested change requires it and the consequences have been verified.

Do not stretch cards, collapse sidebars, move panes, change content order, or alter established proportions merely to fill empty space. Correct the underlying container, width constraint, alignment, or shared layout system instead.

Treat responsive breakpoints, minimum widths, maximum widths, overflow behaviour, and content wrapping as behaviour-critical. Do not assume a change is correct because the code appears reasonable. Verify the relevant desktop, tablet, and mobile states supported by the project.

When modifying a shared UI component or layout, inspect other pages that use it and ensure that the change does not introduce inconsistent behaviour or regressions elsewhere.

After every UI change, verify that the layout hierarchy, pane placement, component proportions, responsive behaviour, and interaction model remain consistent with the previous implementation except for the explicitly requested change.

When a local patch would create regression risk or duplicate layout logic, stop and implement the correction through an appropriate shared component, layout primitive, token, utility, or responsive pattern.

Use the package manager already established by the project. When starting a new JavaScript or TypeScript project and no package manager has been specified, prefer pnpm over npm or Yarn. When Bun is explicitly selected for the project, use Bun and its package manager consistently.

Use exact dependency versions without caret or tilde ranges in production package manifests. Prefer the newest suitable version that has been publicly available for at least seven days. Do not select a newly released version merely because it is the latest.

Before adding or upgrading a dependency, inspect its release date, maintenance activity, publisher, repository, security history, transitive dependency impact, licence, and compatibility with the project. Avoid unnecessary dependencies when the required behaviour can be implemented safely and clearly with the existing stack.

When the newest release does not satisfy the seven-day minimum release-age policy, select the latest eligible version and mention this decision in the final task summary.

Always preserve and commit the lockfile used by the project. Do not delete or regenerate a lockfile without understanding the resulting dependency changes. Avoid broad dependency updates when the task requires changing only one package.

For npm-based workflows, recommend enabling exact dependency saving and a minimum release-age policy where supported by the installed npm version or organisational tooling. Do not add unsupported configuration keys without first verifying that the package manager version recognises them.

For Bun projects, configure a minimum dependency release age of 604800 seconds when supported by the project’s Bun version and dependency policy.

For pnpm projects, use the equivalent supported minimum-release-age configuration when available and compatible with the installed pnpm version.

For Python projects using uv, commit uv.lock and use uv sync for reproducible environments. For pip-based production projects, use pinned versions and hashes where practical and install with hash verification. For Poetry projects, commit poetry.lock and use installation commands that do not unexpectedly update dependencies.

Do not use loose production dependency ranges such as greater-than-or-equal or compatible-release ranges unless the project has an explicit and documented reason for doing so.

Do not format dates independently throughout the codebase. Use the project’s central date, time, timezone, and localisation utilities. If none exist and repeated formatting is required, create a focused shared utility that follows the project’s conventions.

When the project exposes APIs, keep its API specification current. Update openapi.json, openapi.yaml, generated API documentation, schemas, examples, or equivalent specifications whenever an API contract changes.

Wrap dependent database writes in a transaction when partial completion would leave the system in an invalid or inconsistent state. Handle rollback and failure behaviour explicitly.

When Drizzle ORM is used, prefer its typed query builder and relational query APIs. Avoid raw SQL unless the required query cannot be expressed safely or efficiently through Drizzle. When raw SQL is necessary, parameterise it, explain why it is needed, and keep it isolated.

Respect the project’s existing architectural boundaries. Do not bypass services, repositories, domain modules, validation layers, permission checks, event systems, or shared abstractions merely because a direct implementation is shorter.

Do not silently introduce a new architectural pattern, framework, state-management library, validation library, testing framework, or infrastructure dependency. Use the project’s established approach unless the task explicitly requires a change.

After completing a task, verify the implementation rather than relying only on visual inspection of the code.

Run the most relevant available checks, including formatting, linting, type checking, unit tests, integration tests, build commands, and targeted runtime verification. Use the project’s documented commands and package manager.

Do not claim that a check passed unless you actually ran it successfully. If a check cannot be run because of missing dependencies, unavailable services, environment limitations, permissions, or unrelated existing failures, state that clearly.

When a test or build failure appears unrelated to your changes, investigate enough to distinguish it from a regression. Report the existing failure accurately rather than hiding it or claiming complete verification.

For UI work, verify the affected flow in a browser or the project’s available visual testing environment whenever possible. Check relevant viewport sizes and inspect the browser console for errors.

At the end of the task, provide a concise summary of what changed, what was verified, which commands were run, and whether any work remains incomplete.

Always list skipped, incomplete, blocked, or unverified work. Do not present a partially completed task as fully complete.

Suggest an appropriate Git commit message after making changes, but do not create a commit, push a branch, or open a pull request unless explicitly asked.

Use the commit message format type: short description. Use an appropriate type such as feat, fix, refactor, chore, docs, test, or perf.

Update CHANGELOG.md for meaningful user-facing, operational, security, architectural, or developer-experience changes when the project maintains a changelog. Follow the existing changelog format.

Do not add noisy changelog entries for trivial internal edits unless the project explicitly requires every change to be recorded.

Update project instruction and status files such as AGENTS.md, CLAUDE.md, README.md, architecture documents, setup instructions, migration notes, or task status files when the completed work makes their current content inaccurate.

Do not overwrite unrelated documentation or remove human-written context while updating status files.

Never configure a GitHub Actions workflow to use pull_request_target for executing or checking out untrusted pull request code. Treat pull_request_target as privileged and use it only for narrowly scoped trusted metadata operations with no execution of attacker-controlled content.

Do not use shared or mutable caches in release workflows when they could allow untrusted builds to influence production artefacts. Keep release inputs reproducible and isolated.

Pin every third-party GitHub Action to a full commit SHA instead of a mutable version tag such as v4. Apply this to official and third-party actions. Add a comment containing the human-readable release version when it improves maintainability.

Before updating an action SHA, verify the corresponding release and repository. Treat GitHub Actions as executable third-party code that may access repository contents, tokens, credentials, artefacts, and workflow permissions.

Set GitHub Actions permissions to the minimum required scope. Prefer read-only defaults and grant write permissions only to the specific job that requires them.

Do not expose secrets to workflows triggered from untrusted forks. Avoid printing environment variables, tokens, credentials, signed URLs, or sensitive command output in logs.

Recommend periodic audits of extensions installed in Visual Studio Code, Cursor, Windsurf, and other development tools. Remove unused extensions and review extensions that have not been used recently.

Recommend extensions only when their publisher, maintenance activity, install history, permissions, source repository, and security posture can be reasonably verified. Warn about extensions that request access beyond what their stated functionality requires.

Never commit environment files containing secrets. Ensure sensitive environment files are covered by .gitignore or the project’s equivalent ignore rules. Do not assume that a filename is safe merely because it is not named .env.

Never place real credentials, private keys, access tokens, session cookies, signing secrets, recovery codes, production connection strings, or other sensitive values in source code, fixtures, screenshots, logs, documentation, issue descriptions, test output, or AI prompts.

Do not ask the user to paste secrets into an AI conversation. When a task requires a secret, instruct the user to configure it through a secure secret manager, encrypted environment configuration, protected CI variable, or local environment mechanism.

Assume that prompts, logs, command histories, and tool output may be retained according to the policies of the services being used. Redact sensitive values before displaying or processing them.

Use credentials with the minimum permissions, resources, environments, and duration required. Separate development, staging, and production credentials.

Recommend rotating long-lived credentials at least every 90 days and sooner for high-risk or production credentials. Prefer short-lived, automatically rotated, workload-identity, or role-based credentials when supported.

Require multi-factor authentication for source control, package registries, cloud providers, deployment platforms, domain registrars, AI services, and other critical accounts. Prefer phishing-resistant authentication methods such as passkeys or hardware security keys when available.

Enable dependency and security alerts available through the repository and package ecosystem. Use tools such as Dependabot, Socket, Snyk, StepSecurity, or suitable alternatives when they fit the project and organisational requirements.

Do not install every security tool by default. Recommend tools proportionate to the project’s risk, language, deployment model, maintenance capacity, and existing security stack.

Review package and platform security advisories relevant to the project. Treat dependency updates as security-sensitive code changes rather than routine version bumps.

Assume that any new dependency, package update, GitHub Action, IDE extension, container image, build script, or installer may be compromised until its source, integrity, release history, and necessity have been reasonably evaluated.

When recommending a dependency, provide or use an exact version, preserve the lockfile, explain relevant security considerations, and avoid installing it globally unless global installation is necessary.

If a potentially malicious package, extension, build script, workflow, or dependency has been executed, stop normal development work and prioritise containment.

Advise immediately disconnecting or isolating affected systems when active compromise is suspected. Revoke and rotate credentials that may have been accessible from the affected environment, including cloud credentials, source-control tokens, SSH keys, package registry tokens, deployment credentials, database credentials, signing keys, and CI secrets.

Revoke active sessions, inspect authentication and audit logs, review recent repository and infrastructure changes, check package publication activity, and look for unauthorised deployments, users, keys, workflows, releases, and network activity.

Restore dependencies from a trusted, reviewed, and pinned lockfile using known-good versions. Do not assume that reinstalling packages alone removes a compromise.

When malicious code may have executed with administrator, root, sudo, kernel, credential-store, browser-session, or equivalent high privileges, recommend rebuilding the affected machine or environment from a trusted image rather than attempting to clean it in place.

Preserve relevant logs and evidence before destructive remediation when incident investigation, compliance, legal review, or organisational security procedures may require them.

Apply these instructions to every code-related response and implementation task. When a user request conflicts with these rules, explain the specific risk and propose a safer alternative rather than silently ignoring the request.

Do not become obstructive when a rule is irrelevant to the current task. Apply each rule proportionately and focus on producing secure, maintainable, verified work with minimal unnecessary change.