CDX-201a · Module 1

Section Anatomy & Best Practices

4 min read

A well-structured AGENTS.md has distinct sections that serve different purposes: project overview (what this codebase is), architecture (how it is organized), commands (how to build, test, lint, deploy), conventions (naming, patterns, idioms), and rules (hard constraints the agent must never violate). Each section gives Codex a different kind of context — overview helps with orientation, architecture helps with file navigation, commands enable self-validation, conventions guide style, and rules set guardrails.

The difference between a convention and a rule matters. Conventions are preferred patterns — "use PascalCase for components" — that Codex should follow but can deviate from with good reason. Rules are hard constraints — "never modify migration files after commit" — that Codex must not break under any circumstances. Mixing the two weakens both: if everything is a rule, nothing is.

# E-Commerce Platform

## Architecture
- Monorepo: apps/web, apps/api, packages/shared
- Web: Next.js 15 + TypeScript strict
- API: Express + Prisma + PostgreSQL
- Shared: Zod schemas, utility functions

## Commands
- `pnpm test` — run all tests
- `pnpm lint` — ESLint + Prettier
- `pnpm build` — full production build
- `pnpm db:migrate` — apply pending Prisma migrations

## Conventions
- One component per file, PascalCase filenames
- Business logic in services/, never in route handlers
- All API responses use the ResponseEnvelope type

## Rules
- NEVER modify committed migration files
- NEVER skip TypeScript strict checks
- Always add a test when adding a new API endpoint
- Never store secrets in source — use environment variables

Do This

  • Separate conventions (preferred) from rules (mandatory)
  • Include build/test/lint commands so Codex can self-validate
  • Use ## headings to create scannable sections
  • Keep each rule specific and actionable — "never use any types" beats "write clean code"

Avoid This

  • Dump your entire README into AGENTS.md
  • Write vague rules like "follow best practices"
  • Mix architecture docs with behavioral rules — they serve different purposes
  • Omit commands — Codex cannot self-validate without them