Minimal AGENTS.md

Scenario

You have a small TypeScript project and want an AI coding agent to work in the repository without guessing the basic development workflow.

The project is simple:

• TypeScript
• pnpm
• ESLint
• Vitest

You don't need a large AGENTS.md. You only need to tell the agent the project-specific things it cannot reliably infer.

Repository Structure

my-app/
├── src/
│   ├── index.ts
│   └── utils.ts
├── tests/
│   └── utils.test.ts
├── package.json
├── tsconfig.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## Development

- Use `pnpm` for dependency management.
- Run the application with `pnpm dev`.

## Code

- Write new source code in TypeScript.
- Keep reusable utilities in `src/utils.ts` or an appropriate module under `src/`.
- Follow the existing naming and file organization patterns.

## Testing

- Run relevant tests with `pnpm test`.
- Add or update tests when behavior changes.

## Validation

Before completing a task, run:

- `pnpm lint`
- `pnpm test`

What This Does

This gives the coding agent a small set of repository-specific operating instructions.

The agent now knows:

• which package manager to use;
• where source code belongs;
• that behavioral changes should include tests;
• which validation commands should run before the task is considered complete.

Without these instructions, an agent may still successfully modify the project, but it has to infer more of the workflow from the repository.

What This Does NOT Do

This file does not explain TypeScript, ESLint, Vitest, or general programming practices.

It also does not describe every directory or every possible development task.

For example, instructions such as these would usually add little value:

- Use variables to store values.
- Write readable TypeScript.
- Avoid bugs.
- Use functions when appropriate.

Those are generic expectations rather than useful repository-specific instructions.

Why These Instructions Matter

A useful AGENTS.md reduces unnecessary decisions.

Consider package management.

If the repository uses pnpm but the agent runs:

npm install

it may create an unwanted package-lock.json or produce dependency changes inconsistent with the repository.

The instruction:

- Use `pnpm` for dependency management.

removes that ambiguity with one line.

The same principle applies to testing and validation.

The goal is not to tell the agent everything.

The goal is to tell it the things that matter in this repository.

Key Decisions

Keep the file small

A small project usually needs a small AGENTS.md.

Do not add sections simply because they appear in somebody else's template.

Prefer real commands

Instead of:

- Make sure the project works.

use:

- Run `pnpm lint`.
- Run `pnpm test`.

The second version is actionable and verifiable.

Document project-specific expectations

The most valuable instructions describe decisions the agent could otherwise get wrong.

In this example:

- Use `pnpm`.

is more useful than:

- Write good TypeScript.

When to Use This Pattern

Use this pattern for small repositories where:

• there is one application or package;
• the development workflow is straightforward;
• most instructions apply to the entire repository;
• there are few architectural boundaries;
• nested AGENTS.md files are unnecessary.

Start small.

As the repository becomes more complex, add instructions only when there is a concrete reason to do so.