Agent Instruction Files

Agent instruction files are standardized guide documents Backlog.md prepares for AI coding assistants. They tell AI how to work with Backlog.md, including workflow conventions, command usage, and task-management standards. Through unified instruction files, different AI tools maintain a consistent understanding of the project and avoid workflow drift caused by tool switching.

What Are Instruction Files

AI coding assistants read specific Markdown files in the project as context when starting. Backlog.md leverages this mechanism to generate instruction files containing project-management conventions. These files cover:

• An introduction to Backlog.md's core capabilities
• Task file structure explanation
• Complete CLI command reference
• Acceptance criteria and Definition of Done (DoD) conventions
• Typical workflow examples
• Common mistakes vs. correct practices

After reading these files, AI can accurately use Backlog.md features in conversations without users repeatedly explaining project conventions.

Generating Instruction Files

Backlog.md provides two ways to generate or update agent instruction files.

Auto-Generated During Project Initialization

When running backlog init to initialize a new project, the wizard asks whether to install AI agent instructions:

backlog init my-project
# The interactive wizard shows the option:
# "Install AI agent instructions?"

After choosing to install, Backlog.md generates the corresponding instruction files based on your choices.

Manually Updating Instructions for Existing Projects

For existing projects, you can update or regenerate instruction files at any time with:

backlog agents --update-instructions

This command scans the current project and regenerates all instruction files based on the current configuration, ensuring the content stays in sync with the project's current state. After modifying task status flows, label systems, or other project conventions, it is recommended to run this command to update AI instructions.

Generated File List

Depending on the AI tools you use, Backlog.md generates one or more of the following files:

Note: Cursor no longer generates a separate .cursorrules file owned by Backlog; it uses AGENTS.md uniformly. Repeated generation commands preserve existing user content in AGENTS.md and only update Backlog-managed marked blocks.

Instruction files do not contain a copy of the project state machine (as of v1.53.9): the state machine uses config.yml as the single source of truth, and backlog instructions overview renders it on the fly based on the current configuration. Old state-machine blocks written into AGENTS.md / CLAUDE.md / GEMINI.md by earlier versions are removed during the next backlog init or backlog agents --update-instructions.

CLAUDE.md

Designed specifically for Claude Code and Claude Desktop. Claude tools automatically read CLAUDE.md in the project root as part of the system prompt. This file contains the complete Backlog.md operation guide and is the most comprehensive instruction file.

AGENTS.md

A generic agent instruction file for Cursor and AI tools that do not recognize brand-specific files. The content is basically the same as CLAUDE.md but uses more generic phrasing. Cursor reads AGENTS.md in the project root as a generic agent instruction; some IDE plugins or custom AI clients also prefer AGENTS.md.

GEMINI.md

An instruction file optimized for Google Gemini CLI. Gemini CLI recognizes GEMINI.md in the project root and includes it in context.

.github/copilot-instructions.md

Designed for GitHub Copilot. Because Copilot does not support the MCP protocol, this file focuses more on CLI command references to help Copilot understand how to coordinate with Backlog.md shell commands during code generation. Located under .github/, it only takes effect in GitHub repositories.

Instruction File Content

All generated instruction files follow a unified content framework, mainly including the following modules.

Workflow Guide

Explains the recommended workflow for AI collaborating with Backlog.md:

• Load project reality first: in a new session, before giving any answer or plan, run commands such as backlog config list, backlog search <keyword>, backlog task list, backlog task view <id>, and backlog overview to read the actual statuses, defaultStatus, defaultAssignee, and active tasks.
• Do not assume the default status set [To Do, In Progress, Done]; when setting or validating task statuses, they must fall within the configured statuses.
• defaultStatus must be a member of statuses; if not, prompt the user to fix or choose another default.
• How to read tasks via CLI or MCP.
• How to write an implementation plan before implementation.
• How to complete tasks step by step according to acceptance criteria.
• How to add a final summary and mark the task complete.

This "load reality first" rule is written in the overview guide distributed with the CLI (rather than the project's own AGENTS.md), so it applies to any project using Backlog.md.

The loading cadence for backlog instructions overview is once per session: the guide instructs the agent to run this command once at the start of the session, before giving any answer or taking action; there is no need to repeat it within the same session after it has been read.

References and Line-Number Positioning

The guide specifies that task References support line-number references. Each reference is one of three forms: external URL, project-relative file path, or path with a line range (path:LINE for a single line, path:START-END for a continuous range). The references / addReferences / removeReferences parameters in task creation/editing and MCP follow the same convention; removeReferences matches by the full stored string (including the line-number suffix). Document links similarly distinguish three target types: external URL, Backlog short link (/task/:id, /doc/:id, etc., with optional line-number suffix), and project-relative path.

Date and Multi-Line Input Conventions

The guide also clarifies two common high-frequency input mistakes:

• Date and time fields: CLI and MCP accept local-time input, store it as UTC, and convert back to local time for display. Do not read the UTC value visible in the task file and pass it back as input, or a time-zone offset will be introduced.
• Multi-line text fields: use literal \n inside quotes to represent newlines; do not press the actual Enter key inside quotes—the shell will split it into multiple lines and only the first line will be saved.

Task Creation Conventions

Defines standards for high-quality tasks:

• Title should concisely summarize the task purpose.
• Description should focus on "why" rather than "how".
• Acceptance criteria must be outcome-oriented and verifiable.
• Each task corresponds to an independent Pull Request.

Acceptance Criteria Format

Details the format requirements for acceptance criteria:

• Use numbered checkbox form - [ ] #1 criteria content.
• Add via CLI --ac parameter.
• Manage completion status via --check-ac and --uncheck-ac.
• Support operating on multiple criteria items in a single command.

Command Reference

Provides a complete CLI command quick-reference table, covering:

• Task create, edit, view, archive
• Acceptance criteria and DoD management
• Search and filtering
• Document and decision management
• Board and overview

backlog instructions Volumes

In addition to writing instruction files into the project, the CLI has a built-in set of printable workflow volumes that correspond one-to-one with MCP resources:

backlog instructions            # print volume index
backlog instructions --list     # list available volumes
backlog instructions overview   # print a specific volume

The overview volume carries the project state machine; when printed, it is assembled on the fly from the current config.yml, not a static text (doc-19 FR-8).

MCP vs. CLI Instruction Approach

Backlog.md supports two AI integration approaches, each with applicable scenarios:

Recommended strategy:

• If the AI tool you use supports MCP, prefer the MCP approach.
• For tools such as GitHub Copilot that do not support MCP, use the CLI instruction approach as a supplement.
• Cursor supports both MCP and AGENTS.md instruction files; choose either or use both.
• The two approaches can coexist: MCP handles daily task management, while CLI instruction files ensure Copilot, Cursor, and others also understand project conventions.