Blog

Context Engineering for AI Coding Agents: AGENTS.md Guide

Your AI coding agent doesn’t understand your codebase. Not by default, anyway.

Every time you start a session, it has to discover your project’s structure, infer conventions, and piece together architecture from fragments. That costs tokens, slows down execution, and leads to avoidable mistakes.

Context engineering is the practice of giving agents the right information upfront, so they make better decisions faster.

Here’s how AGENTS.md and agent skills work, and how to use them effectively.

Without proper context, every coding session starts from zero.

What happens without context:

1. Agent reads system prompt
2. Agent explores repository structure
3. Agent infers conventions from code
4. Agent makes assumptions about architecture
5. Agent generates code
6. You correct mistakes
7. Agent learns from corrections
8. Session ends, understanding disappears

Cost: High token usage, slow execution, repeated mistakes.

AGENTS.md is a Markdown file at the root of your repository that gives AI agents spatial awareness of your codebase.

Think of it as the agent-facing counterpart to README.md. While README.md explains your project to humans, AGENTS.md explains it to AI agents.

A strong AGENTS.md includes:

1. Project overview: What the product does and who it’s for
2. Tech stack: Frameworks, languages, databases, tools
3. Architecture decisions: Key patterns and why they exist
4. Coding conventions: Naming, structure, formatting rules
5. Operational boundaries: What not to modify or call

# Project Overview
E-commerce platform built with Next.js 14 and TypeScript.
Serves 100k+ daily active users.

# Tech Stack
- Next.js 14 (App Router)
- TypeScript 5.3
- PostgreSQL + Prisma ORM
- Tailwind CSS
- Vercel deployment

# Architecture
- /app routes use Server Components by default
- Client Components marked with 'use client'
- API routes in /app/api/
- Database queries through Prisma client only

# Coding Conventions
- Use TypeScript strict mode
- Prefer Server Components for data fetching
- Client Components only for interactivity
- All database mutations through Prisma
- Never use useEffect for data fetching

# Operational Boundaries
- Do NOT modify /prisma/schema.prisma without approval
- Do NOT call external APIs without error handling
- Do NOT bypass authentication checks
- Always use transactions for multi-step mutations

If AGENTS.md gives agents a map of your codebase, agent skills give them reusable expertise for specific tasks.

A skill is typically a folder containing:

• SKILL.md: Instructions for the workflow
• Examples: Code samples, templates
• Scripts: Automation tools
• Reference material: Documentation, best practices

Authentication Skill:

/skills/authentication/
  - SKILL.md
  - examples/
    - clerk-setup.ts
    - nextauth-config.ts
  - templates/
    - protected-route.tsx
    - middleware.ts

Database Migration Skill:

/skills/database-migration/
  - SKILL.md
  - scripts/
    - generate-migration.sh
    - test-migration.sh
  - templates/
    - migration-template.ts

Skills load when relevant, not upfront. Instead of front-loading every rule, agents pull in the skill that matches the task.

This keeps context lean while ensuring domain-specific guidance is available when needed.

When a session starts, the agent checks for AGENTS.md at the repository root.

The agent uses AGENTS.md to:

• Understand project constraints
• Follow established patterns
• Avoid anti-patterns
• Respect operational boundaries

With context, the agent produces code that:

• Follows your conventions
• Respects your architecture
• Avoids prohibited patterns
• Requires fewer corrections

Don’t: Document every function and component Do: Focus on high-level patterns and constraints

A bloated AGENTS.md wastes context space and weakens signal-to-noise ratio. Aim for orientation, not exhaustive documentation.

❌ Vague: “Be careful with database changes” ✅ Specific: “Do NOT modify /prisma/schema.prisma without team approval. All schema changes go through migration review process.”

Specific constraints prevent more mistakes.

List the commands agents are most likely to need:

# Common Commands
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run test` - Run test suite
- `npx prisma studio` - Open database GUI
- `npx prisma migrate dev` - Create and apply migration

This reduces discovery time for routine tasks.

Don’t assume the agent knows your stack:

# Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.3 (strict mode)
- Database: PostgreSQL 15
- ORM: Prisma 5.7
- Styling: Tailwind CSS 3.4
- Deployment: Vercel

Explicit stack documentation prevents architectural mismatches.

❌ What: “Use Server Components by default” ✅ Why: “Use Server Components by default to minimize client bundle size and improve initial page load. Our Lighthouse target is 95+ for all pages.”

Context helps agents make better decisions when rules don’t cover edge cases.

Without skill:

1. Agent researches authentication patterns
2. Agent explores existing auth code
3. Agent makes assumptions about your setup
4. Agent generates code
5. You correct mistakes

With authentication skill:

1. Agent loads authentication skill
2. Agent reads your auth patterns from SKILL.md
3. Agent uses your templates and examples
4. Agent generates code following your conventions
5. Fewer corrections needed

1. Clear Purpose:

## Purpose
Implement authentication flows using Clerk in Next.js applications.

## When to Use
- Adding new protected routes
- Implementing sign-in/sign-up flows
- Setting up role-based access control

2. Step-by-Step Workflow:

## Workflow

1. Install dependencies: `npm install @clerk/nextjs`
2. Add environment variables (see .env.example)
3. Wrap app in <ClerkProvider>
4. Create middleware.ts for route protection
5. Add <SignIn /> and <SignUp /> components

3. Code Templates:

import { auth } from '@clerk/nextjs'
import { redirect } from 'next/navigation'

export default async function ProtectedRoute() {
  const { userId } = auth()

  if (!userId) {
    redirect('/sign-in')
  }

  // Your protected content here
}

4. Common Mistakes to Avoid:

## Common Mistakes

❌ Using `useAuth()` in Server Components
✅ Use `auth()` from '@clerk/nextjs' in Server Components

❌ Forgetting to add route to middleware matcher
✅ Update middleware.ts config when adding new protected routes

I tested the same task three ways:

Task: Implement role-based access control (RBAC) for a Next.js app

• Tokens used: 8,420
• Mistakes: 4 (wrong auth patterns, missing middleware, incorrect server/client usage)
• Corrections needed: 15 minutes
• Code quality: Functional but inconsistent with existing patterns

• Tokens used: 5,120
• Mistakes: 2 (minor convention drift)
• Corrections needed: 5 minutes
• Code quality: Consistent with architecture

• Tokens used: 3,840
• Mistakes: 0
• Corrections needed: 0 minutes
• Code quality: Perfectly aligned with conventions

Result: Context engineering reduced token usage by 54% and eliminated mistakes.

Use AGENTS.md for:

• Broad, persistent context
• Project-wide conventions
• Architectural decisions
• Operational boundaries

Use Skills for:

• Specific workflows
• Repeatable tasks
• Domain expertise
• Task-specific patterns

Use Both when:

• Complex projects with multiple workflows
• Teams with specialized areas
• Projects with strict quality requirements

• Write project overview (2-3 sentences)
• List tech stack explicitly
• Document architecture decisions
• Define coding conventions
• Set operational boundaries
• Add common commands

• List repetitive workflows
• Identify error-prone tasks
• Find domain-specific patterns
• Note team-specific practices

• Choose most common workflow
• Write SKILL.md with purpose and workflow
• Add code templates
• Include common mistakes
• Test with real task

• Monitor agent performance
• Update AGENTS.md based on mistakes
• Expand skill library
• Refine based on usage patterns

❌ Too much: 5,000-word AGENTS.md covering every edge case ✅ Right size: 500-1,000 words focusing on high-level patterns

❌ Vague: “Follow best practices” ✅ Specific: “Use Server Components by default. Client Components only for interactivity requiring useState or event handlers.”

❌ Stale: AGENTS.md from 3 months ago, tech stack changed ✅ Current: Update AGENTS.md when architecture changes

❌ Too many skills: 20+ skills loaded for simple project ✅ Focused skills: 3-5 skills for most common workflows

❌ Incomplete: AGENTS.md without tech stack or boundaries ✅ Complete: All sections filled with specific, actionable information

1. Token usage: Should decrease 30-50%
2. Mistake rate: Should drop to near-zero
3. Correction time: Should reduce significantly
4. Code consistency: Should improve measurably

• Use your AI tool’s token counter
• Log mistakes per session
• Time yourself on corrections
• Review code for pattern consistency

Context engineering is becoming essential as AI coding tools mature.

Phase 1 (Now): AI helps write code, but needs hand-holding Phase 2 (Coming): AI understands your project through context Phase 3 (Future): AI proactively suggests improvements based on context

Teams investing in context engineering now will have advantages as AI tools evolve.

1. Context engineering reduces discovery cost: Give agents information upfront instead of making them explore

2. AGENTS.md provides spatial awareness: A map of your codebase for AI agents

3. Skills provide domain expertise: Reusable patterns for specific workflows

4. Specificity prevents mistakes: Detailed constraints > vague guidelines

5. Measure and iterate: Track token usage, mistakes, and consistency

6. Start small: AGENTS.md first, then build skills for common workflows

1. Create AGENTS.md at your repository root
2. Document your tech stack explicitly
3. Define operational boundaries clearly
4. Identify your most repetitive workflow for your first skill
5. Test with a real task and measure improvement

Context engineering isn’t about teaching AI everything—it’s about giving it the right starting point so it makes better decisions faster.

Your future self (and your token budget) will thank you.

Need structured data for your AI agents? Check out SEWWA’s Schema Generator to create JSON-LD markup that helps both search engines and AI agents understand your content.