chore: add and example of AGENTS.md guidelines

Author: jsynowiec

AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md
+
+## Ground rules (always)
+- Be conservative, explicit, and boring.
+- When unsure, ask; don’t guess.
+- Make minimal, targeted changes; avoid refactors unless requested/necessary.
+- Preserve existing structure, conventions, and tooling.
+- Don’t add dependencies without strong justification.
+
+## TypeScript
+- Write strict, idiomatic TS; follow the repo’s tsconfig and lint rules.
+- No `any` (use `unknown`, generics, or proper types).
+- Prefer `interface` for public shapes; `type` for unions/helpers.
+- Prefer immutability (`readonly`, `ReadonlyArray`) where practical.
+- Narrow with type guards; avoid assertions and `!` except as a last resort.
+- Prefer exhaustive handling (`never` checks) for unions.
+- Treat caught errors as `unknown` and narrow before use.
+
+## Node.js
+- Target the repo’s supported Node LTS (don’t assume versions; check config/docs).
+- Prefer `async/await`; never swallow rejections.
+- Avoid module top-level side effects (I/O, network, reading env, global mutations) unless explicitly intended.
+- Env vars: validate centrally; read at runtime (not import-time); don’t mutate in app code (tests only with scoped setup/teardown).
+- Error handling: rethrow with context; preserve `cause` when available; don’t throw strings.
+- Library code should not log; CLIs may log intentionally with consistent exit codes.
+
+## Testing (Vitest)
+- New logic requires tests unless truly trivial (types-only, re-exports, comments/formatting).
+- Tests must be deterministic and isolated; avoid shared mutable state.
+- Prefer behavioral tests; mock sparingly.
+- No committed `.only`/`.skip` (unless explicitly justified).
+- Bug fixes must include a regression test.
+- Avoid snapshots unless they add clear value and are stable.
+
+## Style, docs, and security
+- Follow existing formatting/lint; keep functions small and readable.
+- Prefer named exports.
+- Update docs/comments when behavior changes (comments explain “why”, not “what”).
+- Never log secrets; validate/sanitize external inputs (paths/URLs/user data).
+- Dependency adds must be justified (need, alternatives, maintenance/license/security impact).
+
+## MUST NOT
+- Change public APIs or introduce breaking changes without explicit instruction.
+- Perform stylistic rewrites or micro-optimizations.
+
+## Verify before committing
+- Typecheck + lint + tests pass.
+- New behavior has coverage (including failure paths); no unintended snapshot changes.
+- No unnecessary diff churn; no accidental top-level side effects; env usage is validated and intentional.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -21,6 +21,7 @@
 - Reproducible environments thanks to [Volta][volta]
 - Example configuration for [GitHub Actions][gh-actions]
 - Simple example of TypeScript code and unit test
+- Basic [AGENTS.md][agents-md] guidelines for agents
 
 🤲 Free as in speech: available under the APLv2 license.
 
@@ -79,11 +80,15 @@ In 2023, my team and I gradually switched from Jest to [Vitest][vitest] in all t
 
 Nevertheless, the choice of specific tooling always depends on the specific requirements and characteristics of the project.
 
-### ES Modules
+### Why AGENTS.md over individual configs
+
+The [AGENTS.md][agents-md] format has emerged as a community-driven standard, stewarded by the Agentic AI Foundation under the Linux Foundation. It is the closest thing to a universal config file, promoting consistency across AI coding tools.
 
-This template uses native [ESM][esm]. Make sure to read [this][nodejs-esm], and [this][ts47-esm] first.
+The included guidelines are just an example. You should write your own, project-specific context and instructions.
+
+### ES Modules
 
-If your project requires CommonJS, you will have to [convert to ESM][sindresorhus-esm].
+This template uses native [ESM][esm]. Make sure to read [this][nodejs-esm], and [this][ts47-esm] first. If your project requires CommonJS, you will have to [convert to ESM][sindresorhus-esm].
 
 Please do not open issues for questions regarding CommonJS or ESM on this repo.
 
@@ -119,3 +124,4 @@ Licensed under the APLv2. See the [LICENSE](https://github.com/jsynowiec/node-ty
 [ts47-esm]: https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/#esm-nodejs
 [editorconfig]: https://editorconfig.org
 [vitest]: https://vitest.dev
+[agents-md]: https://agents.md