#ai#howto#opencode
Tue, 13 Jan. 2026 Thomas Bendler ~ 5 min to read

Since AI coding assistants started becoming practical, I spent a lot of time explaining the AI-Agent the same things: “No, we use 2-space indentation here,” “Please use stylua for Lua formatting,” “This is a stow-managed dotfiles repo, not a typical project.” Not surprisingly, this became tedious pretty quickly. And yes, it also still feels weird to talk to a machine like talking to a human.

Anyhow, I discovered that placing an AGENTS.md file in your project root transforms the way AI assistants understand and work with your codebase. So, let me share my findings.

What Is AGENTS.md?

Think of AGENTS.md as a “README for AI.” It’s a Markdown file that lives in your repository root and provides AI coding agents with essential context about your project—the kind of tribal knowledge that usually lives only in developers’ heads.

The good thing is that most modern AI coding tools (GitHub Copilot, Claude, Cursor, and others) automatically detect and read this file when starting to work in your repository.

What Goes Into an AGENTS.md?

Here’s the structure that works well for me:

1. Repository Overview

Start with what the project actually is. AI agents need this context to make sensible decisions:

## Repository Overview
Personal dotfiles managed with GNU Stow. Each top-level directory
(alacritty/, nvim/, tmux/, etc.) contains config files that get
symlinked to `~/.config/` or `~/`.

2. Build/Test Commands

Even if your project has no build system, say so explicitly. This prevents AI from inventing commands that don’t exist:

## Build/Test Commands
- No build system - this is a configuration-only repository
- To apply configs: `stow <directory>` (e.g., `stow nvim`)
- To remove: `stow -D <directory>`

3. Code Style Guidelines

This section is where the real value lives. Be specific about formatters, linters, and conventions:

## Code Style Guidelines

### Lua (Neovim config)
- Formatter: stylua (see `nvim/.config/nvim/stylua.toml`)
- 2 spaces indentation, 120 char line width, Unix line endings
- Prefer single quotes, no call parentheses for simple function calls
- Run: `stylua nvim/.config/nvim/`

### Shell Scripts
- Use shellcheck for linting, shfmt for formatting
- 2 spaces indentation

4. General Conventions

Capture those unwritten rules that every contributor eventually learns:

### General
- UTF-8 encoding, LF line endings
- Keep configs minimal and well-commented
- Follow existing patterns in each config directory

Why This Approach Offers Several Benefits

  1. Consistency — AI-generated code matches your project’s existing style from the first suggestion.

  2. Reduced friction — No more back-and-forth corrections. The agent knows your conventions upfront.

  3. Onboarding documentation — Fortunately, this file also helps human contributors understand project norms.

  4. Tool awareness — Agents know which formatters and linters to run, and how to run them.

  5. Context preservation — Unlike chat history that gets lost, AGENTS.md persists with your repository.

Tips for Writing Effective AGENTS.md

Based on my experience, here’s what makes a difference:

  • Be explicit about what doesn’t exist. “No build system” is useful information.
  • Include actual commands. stylua nvim/.config/nvim/ is better than “use stylua.”
  • Reference config files. Point to stylua.toml or .editorconfig when they exist.
  • Keep it current. Outdated guidance is worse than no guidance.
  • Start small. You can always expand it as you discover gaps.

A Practical Example

Here’s my complete AGENTS.md for a dotfiles repository:

# AGENTS.md - AI Coding Agent Guidelines

## Repository Overview
Personal dotfiles managed with GNU Stow. Each top-level directory
(alacritty/, nvim/, tmux/, etc.) contains config files that get
symlinked to `~/.config/` or `~/`.

## Build/Test Commands
- No build system - this is a configuration-only repository
- To apply configs: `stow <directory>` (e.g., `stow nvim`)
- To remove: `stow -D <directory>`

## Code Style Guidelines

### Lua (Neovim config)
- Formatter: stylua (see `nvim/.config/nvim/stylua.toml`)
- 2 spaces indentation, 120 char line width, Unix line endings
- Prefer single quotes, no call parentheses for simple function calls
- Run: `stylua nvim/.config/nvim/`

### Shell Scripts
- Use shellcheck for linting, shfmt for formatting
- 2 spaces indentation

### General
- UTF-8 encoding, LF line endings
- Keep configs minimal and well-commented
- Follow existing patterns in each config directory

Getting Started

Adding AGENTS.md to your project takes about 10 minutes:

  1. Create AGENTS.md in your repository root
  2. Describe what the project is and how it’s structured
  3. List build/test/deploy commands (or state there are none)
  4. Document your code style rules and preferred tools
  5. Commit and push

That’s it. The next time an AI assistant works in your repo, it will automatically pick up this context. So, if you’re using AI coding assistants regularly, I’d recommend giving AGENTS.md a try. It doesn’t take much time or effort to implement, but increase the quality of the AI results significantly.