AGENTS.md

AGENTS.md is a special file at the root of a branch 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 branch, Tarsk reads the AGENTS.md file from that branch’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 Settings → Instructions (project scope, requires a selected branch), or place the file at the branch root manually.

Creating AGENTS.md

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

## 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

Auto-Generation

If an AGENTS.md file does not exist when the agent first looks for it, Tarsk creates one with default template content. Edit it via Settings → Instructions or directly in the Files panel.

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	Branch root (`AGENTS.md`)	`.agents/rules/*.md`
Loading	Always included in system prompt	Conditionally loaded based on relevance
Scope	One file per branch	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”)