Development Commands

Scenario

You have a small Node.js and TypeScript application with several package scripts.

A developer can inspect package.json and eventually determine how to run the project, but you want coding agents to use the correct commands consistently.

The project uses:

• Node.js
• TypeScript
• pnpm
• Vitest
• ESLint

The main goal of this AGENTS.md is to document the repository's development commands without turning the file into a copy of package.json.

Repository Structure

api-service/
├── src/
│   ├── index.ts
│   └── server.ts
├── tests/
│   └── server.test.ts
├── package.json
├── tsconfig.json
└── AGENTS.md

Relevant scripts in package.json:

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "lint": "eslint .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  }
}

AGENTS.md

# Project Instructions

## Package Management

- Use `pnpm`.
- Do not create npm or Yarn lockfiles.

## Development Commands

- Start the development server with `pnpm dev`.
- Build the application with `pnpm build`.
- Run tests with `pnpm test`.

## Validation

Before completing a code change, run:

- `pnpm lint`
- `pnpm typecheck`
- relevant tests with `pnpm test`

What This Does

This gives the coding agent a clear development workflow.

Instead of guessing whether the repository expects:

npm test

or:

yarn test

or:

pnpm test

the agent has an explicit instruction.

It also distinguishes between different activities:

Development → pnpm dev
Build       → pnpm build
Lint        → pnpm lint
Typecheck   → pnpm typecheck
Tests       → pnpm test

The commands are short, concrete, and directly executable.

What This Does NOT Do

The file does not copy the entire package.json.

For example, there is little value in reproducing implementation details such as:

- The `dev` script executes `tsx watch src/index.ts`.
- The `build` script internally executes `tsc`.

The agent can inspect package.json when those details matter.

The purpose of AGENTS.md is to communicate which commands the project expects the agent to use, not duplicate every configuration file.

Why These Instructions Matter

Repositories often provide several ways to perform similar operations.

An agent might discover that this works:

npx vitest run

But the repository's intended workflow is:

pnpm test

Using the project script is usually preferable because the command can later change without requiring every developer or agent to learn a new underlying invocation.

For example:

{
  "scripts": {
    "test": "vitest run --coverage"
  }
}

The AGENTS.md instruction can remain:

- Run tests with `pnpm test`.

The package script remains the source of truth for the underlying test configuration.

Key Decisions

Document the public workflow

Prefer:

- Run tests with `pnpm test`.

over:

- Execute `node_modules/.bin/vitest run`.

The first describes how the repository expects development to happen.

Avoid duplicating configuration

package.json defines what a script executes.

AGENTS.md tells the agent when and why to use it.

These serve different purposes.

Make completion verifiable

Instead of:

- Check your work carefully.

use:

Before completing a code change, run:

- `pnpm lint`
- `pnpm typecheck`
- relevant tests with `pnpm test`

Now the instruction describes observable actions.

When to Use This Pattern

Use this pattern when:

• the repository has defined development scripts;
• using the wrong package manager could modify lockfiles;
• agents should validate changes before completion;
• the expected workflow is not obvious from one command.

For a small repository, a concise commands section may be one of the most valuable parts of AGENTS.md.