{"slug": "reusable-agents-md-for-agent-assisted-projects", "title": "Reusable AGENTS.md for agent-assisted projects", "summary": "Comprehensive set of reusable defaults and guidelines for AI agents working on software projects. It instructs agents to inspect the workspace, prefer specific search and package tools, and follow project documentation, while emphasizing small, focused commits, clear code, and careful handling of user changes. The guide also covers best practices for version control, pull requests, testing, and code organization, with specific tool preferences for JavaScript and TypeScript projects.", "body_md": "Reusable defaults for agent-assisted projects. Repo-local instructions, user requests, and project docs override this file.\n- Inspect the workspace before assuming the stack, scripts, or architecture.\n- Prefer\nrg\nandrg --files\nfor search. - Read\nREADME.md\n,CONTRIBUTING.md\n,CODING-GUIDELINES.md\n, and project specs when they exist. - Use the repo's package scripts and helper commands before inventing one-off commands.\n- Do not overwrite, revert, or discard user changes unless explicitly asked.\n- If a decision is hard to reverse, pause and confirm. Otherwise make the reasonable call and keep moving.\n- Build in small, working increments.\n- Keep changes focused on the requested behavior and the surrounding ownership boundary.\n- Prefer clear, boring code over clever abstractions.\n- Add an abstraction only when it removes real duplication or matches an existing local pattern.\n- Keep modules small and names specific. Avoid vague\nhelpers\n,utils\n,consts\n, andmisc\nbuckets. - Use direct, concise language. Prefer clarity over perfect grammar.\n- Use team language in project guidance and handoffs:\nwe\nandour\noverI\nandyou\n. - Treat please and thanks as implicit.\n- Prefer small, frequent commits at coherent checkpoints.\n- Use Conventional Commits:\nfeat:\n,fix:\n,test:\n,docs:\n,refactor:\n,chore:\n. - Suggest a commit when a logical slice is complete and verified.\n- Do not commit directly to\nmain\nunless the repo explicitly allows it. - When fixing merge conflicts, prefer rebasing the feature branch on the latest\nmain\n, resolving conflicts there, and continuing with a clean linear history. - Always squash-merge pull requests unless the repo explicitly requires a different merge strategy.\n- Always clean up local feature branches after merge.\n- PR descriptions should be clean Markdown summaries, not pasted terminal dumps.\n- When editing PR bodies from the CLI, use a body file or another shell-safe path so Markdown newlines render correctly.\n- Reply to review comments and close resolved review threads when working on PR feedback.\n- 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.\n- After merges, start the next chore from a fresh branch.\n- Prefer\npnpm\novernpm\nandnpx\nfor JavaScript projects unless the repo says otherwise. - Prefer Biome for formatting/linting, Vitest for tests, and Zod at runtime boundaries when starting TypeScript work.\n- Prefer modern TypeScript, ESM, strict types, and small folder-first modules.\n- Keep implementation and tests adjacent when the codebase supports it, for example\nsrc/lib/thing/index.ts\nandsrc/lib/thing/index.test.ts\n. - Prefer package scripts such as\npnpm test\n,pnpm typecheck\n, andpnpm lint\nover long ad hoc shell commands. - Keep shared agent/tool config portable. Do not commit absolute local paths or machine-specific trust settings.\n- Match the existing codebase before introducing new structure.\n- Keep orchestration thin; put behavior in focused modules with clear ownership.\n- Use named constants or config for tuning values, dimensions, thresholds, and other magic numbers.\n- Put schemas and compatibility decisions first when changing API contracts.\n- Validate data at boundaries: request params, environment variables, external API responses, file formats, and generated data.\n- Prefer deterministic behavior for generators, simulations, tests, and fixtures. Document exceptions.\n- Keep generated output, caches, state files, credentials, and local artifacts out of version control.\n- Do not commit secrets. Use environment, platform config, or an approved secret manager.\n- Prefer TDD for new behavior: failing test, minimal implementation, refactor with tests green.\n- Run the narrowest useful checks for the files changed.\n- For shared code or contract changes, broaden verification to cover affected consumers.\n- For UI, game, graphics, firmware, and mobile work, include visual or device/simulator verification when practical.\n- For infrastructure, deployment, and destructive operations, follow the repo docs as a first-time user. Do not rely on memory or local shortcuts.\n- Report exactly what was run and what remains unverified.\n- If tests cannot run, say why and identify the best next verification step.\n- Keep\nAGENTS.md\nshort and durable. - Do not add branch names, feature numbers, transient status, or\nRecent Changes\nsections to reusable agent guidance. - Move human workflow to\nCONTRIBUTING.md\nand shared coding conventions toCODING-GUIDELINES.md\nwhen those files exist. - Update docs, examples, schemas, and quickstarts in the same slice as behavior changes.\n- Use long command flags in documentation examples when readability matters.\n- End with what changed, what was verified, and any assumptions or follow-ups.\n- Be brief. High signal beats ceremony.", "url": "https://wpnews.pro/news/reusable-agents-md-for-agent-assisted-projects", "canonical_source": "https://gist.github.com/alangorton/21721a7070afe1daf2108ee3d5df92d5", "published_at": "2026-05-22 11:04:20+00:00", "updated_at": "2026-05-22 11:06:50.614706+00:00", "lang": "en", "topics": ["developer-tools", "open-source", "artificial-intelligence", "large-language-models"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/reusable-agents-md-for-agent-assisted-projects", "markdown": "https://wpnews.pro/news/reusable-agents-md-for-agent-assisted-projects.md", "text": "https://wpnews.pro/news/reusable-agents-md-for-agent-assisted-projects.txt", "jsonld": "https://wpnews.pro/news/reusable-agents-md-for-agent-assisted-projects.jsonld"}}