# AGENTS.md Update Guidelines

## Core Principle

Only add information that will genuinely help future Codex sessions. The context window is precious; every line must earn its place.

## What To Add

### Commands and Workflows Discovered

```markdown
## Commands

`npm run build` - Production build.
`npm run lint` - ESLint check required before handoff.
```

Why: saves future sessions from rediscovering commands.

### Gotchas and Non-Obvious Patterns

```markdown
## Gotchas

- Tests must run sequentially because they share a local database.
- Regenerate API clients with `npm run codegen` after editing OpenAPI files.
```

Why: prevents repeated debugging.

### Package Relationships

```markdown
## Architecture

- `packages/api` owns route handlers; `packages/ui` must call it through the shared client.
```

Why: captures relationships that are not obvious from filenames.

### Testing Approaches That Worked

```markdown
## Testing

- API endpoint tests use `tests/helpers/request.ts`; avoid ad hoc server setup.
```

Why: establishes known-good patterns.

### Configuration Quirks

```markdown
## Environment

- `NEXT_PUBLIC_*` variables must be set at build time.
```

Why: environment details often waste time when omitted.

## What Not To Add

### Obvious Code Info

Bad:

```markdown
The `UserService` class handles user operations.
```

The class name already says that.

### Generic Best Practices

Bad:

```markdown
Always write tests for new features.
Use meaningful variable names.
```

Add only project-specific rules.

### One-Off Fixes

Bad:

```markdown
We fixed a bug where the login button did not work.
```

Unless the lesson is durable, leave it out.

### Verbose Explanations

Bad:

```markdown
The authentication system uses JWT tokens. JWT means JSON Web Token...
```

Good:

```markdown
Auth: JWT HS256 tokens in `Authorization: Bearer <token>`.
```

## Diff Format

For each suggested change:

```markdown
### Update: ./AGENTS.md

**Why:** The build command exists but was missing from project instructions.

```diff
+## Commands
+
+`npm run build` - Production build.
```
```

## Validation Checklist

- Each addition is project-specific.
- No generic advice or obvious info.
- Commands are verified against the repo.
- File paths are accurate.
- The wording is concise.
- A new Codex session would benefit from the line.