Improve Your AI Code Output with AGENTS.md
The single file that transforms AI output from generic to production-ready. Real examples, templates, and before/after comparisons.
The Quality Problem
Without context, AI coding agents produce generic output. They write code that works but doesn't match your project's conventions, architecture, or quality standards. A React component might use class components when your project uses hooks. Error handling might be basic try/catch when your project uses a custom error boundary pattern.
The root cause: the AI doesn't know your preferences. It optimizes for 'correct code' rather than 'correct code for YOUR project.' Every time you manually fix these mismatches, you're doing work that AGENTS.md could prevent.
AGENTS.md changes the equation. By declaring your project's conventions once, every AI interaction starts with the right context. The improvement is immediate and dramatic — typically a 40-60% reduction in post-generation edits.
Anatomy of an Effective AGENTS.md
A well-structured AGENTS.md follows a specific pattern that maximizes AI comprehension.
Project identity (2-3 lines)
Start with what the project IS: 'KOSH AI is a dark-themed editorial directory for AI products. Stack: React + Vite + TypeScript, Tailwind CSS, React Query.' Brief, factual, immediately contextual.
Architecture rules (5-10 lines)
Where things live and how they connect: 'Pages in src/pages/, hooks in src/hooks/, API calls through src/lib/api.ts. Data flows: API → hook → component. Never call APIs directly from components.'
## Architecture
- Pages: src/pages/ (one file per route)
- Hooks: src/hooks/ (data fetching + state)
- API: src/lib/api.ts (single source of truth)
- Components: src/components/{feature}/ or src/components/shared/
- Data flow: API → custom hook → component (never direct)Coding conventions (10-15 lines)
The specific patterns you enforce: 'Use named exports. Keep components under 150 lines. Use Tailwind utility classes, never custom CSS. Boolean DB fields return "0"/"1" strings — always use Number(val) > 0.'
Do's and Don'ts (5-10 lines)
Explicit guards against common AI mistakes: 'DO use React Query for all data fetching. DON'T use useEffect for data fetching. DO handle loading and error states. DON'T use placeholder or mock data.'
Current context (3-5 lines, updated frequently)
What you're working on right now: 'Currently adding tutorial detail pages. The tutorials table has a slug field. Tutorial details are fetched from the edge function at /get-directory-data.' Update this section daily.
Before and After Examples
Example 1: Data Fetching
Without AGENTS.md, asking 'add a tools page' produces: a component with useEffect + useState that fetches data directly with fetch(), no loading state, no error handling, and hardcoded mock data as fallback.
With AGENTS.md specifying 'use React Query hooks in src/hooks/,' the same prompt produces: a custom useTools hook with React Query, proper loading skeleton, error state, and data fetched through the API layer.
Example 2: Component Structure
Without AGENTS.md: a 300-line monolithic component with inline styles and mixed concerns.
With AGENTS.md specifying 'keep components under 150 lines, extract hooks, use Tailwind': a focused 80-line component, a custom hook for data logic, and Tailwind classes for all styling.
Example 3: Error Handling
Without AGENTS.md: basic console.error statements.
With AGENTS.md specifying 'use toast notifications for user-facing errors, log to console for debug': proper toast notifications with user-friendly messages and detailed console logs for debugging.
Templates by Project Type
React SPA Template
Focus on: component patterns (functional only, named exports), state management (React Query for server state, useState for UI state), routing conventions, and styling approach (Tailwind classes, design tokens from CSS variables).
Full-Stack App Template
Add: database conventions (camelCase in TS, snake_case in SQL), API patterns (REST or GraphQL), authentication flow (how auth state is checked), and data validation approach (Zod schemas, form validation).
Landing Page Template
Emphasize: design system tokens (colors, typography, spacing), animation patterns (Framer Motion conventions), image handling (lazy loading, responsive images), and SEO requirements (meta tags, semantic HTML).
Mobile App Template
Specify: navigation patterns (stack, tab, drawer), platform-specific conventions (iOS vs Android), native module usage, and performance constraints (list virtualization, image caching).
Measuring Improvement
Track these metrics before and after adopting AGENTS.md:
Edit Distance: How many changes do you make after AI generation? A good AGENTS.md reduces this by 40-60%. Track the number of manual edits per AI-generated file.
Convention Compliance: Does the generated code follow your patterns? Check: correct file placement, proper imports, expected state management approach, and styling consistency.
Time to Usable: How long from prompt to production-ready code? With a good AGENTS.md, most generated code needs only minor adjustments rather than structural refactoring.
Review your AGENTS.md monthly: If you're still making the same corrections repeatedly, those corrections should be added to your AGENTS.md. It's a living document that gets better with use.
