AGENTS.md

AGENTS.md is a special file at the root of a workspace that provides the AI agent with context about your codebase. Think of it as a README for the agent — it tells the agent about your project’s purpose, architecture, conventions, and any other information that helps it work more effectively.

How AGENTS.md Works

When a conversation starts in a workspace, Tarsk reads the AGENTS.md file from that workspace’s directory and includes its content in the agent’s system prompt. Every message in that conversation has access to the project context you defined.

Edit AGENTS.md from the Instructions section of Project Settings (project scope), or place the file at the workspace root manually.

Note

Instructions are per workspace, not global. Each workspace clone has its own AGENTS.md. Changes in one workspace do not affect others until merged via git.

Creating AGENTS.md

Place an AGENTS.md file at the root of your workspace:

AGENTS.md

## Overview

This is a Next.js e-commerce application with Stripe payments. The frontend uses
React Server Components with the App Router, and the API routes handle payment
processing and webhooks.

## Architecture

- `app/` — Next.js App Router pages and layouts
- `app/api/` — API route handlers
- `components/` — Shared React components
- `lib/` — Utility functions and shared logic
- `lib/db.ts` — Database client (Prisma)
- `prisma/` — Prisma schema and migrations

## Conventions

- Use Server Components by default; only add "use client" when state or effects are needed
- All API routes must validate input with Zod schemas
- Database queries go through the Prisma client in `lib/db.ts`
- Never access the database directly from components

Empty File Behavior

If AGENTS.md does not exist, the Instructions section of Project Settings shows an empty editor with a placeholder. Type your instructions and click Save to create the file. Starting a chat does not create it.

What to Include

The best AGENTS.md files are concise and focused on information the agent cannot discover by reading code alone:

Recommended Sections

• Overview — What the project does, its purpose, and target users
• Architecture — Key directories, how the codebase is organized, and major subsystems
• Conventions — Coding standards, naming patterns, and rules the agent should follow
• Testing — How to run tests, what framework is used, where tests live
• Deployment — How the project is built and deployed

What Not to Include

• Information that is obvious from the code
• Large code snippets the agent can read directly from source
• Content that changes frequently and would become stale

Relationship to Rules

AGENTS.md and Rules both provide instructions to the agent, but they serve different purposes:

	AGENTS.md	Rules
Purpose	Project context and architecture	Specific behavioral guidelines
Location	Workspace root (AGENTS.md)	.agents/rules/*.md
Loading	Always included in system prompt	Conditionally loaded based on relevance
Scope	One file per workspace	Multiple rules, each with its own focus

Use AGENTS.md for broad project context and Rules for specific, actionable guidelines.

Tips

• Keep AGENTS.md under 200 lines — the agent has a limited context window
• Update it when the project’s architecture changes significantly
• Commit it to version control so your team benefits from the same agent context
• Use it to document decisions that are hard to reverse (e.g., “This project uses Prisma, not Drizzle”)