Set Up Agent Instructions for a Node.js Monorepo

Problem/Feature Description

A mid-size engineering team is setting up their monorepo for use with AI coding agents. The monorepo contains several packages — a core API server, a background job worker, a shared utilities library, and a CLI tool — all sharing a common TypeScript configuration and a workspace-level package.json. The team has been using AI agents for routine tasks like adding endpoints and fixing bugs, but agents keep making the same avoidable mistakes: running the wrong test command for individual packages, touching the legacy payments/ directory that is still imported in production despite being deprecated, using npm install instead of the workspace-aware npm install -w <pkg>, and not knowing that the job-worker package requires a local Redis instance before tests will pass.

The tech lead wants to create an AGENTS.md file that will prevent these recurring issues. She has also been told that good agent instructions files should be short and focused — previous attempts by other teams were long documents that agents largely ignored because they were filled with information derivable from reading the code.

Your job is to create AGENTS.md (and any module-level AGENTS files you recommend) based on the project information below. The instructions should help agents work effectively without duplicating what is already visible in the codebase.

Output Specification

Produce the following files:

• AGENTS.md — root-level agent instructions
• Any additional module-level AGENTS.md files you decide are appropriate (e.g., job-worker/AGENTS.md)

Input Files

The following information describes the project. Extract it before beginning.

=============== FILE: project-info.txt =============== Repository layout: packages/ api-server/ - Fastify REST API, TypeScript job-worker/ - Background job processor, TypeScript shared/ - Shared utilities and types cli/ - Command line tool payments/ - DEPRECATED: Legacy Stripe integration. Do NOT modify. Still imported by api-server at runtime. package.json - Workspace root (npm workspaces) tsconfig.base.json - Shared TypeScript config extended by all packages

Tech stack: Node.js 22, TypeScript 5, Fastify, BullMQ, PostgreSQL, Redis

Build/test commands: Root: npm test runs ALL packages (slow, use for final check only) Per-package: npm test -w packages/<pkg> runs just that package Per-package install: npm install -w packages/<pkg> <dependency> Type checking: tsc -b from the root (builds all package tsconfigs in dependency order) The api-server package has a seed script: npm run seed -w packages/api-server — this MUST be run after any schema migration The job-worker package tests require a local Redis instance running on port 6379; they will hang silently (not fail) if Redis is unavailable Do NOT run npm install from a package directory — it breaks the workspace symlinks

Known do-not-touch areas: payments/ directory: deprecated but still used in production. Modifying it risks breaking live billing. A full replacement is planned for Q3. packages/shared/src/legacy-compat.ts: backward-compat shim imported by external consumers. Do not remove exports from this file.

Non-obvious conventions: Database migrations live in packages/api-server/migrations/ and are run with npm run migrate -w packages/api-server Environment files: each package reads its own .env file (not a root .env). Copy from the corresponding .env.example. The CLI package must be built before testing: npm run build -w packages/cli && npm test -w packages/cli tsconfig.base.json is the source of truth for TypeScript settings — do not modify per-package tsconfig.json compiler options without updating the base first