Setting Up a Project with AGENTS.md

What you'll learn

• What AGENTS.md is and why it helps
• How to generate an AGENTS.md file automatically
• Which sections to include for your team
• How to test and maintain the file over time

Before you start

Make sure you have the following ready, then open a project to configure.

Requirements

• Autohand Code installed. Run autohand --version to verify. See Your First Autohand Session if you need to set up.

Project setup

Navigate to the root of a project you work on regularly. This is where your AGENTS.md will live.

cd path/to/your-project

Step 1: Understand AGENTS.md

AGENTS.md is a plain text file you place at the root of your project. Autohand reads it at the start of every session, so it always has the right context before you type your first prompt.

Think of it as an onboarding document written for the agent, not for humans. Instead of explaining your project architecture out loud at the start of each session, you write it once and the agent picks it up automatically.

The file is committed to your repository, which means your whole team benefits from it. Every developer who uses Autohand on the project gets the same consistent starting context.

Step 2: Generate your AGENTS.md

The fastest way to create an AGENTS.md is to ask Autohand to write one based on your existing project. Navigate to your project root and start a session.

cd path/to/your-project
autohand

Then run this prompt.

Create an AGENTS.md file for this project based on its structure and conventions

The agent will read your project files, identify the tech stack, find your build scripts, and draft an AGENTS.md. Review what it creates before committing. The agent is thorough but may include things that do not apply, or miss things that only you know.

# Review the generated file
cat AGENTS.md

Step 3: Add key sections

A useful AGENTS.md covers these areas. You do not need all of them, but the more context you provide, the better the agent performs.

Commands

List the commands needed to work with the project. The agent uses these instead of guessing.

## Commands

```bash
npm install       # Install dependencies
npm run dev       # Start development server
npm run build     # Build for production
npm test          # Run the test suite
npm run lint      # Run ESLint
```

Architecture overview

Describe how the project is structured at a high level. A short paragraph is enough.

## Architecture

This is a Next.js application with a PostgreSQL database.
The frontend lives in `src/app/`, API routes are in `src/app/api/`,
and shared utilities are in `src/lib/`. Authentication uses NextAuth.js.

Tech stack

Name the key libraries and frameworks so the agent does not need to infer them.

## Tech Stack

- Next.js 15 with App Router
- TypeScript 5
- Prisma ORM with PostgreSQL
- Tailwind CSS
- Vitest for unit tests
- Playwright for E2E tests

Coding conventions

Describe any patterns your team follows that are not obvious from the code itself.

## Conventions

- Use named exports only, no default exports
- All async functions must have explicit return types
- Error handling: throw domain errors, never return null for errors
- API route handlers go in `route.ts` files, logic goes in `src/lib/`
- Tests live next to the files they test, named `*.test.ts`

Common patterns

Point out any patterns the agent should follow when generating new code.

## Common Patterns

New database queries go through Prisma service functions in `src/lib/db/`.
Never query the database directly from API route handlers.
Use the `withAuth` wrapper for any protected API routes.

Step 4: Customize for your team

Beyond the basics, add any team-specific rules that the agent should follow. These are the things that would otherwise take weeks for a new developer to learn.

## Rules

- Never use `any` in TypeScript. Use `unknown` and narrow the type.
- Do not install new dependencies without asking first.
- All user-facing strings go through the i18n system in `src/i18n/`.
- Do not modify files in `src/generated/`. These are auto-generated by Prisma.
- The `payments/` module is maintained by the payments team. Read only.

## Forbidden patterns

- Do not use `document.querySelector` directly. Use the React refs pattern.
- Do not write raw SQL. Use Prisma queries.
- Do not commit `.env` files or any file containing secrets.

Step 5: Test your AGENTS.md

After creating or updating your AGENTS.md, verify the agent actually uses it. Start a fresh session and ask a question that depends on the context in the file.

autohand "How do I add a new API endpoint to this project?"

If your AGENTS.md describes the correct pattern, the agent should describe it back to you accurately. If the response is vague or generic, the file may be missing detail in that area.

Another useful test is to ask the agent to create a new file and check whether it follows your conventions.

autohand "Create a new API endpoint at /api/users/[id]/settings that returns the user's notification preferences"

Review the generated code. If it violates any of your conventions, update AGENTS.md to be more explicit about that rule.

Step 6: Keep it updated

AGENTS.md is most useful when it reflects the current state of your project. Treat it like documentation: update it whenever you make significant architectural changes or establish new conventions.

You can ask Autohand to help update it as the project evolves.

autohand "We just migrated from REST to tRPC. Update AGENTS.md to reflect the new API patterns."

If you notice the agent doing something wrong repeatedly in sessions, that is usually a sign that AGENTS.md needs a new rule. Add it immediately so the pattern does not repeat.

autohand "Add a rule to AGENTS.md: all form validation must use Zod schemas, not manual validation code."

What you learned

• Created an AGENTS.md file that gives the agent context about your project
• Added sections for commands, architecture, tech stack, and conventions
• Tested that the agent uses the file correctly in a session

Try next