Frontend + Backend Instructions

Scenario

You maintain a repository containing two applications:

• a React frontend;
• a Node.js backend.

Some instructions apply to the whole repository, but the applications have different architecture and validation requirements.

The root should define shared rules.

Each application should define only the additional guidance relevant to its area.

Repository Structure

product/
├── AGENTS.md
├── frontend/
│   ├── AGENTS.md
│   ├── src/
│   └── package.json
├── backend/
│   ├── AGENTS.md
│   ├── src/
│   └── package.json
├── pnpm-workspace.yaml
└── package.json

AGENTS.md

Root AGENTS.md:

# Repository Instructions

## Workspace

- Use `pnpm`.
- Run workspace installation from the repository root.
- Do not create npm or Yarn lockfiles.

## General Changes

- Keep frontend concerns inside `frontend/`.
- Keep backend concerns inside `backend/`.
- Put cross-application changes in both areas only when the feature genuinely requires them.

## Validation

- Validate every application affected by a change.

frontend/AGENTS.md:

# Frontend Instructions

## React

- Follow the existing feature organization under `src`.
- Keep reusable UI primitives in the existing shared UI area.
- Prefer existing components before introducing new shared primitives.

## API Usage

- Use the existing API client layer for backend requests.
- Do not make ad hoc HTTP requests from components when an appropriate client module exists.

## Validation

For frontend changes, run:

- `pnpm --dir frontend lint`
- `pnpm --dir frontend typecheck`
- `pnpm --dir frontend test`

backend/AGENTS.md:

# Backend Instructions

## Architecture

- Keep HTTP handlers thin.
- Put business logic in the existing service layer.
- Access persistence through repository modules.

## API Changes

- Validate external input using the existing validation layer.
- Preserve established API error-response conventions.

## Validation

For backend changes, run:

- `pnpm --dir backend lint`
- `pnpm --dir backend typecheck`
- `pnpm --dir backend test`

What This Does

The repository now has two levels of guidance.

The root answers questions such as:

Which package manager?
How is the repository divided?
Which applications should be validated?

The scoped files answer questions such as:

How should React code be organized?
How should backend business logic be structured?
Which commands validate this application?

This prevents frontend-specific rules from distracting an agent working only on the backend.

What This Does NOT Do

The scoped files should not copy the root file.

For example, both child files do not need:

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

if that rule already applies to the entire repository.

Likewise, the root file does not need detailed React or backend service-layer instructions.

Those rules are useful only within narrower areas.

Why These Instructions Matter

Imagine the root file contained everything:

React conventions
UI rules
API client rules
Express controllers
services
repositories
database conventions
frontend tests
backend tests

An agent making a small frontend change receives backend instructions that have nothing to do with its task.

As repositories grow, unnecessary instructions make it harder to identify what actually matters.

Scoping allows the repository to say:

These rules are universal.

and separately:

These rules matter only here.

Key Decisions

Root owns shared rules

Package-management and repository-wide expectations belong at the root.

Application files own specialized rules

React conventions belong with the frontend.

Service-layer conventions belong with the backend.

Cross-stack changes require both perspectives

Suppose a feature changes:

backend API contract
+
frontend API consumer

Both scopes matter because both applications are affected.

Avoid duplication

If a child file merely repeats the parent, it probably adds little value.

When to Use This Pattern

Use this pattern when:

• one repository contains frontend and backend applications;
• both share some development rules;
• each application has distinct architecture;
• validation differs by application;
• agents often work within only one side of the stack.

This is often the first useful step beyond a single root AGENTS.md.