# Reusable AGENTS.md for agent-assisted projects > Source: > Published: 2026-05-22 11:04:20+00:00 Reusable defaults for agent-assisted projects. Repo-local instructions, user requests, and project docs override this file. - Inspect the workspace before assuming the stack, scripts, or architecture. - Prefer rg andrg --files for search. - Read README.md ,CONTRIBUTING.md ,CODING-GUIDELINES.md , and project specs when they exist. - Use the repo's package scripts and helper commands before inventing one-off commands. - Do not overwrite, revert, or discard user changes unless explicitly asked. - If a decision is hard to reverse, pause and confirm. Otherwise make the reasonable call and keep moving. - Build in small, working increments. - Keep changes focused on the requested behavior and the surrounding ownership boundary. - Prefer clear, boring code over clever abstractions. - Add an abstraction only when it removes real duplication or matches an existing local pattern. - Keep modules small and names specific. Avoid vague helpers ,utils ,consts , andmisc buckets. - Use direct, concise language. Prefer clarity over perfect grammar. - Use team language in project guidance and handoffs: we andour overI andyou . - Treat please and thanks as implicit. - Prefer small, frequent commits at coherent checkpoints. - Use Conventional Commits: feat: ,fix: ,test: ,docs: ,refactor: ,chore: . - Suggest a commit when a logical slice is complete and verified. - Do not commit directly to main unless the repo explicitly allows it. - When fixing merge conflicts, prefer rebasing the feature branch on the latest main , resolving conflicts there, and continuing with a clean linear history. - Always squash-merge pull requests unless the repo explicitly requires a different merge strategy. - Always clean up local feature branches after merge. - PR descriptions should be clean Markdown summaries, not pasted terminal dumps. - When editing PR bodies from the CLI, use a body file or another shell-safe path so Markdown newlines render correctly. - Reply to review comments and close resolved review threads when working on PR feedback. - When deferring review feedback, add a TODO only if the follow-up belongs in code/docs. Otherwise capture it in the PR, issue, or review reply. - After merges, start the next chore from a fresh branch. - Prefer pnpm overnpm andnpx for JavaScript projects unless the repo says otherwise. - Prefer Biome for formatting/linting, Vitest for tests, and Zod at runtime boundaries when starting TypeScript work. - Prefer modern TypeScript, ESM, strict types, and small folder-first modules. - Keep implementation and tests adjacent when the codebase supports it, for example src/lib/thing/index.ts andsrc/lib/thing/index.test.ts . - Prefer package scripts such as pnpm test ,pnpm typecheck , andpnpm lint over long ad hoc shell commands. - Keep shared agent/tool config portable. Do not commit absolute local paths or machine-specific trust settings. - Match the existing codebase before introducing new structure. - Keep orchestration thin; put behavior in focused modules with clear ownership. - Use named constants or config for tuning values, dimensions, thresholds, and other magic numbers. - Put schemas and compatibility decisions first when changing API contracts. - Validate data at boundaries: request params, environment variables, external API responses, file formats, and generated data. - Prefer deterministic behavior for generators, simulations, tests, and fixtures. Document exceptions. - Keep generated output, caches, state files, credentials, and local artifacts out of version control. - Do not commit secrets. Use environment, platform config, or an approved secret manager. - Prefer TDD for new behavior: failing test, minimal implementation, refactor with tests green. - Run the narrowest useful checks for the files changed. - For shared code or contract changes, broaden verification to cover affected consumers. - For UI, game, graphics, firmware, and mobile work, include visual or device/simulator verification when practical. - For infrastructure, deployment, and destructive operations, follow the repo docs as a first-time user. Do not rely on memory or local shortcuts. - Report exactly what was run and what remains unverified. - If tests cannot run, say why and identify the best next verification step. - Keep AGENTS.md short and durable. - Do not add branch names, feature numbers, transient status, or Recent Changes sections to reusable agent guidance. - Move human workflow to CONTRIBUTING.md and shared coding conventions toCODING-GUIDELINES.md when those files exist. - Update docs, examples, schemas, and quickstarts in the same slice as behavior changes. - Use long command flags in documentation examples when readability matters. - End with what changed, what was verified, and any assumptions or follow-ups. - Be brief. High signal beats ceremony.