Coding Conventions

Scenario

You have a TypeScript application with established coding patterns.

The formatter and linter already handle mechanical concerns such as whitespace and basic syntax rules.

However, the repository also follows conventions that are not fully enforced by tooling.

For example:

• React components use named exports;
• reusable types live close to the feature that owns them;
• files use kebab-case;
• new code should follow existing feature organization.

You want coding agents to follow these conventions without filling AGENTS.md with generic style advice.

Repository Structure

web-app/
├── src/
│   ├── features/
│   │   ├── users/
│   │   │   ├── user-card.tsx
│   │   │   ├── user-list.tsx
│   │   │   └── types.ts
│   │   └── billing/
│   └── shared/
│       └── components/
├── eslint.config.js
├── prettier.config.js
└── AGENTS.md

AGENTS.md

# Project Instructions

## Code Organization

- Keep feature-specific code inside the owning directory under `src/features`.
- Keep code shared by multiple features under `src/shared`.
- Prefer adding code to an existing feature before creating a new top-level directory.

## Naming

- Use kebab-case for new source filenames.
- Follow existing naming patterns when modifying an established module.

## React

- Use named exports for reusable React components.
- Keep feature-specific component types close to the feature that owns them.

## Formatting

- Do not manually introduce formatting conventions that conflict with the configured formatter or linter.
- Run `pnpm lint` before completing a code change.

What This Does

This documents conventions that influence how new code fits into the repository.

For example, an agent creating a component for the users feature should prefer:

src/features/users/user-profile.tsx

rather than inventing:

src/components/UserProfile.tsx

if the project intentionally organizes product code by feature.

The instructions also communicate conventions such as:

- Use named exports for reusable React components.

These are project choices rather than universal React rules.

What This Does NOT Do

The file does not attempt to replace ESLint or Prettier.

Avoid instructions such as:

- Use two spaces for indentation.
- Add semicolons.
- Use double quotes.
- Keep lines below 100 characters.

when those rules are already enforced automatically.

Those rules belong in tooling configuration.

Likewise, avoid subjective instructions such as:

- Write elegant code.
- Use clean architecture.
- Make code readable.

They do not give the agent enough information to make a concrete decision.

Why These Instructions Matter

A coding agent can produce technically correct code that still feels foreign to the repository.

Imagine the existing project uses:

src/features/users/
src/features/billing/
src/features/projects/

but the agent creates:

src/components/
src/services/
src/models/

for one new feature.

The code may work, but the repository becomes less consistent.

The instruction:

- Keep feature-specific code inside the owning directory under `src/features`.

helps the agent extend the architecture already in use.

Key Decisions

Document conventions tooling cannot fully enforce

A formatter can enforce indentation.

It usually cannot decide whether:

user-card.tsx

belongs under:

features/users/

or:

shared/components/

That is where repository guidance becomes valuable.

Describe observable conventions

Prefer:

- Use kebab-case for new source filenames.

over:

- Use consistent filenames.

The first instruction tells the agent what consistency means.

Respect existing code

Repositories often contain exceptions.

That is why:

- Follow existing naming patterns when modifying an established module.

can be safer than demanding that an agent rename older code while completing an unrelated task.

Avoid turning preferences into unnecessary rules

Only document conventions that matter to the repository.

If both named and default exports are intentionally used, there is no reason to invent a rule simply to make AGENTS.md look more complete.

When to Use This Pattern

Use this pattern when a repository has meaningful conventions around:

• file organization;
• naming;
• component structure;
• module ownership;
• exports;
• shared versus feature-specific code.

Let automated tools enforce mechanical style.

Use AGENTS.md for conventions that require context and judgment.