AGENTS.md

AGENTS.md is a special file you place at the root of your project to provide 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 thread, Tarsk reads the AGENTS.md file from the thread’s directory and includes its content in the agent’s system prompt. This means every message in that conversation has access to the project context you defined.

Edit AGENTS.md from Settings → Instructions when a project is selected, or place the file at the project root manually.

Creating AGENTS.md

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

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

Auto-Generation

If an AGENTS.md file does not exist when the agent first looks for it, Tarsk creates one with default template content. You can edit this to replace it with information specific to your project.

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 (e.g. “this file exports a function”)
• Large code snippets that the agent can read directly from the 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	Project root (AGENTS.md)	.agents/rules/*.md
Loading	Always included in system prompt	Conditionally loaded based on relevance
Scope	One file per project	Multiple rules, each with its own focus

Use AGENTS.md for broad project context and Rules for specific, actionable guidelines the agent should follow (e.g., “Always use TypeScript interfaces for API responses” or “Never commit directly to main”).

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 entire 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”)