AGENTS.md — Operating Instructions

+15 Mana ✨
OpenClaw AGENTS.md Reference(DOCUMENTATION)OpenClaw Memory Directives Guide(DOCUMENTATION)

Introduction

AGENTS.md is the main instruction file that tells your OpenClaw agent how to operate within a specific workspace. While SOUL.md defines personality and IDENTITY.md establishes identity, AGENTS.md provides the practical playbook: what to do, how to do it, and what to remember. It is the most frequently edited bootstrap file because it evolves with your projects and workflows.

Key Concepts

  • Operating Instructions: Step-by-step guidance for how the agent should handle common tasks within your workspace
  • Memory Directives: Rules for what the agent should remember and write to MEMORY.md during conversations
  • Behavioral Rules: Workspace-specific rules that supplement the personality defined in SOUL.md
  • Project Context: Information about the codebase, tech stack, and conventions the agent needs to work effectively
  • Workspace Scope: AGENTS.md is per-workspace, so different projects can have different instructions for the same agent

Real World Context

A development team maintains a monorepo with a Go backend and React frontend. Their AGENTS.md instructs the agent to always run go vet before suggesting code changes, to use the team's custom error handling pattern, and to check for breaking API changes when modifying shared types. Without these instructions, the agent would produce syntactically correct but conventionally wrong code that fails code review.

Deep Dive

AGENTS.md lives in the workspace directory and is loaded during bootstrap. It is the file where you put everything the agent needs to know about working in a specific project.

Here is a comprehensive example:

markdown
# Operating Instructions

## Code Standards
- Always use our custom error wrapper: `apperror.Wrap(err, "context")`
- Run `make lint` mentally before suggesting code changes
- All new functions require a doc comment
- Use table-driven tests for Go code

## Git Workflow
- Branch naming: `feat/`, `fix/`, `chore/` prefixes
- Commit messages follow Conventional Commits format
- Never force-push to main or develop branches
- Always suggest running tests before committing

## Memory Directives
- Remember any architectural decisions discussed in this session
- Track which files were modified and why
- Note any tech debt or TODOs mentioned during conversation
- Forget temporary debugging steps after the issue is resolved

## Project Context
- Backend: Go 1.22 with Chi router
- Frontend: React 19 with Tailwind v4
- Database: PostgreSQL 16 with sqlc for queries
- CI: GitHub Actions with required checks

## Common Tasks
When asked to add an API endpoint:
1. Define the route in `internal/routes/`
2. Create handler in `internal/handlers/`
3. Add sqlc query if database access needed
4. Write table-driven test in `_test.go` file
5. Update the OpenAPI spec in `docs/api.yaml`

This AGENTS.md gives the agent a complete operational playbook. The code standards section prevents it from generating non-idiomatic code. The git workflow section ensures it follows team conventions. The memory directives tell it what to persist across conversations. The project context provides technical grounding. The common tasks section gives step-by-step recipes for frequent operations.

Memory directives are particularly powerful. They instruct the agent to proactively write important information to MEMORY.md:

markdown
## Memory Directives

### Always Remember
- Architectural decisions and their rationale
- Patterns the user prefers (naming, structure, style)
- Bugs found and their root causes
- Dependencies added or removed

### Never Remember
- Temporary debugging output
- One-off exploratory questions
- Credentials or secrets mentioned in passing

These directives create a feedback loop where the agent builds a knowledge base about your project over time, making it increasingly effective with each conversation.

Common Pitfalls

  • Duplicating SOUL.md content: AGENTS.md is for workspace-specific operating instructions, not personality. If you find yourself writing tone or persona rules, they belong in SOUL.md.
  • Writing overly rigid instructions: Instructions like "never use any package not already in go.mod" prevent the agent from suggesting legitimate dependency additions. Leave room for judgment.
  • Forgetting to update after tech stack changes: If you migrate from React to Svelte but AGENTS.md still references React patterns, the agent will give outdated guidance.

Best Practices

  • Structure with clear sections: Use Markdown headers for Code Standards, Git Workflow, Memory Directives, Project Context, and Common Tasks.
  • Include recipes for common tasks: Step-by-step instructions for frequent operations (adding endpoints, creating components, writing tests) dramatically improve agent output.
  • Review AGENTS.md during sprint planning: As your project evolves, keep AGENTS.md current with your latest conventions and priorities.

Summary

  • AGENTS.md is the primary operating instructions file, scoped to a specific workspace
  • It covers code standards, git workflow, memory directives, project context, and common task recipes
  • Memory directives create a feedback loop where the agent builds project knowledge over time
  • It supplements SOUL.md (personality) and IDENTITY.md (identity) with practical operational guidance
  • Keep it current with your project's evolving conventions and tech stack
✓ Completed