Skip to main content

​
Overview

You can provide instructions to Poolside agents from one or more of these sources. Poolside applies them in the following order:
SourceLocationUse it to define
1. Agent instructionsSaved managed agent in Poolside ConsoleWhat the agent does, including its role, tasks, and purpose
2. AGENTS.md in the current directoryCurrent directoryHow the agent works in this part of your codebase, including rules, constraints, and directory-specific context
3. AGENTS.md in parent directoriesParent directories to repository rootHow the agent works across broader parts of your codebase, including rules, constraints, and project context
4. .poolsideYour machinePersonal preferences for all your projects
When you run a managed agent, Poolside combines its agent instructions with any applicable AGENTS.md and .poolside files.
Because agent behavior is not deterministic, responses do not always reflect the order above perfectly.

​
How to set up instructions

For most teams, the best place to start is an AGENTS.md file at the root of the repository.
  1. Add an AGENTS.md file at the root of your repository. Include a few clear rules about project structure, coding conventions, and common workflows. See Example AGENTS.md.
  2. Add nested AGENTS.md files only when a subdirectory needs additional instructions.
  3. Add a .poolside file for personal preferences you want across projects. See Example .poolside.
  4. Use agent instructions when you want reusable behavior for a saved managed agent. See Managed agents.
  5. Refine your instructions if the agent misses important context or behaves inconsistently.

​
Agent instructions

Agent instructions are configured in Poolside Console when you create or edit an agent. They define the agent’s role and the tasks it should perform, and apply every time the agent runs. Agent instructions apply to managed agents only. They take priority over AGENTS.md and .poolside files. To configure agent instructions, see Managed agents.

​
AGENTS.md

Use an AGENTS.md file to define rules, constraints, and project-specific context for the agent. Place one at the root of your repository for rules that apply everywhere, and add more AGENTS.md files in subdirectories to scope instructions to specific parts of the codebase. Poolside combines all AGENTS.md files that apply to the directory the agent is working in. A file in a subdirectory takes precedence over a file in a parent directory. 
repo/
├── AGENTS.md              # instructions for the whole repository
├── app/
│   ├── AGENTS.md          # instructions for all app code
│   └── ui/
│       └── AGENTS.md      # instructions for UI code
└── api/
    └── AGENTS.md          # instructions for API code
In this example, three AGENTS.md files apply when the agent works in app/ui/: app/ui/AGENTS.md, app/AGENTS.md, and the root AGENTS.md. The closest file takes priority, so app/ui/AGENTS.md takes precedence over app/AGENTS.md, which takes precedence over the root AGENTS.md. Common uses include:
  • Defining coding standards and conventions
  • Setting constraints on agent behavior
  • Providing context about your project’s structure or architecture
  • Specifying workflows or required steps for common tasks

​
Example AGENTS.md

## Project overview

This is a Go REST API. The `internal/` directory contains business logic; `cmd/` contains entry points.

## Development

- Run tests with `go test ./...`
- Use `golangci-lint run` before committing

## Conventions

- Return errors to the caller; do not log them at the point of creation.
- New database queries go in `internal/store/`, not inline in handlers.

​
.poolside

Use a .poolside file to set personal preferences that apply across all your projects. It uses the same Markdown format as AGENTS.md. Poolside reads .poolside after the applicable AGENTS.md files. Use .poolside for preferences that should follow you across projects, and use AGENTS.md for project-specific rules that take priority. This Markdown file is separate from the .poolside/ directory that stores settings such as tool permissions. By default, Poolside looks for your .poolside file at ~/.config/poolside/.poolside. To use a different location, set the XDG_CONFIG_HOME environment variable.

​
Example .poolside

## Response preferences

- Put the code before the explanation.
- Keep explanations concise unless I ask for more detail.
- When you suggest shell commands, explain any destructive steps.

## Coding preferences

- Prefer immutable patterns over mutation where reasonable.
- Add docstrings to new public functions.

​
Tips and caveats

  • Keep instructions short and specific.
  • Use Markdown headings to organize rules.
  • Add a short example if the model struggles to follow a rule.
  • Start with a few clear instructions and refine them over time.
  • Use these files to control output format, such as verbosity or code-only responses.
  • What you type in the session can override AGENTS.md guidance.
  • Empty .poolside and AGENTS.md files are not sent to the model.
  • The model may not follow instructions consistently.