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.

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.

Tip: A good AGENTS.md cuts the back-and-forth at the start of sessions significantly. The agent spends less time exploring and more time doing.

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.

Then run this prompt.

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.

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.

Architecture overview

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

Tech stack

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

Coding conventions

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

Common patterns

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

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.

Tip: Forbidden patterns are especially valuable. They prevent the agent from doing things that look reasonable but violate your project's specific constraints.

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.

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.

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.

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.

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

autohand "Review my AGENTS.md and suggest any missing sections based on what you see in this project"