AGENTS.md: Make AI Actually Get Your Code

Here's the thing nobody tells you about vibe coding: the AI doesn't know your project. At all.

You've got a design system. Specific component patterns. That weird naming convention your team agreed on three sprints ago. The AI knows none of it. So it generates React components with inline styles when you use Tailwind. It creates buttons that look nothing like your existing ones. It ignores your folder structure entirely.

And then you spend 30 minutes fixing what should've taken 30 seconds.

I kept running into this until I discovered AGENTS.md—a simple markdown file that tells AI tools exactly how your project works. The difference was immediate. Same prompts, dramatically better output.

Key Takeaways:

• AGENTS.md is a context file that tells AI coding tools your project's rules, patterns, and preferences
• Proper context engineering can improve AI output quality by 70-90% on first generation
• Different tools use different files (.cursorrules, CLAUDE.md, .copilot-instructions) but the concept is identical
• Frontend-specific context—design systems, component patterns, styling rules—makes the biggest difference

In This Article

• What is AGENTS.md?
• Setting Up Your First AGENTS.md
• What to Include
• Before and After Examples
• Tool-Specific Files
• Hierarchical Context
• Template
• Common Mistakes
• FAQ

What is AGENTS.md? The Standard AI Tools Actually Read

AGENTS.md is a markdown file in your project root that provides context to AI coding agents. Think of it as onboarding documentation—but for AI tools instead of new developers.

The format has become an industry standard shockingly fast. OpenAI Codex reads it. Google's Jules reads it. The Linux Foundation endorsed it in early 2025. Most AI IDEs now look for context files automatically.

Here's why this matters: AI models are generic. They've been trained on millions of codebases with wildly different patterns. Without project-specific context, they default to "average" solutions—which rarely match YOUR setup.

An AGENTS.md file tells the AI:

• What frameworks and libraries you use
• Your coding style and conventions
• Component patterns and file structure
• What to do (and what to avoid)

It's not magic. It's just... context. And context is everything in context engineering for AI coding.

Setting Up Your First AGENTS.md for Frontend Projects

Let's get practical. Create a file called AGENTS.md in your project root:

your-project/
├── AGENTS.md        ← This file
├── src/
├── package.json
└── ...

The file is just markdown. Nothing special to install. Here's a minimal starting point:

# Project Context

## Tech Stack
- React 18 with TypeScript
- Tailwind CSS for styling
- shadcn/ui component library
- Vite for bundling

## Code Style
- Functional components only (no class components)
- Use TypeScript interfaces, not types
- Prefer named exports over default exports

## File Structure
- Components go in `src/components/`
- Pages go in `src/pages/`
- Shared utilities in `src/lib/`

That's it. That's a working AGENTS.md file.

When you prompt an AI tool that reads this file, it automatically knows to:

• Use TypeScript with interfaces
• Generate Tailwind classes instead of CSS
• Follow your export patterns
• Put files in the right places

No more explaining the basics in every single prompt.

What to Include: The Frontend Essentials

Here's my opinionated take on what actually matters for frontend projects. I've tested this across dozens of React and Next.js apps, and these sections make the biggest difference.

1. Design System Rules

This is where most people fail. You've got a color palette, spacing system, and typography scale—tell the AI about it:

## Design System

### Colors (use Tailwind classes)
- Primary: `bg-blue-600`, `text-blue-600`
- Secondary: `bg-slate-700`, `text-slate-700`
- Accent: `bg-emerald-500`
- Error: `text-red-500`, `border-red-500`

### Spacing
- Component padding: p-4 (small), p-6 (medium), p-8 (large)
- Section gaps: space-y-8 or gap-8
- Never use arbitrary values like p-[13px]

### Typography
- Headings: font-bold tracking-tight
- Body: text-slate-600 dark:text-slate-300
- Small text: text-sm text-slate-500

Without this section, AI will generate components using random colors that clash with everything else in your app.

2. Component Patterns

Tell the AI how YOU build components:

## Component Patterns

### Button Pattern
Always use the existing Button component from `@/components/ui/button`:
```tsx
import { Button } from "@/components/ui/button"
<Button variant="default" size="md">Click me</Button>

Never create new button components. Use variants: default, secondary, outline, ghost, destructive.

Card Pattern

Use @/components/ui/card for all card-like containers:

import { Card, CardHeader, CardContent } from "@/components/ui/card"

Form Inputs

Always use react-hook-form with zod validation. Import from @/components/ui/form.

This is huge. Instead of the AI inventing new button styles, it uses your existing components. Your UI stays consistent.

### 3. What NOT to Do

Negative constraints are surprisingly effective:

```markdown
## Constraints (Important!)

DO NOT:
- Use inline styles (always use Tailwind)
- Create new UI primitives if shadcn/ui has one
- Use any, unknown, or @ts-ignore in TypeScript
- Import from relative paths like "../../../" - use @ path aliases
- Add console.log statements
- Use deprecated React patterns (componentDidMount, etc.)

I call this the "guardrails section." It prevents the AI from doing things you'll just have to fix later.

Before and After: The Difference Context Makes

Let me show you what this looks like in practice.

Prompt: "Create a pricing card component with three tiers"

Without AGENTS.md:

// AI generates this mess
export default function PricingCard() {
  return (
    <div style={{ padding: '20px', border: '1px solid #ccc', borderRadius: '8px' }}>
      <h2 style={{ fontSize: '24px', fontWeight: 'bold' }}>Basic</h2>
      <p style={{ color: '#666' }}>$9/month</p>
      <button style={{ backgroundColor: 'blue', color: 'white', padding: '10px 20px' }}>
        Get Started
      </button>
    </div>
  )
}

Inline styles everywhere. No TypeScript. Default export. Generic colors. This is useless in a Tailwind project.

With AGENTS.md:

// Same prompt, but AI knows your context
import { Card, CardHeader, CardContent, CardFooter } from "@/components/ui/card"
import { Button } from "@/components/ui/button"

interface PricingTier {
  name: string
  price: number
  features: string[]
  highlighted?: boolean
}

export function PricingCard({ tier }: { tier: PricingTier }) {
  return (
    <Card className={tier.highlighted ? "border-blue-600 border-2" : ""}>
      <CardHeader>
        <h3 className="text-xl font-bold tracking-tight">{tier.name}</h3>
        <p className="text-3xl font-bold text-blue-600">${tier.price}/mo</p>
      </CardHeader>
      <CardContent className="space-y-4">
        {tier.features.map((feature) => (
          <p key={feature} className="text-slate-600">{feature}</p>
        ))}
      </CardContent>
      <CardFooter>
        <Button variant={tier.highlighted ? "default" : "outline"} className="w-full">
          Get Started
        </Button>
      </CardFooter>
    </Card>
  )
}

Same prompt. Night and day difference. The AI used your component library, followed your TypeScript patterns, applied your color system.

This is why people who set up proper context files ship 3x faster than those who don't. They're not fighting the AI's defaults anymore.

If you want to dive deeper into this, check out our guide on vibe coding best practices—context management is one of the core principles.

Tool-Specific Files: .cursorrules, CLAUDE.md, and Friends

Different AI tools read different files. The good news: the FORMAT is basically identical. You write it once, then copy to multiple files if needed.

Tool	Context File	Location
OpenAI Codex	AGENTS.md	Project root
Cursor	.cursorrules	Project root
Claude (Anthropic)	CLAUDE.md	Project root
GitHub Copilot	.copilot-instructions	.github/ folder
Google Jules	AGENTS.md	Project root
Windsurf	.windsurfrules	Project root

Here's my approach: I maintain one master AGENTS.md and create symlinks or copies for other tools:

# Create cursorrules from your AGENTS.md
cp AGENTS.md .cursorrules

# Or symlink so changes sync automatically
ln -s AGENTS.md .cursorrules

Some tools have slightly different features—Cursor supports @file references, Claude has certain formatting preferences—but 90% of your content will be identical.

The point is: don't overthink it. Write good context once, distribute it everywhere.

Hierarchical Context: Folder-Level AGENTS.md Files

Here's a pro tip that levels up your context game: you can have MULTIPLE context files at different folder levels.

your-project/
├── AGENTS.md                    # Global project rules
├── src/
│   ├── components/
│   │   └── AGENTS.md           # Component-specific patterns
│   ├── pages/
│   │   └── AGENTS.md           # Page-specific conventions
│   └── api/
│       └── AGENTS.md           # API route patterns

The AI reads these hierarchically—global rules apply everywhere, then folder-specific rules add or override.

Example: Your global file says "use TypeScript strict mode." Your /components/AGENTS.md adds specific component patterns. Your /api/AGENTS.md specifies error handling conventions for routes.

This is especially powerful for larger projects where different parts of the codebase have different conventions.

# src/components/AGENTS.md

## Component Rules for This Folder

All components here should:
- Be wrapped with React.memo() if they're used in lists
- Include displayName for debugging
- Export prop interfaces separately for reuse

Example structure:
```tsx
import { memo } from 'react'

export interface MyComponentProps {
  // ...
}

export const MyComponent = memo(function MyComponent(props: MyComponentProps) {
  // ...
})
MyComponent.displayName = 'MyComponent'

## Template: Copy-Paste AGENTS.md for React + Tailwind

Here's a battle-tested template. Copy this, customize it for your project, and watch your AI output quality skyrocket.

```markdown
# AGENTS.md - Project Context for AI Coding Agents

## Overview
This is a [YOUR PROJECT TYPE] built with React, TypeScript, and Tailwind CSS.

## Tech Stack
- React 18 with TypeScript 5
- Tailwind CSS 3.4
- shadcn/ui component library
- React Hook Form + Zod for forms
- TanStack Query for data fetching
- Vite / Next.js (pick one)

## Project Structure

src/ ├── components/ # Reusable UI components │ └── ui/ # shadcn/ui primitives ├── pages/ # Page components / routes ├── hooks/ # Custom React hooks ├── lib/ # Utilities and helpers ├── types/ # TypeScript type definitions └── styles/ # Global styles (minimal, mostly Tailwind)

## Code Conventions

### TypeScript
- Use `interface` for object shapes, `type` for unions/primitives
- Never use `any` - use `unknown` and narrow types properly
- Export interfaces for component props

### Components
- Functional components with hooks only
- Use named exports: `export function Component()`
- Colocate component-specific types in the same file
- Use absolute imports with `@/` prefix

### Styling
- Tailwind CSS only - no inline styles, no CSS modules
- Use design tokens from tailwind.config.ts
- Mobile-first responsive: base styles, then sm:, md:, lg:
- Dark mode via `dark:` variant

### Existing Components (USE THESE)
- Button: `@/components/ui/button` (variants: default, secondary, outline, ghost)
- Card: `@/components/ui/card`
- Input: `@/components/ui/input`
- Form: `@/components/ui/form` (with react-hook-form)
- Dialog: `@/components/ui/dialog`
- See shadcn/ui docs for full list

## Design System

### Colors
- Primary: blue-600 / blue-500
- Secondary: slate-700 / slate-600
- Background: white / slate-50
- Text: slate-900 (headings), slate-600 (body)
- Error: red-500
- Success: emerald-500

### Typography
- Headings: font-bold tracking-tight
- Body: text-base text-slate-600
- Caption: text-sm text-slate-500

### Spacing
- Component padding: p-4, p-6
- Section gaps: space-y-8
- Card padding: p-6

## DO NOT
- Use inline styles or style prop
- Create new primitive components if shadcn/ui has one
- Use relative imports like "../../../"
- Add console.log in generated code
- Use class components or lifecycle methods
- Hardcode colors - use Tailwind classes

Customize this for YOUR stack. Add your specific libraries, conventions, and patterns. The more specific you are, the better results you'll get.

Want to test this immediately?

Try with Fardino →

Common Mistakes That Kill Your Context

After reviewing dozens of AGENTS.md files, I see the same problems repeatedly. Don't make these mistakes:

1. Being Too Vague

❌ "Use good TypeScript practices" ✅ "Use interfaces for object shapes. No any types. Export prop interfaces."

Vague instructions get vague results. Be specific.

2. Information Overload

Your context file shouldn't be a novel. AI models have context limits. A 500-line AGENTS.md will get truncated, and the AI might miss the important parts.

Keep it focused: 150-300 lines is the sweet spot for most projects.

3. Outdated Information

You added a new component library last month. Updated the design system. Switched from CSS Modules to Tailwind. But your AGENTS.md still references the old setup.

Stale context is worse than no context—it actively misleads the AI.

Fix: Review your context files monthly. Add it to your sprint checklist.

4. No Examples

Rules without examples are hard to follow—for humans AND AI. When you specify a pattern, show a code example:

❌ "Use the Button component correctly" ✅ "Use the Button component like this: <Button variant="outline" size="sm">Text</Button>"

5. Ignoring Negative Constraints

Telling the AI what TO do is only half the battle. Tell it what NOT to do. This prevents the most common issues before they happen.

If you're still seeing common vibe coding mistakes in your output, your constraints section probably needs work.

You Might Also Like

• Context Engineering for AI Coding: The Complete Guide - Deep dive into context management strategies
• Vibe Debugging: 5-Step Workflow That Fixes Any AI UI - When AI output still needs fixing
• Fix AI-Generated Code Errors (Actually Works) - Quick fixes for common issues

Frequently Asked Questions

What is AGENTS.md?

AGENTS.md is a markdown file that provides project context to AI coding agents. It tells AI tools about your tech stack, coding conventions, design system, and patterns so they generate code that matches your project's existing style. The format is supported by OpenAI Codex, Google Jules, and many AI IDEs.

How do I create an AGENTS.md file?

Create a file named AGENTS.md in your project root. Write markdown sections covering your tech stack, code conventions, component patterns, and constraints. There's no special syntax—it's just markdown. Start with a minimal file and expand it as you notice common issues in AI output.

Does AGENTS.md work with Cursor?

Cursor uses a similar file called .cursorrules in the project root. The format is nearly identical to AGENTS.md. You can copy your AGENTS.md content to .cursorrules or create a symlink. Cursor also reads CLAUDE.md files for Claude model context.

How long should my AGENTS.md file be?

Aim for 150-300 lines. Too short and you're missing important context. Too long and you risk hitting context limits or burying important information. Focus on patterns that affect EVERY component, not edge cases. You can use folder-level context files for specific subsections of your codebase.

What's the difference between AGENTS.md and .cursorrules?

They serve the same purpose—providing project context to AI tools. AGENTS.md is the emerging cross-tool standard (supported by OpenAI, Google, Linux Foundation). .cursorrules is Cursor-specific. For maximum compatibility, maintain both. The content can be identical; just copy to both files.

---

Written by the Fardino Team. We build AI tools for frontend developers. Try Fardino free →