creating-agents-md

Overview

The agents.md format provides project-specific context for AI coding assistants. It's the simplest format: plain markdown only with NO YAML frontmatter, NO special syntax.

CRITICAL:

• No frontmatter - Pure markdown only (no YAML)
• Free-form content - No required structure
• Single file - Typically agents.md in project root

Quick Reference

| Aspect | Requirement | |--------|-------------| | Format | Plain markdown | | Frontmatter | None (forbidden) | | Structure | Free-form | | File location | agents.md in project root |

Creating agents.md Files

Plain markdown with no frontmatter:

# TaskMaster Development Guide

## Project Overview

TaskMaster is a task management application for remote teams, built with real-time collaboration features and offline-first architecture.

## Architecture

### Frontend

- React 18 with TypeScript
- Vite for build tooling
- Zustand for state management
- React Query for server state
- Tailwind CSS for styling

### Backend

- Node.js with Express
- PostgreSQL with Prisma ORM
- WebSocket for real-time features
- Redis for caching and pub/sub
- JWT for authentication

## Coding Conventions

- Use TypeScript strict mode
- Functional components with hooks (no class components)
- Server components by default in Next.js
- Colocate tests with source files (*.test.tsx)
- Use Zod for runtime validation

## File Structure

\`\`\`
src/
  components/     # Reusable UI components
  features/       # Feature-based modules
  hooks/          # Custom React hooks
  lib/            # Utility functions
  pages/          # Route pages
  types/          # TypeScript types
\`\`\`

## Development Workflow

1. Create feature branch from `main`
2. Write tests first (TDD)
3. Implement feature
4. Run `pnpm test` and `pnpm lint`
5. Create PR with description
6. Merge after approval

## Testing

- Use Vitest for unit tests
- Use Playwright for E2E tests
- Aim for 80% coverage on new code
- Mock external dependencies

What to Include

Focus on project-specific information AI doesn't already know:

High Priority:

• Project overview and purpose
• Architecture decisions and patterns
• Tech stack and dependencies
• File structure and organization
• Coding conventions
• Development workflow
• Testing approach
• Domain knowledge and business logic

Skip:

• General programming best practices
• Language syntax explanations
• Framework basics
• Obvious code quality rules

Example: Backend API Project

# Payment Gateway API

## Overview

RESTful API for payment processing with support for multiple payment providers.

## Tech Stack

- Node.js 20.x
- Express
- PostgreSQL 15
- Redis for rate limiting
- Stripe and PayPal integrations

## API Design

### Endpoints

All endpoints follow REST conventions:

- `GET /api/payments` - List payments
- `GET /api/payments/:id` - Get payment details
- `POST /api/payments` - Create payment
- `PUT /api/payments/:id` - Update payment
- `DELETE /api/payments/:id` - Cancel payment

### Error Handling

Return consistent error format:

\`\`\`json
{
  "error": {
    "code": "PAYMENT_FAILED",
    "message": "Payment could not be processed",
    "details": {...}
  }
}
\`\`\`

## Security

- All endpoints require JWT authentication
- Rate limiting: 100 requests/minute per IP
- Input validation with Zod schemas
- SQL injection prevention via Prisma
- PCI DSS compliance for payment data

## Database

### Conventions

- Use snake_case for table/column names
- Add timestamps (created_at, updated_at) to all tables
- Use UUIDs for primary keys
- Foreign keys follow `{table}_id` pattern

Example: Frontend Component Library

# Design System Components

A React component library following Atomic Design principles.

## Component Structure

All components follow this structure:

\`\`\`
ComponentName/
  ComponentName.tsx       # Main component
  ComponentName.test.tsx  # Tests
  ComponentName.stories.tsx # Storybook stories
  index.ts                 # Exports
\`\`\`

## Styling

- Use Tailwind CSS utility classes
- Create custom classes in `styles/components/` for complex components
- Follow BEM naming for custom classes
- Responsive by default (mobile-first)

## TypeScript

\`\`\`typescript
// Good: Explicit prop types
interface ButtonProps {
  variant: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

export function Button({ variant, size = 'md', ...props }: ButtonProps) {
  return <button className={cn(variants[variant], sizes[size])} {...props} />;
}
\`\`\`

## Accessibility

- All interactive elements must be keyboard accessible
- Use semantic HTML (button, nav, main, etc.)
- Include ARIA labels for icon-only buttons
- Test with screen readers
- Maintain minimum 4.5:1 contrast ratio

Content Format

Free-form markdown including:

• Project overview: Purpose and goals
• Architecture notes: Technical decisions and patterns
• Conventions: Coding standards and practices
• Context: Domain knowledge and business logic
• Workflows: Development processes
• File structure: Directory organization
• Dependencies: Key libraries and tools

Common Mistakes

| Mistake | Fix | |---------|-----| | Adding YAML frontmatter | No frontmatter allowed - plain markdown only | | Generic best practices | Focus on project-specific patterns | | Verbose explanations | Be concise, AI already knows general concepts | | Language tutorials | Skip basics, focus on project conventions | | Missing context | Include domain knowledge and business logic |

Writing Style

Concise (Good):

## Testing

- Vitest for unit tests
- Playwright for E2E
- 80% coverage target
- Mock external dependencies

Verbose (Bad):

## Testing

When you are writing tests, it's important to understand that we use Vitest
for our unit tests because it's fast and modern. For end-to-end testing,
we have chosen to use Playwright because it provides excellent cross-browser
support and has a great developer experience...

File Placement

Typically in project root:

project-root/
  agents.md           # Main file
  src/
  tests/
  package.json

Can also be in subdirectories for monorepos:

monorepo/
  packages/
    frontend/
      agents.md       # Frontend-specific context
    backend/
      agents.md       # Backend-specific context

Validation

Documentation: /Users/khaliqgant/Projects/prpm/app/packages/converters/docs/agents-md.md

Schema location: /Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/agents-md.schema.json

Best Practices

1. Be concise: Focus on project-specific info (AI knows general practices)
2. Keep updated: Review and update as project evolves
3. Real examples: Show actual code patterns from your project
4. Plain markdown: No YAML frontmatter or special syntax
5. Human-readable: Write for both AI and human developers
6. Project-specific: Avoid generic advice that AI already knows
7. Natural structure: Organize however makes sense for your project

Migration from Other Formats

When converting to agents.md:

1. Strip all frontmatter - Remove YAML headers completely
2. Focus on content - Keep only markdown content
3. Combine files - Merge multiple rule files into one cohesive document
4. Simplify - Remove format-specific features (globs, regex, etc.)
5. Plain markdown only - Use standard markdown syntax

Official Specification

For the authoritative specification, see: https://github.com/openai/agents.md

---

Remember: agents.md uses plain markdown with NO frontmatter. Free-form structure. Focus on project-specific context AI doesn't already know.