Complete Small Project

Scenario

You have a small production API for managing tasks.

The project is large enough that a coding agent needs guidance about commands, architecture, testing, and boundaries, but small enough that everything can still be described in one root AGENTS.md.

The application uses:

• Node.js
• Express
• TypeScript
• PostgreSQL
• Zod
• Vitest
• pnpm

This example combines the ideas from the previous Foundation examples into one practical file.

Repository Structure

task-api/
├── src/
│   ├── routes/
│   │   └── tasks.ts
│   ├── services/
│   │   └── task-service.ts
│   ├── repositories/
│   │   └── task-repository.ts
│   ├── schemas/
│   │   └── task-schema.ts
│   └── server.ts
├── tests/
│   └── tasks.test.ts
├── migrations/
├── package.json
├── tsconfig.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## Development

- Use `pnpm`.
- Start the development server with `pnpm dev`.
- Do not create npm or Yarn lockfiles.

## Architecture

- Keep HTTP routing concerns under `src/routes`.
- Put application business logic under `src/services`.
- Access the database through modules under `src/repositories`.
- Keep request validation schemas under `src/schemas`.
- Do not query the database directly from route handlers.

## Validation

- Validate incoming API payloads using the existing Zod schemas.
- Preserve the existing API error-response format when changing endpoints.

## Database

- Do not modify an already-applied migration to change database behavior.
- Create a new migration for schema changes.

## Testing

- Add or update tests when API behavior changes.
- Add a regression test when fixing a reproducible bug.
- Run tests relevant to the changed behavior.

## Completion

Before completing a task, run:

- `pnpm lint`
- `pnpm typecheck`
- `pnpm test`

What This Does

This AGENTS.md gives the agent enough information to work effectively across the small application.

It covers five important areas:

Development → how to work with the repository
Architecture → where different responsibilities belong
Validation   → how API input is handled
Database     → how schema changes are made
Testing      → how behavior changes are verified

For example, if asked to add:

POST /tasks

the agent knows that the implementation should not simply place everything inside the route handler.

The expected flow is closer to:

Request
   ↓
Route
   ↓
Validation
   ↓
Service
   ↓
Repository
   ↓
Database

What This Does NOT Do

The file does not describe every implementation detail.

It does not specify:

• every database table;
• every endpoint;
• every Zod schema;
• every service function;
• every test case.

Those details belong in the code and supporting documentation.

It also avoids instructions such as:

- Always create an interface for every service.
- Every function must be less than 20 lines.
- Every file must contain only one function.

unless the project genuinely requires those constraints.

An AGENTS.md should help an agent fit into the project, not impose arbitrary complexity.

Why These Instructions Matter

This example shows how several small instructions work together during a real task.

Suppose the request is:

Add a due date to tasks.

The agent may need to change:

database schema
request validation
service logic
repository queries
tests

The database instruction tells it:

- Create a new migration for schema changes.

The architecture instructions tell it where persistence and business logic belong.

The validation instruction tells it to update the appropriate Zod schema.

The testing instructions tell it to verify the changed API behavior.

No individual instruction describes how to implement the entire feature.

Together, they establish the project's operating boundaries.

Key Decisions

One root file is enough

This project has several directories, but that does not automatically mean it needs nested AGENTS.md files.

The current rules are small enough and broad enough to remain understandable in one root file.

Architecture instructions describe responsibilities

Instead of saying:

- Put task code in `task-service.ts`.

the file says:

- Put application business logic under `src/services`.

This remains useful when the project gains additional services.

Database changes have a workflow

The instruction:

- Do not modify an already-applied migration to change database behavior.
- Create a new migration for schema changes.

protects migration history while still telling the agent how to proceed.

Bug fixes include regression protection

When a reproducible bug is fixed, a regression test helps ensure the same behavior does not accidentally return later.

That is more actionable than simply saying:

- Test your bug fixes.

Completion has a concrete definition

The agent does not have to guess what "make sure everything works" means.

For this repository, baseline validation is explicitly:

pnpm lint
pnpm typecheck
pnpm test

When to Use This Pattern

Use this pattern when:

• one repository contains a small application;
• the architecture has several clear layers;
• most instructions apply across the whole project;
• there are important database or validation workflows;
• a single root AGENTS.md remains easy to understand.

As the project grows, some instructions may become specific to individual areas.

At that point, consider introducing scoped AGENTS.md files rather than continuously expanding the root file.